@wildwinter/app-shell 0.38.0 → 0.40.0

package/dist/index.d.ts

@@ -1,61 +1,28 @@
-export { EDIT_MENU, GO_MENU, MenuLabel, PANE_MENU } from './menu.js';
+export { EDIT_MENU, FILE_MENU, GO_MENU, MenuLabel, PANE_MENU, PLAY_MENU, PUBLISH_MENU, REVIEW_MENU, VIEW_MENU } from './menu.js';
+export { HintBarItem, KeyHintOptions, KeyPlatform, hintBar, isKeyCombo, keyHint, keyLabel, keyLegends, keyPlatform, setKeyPlatform, tipWithKey } from './keys.js';
+export { ProblemCopy, ProblemCopyEntry, ProblemCopyTable, ProblemLike, defaultProblemCopy, describeProblem, problemLine, problemName } from './problems.js';
+export { D as DefaultControlOptions, a as DupGuard, P as PROPERTY_TYPES, b as PropertyDeclLike, c as PropertyListHandle, d as PropertyListOptions, e as PropertyListType, S as SettingsDialog, f as SettingsDialogOptions, g as SettingsSection, h as SettingsSectionHandle, i as defaultControl, j as dupGuard, k as expandableRow, l as focusNewRow, m as mountPropertyList, n as mountSettingsDialog, r as revealRow, o as revealRowWhenReady } from './property-list-D3VZCJzi.js';
+export { DialogFrame, DialogFrameOptions, dialogFrame } from './dialog.js';
+export { Floating, FloatingOptions, createFloating } from './floating.js';
+export { ContextItem, PopoverOptions, openContextMenu, openPopover } from './context-menu.js';
 export { JOB_PROGRESS, JobProgress } from './job.js';
+export { UpdaterLink, UpdaterViewOptions, feedUpdaterDownloadProgress, showUpdaterDialog } from './updater-view.js';
+export { UpdaterDownloadProgress, UpdaterPromptOptions } from './updater.js';
+export { Welcome, WelcomeAction, WelcomeGroup, WelcomeGroupItem, WelcomeOptions, WelcomeRecent, mountWelcome } from './welcome.js';
+export { LinkStatus, LinkStatusChip, LinkStatusClass, LinkStatusOptions, linkAddress, linkStatusClass, linkStatusTip, mountLinkStatus } from './link-status.js';
+export { Debounced, copyWithFeedback, debounce, formatCount, isEditableTarget, plural, relativeTime } from './util.js';
+import './app-store.js';
+import 'electron';
 
