/* 8-BIT NES — type surface (hand-written; the package ships zero-build ESM). */

/** [freqHz, durationSec] pairs played as a square-wave sequence. */
export type SfxSeq = ReadonlyArray<readonly [number, number]>;

/** localStorage wrapper that falls back to memory in private mode / quota errors. */
export declare const store: {
  get(key: string): string | null;
  set(key: string, value: string): void;
};

/** Built-in chiptune SFX sequences. */
export declare const SFX: {
  coin: SfxSeq;
  bad: SfxSeq;
  clear: SfxSeq;
  unlock: SfxSeq;
};

/** Play a square-wave sequence. Silent when muted or audio unavailable — never throws. */
export declare function bleep(seq: SfxSeq): void;

export declare function setMute(muted: boolean): void;
export declare function isMuted(): boolean;

/** Float a "+N XP" label upward from an element (smooth ease-out motion). */
export declare function floatXP(el: HTMLElement, text?: string, color?: string): void;

/** Dispatch XP on the `nes:xp` document bus (an <nes-hud> listens) + optional floater. */
export declare function grantXP(amount: number, srcEl?: HTMLElement): void;

/** Accent names mapped in base.css (`--accent` + `--accent-d`). `good` (green) is the primary/default. */
export type Accent =
  | "blue"
  | "gold"
  | "cyan"
  | "purple"
  | "lime"
  | "teal"
  | "indigo"
  | "pink"
  | "steel"
  | "good"
  | "warn"
  | "crit";

/** Options for {@link toast}. */
export interface ToastOptions {
  /** Accent name mapped in base.css (`good`/green default — the primary accent). */
  accent?: Accent;
  /** Auto-dismiss delay in ms; `0` keeps it (and forces a dismiss button). Default 3200. */
  timeout?: number;
  /** A mono uppercase line above the message. */
  title?: string;
  /** An UNDO-style button; clicking it runs `onClick` and dismisses the toast. */
  action?: { label: string; onClick?: () => void };
  /** Show the ✕. Default true (always true when `timeout` is 0). */
  dismissible?: boolean;
  /** Treat `msg` as markup. Default false — `msg` is text, so it cannot inject. */
  html?: boolean;
  /** How many toasts stay on screen; the oldest beyond this are dropped. Default 4. */
  max?: number;
  /** Bleep on show. Default true (`crit` bleeps sad). */
  sound?: boolean;
}

/** A toast element, with its own dismiss. */
export interface ToastElement extends HTMLElement {
  /** Fade it out and remove it. Safe to call twice. */
  dismiss(): void;
}

/**
 * Show a transient toast (auto-creates the live-region host on first call).
 * `msg` is TEXT unless `html: true`. Pauses while hovered or focused, and can be
 * swiped away on touch. A `crit` toast interrupts (assertive) instead of waiting.
 */
export declare function toast(msg: string, opts?: ToastOptions): ToastElement;

/** Options for {@link confirmDialog}. */
export interface ConfirmOptions {
  /** The question, in the header. Default "Are you sure?". */
  title?: string;
  /** One line of consequence — say what cannot be undone. */
  body?: string;
  /** The destructive button's text. Default "Confirm". */
  confirmLabel?: string;
  /** The safe button's text. Default "Cancel". */
  cancelLabel?: string;
  /** Accent for the dialog and the confirm button. Default "crit". */
  accent?: Accent;
  /** Treat `body` as markup. Default false. */
  html?: boolean;
}

/**
 * A destructive confirm as a promise, on `<dialog>.showModal()`. Resolves false on
 * Cancel, Esc and a backdrop click. Focus starts on Cancel, so Enter is never the
 * destructive answer.
 */
export declare function confirmDialog(opts?: ConfirmOptions): Promise<boolean>;

/** Highlight code to HTML with `.t-*` token spans (used by <nes-code>). */
export declare function highlightCode(code: string): string;

/** A breakpoint width read from tokens.css, so JS switches shape at the same width
 *  a media query does (CSS cannot read a var() inside `@media`).
 *  `matchMedia(`(min-width: ${bp("lg")})`)` */
