@wildwinter/app-shell 0.46.5 → 0.48.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { EDIT_MENU, FILE_MENU, GO_MENU, MenuLabel, PANE_MENU, PLAY_MENU, PUBLISH_MENU, REVIEW_MENU, VIEW_MENU } from './menu.cjs';
 export { HintBarItem, KeyHintOptions, KeyPlatform, hintBar, isKeyCombo, keyHint, keyLabel, keyLegends, keyPlatform, setKeyPlatform, tipWithKey } from './keys.cjs';
 export { ProblemCopy, ProblemCopyEntry, ProblemCopyTable, ProblemLike, defaultProblemCopy, describeProblem, problemLine, problemName } from './problems.cjs';
-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.cjs';
+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-BgZlkcbz.cjs';
 export { DialogFrame, DialogFrameOptions, dialogFrame } from './dialog.cjs';
 export { Floating, FloatingOptions, createFloating } from './floating.cjs';
 export { ContextItem, PopoverOptions, openContextMenu, openPopover } from './context-menu.cjs';
@@ -87,7 +87,9 @@ declare const icon: {
 };
 /**
  * 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.
+ * 2026-09 review found the apps drawing by hand with nothing to check against,
+ * and the two the 2026-10 Patterpad review found the same way (`copy`,
+ * `speaker`).
  */
 type IconName = keyof typeof icon
 /** History back, the topbar's quiet arrow pair (nav-history.ts). An ARROW,
@@ -107,7 +109,13 @@ type IconName = keyof typeof icon
  | "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";
+ | "record"
+/** Copy this to the clipboard. The confirmation is `tick`, shown by the
+ *  caller while `copyWithFeedback` holds `.copied` on the button. */
+ | "copy"
+/** Sound: play with audio, a table read. The act of hearing, not a volume
+ *  control. */
+ | "speaker";
 /**
  * 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.
@@ -128,6 +136,7 @@ declare const iconSvg: {
     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 copy: string;
     readonly play: string;
     readonly more: string;
     readonly collapsed: string;
@@ -159,6 +168,7 @@ declare const iconSvg: {
     readonly pin: string;
     readonly settings: string;
     readonly record: string;
+    readonly speaker: string;
 };
 type IconSvgName = keyof typeof iconSvg;
 /** Every word, in table order, for a test or a gallery to walk. */
@@ -205,8 +215,13 @@ declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrPr
  *  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;
+/** The sentence under a settings row: plain text, or nodes when it carries
+ *  markup (a `code` for a file name, a `b` for an option's name). */
+type FieldHint = string | Node | Array<string | Node>;
 /**
- * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
+ * A captioned field, the family's settings row (the 2026-10 review, ruling C):
+ * the caption on the left and the control inline beside it,
+ * `<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
@@ -214,12 +229,44 @@ declare function iconBtn(name: IconName | (string & {}), title: string, onClick:
  * 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.
+ * all - the click never reached the chip. The same rule makes a control GROUP safe to caption: a field
+ * with its own Choose… or Import… button beside it (`.shell-inline`) captions the field, and the button
+ * stays a button.
  *
  * 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.
+ *
+ * With a `hint`, the row and the sentence under it come back together in a `.shell-field`, the hint as
+ * the field's description (`aria-describedby`) rather than inside the label, where it would become part
+ * of the field's NAME and be read out every time it takes focus. Without one, the row is exactly what it
+ * always was.
+ */
+declare function labelled(label: string, control: HTMLElement, hint?: FieldHint): HTMLElement;
+interface LabelledToggleOptions {
+    checked?: boolean;
+    /** The sentence under the row: what turning it on does. */
+    hint?: FieldHint;
+    /** An option that only means something while the row above it is set (Patterpad's "Embed source
+     *  language for debug" under an IDs-only build): indented under that row with a rule, so it reads as
+     *  belonging to it rather than as a peer. */
+    sub?: boolean;
+    disabled?: boolean;
+    /** Fired on every flip, with the new state. The input is handed back too, for a caller that reads it
+     *  on Save instead. */
+    onChange?: (checked: boolean) => void;
+}
+/**
+ * The settings toggle, `labelled`'s partner (ruling C): the caption on the left, the checkbox beside it
+ * where any other row has its control, and the optional hint under the row. One shape in both apps, so
+ * a switch in one app's settings looks like a switch in the other's. Clicking the caption flips it, as
+ * the label is the checkbox's.
+ *
+ * Returns the outermost row (to append, hide, or indent) and the input (to read or listen to).
  */