-type Child = Node | string | null | undefined;
-interface ElProps {
-    className?: string;
-    text?: string;
-    /** A NATIVE rollover. Prefer `tip`: `title` is OS chrome on the platform's own
-     *  slow delay, which is the seam the themed tooltip exists to close. */
-    title?: string;
-    /** A themed rollover (`data-tip`, picked up by the delegated controller that
-     *  `initTooltips()` wires). Also the accessible name, since the elements that
-     *  want one are usually icon buttons with no text of their own. */
-    tip?: string;
-    onClick?: (event: MouseEvent) => void;
-}
-declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrProps?: string | ElProps, ...children: Child[]): HTMLElementTagNameMap[K];
-/** A small square glyph button (the move/delete controls list editors share).
- *  Its rollover is the THEMED one (`data-tip`), so an app that has called
- *  `initTooltips()` gets our bubble rather than the platform's. */
-declare function iconBtn(glyph: string, title: string, onClick: () => void, disabled?: boolean, danger?: boolean): HTMLButtonElement;
 /**
- * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
- *
- * The label is pointed at the field it captions, EXPLICITLY, and never at a button. A `<label>` with no
- * `for` forwards a click to its first labelable descendant, and buttons are labelable - so a caption
- * wrapped around a control containing buttons (`tagChips`, whose every chip carries a remove button)
- * turns every click on the row's dead space into a press of the FIRST button in it. That shipped:
- * patterkit/patter#44, where clicking a Game Data list value anywhere but its ✕ deleted the first value
- * in the list. Reported as "clicking a value removes the wrong one", which is not a wrong-index bug at
- * all - the click never reached the chip.
+ * The typed glyphs the vocabulary used to draw.
  *
- * When the control holds no labelable field (a chips editor with the add input removed, say), this is a
- * plain `<div>`: no caption behaviour is better than a caption that presses something.
- */
-declare function labelled(label: string, control: HTMLElement): HTMLElement;
-/** Swap item `i` with its neighbour `i + delta` IN PLACE (the up/down reorder list editors share);
- *  a no-op when the target is out of range. Returns whether anything moved. */
-declare function moveItem<T>(arr: T[], i: number, delta: number): boolean;
-/** A tag-style editor for a string-list field (an enum's allowed values / flags): removable chips + an
- *  add input (Enter or "," commits; blank / duplicate ignored). Mutates `holder.values` in place (read
- *  back on save). `onChange` fires after any add / remove so callers can refresh a dependent control. */
-declare function tagChips(holder: {
-    values?: string[];
-}, onChange?: () => void): HTMLElement;
-
-/** Curated colour slots; must match the `--char-*` set defined per theme. */
-declare const PALETTE_SIZE = 12;
-declare const PALETTE: readonly string[];
-/** Hash a name to a palette slot: FNV-1a + an fmix32 avalanche, well
- *  distributed even for short, similar names. */
-declare function colourIndex(name: string): number;
-/** The theme-aware CSS variable reference for a name's slot. */
-declare function colourFor(name: string): string;
-
-/**
- * Named by what it MEANS. Grouped by the job, because that is how a caller
- * looks for one.
+ * @deprecated Since the move to drawn icons (design-language.md, "Icons are
+ * drawn"). Kept byte-for-byte so a consumer still doing
+ * `textContent = icon.close` keeps working while each app moves; a new call
+ * site uses `iconNode(name)` (a node to append) or `iconHtml(name)` (for an
+ * innerHTML build). The names are the same in all three. Removed once both
+ * apps have moved.
  */
 declare const icon: {
     /** Close a panel, a dialog, a popover. Patterpad's, twelve times over. */
@@ -117,24 +84,210 @@ declare const icon: {
      *  comments are the conversation, and the two must never look alike. */
     readonly comment: "❝";
 };
-type IconName = keyof typeof icon;
 /**
- * The few shapes no glyph says honestly, as inline SVG.
- *
- * `currentColor` throughout, so they take the colour of the button they sit in
- * exactly as the glyphs do, and sized in the markup for the same reason: an icon
- * that needs a CSS rule to be the right size is an icon that will be the wrong
- * size somewhere.
+ * Every word in the vocabulary. The 26 the glyph table had, plus the seven the
+ * 2026-09 review found the apps drawing by hand with nothing to check against.
+ */
+type IconName = keyof typeof icon
+/** History back, the topbar's quiet arrow pair (nav-history.ts). An ARROW,
+ *  not a chevron: a chevron says structure, an arrow says time (the author's
+ *  ruling, 2026-08-28). Added beside `arrowRight` so the pair share a set. */
+ | "arrowLeft"
+/** History forward; also the one honest "go there" arrow where a link used
+ *  to carry a typed one. */
+ | "arrowRight"
+/** Connect to a server, a live link, a running game. */
+ | "connect"
+/** Search. */
+ | "search"
+/** Keep this window on top (tool-window-web.ts). */
+ | "pin"
+/** Settings. */
+ | "settings"
+/** Record. The icon is the DISC; painting it in the danger colour while
+ *  recording is the caller's job, through the button's own colour. */
+ | "record";
+/**
+ * The drawings as strings, by word, for a caller that builds markup itself.
+ * Prefer `iconHtml(name, size)`, which sizes it; these carry no width/height.
  *
- * Lifted from Patterpad, which drew them first.
+ * Two legacy entries ride along unchanged: `noteFilled` and `noteOutline`, the
+ * has-notes / no-notes pair Patterpad drew on a 16-unit grid before the set
+ * existed. They are sized in the markup (13px) and on their own grid, so they
+ * are NOT part of the vocabulary above and `iconNode` does not know them; no
+ * app uses them today. They stay until a 24-grid pair replaces them, because
+ * their two-state meaning (there are notes / there are none) has no Lucide
+ * shape, and re-weighting the 16-grid drawing to the family stroke merges its
+ * text lines.
  */
 declare const iconSvg: {
-    /** A document with lines: notes exist on this thing. */
+    /** A document with lines: notes exist on this thing. (legacy, 16 grid) */
     readonly noteFilled: "<svg viewBox=\"0 0 16 16\" width=\"13\" height=\"13\" fill=\"currentColor\" fill-rule=\"evenodd\" aria-hidden=\"true\"><path d=\"M3.4 1.4h5.3L12.6 5.3v8.1a1.2 1.2 0 0 1-1.2 1.2H3.4a1.2 1.2 0 0 1-1.2-1.2V2.6A1.2 1.2 0 0 1 3.4 1.4ZM4.9 6.8h6.2v1.1H4.9Zm0 2.1h6.2v1.1H4.9Zm0 2.1h3.7v1.1H4.9Z\"/></svg>";
-    /** The same document, empty: nothing written here yet. */
+    /** The same document, empty: nothing written here yet. (legacy, 16 grid) */
     readonly noteOutline: "<svg viewBox=\"0 0 16 16\" width=\"13\" height=\"13\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.1\" stroke-linejoin=\"round\" stroke-linecap=\"round\" aria-hidden=\"true\"><path d=\"M3.4 2h4.9l3.9 3.9v7.5a1 1 0 0 1-1 1H3.4a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1Z\"/><path d=\"M8.3 2.2v3.8h3.8\"/><path d=\"M4.9 8h6.2M4.9 10h6.2M4.9 12h3.7\" stroke-width=\"0.95\"/></svg>";
+    readonly search: string;
+    readonly close: string;
+    readonly play: string;
+    readonly more: string;
+    readonly collapsed: string;
+    readonly expanded: string;
+    readonly dropdown: string;
+    readonly back: string;
+    readonly forward: string;
+    readonly up: string;
+    readonly down: string;
+    readonly tick: string;
+    readonly locked: string;
+    readonly readOnly: string;
+    readonly checkedOut: string;
+    readonly modified: string;
+    readonly untracked: string;
+    readonly warning: string;
+    readonly dot: string;
+    readonly restart: string;
+    readonly viewCards: string;
+    readonly viewTable: string;
+    readonly viewNode: string;
+    readonly grip: string;
+    readonly add: string;
+    readonly note: string;
+    readonly comment: string;
+    readonly arrowLeft: string;
+    readonly arrowRight: string;
+    readonly connect: string;
+    readonly pin: string;
+    readonly settings: string;
+    readonly record: string;
 };
 type IconSvgName = keyof typeof iconSvg;
+/** Every word, in table order, for a test or a gallery to walk. */
+declare const ICON_NAMES: IconName[];
+/** The default size: 14px, the family's icon inside its small square button. */
+declare const ICON_SIZE = 14;
+/**
+ * The drawing as markup with its size set, for a caller building innerHTML.
+ * `data-icon` carries the word, so a stylesheet or a test can find it.
+ */
+declare function iconHtml(name: IconName, size?: number): string;
+/**
+ * The drawing as a fresh SVG node, sized. Append it where the glyph used to be
+ * set as text; it is `aria-hidden`, so the button's accessible name stays the
+ * button's (`aria-label` / `data-tip`), as it always had to.
+ */
+declare function iconNode(name: IconName, size?: number): SVGSVGElement;
+/** The word a deprecated glyph stood for, or undefined for any other string. */
+declare function iconNameOfGlyph(glyph: string): IconName | undefined;
+/** Whether a string is a word in the vocabulary. */
+declare function isIconName(s: string): s is IconName;
+
+type Child = Node | string | null | undefined;
+interface ElProps {
+    className?: string;
+    text?: string;
+    /** A NATIVE rollover. Prefer `tip`: `title` is OS chrome on the platform's own
+     *  slow delay, which is the seam the themed tooltip exists to close. */
+    title?: string;
+    /** A themed rollover (`data-tip`, picked up by the delegated controller that
+     *  `initTooltips()` wires). Also the accessible name, since the elements that
+     *  want one are usually icon buttons with no text of their own. */
+    tip?: string;
+    onClick?: (event: MouseEvent) => void;
+}
+declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrProps?: string | ElProps, ...children: Child[]): HTMLElementTagNameMap[K];
+/** A small square icon button (the move/delete controls list editors share).
+ *  Its rollover is the THEMED one (`data-tip`), so an app that has called
+ *  `initTooltips()` gets our bubble rather than the platform's.
+ *
+ *  `name` is a word from the vocabulary ("up", "close"), drawn at 14px. A
+ *  typed glyph from the deprecated `icon` table ("↑", "✕") is accepted for
+ *  now and drawn as the word it stood for, so an app that has not moved its
+ *  call sites yet still gets the drawn set; any other string is set as text,
+ *  which is the old behaviour and on its way out. */
+declare function iconBtn(name: IconName | (string & {}), title: string, onClick: () => void, disabled?: boolean, danger?: boolean): HTMLButtonElement;
+/**
+ * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
+ *
+ * The label is pointed at the field it captions, EXPLICITLY, and never at a button. A `<label>` with no
+ * `for` forwards a click to its first labelable descendant, and buttons are labelable - so a caption
+ * wrapped around a control containing buttons (`tagChips`, whose every chip carries a remove button)
+ * turns every click on the row's dead space into a press of the FIRST button in it. That shipped:
+ * patterkit/patter#44, where clicking a Game Data list value anywhere but its ✕ deleted the first value
+ * in the list. Reported as "clicking a value removes the wrong one", which is not a wrong-index bug at
+ * all - the click never reached the chip.
+ *
+ * When the control holds no labelable field (a chips editor with the add input removed, say), this is a
+ * plain `<div>`: no caption behaviour is better than a caption that presses something.
+ */
+declare function labelled(label: string, control: HTMLElement): HTMLElement;
+/** Swap item `i` with its neighbour `i + delta` IN PLACE (the up/down reorder list editors share);
+ *  a no-op when the target is out of range. Returns whether anything moved. */
+declare function moveItem<T>(arr: T[], i: number, delta: number): boolean;
+/** A tag-style editor for a string-list field (an enum's allowed values / flags): removable chips + an
+ *  add input (Enter or "," commits; blank / duplicate ignored). Mutates `holder.values` in place (read
+ *  back on save). `onChange` fires after any add / remove so callers can refresh a dependent control. */
+declare function tagChips(holder: {
+    values?: string[];
+}, onChange?: () => void): HTMLElement;
+/**
+ * An ORDERED chips editor for a string-list field whose order means something
+ * (a quality's stages: `advance()` walks them, so 2 comes after 1): numbered
+ * chips, each with move-earlier / move-later / remove, plus an add input
+ * (Enter or "," commits; blank / duplicate ignored). Mutates `holder.stages`
+ * in place; `onChange` fires after any add / move / remove.
+ *
+ * Patterpad's, lifted (ui-review-2026-09, finding 3); Storyletter had been
+ * faking it with `tagChips` over a `values` holder, which loses the order
+ * controls. Same class family as `tagChips` (`.shell-tags`), so it is styled by
+ * settings.css already.
+ */
+declare function stageChips(holder: {
+    stages?: string[];
+}, onChange?: () => void): HTMLElement;
+/**
+ * Make `el` a drag source and a drop target for HTML5 drag-to-reorder among
+ * its siblings. While carried it wears `.dragging`; a hovered target wears
+ * `.drop-before` or `.drop-after` by the midpoint test on `axis` ("y" for
+ * rows, "x" for a wrapping grid); a drop calls `onMove(draggedId, before,
+ * targetId)` and the caller reorders its model and re-renders.
+ *
+ * Storyletter's `wireCardDrag`, lifted (ui-review-2026-09, finding 30);
+ * Patterpad's `wireSceneDrag` is the same idea fixed on "y". The marks are
+ * classes only: the app draws them (Patterpad's `box-shadow: 0 -2px 0 0
+ * var(--accent)` pair is the family's look).
+ */
+declare function wireReorder(el: HTMLElement, id: string, axis: "x" | "y", onMove: (id: string, before: boolean, targetId: string) => void): void;
+/**
+ * A metadata line: `parts` as spans in a flex row, separated by a drawn
+ * 3px disc (a `::before` on every part after the first, in controls.css),
+ * so `metaLine(["6 runs", "200 max steps", "seed 4"])` is what
+ * "6 runs · 200 max steps · seed 4" used to be, without the typed dot.
+ * Empty, null and undefined parts are skipped, so a caller can pass an
+ * optional segment without branching.
+ */
+declare function metaLine(parts: (string | Node | null | undefined)[]): HTMLElement;
+interface Crumb {
+    label: string;
+    /** Makes the crumb a button. Ignored on the last crumb, which is where the
+     *  reader already is. */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * A breadcrumb trail: each crumb a span, or a button when it carries
+ * `onClick` and is not the last, with `iconNode("forward", 12)` drawn between
+ * them. `breadcrumb(["Box", "Deck", "Card"])` is what "Box › Deck › Card"
+ * used to be; the chevrons are the family's own drawing, not a symbol-font
+ * character.
+ */
+declare function breadcrumb(parts: (string | Crumb)[]): HTMLElement;
+
+/** Curated colour slots; must match the `--char-*` set defined per theme. */
+declare const PALETTE_SIZE = 12;
+declare const PALETTE: readonly string[];
+/** Hash a name to a palette slot: FNV-1a + an fmix32 avalanche, well
+ *  distributed even for short, similar names. */
+declare function colourIndex(name: string): number;
+/** The theme-aware CSS variable reference for a name's slot. */
+declare function colourFor(name: string): string;
 
 type PaneSide = "nav" | "inspector";
 interface PaneSideConfig {
@@ -148,7 +301,10 @@ interface PaneSideConfig {
     resizable?: boolean;
     /** Noun for the toggle's tooltip/aria, e.g. "navigator" / "inspector". */
     label?: string;
-    /** Shortcut hint appended to the tooltip, e.g. "Cmd+1". */
+    /** The key that toggles the pane, bracketed after the tooltip. A combo in
+     *  the portable spelling ("Mod+1") is drawn for the platform through
+     *  `tipWithKey`: "(⌘1)" on a Mac, "(Ctrl+1)" elsewhere. Anything else is a
+     *  literal and goes in verbatim, as it always has ("Cmd+1" stays "Cmd+1"). */
     shortcutHint?: string;
     /** false = the pane is not offered at all: no toggle, togglePane ignored,
      *  forced closed whatever the remembered state says. For a slot a host has
@@ -168,6 +324,18 @@ interface PaneShellOptions {
     initial?: Partial<PaneShellState>;
     /** Persist state after any toggle or resize (host wires it to its store). */
     onChange?: (state: PaneShellState) => void;
+    /** The toggle's rollover for a side in a given state. Default: "Show
+     *  navigator" / "Hide navigator" from the side's `label`, with the
+     *  `shortcutHint` in brackets (platform-true when it is a combo). Written as
+     *  `data-tip` (the themed tooltip) and as the accessible name; never as
+     *  `title`. */
+    tipFor?: (side: PaneSide, open: boolean) => string;
+    /** An extra class per side, toggled on the `.panes` grid whenever that side
+     *  is collapsed, beside the shell's own `no-nav` / `no-inspector`. For an
+     *  app whose stylesheet already keys on its own name for the state
+     *  (Patterpad's `props-doc-open`), so its rules ride the shell's collapse
+     *  rather than a second copy of it. */
+    collapseAlso?: Partial<Record<PaneSide, string>>;
 }
 interface PaneShell {
     /** The frame element (top bar + panes); mount it into the app container. */
@@ -182,7 +350,13 @@ interface PaneShell {
     readonly inspector: HTMLElement;
     togglePane(side: PaneSide): void;
     setPaneOpen(side: PaneSide, open: boolean): void;
+    /** Whether the pane is showing: open, and not held closed. */
     isOpen(side: PaneSide): boolean;
+    /** Fold a side away WITHOUT changing what the person chose: a mode that has
+     *  no use for the inspector (Patterpad's properties page) holds it closed,
+     *  and releasing the hold restores whatever was remembered. Not persisted;
+     *  the toggle keeps reporting the remembered state. */
+    holdClosed(side: PaneSide, held: boolean): void;
     /** Clear dragged widths back to the config defaults. */
     resetWidths(): void;
     /** A snapshot of the current state (open + widths). */
@@ -191,78 +365,6 @@ interface PaneShell {
 }
 declare function mountPaneShell(host: HTMLElement, opts: PaneShellOptions): PaneShell;
 
-/** A compact list row: a single `.set-rowline` (inline controls) plus, when
- *  `details` are given, a disclosure that reveals a `.set-details` panel below,
- *  so a list scans like a table with secondary fields tucked away. `name` is
- *  what the row declares (a property's name, a field's), stamped on it as
- *  `data-name` so `revealRow` can land on it. */
-declare function expandableRow(opts: {
-    line: HTMLElement[];
-    details?: HTMLElement[];
-    name?: string;
-}): HTMLElement;
-/**
- * Land on one row of a list by the `name` it was built with: open its details
- * (an enum's values sit behind the disclosure, and they are usually what the
- * jump was for), bring it to the middle of its scroller, and light it for a
- * moment (`.set-row.landed` in settings.css). "Go to definition" in both apps
- * used to open the page a property is declared on and stop there, with the
- * declaration below the fold and nothing marking it (Storyletter, 2026-09-14).
- *
- * Returns false when no row carries the name, so a host whose page fills in
- * asynchronously can ask again on a later frame; asking again is the host's,
- * since only the host knows what opens on its own time. The row is matched by
- * reading the stamp rather than by an attribute selector, so a name needs no
- * escaping.
- */
-declare function revealRow(within: ParentNode, name: string): boolean;
-/** After a "+ Add" re-renders a list, bring the new (last) row into view and
- *  focus its name input (`.set-name`, else the first input). */
-declare function focusNewRow(listEl: HTMLElement | null | undefined): void;
-interface DupGuard {
-    /** Forget the previous render's inputs (call at the top of render). */
-    reset(): void;
-    /** Register a name input; `key` returns the comparison string (default the
-     *  input's value). Re-checks live on input. `also` = extra inputs that change the key. */
-    track(input: HTMLInputElement, key?: () => string, also?: HTMLInputElement[]): void;
-    /** Re-paint duplicates; true if any two non-blank keys collide. */
-    check(): boolean;
-    /** The first input currently flagged (after a fresh check), or null. */
-    firstDuplicate(): HTMLInputElement | null;
-}
-/** Case-insensitive duplicate-name detection: paints clashing inputs `.invalid`
- *  and lets a Save gate block + jump via `firstDuplicate()`. */
-declare function dupGuard(): DupGuard;
-interface SettingsSectionHandle {
-    /** The first invalid control to jump to, blocking Save (e.g. a duplicate name). */
-    firstInvalid?(): HTMLElement | null;
-}
-interface SettingsSection {
-    id: string;
-    label: string;
-    /** Optional left-rail group heading above this tab. */
-    group?: string;
-    /** Build the section body into `host`; called fresh on each open so it reads
-     *  the current data. Return a handle (for the Save gate). */
-    mount(host: HTMLElement): SettingsSectionHandle;
-}
-interface SettingsDialogOptions {
-    title: string;
-    sections: SettingsSection[];
-    /** Fired when Save is clicked and every section validates. The app reads its
-     *  own section state and persists. May be async; the dialog stays open until
-     *  it resolves, then closes. */
-    onSave: () => void | Promise<void>;
-}
-interface SettingsDialog {
-    /** Open (optionally on a given tab id). Sections re-mount from current data. */
-    open(tabId?: string): void;
-    destroy(): void;
-}
-/** Build a settings dialog. The frame owns the modal, the tab rail, save-on-Save
- *  (with a validation gate), and Cancel; the sections own their content + state. */
-declare function mountSettingsDialog(opts: SettingsDialogOptions): SettingsDialog;
-
 interface PinButtonOptions {
     pinned: boolean;
     /** Persist the choice. The button reflects the click itself. */
@@ -284,11 +386,93 @@ interface PinButton {
 /** The always-on-top pin: `.swin-pin`, aria-pressed, and a tooltip that says
  *  what a click will do (the richest of the family's variants, kept). */
 declare function pinButton(opts: PinButtonOptions): PinButton;
+interface ToolWindowHeadOptions {
+    /** The window's own name. Constant: it says which window this is, so it must
+     *  not change as projects open and close. Omitted by a window whose mode
+     *  tabs stand where the title would be (Find): pass them as `tabs`. */
+    title?: string;
+    /** Mode tabs in the title's place (Find's bar: modes left, pin and close right). */
+    tabs?: HTMLElement;
+    /** A pin BUILT ALREADY, for a window that mounts its chrome once and drives
+     *  the button with `pin.set(on)` rather than rebuilding the bar. That is the
+     *  better shape (no re-entrancy question, survives a partial repaint), so the
+     *  helper takes either. */
+    pin?: {
+        el: HTMLElement;
+    };
+    pinned?: boolean;
+    onPin?: (on: boolean) => void;
+    onClose: () => void;
+    /** Between the title and the spacer: a subtitle, the project name. */
+    lead?: (Node | string | null)[];
+    /** Between the spacer and the pin: this window's own controls. */
+    trail?: (Node | string | null)[];
+    /** An extra class beside `swin-head`, for a window that styles its own bar. */
+    className?: string;
+    /**
+     * Escape closes the window (default true): the family's rule, written once
+     * here rather than per window.
+     *
+     * The listener stands aside on its own for a field's Escape (an input,
+     * textarea, select or contenteditable target: clearing, cancelling an edit)
+     * and for an Escape a deeper handler has already `preventDefault()`ed.
+     * `"always"` drops the first of those: a window whose focus LIVES in a
+     * field (Find, whose query box is where the typing is) still closes on
+     * Escape from it. `false` turns the listener off for a window that owns
+     * Escape entirely; it calls `onClose` itself when nothing smaller is left.
+     */
+    esc?: boolean | "always";
+    /**
+     * A window that layers Escape (a selection to clear, a pending outcome to
+     * drop, a sweep that must not be closed out from under) says so here:
+     * return true when the key was consumed and the window stays open, false
+     * to let it close. Innermost first; the window is last.
+     */
+    onEscape?: () => boolean;
+}
+/** The `.swin-head` bar every tool window wears: title (or tabs), lead, spacer,
+ *  trail, pin, close. The close button says "Close (Esc)" once, here, rather
+ *  than in every window. */
+declare function toolWindowHead(opts: ToolWindowHeadOptions): HTMLElement;
+interface FollowButtonOptions {
+    on: boolean;
+    /** Persist the choice. The button reflects the click itself. */
+    onToggle: (on: boolean) => void;
+    /** What the editor opens as the run goes: "line" (Patterpad), "card"
+     *  (Storyletter). Default "line". */
+    what?: string;
+}
+/** A toggle and the handle to drive it, the same shape `pinButton` returns. */
+interface FollowButton {
+    el: HTMLButtonElement;
+    /** Reflect a state decided elsewhere, without calling `onToggle`. */
+    set: (on: boolean) => void;
+}
+/**
+ * "Follow in the editor": the play surface's toggle that makes the EDITOR
+ * follow the run, opening each line / card as it plays. Both play surfaces
+ * built one (patterpad play.ts, studio table.ts) with the same label and
+ * paraphrased tips; this is the one wording.
+ *
+ * The LABEL is the careful part. "Follow" alone would match the vocabulary of
+ * a window that follows the editor; this is the other direction, the editor
+ * following the run. Off by default and remembered by the host: following is
+ * the author asking for it.
+ */
+declare function followButton(opts: FollowButtonOptions): FollowButton;
 
 interface ConfirmOptions {
     title: string;
-    body: string;
-    /** The destructive button's label ("Delete box", "Restart"). */
+    /** One plain sentence, ending with what undo does. */
+    body?: string;
+    /**
+     * Content that is evidence rather than a sentence: a list of the scenes that
+     * refer to the thing, a warning line. Rendered after `body` when both are
+     * given. The caller styles it; the frame's body is a column with a gap.
+     */
+    bodyNode?: HTMLElement;
+    /** The destructive button's label, which names its object ("Delete scene",
+     *  "Remove language"). */
     confirmLabel: string;
 }
 /** Resolves true on confirm; false on Cancel / Esc / backdrop. */
@@ -353,6 +537,11 @@ interface AnchoredPanelOptions {
     ignoreDown?: string;
     /** While something matching this exists, Escape belongs to it, not to us. */
     deferEscape?: string;
+    /** Where the panel is appended. Default <body>. A panel opened from inside a
+     *  modal <dialog> passes the dialog: a body-level node sits behind the scrim,
+     *  inert, while one inside the dialog paints in its top layer. Placement is
+     *  viewport-relative either way (`position: fixed`). */
+    host?: HTMLElement;
     onClose?: () => void;
 }
 declare function openAnchoredPanel(opts: AnchoredPanelOptions): AnchoredPanel | null;
@@ -381,7 +570,7 @@ declare function isValidGameId(gameId: string): boolean;
  *  app probes the real parser to prove the list is still true. */
 declare const RESERVED_PROPERTY_NAMES: readonly string[];
 /** What an editor should tell an author, in one line. */
-declare const PROPERTY_NAME_HINT = "Lower case letters, digits and underscores. Cannot start with a digit. No hyphens or spaces.";
+declare const PROPERTY_NAME_HINT = "Lower case letters, digits, and underscores. It can't start with a digit. No hyphens or spaces.";
 /**
  * Coerce a label into a legal property name: lower case, apostrophes dropped,
  * runs of anything else to a single underscore, no trailing underscore, an
@@ -523,14 +712,20 @@ type VcMap = ReadonlyMap<string, ShardVc>;
  *  box + tags + hands shards), most actionable winning: any holder locks it,
  *  any stale shard makes it stale, any read-only shard makes it read-only. */
 declare function foldVc(shards: VcMap, keys: string | undefined): ShardVc | undefined;
-/** The one badge an item flies, by priority, or null when there is nothing to
- *  say. Monochrome typographic glyphs (never colour emoji), so each inherits
- *  its themed colour and reads the same in Linen and Baize. */
-declare function vcBadgeFor(s: ShardVc | undefined): {
+/** What a row flies: the word to draw (`name`), the class that colours it,
+ *  and the rollover. `glyph` is the deprecated typed character for a caller
+ *  still setting text; it goes when `icon` does. */
+interface VcBadge {
+    name: IconName;
+    /** @deprecated Draw `name` with `iconNode` instead. */
     glyph: string;
     cls: string;
     title: string;
-} | null;
+}
+/** The one badge an item flies, by priority, or null when there is nothing to
+ *  say. Drawn monochrome (never colour emoji), so each inherits its themed
+ *  colour and reads the same in Linen and Baize. */
+declare function vcBadgeFor(s: ShardVc | undefined): VcBadge | null;
 /** Repaint the badge on every item under `root` that names a shard (its
  *  `data-vc`). In place: no re-render, so nothing loses focus or scroll. */
 declare function paintVcBadges(root: ParentNode, shards: VcMap): void;
@@ -550,6 +745,21 @@ interface IdentityOptions {
     current?: Identity;
     /** A name to offer when there is none: the VCS's, one day. */
     suggested?: Identity;
+    /**
+     * `"welcome"` is the first run ("Welcome to <appName>", Continue); `"edit"`
+     * is the menu item ("User information", Save). Absent, the title is the
+     * shell's "Who is working here?" and the button is Save.
+     */
+    mode?: "welcome" | "edit";
+    /** Names the app in the welcome title. Without it the title is "Welcome". */
+    appName?: string;
+    /**
+     * By default a skip resolves `undefined` and the app asks again next launch.
+     * With this on, a skip resolves `{ name: "" }`: the app stores the blank and
+     * never asks again (Patterpad's first run, where main fills in a default).
+     * A Save with an empty name counts as a skip either way.
+     */
+    neverAskAgainOnSkip?: boolean;
 }
 /** Ask, and record the answer. Resolves when the dialog closes, either way. */
 declare function askIdentity(opts?: IdentityOptions): Promise<Identity | undefined>;
@@ -651,23 +861,42 @@ interface CommentsOptions {
 }
 declare function openComments(opts: CommentsOptions): void;
 
+/** Per-run overrides for a strip that serves several kinds of job (the main
+ *  window's: a countable export beside an uncountable pull). Each begin()
+ *  starts from the mount options and applies these on top. */
+interface JobBeginOptions {
+    /** Pin the band regardless of what the job reports. */
+    indeterminate?: boolean;
+    /** Show Cancel for this run. */
+    cancellable?: boolean;
+}
 interface JobProgressView {
     /** The strip; mount it where the job belongs. */
     readonly element: HTMLElement;
     /** Show the strip, reset to zero, and (optionally) name what is running. */
-    begin(label?: string): void;
-    /** Feed it a progress message from the main-side host. */
+    begin(label?: string, run?: JobBeginOptions): void;
+    /** Feed it a progress message from the main-side host. A `total` of 0
+     *  (the host's "no idea yet") draws the indeterminate band; the first
+     *  positive total flips the strip to the determinate bar. */
     update(done: number, total: number, elapsedMs: number): void;
     /** Hide the strip (the job finished, failed, or was cancelled). */
     end(): void;
     readonly visible: boolean;
+    /** True while the strip is drawing the band rather than the bar. */
+    readonly indeterminate: boolean;
 }
 interface JobProgressOptions {
     /** Called when Cancel is clicked. The button disables itself and says so;
-     *  the job stops at its next yield, and the host then calls end(). */
-    onCancel: () => void;
+     *  the job stops at its next yield, and the host then calls end(). Omit it
+     *  for a strip whose jobs cannot be stopped: Cancel is then not drawn. */
+    onCancel?: () => void;
     /** The word for the units, for the count readout (default "runs"). */
     units?: string;
+    /** Always draw the band and never the count, whatever the job reports.
+     *  Default: follow the data (band until a total arrives). */
+    indeterminate?: boolean;
+    /** Draw Cancel. Default: only when `onCancel` was given. */
+    cancellable?: boolean;
 }
 declare function mountJobProgress(host: HTMLElement, opts: JobProgressOptions): JobProgressView;
 
@@ -831,8 +1060,12 @@ interface StepperItem {
     /** An extra class on the kind chip, so an app can colour its own kinds
      *  (Storyletter's `sev-error`, and `done` for a resolved thread). */
     kindClass?: string;
-    /** Where it is, in the app's own address. Set in the mono face. */
-    where?: string;
+    /** Where it is. A string is the app's own address, set in the mono face; a
+     *  Node is a made element, a `breadcrumb(["Box", "Deck", "Card"])` say,
+     *  drawn as it is. Give the bar plain crumbs: the whole entry is already
+     *  the button that goes there, so a crumb with its own click has nowhere
+     *  else to take you. */
+    where?: string | Node;
     /** The entry itself, in one line. Overflow is clipped, not wrapped: the bar
      *  is one row high and stays that way however long the sentence is. */
     text: string;
@@ -918,4 +1151,4 @@ declare function historyNav(onBack: () => void, onForward: () => void): {
     set(canBack: boolean, canForward: boolean): void;
 };
 
-export { type AboutOptions, type AnchoredPanel, type AnchoredPanelOptions, type Child, type Comment, type CommentMessage, type CommentsOptions, type ConfirmOptions, type DocLine, type DupGuard, type ElProps, type GameIdEditorOptions, type IconName, type IconSvgName, type Identity, type IdentityOptions, type JobProgressOptions, type JobProgressView, type NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, type SaveController, type SaveControllerOptions, type SaveIndicator, type SaveStatus, type SettingsDialog, type SettingsDialogOptions, type SettingsSection, type SettingsSectionHandle, type ShardVc, type StaleBarOptions, type StepperBarOptions, type StepperItem, type StepperTone, type TipRect, type ToastKind, type ToastOptions, type TooltipOptions, type VcMap, askIdentity, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dismissToast, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, revealRow, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, toast, vcBadgeFor };
+export { type AboutOptions, type AnchoredPanel, type AnchoredPanelOptions, type Child, type Comment, type CommentMessage, type CommentsOptions, type ConfirmOptions, type Crumb, type DocLine, type ElProps, type FollowButton, type FollowButtonOptions, type GameIdEditorOptions, ICON_NAMES, ICON_SIZE, type IconName, type IconSvgName, type Identity, type IdentityOptions, type JobBeginOptions, type JobProgressOptions, type JobProgressView, type NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, type SaveController, type SaveControllerOptions, type SaveIndicator, type SaveStatus, type ShardVc, type StaleBarOptions, type StepperBarOptions, type StepperItem, type StepperTone, type TipRect, type ToastKind, type ToastOptions, type ToolWindowHeadOptions, type TooltipOptions, type VcBadge, type VcMap, askIdentity, bindPropertyName, bindPropertyRef, breadcrumb, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dismissToast, el, firstIllegalPropertyName, foldVc, followButton, gameIdify, hideTip, historyNav, icon, iconBtn, iconHtml, iconNameOfGlyph, iconNode, iconSvg, initTooltips, isCaseOnlyPropertyName, isIconName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, metaLine, mountJobProgress, mountPaneShell, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, saveIndicator, showAbout, stageChips, staleBar, tagChips, tipAt, tipBold, toast, toolWindowHead, vcBadgeFor, wireReorder };