export declare function bp(name: "sm" | "lg" | "xl", fallback?: string): string;

/* ---- custom elements ---- */

export interface NesSoundElement extends HTMLElement {}
export interface NesCollapsibleElement extends HTMLElement {}
export interface NesHudElement extends HTMLElement {
  /** Add XP directly (also persisted under `${ns}_xp`). */
  add(amount: number): void;
}
export interface NesQuizElement extends HTMLElement {}
export interface NesTabsElement extends HTMLElement {}
export interface NesCodeElement extends HTMLElement {}

/* ---- Form module ---- */

/** <nes-form>: native constraint validation → inline errors → `nes:submit`. */
export interface NesFormElement extends HTMLElement {
  /** The wrapping <form> (created on connect). */
  form: HTMLFormElement;
  /** Validate every control; on success dispatch `nes:submit`, else focus the first bad field. */
  submit(): void;
}
/** <nes-number>: auto-wired − [n] + stepper over a native number input. */
export interface NesNumberElement extends HTMLElement {
  value: string;
}
/**
 * <nes-switcher>: cycle a small option set with ◀ / ▶ (arcade settings row).
 * Options come from a child `<script type="application/json">` (strings or
 * `{value,label}`). Wraps around unless `no-wrap` is set; emits `nes:change`
 * with `{value,index}`. Keeps a hidden `<input name>` for form submit.
 */
export interface NesSwitcherElement extends HTMLElement {
  /** the currently-selected option value. */
  value: string;
}
/** <nes-rating>: click / arrow-key star picker (add `readonly` for display only). */
export interface NesRatingElement extends HTMLElement {
  value: number;
}
/** <nes-tags>: chip input; value is the ordered tag list. */
export interface NesTagsElement extends HTMLElement {
  readonly value: string[];
}
/** <nes-pin>: N single-char cells; fires `nes:complete` when full. */
export interface NesPinElement extends HTMLElement {
  readonly value: string;
}
/** <nes-file>: click-or-drop upload zone with a removable file list. */
export interface NesFileElement extends HTMLElement {
  readonly files: File[];
}
/** <nes-listbox>: roving-focus option list; `value` is a string (or string[] when `multiple`). */
export interface NesListboxElement extends HTMLElement {
  readonly value: string | string[] | null;
}
/** <nes-input-menu>: free-text combobox (autocomplete; value = typed text). */
export interface NesInputMenuElement extends HTMLElement {
  value: string;
}
/** <nes-select-menu>: strict searchable single-select (value ∈ options). */
export interface NesSelectMenuElement extends HTMLElement {
  value: string;
}
/** <nes-tree>: hierarchical folder/file tree; `value` is a string (or string[] when `multiple`). */
export interface NesTreeElement extends HTMLElement {
  readonly value: string | string[] | null;
}

/* ---- AI Chat module ---- */

/** <nes-chat-prompt>: auto-growing prompt + send/stop button. Fires `nes:submit`/`nes:stop`. */
export interface NesChatPromptElement extends HTMLElement {
  value: string;
  /** Streaming flag: mirror of the `busy` attribute — flips Send → Stop. */
  setBusy(busy: boolean): void;
  focus(): void;
}
/** <nes-chat-messages>: scroll container that auto-sticks to the newest message. */
export interface NesChatMessagesElement extends HTMLElement {
  scrollToBottom(): void;
}
/** <nes-icon name="…">: renders a pixel icon by name (see `8bit-nes/icons`). */
export interface NesIconElement extends HTMLElement {}

/* ---- Typography / MDC module ---- */

/** A single node in an <nes-code-tree> (folders nest via `children`, files carry `code`). */
export interface CodeTreeNode {
  label: string;
  /** File source; presence marks this node as a selectable file (folders omit it). */
  code?: string;
  /** Optional leading glyph (emoji/char) shown before the label. */
  icon?: string;
  /** Start a folder expanded. */
  expanded?: boolean;
  children?: CodeTreeNode[];
}
/**
 * <nes-code-tree>: file tree (left) + syntax-highlighted code viewer (right).
 * Reads a `<script type="application/json">` child of {@link CodeTreeNode}[].
 * Ideal for rendering repo/snippet layouts from AI-generated MDC output.
 */