-declare function labelled(label: string, control: HTMLElement): HTMLElement;
+declare function labelledToggle(label: string, opts?: LabelledToggleOptions): {
+    row: HTMLElement;
+    input: HTMLInputElement;
+};
 /** 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;
@@ -229,12 +276,28 @@ declare function moveItem<T>(arr: T[], i: number, delta: number): boolean;
 declare function tagChips(holder: {
     values?: string[];
 }, onChange?: () => void): HTMLElement;
+/** What `stageChips` tells its caller beyond "something changed". */
+interface StageChipsOptions {
+    /**
+     * A stage was renamed in place, `from` to `to`. Given, a rename calls this
+     * INSTEAD of `onChange`: values are stored by stage name, so whoever knows
+     * where those values live has to carry them, and doing it as one edit is
+     * theirs to arrange. Absent, a rename is an ordinary change.
+     */
+    onRename?: (from: string, to: string) => void;
+    /** The stages were reordered (after `onChange`): the one edit that changes
+     *  what every ordering gate means without changing any value. */
+    onReorder?: () => void;
+}
 /**
  * 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.
+ * (Enter or "," commits; blank / duplicate ignored). A stage's name renames
+ * in place when clicked (Enter or blur commits, Escape cancels; blank, the same
+ * name or another stage's is ignored). Mutates `holder.stages` in place;
+ * `onChange` fires after any add / move / remove, and after a rename unless
+ * `opts.onRename` takes it.
  *
  * Patterpad's, lifted (ui-review-2026-09, finding 3); Storyletter had been
  * faking it with `tagChips` over a `values` holder, which loses the order
@@ -243,7 +306,7 @@ declare function tagChips(holder: {
  */
 declare function stageChips(holder: {
     stages?: string[];
-}, onChange?: () => void): HTMLElement;
+}, onChange?: () => void, opts?: StageChipsOptions): 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
@@ -775,7 +838,9 @@ interface DocLine {
  *  what stops a note being copied down and then disagreeing with itself. */
 interface Notes {
     own: DocLine[];
-    inherited: {
+    /** Outermost first. Absent or empty in an app whose own UI already shows
+     *  each ancestor's notes (Patterpad's stacked inspector). */
+    inherited?: {
         id: string;
         label: string;
         lines: DocLine[];
@@ -784,13 +849,25 @@ interface Notes {
     classes: string[];
 }
 interface NotesEditorOptions {
-    /** What this is about, for the dialog's title ("Notes: Arrive at the gate"). */
-    subject: string;
+    /** What this is about, for the dialog's title ("Notes: Arrive at the gate").
+     *  Absent, the title is "Notes". */
+    subject?: string;
+    /** One line under the title, for what the classes are FOR in this app
+     *  (Patterpad's "A VO note travels with the voice script…"): the dialog
+     *  frame's own sub line. */
+    sub?: string;
     notes: Notes;
+    /** Open on this class: its text area is shown even when empty, and the
+     *  caret is in it. Patterpad's "Needs re-record" asks why the line needs
+     *  another take, and the answer is a VO note, so it opens on "vo". Ignored
+     *  when the class is neither offered (`notes.classes`) nor already written
+     *  on, so a prompt cannot add a class the thing does not take. "" is the
+     *  editor-only bucket. */
+    focus?: string;
     /** Commit. Called once, on close, and only when something changed. */
     save: (lines: DocLine[]) => void;
 }
-/** Open the notes modal. Resolves when it closes. */
+/** Open the notes modal. Returns at once; `save` runs when it closes. */
 declare function openNotesEditor(opts: NotesEditorOptions): void;
 
 /** One message. The author is a NAME stamped at posting time, not a reference:
@@ -1135,6 +1212,12 @@ interface NavHistory<Place> {
      *  is validating the whole stack on every paint). */
     canBack(): boolean;
     canForward(): boolean;
+    /** Forget both sides, for when the places stop meaning anything: a
+     *  different project opened, or the welcome screen with none. Without it
+     *  Back walks into the project just closed (Patterpad, 2026-10-07: on the
+     *  welcome screen the arrows looked live and did nothing). The caller
+     *  re-`set`s its arrows afterwards, as after any other change. */
+    clear(): void;
 }
 declare function createNavHistory<Place>(opts: NavHistoryOptions<Place>): NavHistory<Place>;
 /**
@@ -1158,4 +1241,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 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 };
+export { type AboutOptions, type AnchoredPanel, type AnchoredPanelOptions, type Child, type Comment, type CommentMessage, type CommentsOptions, type ConfirmOptions, type Crumb, type DocLine, type ElProps, type FieldHint, 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 LabelledToggleOptions, 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 StageChipsOptions, 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, labelledToggle, 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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { 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-BgZlkcbz.js';
 export { DialogFrame, DialogFrameOptions, dialogFrame } from './dialog.js';
 export { Floating, FloatingOptions, createFloating } from './floating.js';
 export { ContextItem, PopoverOptions, openContextMenu, openPopover } from './context-menu.js';
@@ -87,7 +87,9 @@ declare const icon: {
 };
 /**
  * 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.
+ * 2026-09 review found the apps drawing by hand with nothing to check against,
+ * and the two the 2026-10 Patterpad review found the same way (`copy`,
+ * `speaker`).
  */
 type IconName = keyof typeof icon
 /** History back, the topbar's quiet arrow pair (nav-history.ts). An ARROW,
@@ -107,7 +109,13 @@ type IconName = keyof typeof icon
  | "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";
+ | "record"
+/** Copy this to the clipboard. The confirmation is `tick`, shown by the
+ *  caller while `copyWithFeedback` holds `.copied` on the button. */
+ | "copy"
+/** Sound: play with audio, a table read. The act of hearing, not a volume
+ *  control. */
+ | "speaker";
 /**
  * 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.
@@ -128,6 +136,7 @@ declare const iconSvg: {
     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 copy: string;
     readonly play: string;
     readonly more: string;
     readonly collapsed: string;
@@ -159,6 +168,7 @@ declare const iconSvg: {
     readonly pin: string;
     readonly settings: string;
     readonly record: string;
+    readonly speaker: string;
 };
 type IconSvgName = keyof typeof iconSvg;
 /** Every word, in table order, for a test or a gallery to walk. */
@@ -205,8 +215,13 @@ declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrPr
  *  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;
+/** The sentence under a settings row: plain text, or nodes when it carries
+ *  markup (a `code` for a file name, a `b` for an option's name). */
+type FieldHint = string | Node | Array<string | Node>;
 /**
- * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
+ * A captioned field, the family's settings row (the 2026-10 review, ruling C):
+ * the caption on the left and the control inline beside it,
+ * `<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
@@ -214,12 +229,44 @@ declare function iconBtn(name: IconName | (string & {}), title: string, onClick:
  * 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.
+ * all - the click never reached the chip. The same rule makes a control GROUP safe to caption: a field
+ * with its own Choose… or Import… button beside it (`.shell-inline`) captions the field, and the button
+ * stays a button.
  *
  * 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.
+ *
+ * With a `hint`, the row and the sentence under it come back together in a `.shell-field`, the hint as
+ * the field's description (`aria-describedby`) rather than inside the label, where it would become part
+ * of the field's NAME and be read out every time it takes focus. Without one, the row is exactly what it
+ * always was.
+ */
+declare function labelled(label: string, control: HTMLElement, hint?: FieldHint): HTMLElement;
+interface LabelledToggleOptions {
+    checked?: boolean;
+    /** The sentence under the row: what turning it on does. */
+    hint?: FieldHint;
+    /** An option that only means something while the row above it is set (Patterpad's "Embed source
+     *  language for debug" under an IDs-only build): indented under that row with a rule, so it reads as
+     *  belonging to it rather than as a peer. */
+    sub?: boolean;
+    disabled?: boolean;
+    /** Fired on every flip, with the new state. The input is handed back too, for a caller that reads it
+     *  on Save instead. */
+    onChange?: (checked: boolean) => void;
+}
+/**
+ * The settings toggle, `labelled`'s partner (ruling C): the caption on the left, the checkbox beside it
+ * where any other row has its control, and the optional hint under the row. One shape in both apps, so
+ * a switch in one app's settings looks like a switch in the other's. Clicking the caption flips it, as
+ * the label is the checkbox's.
+ *
+ * Returns the outermost row (to append, hide, or indent) and the input (to read or listen to).
  */
-declare function labelled(label: string, control: HTMLElement): HTMLElement;
+declare function labelledToggle(label: string, opts?: LabelledToggleOptions): {
+    row: HTMLElement;
+    input: HTMLInputElement;
+};
 /** 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;
@@ -229,12 +276,28 @@ declare function moveItem<T>(arr: T[], i: number, delta: number): boolean;
 declare function tagChips(holder: {
     values?: string[];
 }, onChange?: () => void): HTMLElement;
+/** What `stageChips` tells its caller beyond "something changed". */
+interface StageChipsOptions {
+    /**
+     * A stage was renamed in place, `from` to `to`. Given, a rename calls this
+     * INSTEAD of `onChange`: values are stored by stage name, so whoever knows
+     * where those values live has to carry them, and doing it as one edit is
+     * theirs to arrange. Absent, a rename is an ordinary change.
+     */
+    onRename?: (from: string, to: string) => void;
+    /** The stages were reordered (after `onChange`): the one edit that changes
+     *  what every ordering gate means without changing any value. */
+    onReorder?: () => void;
+}
 /**
  * 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.
+ * (Enter or "," commits; blank / duplicate ignored). A stage's name renames
+ * in place when clicked (Enter or blur commits, Escape cancels; blank, the same
+ * name or another stage's is ignored). Mutates `holder.stages` in place;
+ * `onChange` fires after any add / move / remove, and after a rename unless
+ * `opts.onRename` takes it.
  *
  * Patterpad's, lifted (ui-review-2026-09, finding 3); Storyletter had been
  * faking it with `tagChips` over a `values` holder, which loses the order
@@ -243,7 +306,7 @@ declare function tagChips(holder: {
  */
 declare function stageChips(holder: {
     stages?: string[];
-}, onChange?: () => void): HTMLElement;
+}, onChange?: () => void, opts?: StageChipsOptions): 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
@@ -775,7 +838,9 @@ interface DocLine {
  *  what stops a note being copied down and then disagreeing with itself. */
 interface Notes {
     own: DocLine[];
-    inherited: {
+    /** Outermost first. Absent or empty in an app whose own UI already shows
+     *  each ancestor's notes (Patterpad's stacked inspector). */
+    inherited?: {
         id: string;
         label: string;
         lines: DocLine[];
@@ -784,13 +849,25 @@ interface Notes {
     classes: string[];
 }
 interface NotesEditorOptions {
-    /** What this is about, for the dialog's title ("Notes: Arrive at the gate"). */
-    subject: string;
+    /** What this is about, for the dialog's title ("Notes: Arrive at the gate").
+     *  Absent, the title is "Notes". */
+    subject?: string;
+    /** One line under the title, for what the classes are FOR in this app
+     *  (Patterpad's "A VO note travels with the voice script…"): the dialog
+     *  frame's own sub line. */
+    sub?: string;
     notes: Notes;
+    /** Open on this class: its text area is shown even when empty, and the
+     *  caret is in it. Patterpad's "Needs re-record" asks why the line needs
+     *  another take, and the answer is a VO note, so it opens on "vo". Ignored
+     *  when the class is neither offered (`notes.classes`) nor already written
+     *  on, so a prompt cannot add a class the thing does not take. "" is the
+     *  editor-only bucket. */
+    focus?: string;
     /** Commit. Called once, on close, and only when something changed. */
     save: (lines: DocLine[]) => void;
 }
-/** Open the notes modal. Resolves when it closes. */
+/** Open the notes modal. Returns at once; `save` runs when it closes. */
 declare function openNotesEditor(opts: NotesEditorOptions): void;
 
 /** One message. The author is a NAME stamped at posting time, not a reference:
@@ -1135,6 +1212,12 @@ interface NavHistory<Place> {
      *  is validating the whole stack on every paint). */
     canBack(): boolean;
     canForward(): boolean;
+    /** Forget both sides, for when the places stop meaning anything: a
+     *  different project opened, or the welcome screen with none. Without it
+     *  Back walks into the project just closed (Patterpad, 2026-10-07: on the
+     *  welcome screen the arrows looked live and did nothing). The caller
+     *  re-`set`s its arrows afterwards, as after any other change. */
+    clear(): void;
 }
 declare function createNavHistory<Place>(opts: NavHistoryOptions<Place>): NavHistory<Place>;
 /**
@@ -1158,4 +1241,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 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 };
+export { type AboutOptions, type AnchoredPanel, type AnchoredPanelOptions, type Child, type Comment, type CommentMessage, type CommentsOptions, type ConfirmOptions, type Crumb, type DocLine, type ElProps, type FieldHint, 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 LabelledToggleOptions, 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 StageChipsOptions, 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, labelledToggle, 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 };

package/dist/index.js

@@ -1,21 +1,21 @@
-export { mountWelcome } from './chunk-CUFREPJ5.js';
-export { feedUpdaterDownloadProgress, showUpdaterDialog } from './chunk-WKPKBAXS.js';
+export { mountWelcome } from './chunk-XSS7KM6F.js';
+export { feedUpdaterDownloadProgress, showUpdaterDialog } from './chunk-C245WRPF.js';
 export { defaultProblemCopy, describeProblem, problemLine, problemName } from './chunk-4OAORWEM.js';
-export { PROPERTY_NAME_HINT, PROPERTY_TYPES, RESERVED_PROPERTY_NAMES, bindPropertyName, bindPropertyRef, defaultControl, dupGuard, expandableRow, firstIllegalPropertyName, focusNewRow, isCaseOnlyPropertyName, isValidPropertyName, mountPropertyList, mountSettingsDialog, propertyNameProblem, propertyNameify, propertyRefProblem, revalidatePropertyRefs, revealRow, revealRowWhenReady } from './chunk-R3NXPHRZ.js';
+export { PROPERTY_NAME_HINT, PROPERTY_TYPES, RESERVED_PROPERTY_NAMES, bindPropertyName, bindPropertyRef, defaultControl, dupGuard, expandableRow, firstIllegalPropertyName, focusNewRow, isCaseOnlyPropertyName, isValidPropertyName, mountPropertyList, mountSettingsDialog, propertyNameProblem, propertyNameify, propertyRefProblem, revalidatePropertyRefs, revealRow, revealRowWhenReady } from './chunk-CRUILFAT.js';
 import { isKeyCombo, tipWithKey } from './chunk-YWMSQFXX.js';
 export { hintBar, isKeyCombo, keyHint, keyLabel, keyLegends, keyPlatform, setKeyPlatform, tipWithKey } from './chunk-YWMSQFXX.js';
-export { kitTile, openKitGallery } from './chunk-J6RSONXM.js';
-export { linkAddress, linkStatusClass, linkStatusTip, mountLinkStatus } from './chunk-B2TC6Q5J.js';
+export { kitTile, openKitGallery } from './chunk-62KWJPRP.js';
+export { linkAddress, linkStatusClass, linkStatusTip, mountLinkStatus } from './chunk-UQTUCOGV.js';
 import { isEditableTarget } from './chunk-QVACRWG7.js';
 export { copyWithFeedback, debounce, formatCount, isEditableTarget, isLocalOrigin, plural, relativeTime } from './chunk-QVACRWG7.js';
-export { EDIT_MENU, FILE_MENU, GO_MENU, PANE_MENU, PLAY_MENU, PUBLISH_MENU, REVIEW_MENU, VIEW_MENU } from './chunk-2ECJUTSX.js';
-import { dialogFrame } from './chunk-YRFJLJUH.js';
-export { dialogFrame } from './chunk-YRFJLJUH.js';
+export { EDIT_MENU, FILE_MENU, GO_MENU, PANE_MENU, PLAY_MENU, PUBLISH_MENU, REVIEW_MENU, VIEW_MENU } from './chunk-T25WXWPB.js';
+import { dialogFrame } from './chunk-VXEFIL43.js';
+export { dialogFrame } from './chunk-VXEFIL43.js';
 export { createFloating } from './chunk-PFERSFRB.js';
 export { JOB_PROGRESS } from './chunk-MDGOIT3O.js';
-export { openContextMenu, openPopover } from './chunk-EHR2KBZC.js';
-import { ensureTooltipHost, el, iconNode, labelled, icon } from './chunk-UG2P777F.js';
-export { ICON_NAMES, ICON_SIZE, breadcrumb, el, hideTip, icon, iconBtn, iconHtml, iconNameOfGlyph, iconNode, iconSvg, initTooltips, isIconName, labelled, metaLine, moveItem, stageChips, tagChips, tipAt, tipBold, wireReorder } from './chunk-UG2P777F.js';
+export { openContextMenu, openPopover } from './chunk-OMG6A5YB.js';
+import { ensureTooltipHost, el, iconNode, labelled, icon } from './chunk-W4WC4FO5.js';
+export { ICON_NAMES, ICON_SIZE, breadcrumb, el, hideTip, icon, iconBtn, iconHtml, iconNameOfGlyph, iconNode, iconSvg, initTooltips, isIconName, labelled, labelledToggle, metaLine, moveItem, stageChips, tagChips, tipAt, tipBold, wireReorder } from './chunk-W4WC4FO5.js';
 import { closeWithExit } from './chunk-IU7EY6BI.js';
 export { closeWithExit } from './chunk-IU7EY6BI.js';
 
@@ -640,16 +640,19 @@ var CLASS_LABEL = {
   everyone: "Everyone",
   writing: "Writing",
   vo: "Voice (VO)",
-  loc: "Localisers"
+  loc: "Localisers",
+  editor: "Editors"
 };
 var label = (cls) => cls === EDITOR_ONLY ? "Note (editor-only)" : CLASS_LABEL[cls] ?? cls[0].toUpperCase() + cls.slice(1);
 var PLACEHOLDER = {
   vo: "Direction for the voice actor or director",
-  loc: "Context for translators"
+  loc: "Context for translators",
+  editor: "Context for an outside editor"
 };
 var placeholder = (cls) => cls === EDITOR_ONLY ? "An internal note, never exported" : PLACEHOLDER[cls] ?? "Why this is here";
 function openNotesEditor(opts) {
   const { notes } = opts;
+  const inherited = notes.inherited ?? [];
   const seed = /* @__PURE__ */ new Map();
   for (const line of notes.own) {
     const key = line.type ?? EDITOR_ONLY;
@@ -657,6 +660,8 @@ function openNotesEditor(opts) {
 ${line.text}` : line.text);
   }
   const shown = [...seed.keys()];
+  const focus = opts.focus !== void 0 && (opts.focus === EDITOR_ONLY || notes.classes.includes(opts.focus) || seed.has(opts.focus)) ? opts.focus : void 0;
+  if (focus !== void 0 && !shown.includes(focus)) shown.push(focus);
   if (shown.length === 0) shown.push(notes.classes[0] ?? EDITOR_ONLY);
   const areas = /* @__PURE__ */ new Map();
   const value = () => {
@@ -674,13 +679,13 @@ ${line.text}` : line.text);
   const body = el("div", "shell-notes-body");
   const render = () => {
     body.replaceChildren();
-    if (notes.inherited.length > 0) {
+    if (inherited.length > 0) {
       const from = el(
         "div",
         { className: "shell-notes-inherited" },
         el("div", "shell-notes-caption", "Inherited")
       );
-      for (const level of notes.inherited) {
+      for (const level of inherited) {
         from.append(el(
           "div",
           { className: "shell-notes-level" },
@@ -737,7 +742,12 @@ ${line.text}` : line.text);
     const next = value();
     if (JSON.stringify(next) !== before) opts.save(next);
   };
-  const frame = dialogFrame({ title: `Notes: ${opts.subject}`, className: "shell-notes", onClose: commit });
+  const frame = dialogFrame({
+    title: opts.subject !== void 0 ? `Notes: ${opts.subject}` : "Notes",
+    ...opts.sub !== void 0 ? { sub: opts.sub } : {},
+    className: "shell-notes",
+    onClose: commit
+  });
   frame.body.append(body);
   frame.actions.append(done);
   done.addEventListener("click", () => {
@@ -745,7 +755,7 @@ ${line.text}` : line.text);
     frame.close();
   });
   frame.open();
-  areas.get(shown[0] ?? EDITOR_ONLY)?.focus();
+  areas.get(focus ?? shown[0] ?? EDITOR_ONLY)?.focus();
 }
 
 // src/comments.ts
@@ -1217,6 +1227,10 @@ function createNavHistory(opts) {
     },
     canForward() {
       return ahead.length > 0;
+    },
+    clear() {
+      past = [];
+      ahead = [];
     }
   };
 }