export interface NesCodeTreeElement extends HTMLElement {}

/* ---- Visualize module ---- */

/** Mermaid config (themeVariables + fonts + label size) mapped to 8-BIT NES tokens.
 *  Label size comes from `--mmd-fs` (falling back to `--fs-body`), resolved to px so
 *  both `config.fontSize` (number) and `themeVariables.fontSize` (CSS length) agree.
 *  Pass the result to `mermaid.initialize(...)` when bringing your own instance. */
export declare function mermaidTheme(root?: Element): Record<string, unknown>;

/** Opt into lazy-loading mermaid from `url` (a CDN or self-hosted ESM build).
 *  Until called (or `globalThis.mermaid` set, or a per-element `src`), diagrams
 *  render their raw source and no mermaid is fetched — zero bytes by default. */
export declare function enableMermaid(url: string): void;

/**
 * <nes-mermaid>: render a Mermaid diagram, themed to the system. Mermaid itself
 * is never bundled — it uses `globalThis.mermaid`, a per-element `src`, or the
 * URL from {@link enableMermaid}. Streaming-safe: assign `.code` on each chunk;
 * partial/invalid syntax keeps the last good render. Renders with
 * `securityLevel:"strict"` since AI output is untrusted. Emits `nes:render`,
 * `nes:node` (on node click), and `nes:theme` — cancelable, once, before
 * `initialize()`: amend `detail.config` to change any mermaid option, or
 * `preventDefault()` to keep a config you set yourself.
 */
export interface NesMermaidElement extends HTMLElement {
  /** current diagram source; set it to (re-)render (debounced). */
  code: string;
  /** force a (debounced) re-render. */
  render(): void;
  /** spotlight nodes whose label matches (string or array); dims the rest. */
  highlight(focus: string | string[]): void;
}

/** One step of a {@link NesWalkthroughElement}. */
export interface WalkthroughStep {
  title?: string;
  /** step content as HTML. */
  body?: string;
  /** node labels to spotlight in the `for` target (if it has `highlight()`). */
  focus?: string[];
}
/**
 * <nes-walkthrough>: step-by-step "How it works". Prev/Next + arrow keys +
 * progress dots. Reads a `<script type="application/json">` of
 * {@link WalkthroughStep}[]. With `for="<id>"` pointing at a {@link
 * NesMermaidElement} (or anything exposing `highlight()`), each step spotlights
 * its `focus` labels — a principle unfolds one piece at a time. Emits `nes:step`.
 */
export interface NesWalkthroughElement extends HTMLElement {
  /** current step index (0-based). */
  readonly index: number;
  go(n: number): void;
  next(): void;
  prev(): void;
  /** stop autoplay (also called automatically on the first user interaction). */
  stopAuto(): void;
}

/**
 * <nes-zoom>: pan + zoom wrapper for any content (big diagrams, images,
 * screenshots). Wheel / drag / buttons / keyboard (`+` `-` `0`). Zero-dep CSS
 * transform — wrap an <nes-mermaid> to make a large diagram explorable.
 */
export interface NesZoomElement extends HTMLElement {
  zoomBy(factor: number): void;
  zoomTo(scale: number): void;
  reset(): void;
}

/** One hotspot of a {@link NesAnnotateElement} (x/y are percentages). */
export interface AnnotatePoint {
  x: number;
  y: number;
  /** marker label (defaults to its 1-based index). */
  label?: string | number;
  title?: string;
  /** popover body as HTML. */
  body?: string;
}
/**
 * <nes-annotate>: numbered hotspot markers + popovers positioned (by %) over
 * any child content (image, diagram). Reads a `<script type="application/json">`
 * of {@link AnnotatePoint}[]. Emits `nes:annotate`. Great for spatial "how it
 * works" explanations.
 */
export interface NesAnnotateElement extends HTMLElement {
  open(index: number): void;
  close(): void;
}

/**
 * <nes-compare>: before/after A-B slider. Takes its first two element children
 * (A over B) and reveals A with a draggable divider. Pointer + keyboard (←/→).
 * Set the initial split with the `value` attribute (0–100).
 */
export interface NesCompareElement extends HTMLElement {
  /** move the divider to `pos` percent (0–100). */
  set(pos: number): void;
}

/** A node in a {@link NesGraphElement} knowledge graph. */
export interface GraphNode {
  /** unique id, referenced by {@link GraphEdge.source}/`target`. */
  id: string;
  /** display label (defaults to `id`). */
  label?: string;
  /** accent name (`"purple"`, `"cyan"`, …) that colours the node. */
  group?: string;
  /** pin the node at this x (0–100); omit to let the layout place it. */
  x?: number;
  /** pin the node at this y (0–100); omit to let the layout place it. */
  y?: number;
}
/** An edge (undirected line) between two {@link GraphNode}s by id. */
export interface GraphEdge {
  source: string;
  target: string;
}
/**
 * <nes-graph>: a knowledge graph. Force-lays-out `{nodes,edges}` deterministically
 * (no deps, no randomness) as crisp SVG; clicking a node focuses its neighbourhood
 * (dimming the rest) and emits `nes:node`. Data comes from a child
 * `<script type="application/json">`, the `data` attribute, or the `.data` property.
 * Wrap in {@link NesZoomElement} for pan/zoom.
 */
export interface NesGraphElement extends HTMLElement {
  /** the graph data; assigning re-runs the layout. */
  data: { nodes: GraphNode[]; edges: GraphEdge[] };
  /** focus a node by id (dims the rest); pass `null`/omit to clear. */
  focusNode(id?: string | null): void;
}

/* ---- OpenCode module (vibe-coding workspace) ---- */

/** Line counts from the last {@link NesDiffElement} render (also the `nes:diff` detail). */
export interface DiffStat {
  /** files touched (from `diff --git` / `+++` headers). */
  files: number;
  added: number;
  removed: number;
}

/**
 * <nes-diff>: renders a unified diff (git / agent output) as on-brand `.diff`
 * markup and emits `nes:diff` with the totals. Parsing + rendering only — wrap
 * it in `.hunk` for review chrome. Feed it as text content or via `.value`.
 */
export interface NesDiffElement extends HTMLElement {
  /** the raw unified-diff text; assigning re-renders. */
  value: string;
  /** totals from the last render. */
  readonly stat: DiffStat;
  render(): void;
}

/** Tint applied to a log line pushed into {@link NesLogsElement}. */
export type LogLevel = "info" | "debug" | "warn" | "error" | "done";

/**
 * <nes-logs>: a streaming log surface that follows the tail unless the reader
 * scrolls up. Ring-buffered (`max`) and filterable (`level`). The toolbar is
 * deliberately not its job — compose `.btn` / `.segment` beside it.
 */
export interface NesLogsElement extends HTMLElement {
  /** ring-buffer cap (the `max` attribute; default 500). */
  readonly max: number;
  /** whether the view is currently stuck to the tail. */
  readonly pinned: boolean;
  /** append one line; returns the created `.logline`. */
  push(text: string, level?: LogLevel): HTMLElement;
  clear(): void;
  /** jump back to the tail. */
  follow(): void;
}

/** Viewport preset for {@link NesPreviewElement} (375px / 768px / full). */
export type PreviewView = "mobile" | "tablet" | "desktop";

/**
 * <nes-preview>: the running app in a framed viewport — URL bar, reload and
 * 375/768/full widths. Emits `nes:navigate` on reload/navigation. A `sandbox`
 * attribute is passed through to the iframe verbatim.
 */
export interface NesPreviewElement extends HTMLElement {
  /** the previewed address (reflects the `src` attribute). */
  url: string;
  /** the active viewport preset (reflects the `view` attribute). */
  view: PreviewView;
  /** reload the frame (or navigate, if the URL field was edited). */
  reload(): void;
}

/**
 * <nes-toc>: Map of Content — the live "on this page" index. Builds itself from
 * the headings in `target`, follows the scroll (marking `.active` +
 * `aria-current`), and hides itself when there are fewer than `min` headings.
 * Mobile-first: a collapsible sticky bar naming the current section, becoming an
 * open sticky rail from `rail-at`. Renders its list as the `.outline` recipe.
 */
/** `<nes-popover>` — an anchored panel in the top layer (native popover API). */
export interface NesPopoverElement extends HTMLElement {
  /** Where the panel sits; it flips and shifts to stay on screen. */
  placement?: string;
  /** Read-only: is it open. */
  readonly open: boolean;
  show(): void;
  hide(): void;
  toggle(): void;
  /** Re-position against the trigger (already called on scroll and resize). */
  place(): void;
}

/** `<nes-split>` — two panes and a draggable, keyboard-movable divider. */
export interface NesSplitElement extends HTMLElement {
  /** The first pane's size in %. Setting it clamps to `min` and fires `nes:resize`. */
  at: number;
  /** Read-only: is it stacked (`dir="column"`). */
  readonly column: boolean;
}

export interface NesTocElement extends HTMLElement {
  /** the headings currently indexed, in document order. */
  readonly headings: HTMLElement[];
  /** id of the section the reader is in. */
  readonly active: string;
  /** px used for the scroll-spy edge and the heading `scroll-margin` fallback. */
  readonly offset: number;
  /** collapse/expand the bar (no-op in the rail shape). */
  open: boolean;
  /** rebuild from the current DOM — call after a client-side route change. */
  refresh(): void;
}

/** How a ghost suggestion should be produced. */
export type EditorSuggestMode =
  /** continue the text in the same language */
  | "continue"
  /** ghost the target-language rendering of the current text (bilingual) */
  | "translate"
  /** ghost a grammar/spelling correction (language practice) */
  | "correct";

/** Rich context passed to an editor's `suggest` provider (and the `nes:suggest`
 *  event). Enough for source→target inference: translate or continue the draft. */
export interface EditorSuggestContext {
  /** full plain text of the document (ghost excluded). */
  text: string;
  /** text from the document start up to the caret. */
  textBefore: string;
  /** text from the caret to the document end. */
  textAfter: string;
  /** plain text of the block the caret is in. */
  block: string;
  /** source language (the `lang` attribute), e.g. "vi". */
  lang: string;
  /** target language (the `target-lang` attribute), e.g. "en". */
  targetLang: string;
  /** current ghost mode (toggled by the toolbar language chip). */
  mode: EditorSuggestMode;
}

/** Detail of the `nes:ai` event — an AI action was invoked from the editor. */
export interface EditorAIDetail {
  /** which action: "ask" | "translate" | "improve" | "continue" | "fix" | "summarize". */
  command: string;
  /** full plain text of the document. */
  text: string;
  /** the currently selected text (empty if none). */
  selection: string;
  lang: string;
  targetLang: string;
  /** insert HTML at the caret. */
  insert: (html: string) => void;
  /** replace the current selection with HTML (or insert at caret if none). */
  replace: (html: string) => void;
}

/**
 * <nes-editor>: lightweight, AI-first contenteditable rich-text editor —
 * toolbar, slash (/) / mention (@) / emoji (:) menus, block drag handle,
 * VSCode-style Tab ghost autocomplete, and a bring-your-own-model AI hook.
 * Bilingual: set `lang` + `target-lang` (+ `suggest-mode`) so a `suggest`
 * provider can ghost the target-language rendering for Tab — write in one
 * language, Tab out the other (blog + language practice). Emits
 * `nes:input`/`nes:submit`/`nes:mention`/`nes:ai`/`nes:suggest`.
 */
export interface NesEditorElement extends HTMLElement {
  /** current HTML content (ghost suggestion excluded). */
  value: string;
  /** current plain text. */
  readonly text: () => string;
  /** insert HTML at the caret (e.g. AI-generated content). */
  insert(html: string): void;
  /** replace the current selection with HTML (or insert at caret if none). */
  replaceSelection(html: string): void;
  /** show a dim inline ghost suggestion the user accepts with Tab. */
  showGhost(text: string): void;
  /** trigger an AI action programmatically (fires `nes:ai`). */
  triggerAI(command?: string): void;
  focus(): void;
  /** optional async provider for Tab autocomplete; return "" for no suggestion. */
  suggest?: (ctx: EditorSuggestContext) => string | Promise<string>;
}

/** Detail of the `nes:answer` event bubbled by <nes-quiz>. */
export interface NesAnswerDetail {
  correct: boolean;
  choice: number;
}

/** Detail of the `nes:submit` event bubbled by <nes-form>. */
export interface NesSubmitDetail {
  /** Flat form values (from `FormData`). */
  data: Record<string, string>;
  form: HTMLFormElement;
}

declare global {
  interface HTMLElementTagNameMap {
    "nes-sound": NesSoundElement;
    "nes-collapsible": NesCollapsibleElement;
    "nes-hud": NesHudElement;
    "nes-quiz": NesQuizElement;
    "nes-tabs": NesTabsElement;
    "nes-code": NesCodeElement;
    "nes-form": NesFormElement;
    "nes-number": NesNumberElement;
    "nes-switcher": NesSwitcherElement;
    "nes-rating": NesRatingElement;
    "nes-tags": NesTagsElement;
    "nes-pin": NesPinElement;
    "nes-file": NesFileElement;
    "nes-listbox": NesListboxElement;
    "nes-input-menu": NesInputMenuElement;
    "nes-select-menu": NesSelectMenuElement;
    "nes-tree": NesTreeElement;
    "nes-chat-prompt": NesChatPromptElement;
    "nes-chat-messages": NesChatMessagesElement;
    "nes-icon": NesIconElement;
    "nes-editor": NesEditorElement;
    "nes-code-tree": NesCodeTreeElement;
    "nes-mermaid": NesMermaidElement;
    "nes-walkthrough": NesWalkthroughElement;
    "nes-zoom": NesZoomElement;
    "nes-annotate": NesAnnotateElement;
    "nes-compare": NesCompareElement;
    "nes-graph": NesGraphElement;
    "nes-diff": NesDiffElement;
    "nes-logs": NesLogsElement;
    "nes-preview": NesPreviewElement;
    "nes-toc": NesTocElement;
    "nes-popover": NesPopoverElement;
    "nes-split": NesSplitElement;
  }
  interface DocumentEventMap {
    "nes:xp": CustomEvent<{ amount: number }>;
    "nes:mute": CustomEvent<{ muted: boolean }>;
  }
  interface HTMLElementEventMap {
    "nes:answer": CustomEvent<NesAnswerDetail>;
    "nes:submit": CustomEvent<NesSubmitDetail>;
    "nes:invalid": CustomEvent<Record<string, never>>;
    "nes:complete": CustomEvent<{ value: string }>;
    "nes:change": CustomEvent<{ value?: unknown; files?: File[] }>;
    "nes:toggle": CustomEvent<{ value: string; expanded: boolean }>;
    "nes:stop": CustomEvent<Record<string, never>>;
    "nes:input": CustomEvent<{ html: string; text: string }>;
    "nes:mention": CustomEvent<{ value: string; label: string }>;
    "nes:ai": CustomEvent<EditorAIDetail>;
    "nes:suggest": CustomEvent<EditorSuggestContext & { accept: (suggestion: string) => void }>;
    "nes:render": CustomEvent<{ ok: boolean }>;
    "nes:node": CustomEvent<{ label: string; id: string; group?: string }>;
    "nes:step": CustomEvent<{ index: number; step: WalkthroughStep }>;
    "nes:annotate": CustomEvent<{ index: number }>;
    "nes:diff": CustomEvent<DiffStat>;
    "nes:navigate": CustomEvent<{ url: string }>;
    "nes:section": CustomEvent<{ id: string; text: string }>;
    "nes:open": CustomEvent<void>;
    "nes:close": CustomEvent<void>;
    "nes:resize": CustomEvent<{ at: number }>;
    "nes:theme": CustomEvent<{ config: Record<string, unknown>; mermaid: unknown }>;
  }
}