@embedpdf/core-ui 3.0.0-next.14 → 3.0.0-next.16

package/dist/index.d.cts

@@ -1,19 +1,21 @@
 //#region src/schema.d.ts
 /**
- * @embedpdf/core-ui — the structure-only schema vocabulary.
+ * @embedpdf/core-ui — the structure-only bar vocabulary.
  *
- * The schema contains ONLY what a designer decides and the runtime cannot
+ * A bar contains only what a designer decides and the runtime cannot
  * compute: order, grouping, importance, and each item's degradation ladder.
- * Everything the runtime CAN compute is banned from it by construction:
+ * Everything the runtime can compute is banned from it by construction:
  * no breakpoints, no show/hide lists, no locale overrides, no dividers, no
  * spacers, no hand-written overflow menus. Fit is measured and solved at
  * runtime (see solver.ts); the overflow menu is derived (see projection.ts).
+ * Where bars go, and the menus and panels around them, is the viewer's
+ * layout (see layout.ts).
  */
 /** Presentation ladder for a command button, richest first. */
 type Variant = 'icon+label' | 'icon' | 'label';
 /**
  * Who yields space first. 1 = first to degrade/overflow · 3 = default ·
- * 5 = pinned: may still degrade variants, but NEVER leaves the bar.
+ * 5 = pinned: may still degrade variants, but never leaves the bar.
  */
 type Importance = 1 | 2 | 3 | 4 | 5;
 declare const PINNED: Importance;
@@ -26,16 +28,17 @@ interface BarItem {
 }
 /**
  * An app-rendered slot (e.g. the inline zoom strip). Each named variant is
- * measured like any command button. The ladder MUST terminate in a command
- * (`terminal`) so the item always has a menu form when it overflows — this
- * is what makes the overflow projection total.
+ * measured like any command button. Its `terminal` command is its menu form,
+ * what it becomes when it overflows; an item without one never leaves the bar
+ * (it is pinned, and so is its group), which keeps the overflow projection
+ * total.
  */
 interface CustomItem {
   readonly slot: string;
   /** Named presentation variants, richest first. Default: ['default']. */
   readonly variants?: readonly string[];
   /** The command that stands in for this slot in menus (its last resort). */
-  readonly terminal: string;
+  readonly terminal?: string;
   readonly importance?: Importance;
 }
 type BarChild = BarItem | CustomItem | string;
@@ -46,22 +49,27 @@ interface BarGroup {
   /** Presentation hint: 'tabs' renders as a tab strip and projects as radio rows. */
   readonly role?: 'buttons' | 'tabs';
   /**
-   * Stage 1 of the GROUP degradation ladder: under pressure, move trailing
-   * children (rightmost first, at the CHILD's importance) into a derived
+   * Stage 1 of the group degradation ladder: under pressure, move trailing
+   * children (rightmost first, at the child's importance) into a derived
    * group-local disclosure — a trigger rendered inside the group opening a
    * menu of the hidden children. Never sheds the last visible child: below
-   * that floor the group `collapse`s (stage 2) or overflows whole. This is
-   * v2's `overflow-tabs-button`, computed instead of authored.
+   * that floor the group `collapse`s (stage 2) or overflows whole. The
+   * disclosure is computed, never authored.
    */
   readonly shed?: boolean;
   /**
-   * Stage 2: what the WHOLE group degrades to once its children have
+   * Stage 2: what the whole group degrades to once its children have
    * exhausted their ladders (and shedding, if enabled, has hit its floor): a
    * single menu button or a select-style picker. Groups with neither `shed`
    * nor `collapse` send children to the global overflow menu one by one.
    */
   readonly collapse?: 'menu' | 'select';
   readonly importance?: Importance;
+  /**
+   * Shows only while something that isn't dependent shows in the same bar, like undo and redo
+   * beside a mode's tools: a bar with only dependent groups left shows nothing.
+   */
+  readonly dependent?: boolean;
   readonly items: readonly BarChild[];
 }
 /**
@@ -69,11 +77,11 @@ interface BarGroup {
  * within a section — never across sections, never from schema data.
  *
  * The names are direction-aware (RTL flips start/end) and `center` is a
- * SOFT contract: "balance this segment in the space left over by start and
+ * soft contract: "balance this segment in the space left over by start and
  * end". With symmetric flanks that coincides with true centering; with a
  * heavy flank the segment drifts rather than fights — segments never
- * overlap, matching how every toolbar convention (including v2's
- * spacer-flanked tabs) treats its middle region. Strict geometric centering
+ * overlap, matching how every toolbar convention (including spacer-flanked
+ * tabs) treats its middle region. Strict geometric centering
  * would be a solver concern (a tighter budget: 2×max(start,end)+center),
  * deliberately not offered until a product needs it.
  */
@@ -86,57 +94,16 @@ interface BarSchema {
   readonly id: string;
   readonly sections: BarSections;
 }
-/** A run of command rows; separators derive between sections. */
-interface MenuSection {
-  /** Optional section heading (i18n key). */
-  readonly labelKey?: string;
-  readonly items: readonly string[];
-}
-interface MenuSchema {
-  readonly id: string;
-  readonly sections: readonly MenuSection[];
-}
-/**
- * The shell FRAME — region arrangement and visibility. Regions are a FIXED
- * vocabulary (each carries semantics the shell must own: the toolbar's
- * measurement physics, the document gate, aria landmarks); what's YOURS is
- * where they sit, whether they show, and — through the region slots — what
- * fills them. Part of the chrome value because it is structure: owned, never
- * merged. Free-form layout is deliberately not offered — wanting a different
- * frame architecture is what headless is for.
- */
-interface FrameSchema {
-  /** Where the main bar lives. Its mode band rides the CONTENT side (below a
-   *  top bar, above a bottom bar). Default: 'top'. */
-  readonly toolbar?: 'top' | 'bottom';
-  /** Document tab strip: 'multiple' shows it only with >1 tab. A hidden
-   *  region hides its SLOT too — visibility outranks slotted content.
-   *  Default: 'always'. */
-  readonly tabs?: 'always' | 'multiple' | 'never';
-  /** The header row — a socket only: the chrome ships no header of its own,
-   *  so it renders nothing until a `slot="header"` child fills it. `false`
-   *  removes the socket, keeping a slotted header out. Default: true. */
-  readonly header?: boolean;
-}
-interface ChromeSchema {
-  /** Standalone bars (e.g. the main toolbar). */
-  readonly bars: Readonly<Record<string, BarSchema>>;
-  /** Secondary bars keyed by tool mode — WHICH one shows is derived from the
-   *  interaction hub's active tool, never stored. */
-  readonly modeBars?: Readonly<Record<string, BarSchema>>;
-  /** Named dropdown menus referenced by commands' `menu:` targets. */
-  readonly menus?: Readonly<Record<string, MenuSchema>>;
-  /** Contextual strips (selection menus) — same BarSchema, same fit engine. */
-  readonly strips?: Readonly<Record<string, BarSchema>>;
-  /** Region arrangement & visibility. Omitted = the default frame. */
-  readonly frame?: FrameSchema;
-}
-declare function item(command: string, opts?: Omit<BarItem, 'command'>): BarItem;
-declare function custom(slot: string, opts: Omit<CustomItem, 'slot'>): CustomItem;
-declare function group(id: string, items: readonly BarChild[]): BarGroup;
-declare function group(id: string, opts: Omit<BarGroup, 'id' | 'items'> & {
-  items?: readonly BarChild[];
-}, items?: readonly BarChild[]): BarGroup;
+/** A command button: `item('zoom:in', { variants: ['icon+label', 'icon'] })`. */
+declare function item(command: string, options?: Omit<BarItem, 'command'>): BarItem;
+/**
+ * An item you draw yourself, by its slot name, and the command it becomes in the "More" menu:
+ * `custom('page-number', 'page:go-to', { variants: ['full', 'compact'] })`. Without a command,
+ * the item never leaves the bar.
+ */
+declare function custom(slot: string, terminal?: string, options?: Omit<CustomItem, 'slot' | 'terminal'>): CustomItem;
+/** A group of items, with a separator between groups: `group('zoom', ['zoom:out', 'zoom:in'])`. */
+declare function group(id: string, items: readonly BarChild[], options?: Omit<BarGroup, 'id' | 'items'>): BarGroup;
 type NormalizedUnit = {
   readonly kind: 'command';
   /** Unique within the bar: `${groupId}:${command}`. Measurement + assignment key. */
@@ -149,7 +116,11 @@ type NormalizedUnit = {
   readonly key: string;
   readonly slot: string;
   readonly variants: readonly string[];
-  readonly terminal: string;
+  /**
+   * The command it becomes in menus, or null for an item without one, which
+   * {@link filterBar} keeps, pinned.
+   */
+  readonly terminal: string | null;
   readonly importance: Importance;
 };
 interface NormalizedGroup {
@@ -159,6 +130,8 @@ interface NormalizedGroup {
   readonly shed: boolean;
   readonly collapse?: 'menu' | 'select';
   readonly importance: Importance;
+  /** See {@link BarGroup.dependent}; the rule is {@link hasVisibleUnits}. */
+  readonly dependent: boolean;
   readonly units: readonly NormalizedUnit[];
 }
 interface NormalizedSection {
@@ -170,76 +143,396 @@ interface NormalizedBar {
   readonly sections: readonly NormalizedSection[];
 }
 declare const DEFAULT_IMPORTANCE: Importance;
-/** Resolve shorthands + defaults; validate uniqueness. Solver/projection input. */
+/** Whether a unit is a custom item with no command to become in menus: it never leaves the bar. */
+declare const isStandaloneUnit: (unit: NormalizedUnit) => boolean;
+/** The command a unit runs: its own, or a custom item's `terminal`; null for a standalone item. */
+declare const commandOfUnit: (unit: NormalizedUnit) => string | null;
+/**
+ * Resolve shorthands + defaults; validate uniqueness. Solver/projection input.
+ * A group holding a custom item without a command is pinned with it: it never
+ * collapses or overflows whole, so the item stays in the bar.
+ */
 declare function normalizeBar(bar: BarSchema): NormalizedBar;
 /**
  * Drop units whose command is currently invisible (permissions, disabled
- * categories, contextual visibility) BEFORE solving — an invisible unit must
+ * categories, contextual visibility) before solving — an invisible unit must
  * not consume budget or appear in the overflow. Groups that empty out vanish
- * naturally in the solver's separator math and in the projection.
+ * naturally in the solver's separator math and in the projection. A custom
+ * item without a command has nothing to ask `keep` about, and stays. A bar
+ * that shows nothing ({@link hasVisibleUnits}) keeps no unit at all, so its
+ * dependent groups go too.
  */
 declare function filterBar(bar: NormalizedBar, keep: (unit: NormalizedUnit) => boolean): NormalizedBar;
 /**
- * Identity + validation. Checks what is checkable without a command registry:
- * bars normalize cleanly, and every `menu` a strip/bar could reference exists
- * is left to `validateChrome` (which also takes the known command ids).
+ * Whether the bar shows anything once `keep` (as for {@link filterBar}) has had its say: a unit
+ * left in a group that isn't dependent. Dependent groups show only beside one, so a bar with
+ * only dependent groups left shows nothing.
  */
-declare function defineChrome<T extends ChromeSchema>(chrome: T): T;
-/** Dev-time cross-check: every command referenced by the chrome exists. */
-declare function validateChrome(chrome: ChromeSchema, knownCommands: ReadonlySet<string>): string[];
+declare function hasVisibleUnits(bar: NormalizedBar, keep: (unit: NormalizedUnit) => boolean): boolean;
 //#endregion
-//#region src/transforms.d.ts
-interface AddItemSpec {
-  /** Bar id ('main', 'annotate', …) or a modeBars surface key ('mode:annotate'). */
-  readonly bar: string;
-  readonly section: keyof BarSections;
-  /** Target group id. Unknown in the bar → a new group is created at the end
-   *  of `section`; known but in a DIFFERENT section → error (group ids are
-   *  bar-unique, so that is a contradiction, not a request). */
-  readonly group: string;
-  readonly item: BarChild;
-  /** Insert position within the group. Default: append. */
-  readonly at?: number;
-}
-/** Insert `spec.item` into a group of one bar. See AddItemSpec for semantics. */
-declare function addItem(schema: ChromeSchema, spec: AddItemSpec): ChromeSchema;
-/**
- * Purge commands (or custom slots, by slot name) from every bar, mode bar,
- * strip, and menu. Groups and menu sections that empty out are dropped;
- * emptied menus keep their key (commands may still target them) with no rows.
- */
-declare function removeItems(schema: ChromeSchema, ids: readonly string[]): ChromeSchema;
-/**
- * Swap a command in place everywhere it appears — bars, mode bars, strips,
- * and (when the replacement is itself a plain command) menu rows.
- */
-declare function replaceItem(schema: ChromeSchema, id: string, item: BarChild): ChromeSchema;
-//#endregion
-//#region src/helpers.d.ts
-declare const chromeHelpers: {
-  readonly addItem: typeof addItem;
-  readonly removeItems: typeof removeItems;
-  readonly replaceItem: typeof replaceItem;
-  readonly item: typeof item;
-  readonly group: typeof group;
-  readonly custom: typeof custom;
-  readonly defineChrome: typeof defineChrome;
+//#region src/layout.d.ts
+/** An edge of the viewer. `start` and `end` follow the language: left and right, swapped in a right-to-left one. */
+type BarEdge = 'top' | 'bottom' | 'start' | 'end';
+/** Where a floating bar sits over the pages. */
+type FloatPosition = 'top-start' | 'top' | 'top-end' | 'start' | 'end' | 'bottom-start' | 'bottom' | 'bottom-end';
+/** What a bar over a selection follows: selected text, or selected annotations. */
+type SelectionTarget = 'selection' | 'annotation';
+/**
+ * Where a bar goes: along an edge, floating over the pages, along another bar on the side of the
+ * pages, or over what's selected. Bars on one edge stack from the outside in, in the order they
+ * were added; `before` and `after` put a bar next to another bar on that edge.
+ */
+type BarPlace = BarEdge | {
+  readonly edge: BarEdge;
+  readonly before?: string;
+  readonly after?: string;
+} | {
+  readonly float: FloatPosition;
+} | {
+  readonly with: string;
+} | {
+  readonly at: SelectionTarget;
 };
-type ChromeHelpers = typeof chromeHelpers;
+/** A command with options. */
+interface LayoutCommandItem {
+  readonly command: string;
+  /** How it may show, richest first. Default `['icon']`. */
+  readonly variants?: readonly Variant[];
+  /** Who makes room first: `1` to `5` (never leaves the bar). Default `3`. */
+  readonly importance?: Importance;
+}
+/** Your own component, by its id. `command` is what it becomes in the "More" menu; without one, it never leaves the bar. */
+interface LayoutCustomItem {
+  readonly custom: string;
+  readonly command?: string;
+  /** Your component's forms, largest first. Default `['default']`. */
+  readonly variants?: readonly string[];
+  readonly importance?: Importance;
+}
+/** A command id, a command with options, or your own component. */
+type LayoutItem = string | LayoutCommandItem | LayoutCustomItem;
+/** A group that needs a name or options. */
+interface LayoutGroupObject {
+  /** Its name, so `add(item, { group })` can find it. */
+  readonly id?: string;
+  readonly items: readonly LayoutItem[];
+  /** Fold into one button with a menu (`'menu'`) or a dropdown (`'select'`) when there's no room. */
+  readonly collapse?: 'menu' | 'select';
+  /** Move items behind a button inside the group before the group folds or leaves the bar. */
+  readonly shed?: boolean;
+  /** Who makes room first: `1` to `5`. Default `3`. */
+  readonly importance?: Importance;
+  /** Its title in the "More" menu, as a translation key. */
+  readonly titleKey?: string;
+  /**
+   * Show only while something in the bar that isn't dependent shows, like undo and redo beside a
+   * mode's tools. A bar with only dependent groups left is empty, and a mode's tab goes with it.
+   */
+  readonly dependent?: boolean;
+}
+/** A group of items, with a line between groups: an array, or an object when it needs a name or options. */
+type LayoutGroup = readonly LayoutItem[] | LayoutGroupObject;
+/** A section of a bar: its groups in order. A lone item is a group of one. */
+type LayoutSection = readonly (LayoutGroup | LayoutItem)[];
+/** A bar's sections: `start` (left), `center` and `end` (right); `start` and `end` swap in a right-to-left language. */
+type SectionName = 'start' | 'center' | 'end';
+interface LayoutBar {
+  readonly place: BarPlace;
+  /** Shown in this mode only. The mode gets a tab, titled by the bar's title, and a `mode:<mode>` command. */
+  readonly mode?: string;
+  readonly title?: string;
+  /** The title as a translation key. */
+  readonly titleKey?: string;
+  readonly start?: LayoutSection;
+  readonly center?: LayoutSection;
+  readonly end?: LayoutSection;
+}
+/** A section of a menu: an array of command ids, or an object when it has a title. */
+type LayoutMenuSection = readonly string[] | {
+  readonly title?: string;
+  /** The title as a translation key. */
+  readonly titleKey?: string;
+  readonly items: readonly string[];
+};
+/** A menu: its sections, with a line between them. */
+type LayoutMenu = readonly LayoutMenuSection[];
+/** How a panel opens: beside the pages, over them, or up from the bottom. */
+type PanelPresentation = 'dock' | 'overlay' | 'sheet';
+/** How a panel opens at each of the viewer's sizes. A size left out opens the default way. */
+interface PanelPresentationBySize {
+  readonly compact?: PanelPresentation;
+  readonly medium?: PanelPresentation;
+  readonly expanded?: PanelPresentation;
+}
+/** A panel's width: the one it starts at, and the narrowest and widest it can be dragged to. */
+interface PanelWidth {
+  /** In px. Default `288`. */
+  readonly initial?: number;
+  /** In px. Default `200`. */
+  readonly min?: number;
+  /** In px. Default `640`. A docked panel never takes more than half the viewer. */
+  readonly max?: number;
+}
+interface LayoutPanel {
+  /** Default `'end'`. */
+  readonly side?: 'start' | 'end';
+  readonly title?: string;
+  /** The title as a translation key. */
+  readonly titleKey?: string;
+  /** Its button's icon. */
+  readonly icon?: string;
+  /**
+   * How it opens: the same way at every size, or per size. Default
+   * `{ compact: 'sheet', medium: 'overlay', expanded: 'dock' }`.
+   */
+  readonly present?: PanelPresentation | PanelPresentationBySize;
+  /** Its width in px (where it starts), or where it starts and how far it drags. Default `288`. */
+  readonly width?: number | PanelWidth;
+  /** Whether people can drag its edge to change its width. Default `true`. */
+  readonly resizable?: boolean;
+}
+/**
+ * Changes to a panel: the fields to set. `present` and `width` change only what they name: a
+ * map of sizes keeps the other sizes, and a number or `{ initial }` keeps `min` and `max`.
+ */
+type LayoutPanelPatch = Partial<LayoutPanel>;
+/** When the document tabs show: always, while more than one document is open, or never. */
+type TabsVisibility = 'always' | 'multiple' | 'never';
+/** A layout as plain data: bars, menus and panels, each by id. */
+interface LayoutData {
+  readonly bars?: Readonly<Record<string, LayoutBar>>;
+  readonly menus?: Readonly<Record<string, LayoutMenu>>;
+  readonly panels?: Readonly<Record<string, LayoutPanel>>;
+  readonly tabs?: TabsVisibility;
+}
+/** Where {@link Layout.add} puts an item. */
+interface AddItemOptions {
+  /** The bar or menu. A bar wins over a menu with the same id. */
+  readonly to: string;
+  /** The bar's section for a new group. Default `'end'`. */
+  readonly section?: SectionName;
+  /** The group to join, by id; a new id starts a new group at the end of the section. */
+  readonly group?: string;
+  /** An item to put it before, in that item's group. */
+  readonly before?: string;
+  /** An item to put it after, in that item's group. */
+  readonly after?: string;
+}
+/** Where {@link Layout.remove} takes items from. */
+interface RemoveItemOptions {
+  /** The bar or menu: always one place. To leave something out everywhere, turn it off instead. */
+  readonly from: string;
+}
+/**
+ * A layout: its data and the edits. Every edit returns a new layout and leaves this one as it
+ * was; an edit that names an id the layout doesn't have changes nothing and records a warning.
+ */
+interface Layout {
+  /** Move a bar. */
+  place(bar: string, place: BarPlace): Layout;
+  /** Add a bar, or replace the bar with that id. */
+  addBar(id: string, bar: LayoutBar): Layout;
+  /** Remove a bar. Removing a mode's bar removes its tab. */
+  removeBar(id: string): Layout;
+  /** Put an item in a bar or a menu: at the end of a section, in a group, or next to an item. */
+  add(item: LayoutItem, options: AddItemOptions): Layout;
+  /** Take items out of one bar or menu; a group or section with nothing left goes with them. */
+  remove(ids: string | readonly string[], options: RemoveItemOptions): Layout;
+  /** Put another item in an item's place, in every bar and menu. */
+  replace(id: string, item: LayoutItem): Layout;
+  /** Add a menu, or replace the menu with that id. */
+  addMenu(id: string, sections: LayoutMenu): Layout;
+  /** Add a panel, or replace the panel with that id. */
+  addPanel(id: string, panel: LayoutPanel): Layout;
+  /** Change a panel's fields. */
+  panel(id: string, changes: LayoutPanelPatch): Layout;
+  /**
+   * Change every panel's fields, as `panel(id, changes)` changes one: every panel the layout has
+   * so far, so a panel added after it keeps its own.
+   */
+  panels(changes: LayoutPanelPatch): Layout;
+  /** Remove a panel, and its `panel:<id>` button from every bar and menu. */
+  removePanel(id: string): Layout;
+  /** When the document tabs show. */
+  tabs(visibility: TabsVisibility): Layout;
+  /** The layout as plain data. */
+  toJSON(): LayoutData;
+}
+/** A layout of `data`, which it never changes. */
+declare function createLayout(data?: LayoutData): Layout;
+/** Whether `value` is a layout made by {@link createLayout} or one of its edits. */
+declare function isLayout(value: unknown): value is Layout;
+/** What an item is called in edits: its command id, your component's id, or `''` for a non-item. */
+declare function itemIdOf(item: LayoutItem): string;
+/** The command an item runs or stands for in menus, or `null` for your component without one. */
+declare function itemCommandOf(item: LayoutItem): string | null;
+/** A panel's `present` as a map of sizes: one way at every size, or the sizes it names. */
+declare const panelPresentationsOf: (present: PanelPresentation | PanelPresentationBySize) => PanelPresentationBySize;
+/** A panel's `width` as its fields: a number is where it starts. */
+declare const panelWidthFieldsOf: (width: number | PanelWidth) => PanelWidth;
+/** The viewer's size class, from its own width. */
+type ViewerSize = 'compact' | 'medium' | 'expanded';
+/** What the layout function knows about the viewer, measured on the viewer itself. */
+interface LayoutEnv {
+  /** `'compact'` under 600 px, `'medium'` to 1023 px, `'expanded'` from 1024 px. */
+  readonly size: ViewerSize;
+  /** The viewer's width, in px. */
+  readonly width: number;
+  /** Whether the main way of pointing is a finger. */
+  readonly touch: boolean;
+  /** How the user's language reads. */
+  readonly dir: 'ltr' | 'rtl';
+}
+/** The narrowest a medium viewer is, in px. */
+declare const MEDIUM_MIN_WIDTH_PX = 600;
+/** The narrowest an expanded viewer is, in px. */
+declare const EXPANDED_MIN_WIDTH_PX = 1024;
+/** The size class of a viewer this wide. */
+declare function sizeOf(widthPx: number): ViewerSize;
+/** Whether two envs are the same: the layout function runs again only when one of the fields changes. */
+declare const sameLayoutEnv: (left: LayoutEnv, right: LayoutEnv) => boolean;
+/** Gets the default layout and the viewer's env, and returns your layout. */
+type LayoutFunction = (layout: Layout, env: LayoutEnv) => Layout | LayoutData;
+/** What the `layout` config takes: a layout, plain layout data, or a function of the default. */
+type LayoutOption = Layout | LayoutData | LayoutFunction;
+/**
+ * The layout an option gives at this env: the default without one, the function's result, or
+ * the option itself. A function that throws or returns no layout gives the default, with a
+ * warning saying so.
+ */
+declare function resolveLayout(option: LayoutOption | null | undefined, defaults: Layout, env: LayoutEnv): Layout;
+//#endregion
+//#region src/layout-compile.d.ts
+/** The id of the group that holds the mode tabs. */
+declare const MODES_GROUP = "modes";
+/** The command of the mode with no bar of its own: viewing. */
+declare const VIEW_MODE_COMMAND = "mode:view";
+/** The command that opens a mode, and its tab. */
+declare const modeCommandOf: (mode: string) => string;
+/** The command that opens and closes a panel, and its button. */
+declare const panelCommandOf: (panel: string) => string;
+/** Every place a bar can float over the pages: each corner, and the middle of each side. */
+declare const FLOAT_POSITIONS: readonly FloatPosition[];
+/** The edge a place is on, or `null` for a place that isn't an edge. */
+declare function edgeOf(place: BarPlace | undefined): BarEdge | null;
+/** The bar a place rides along, or `null`. */
+declare function hostOf(place: BarPlace | undefined): string | null;
+/** What a place follows when it is over a selection, or `null`. */
+declare function selectionOf(place: BarPlace | undefined): SelectionTarget | null;
+/** Where a place floats over the pages, or `null` for a place that doesn't float. */
+declare function floatOf(place: BarPlace | undefined): FloatPosition | null;
+/**
+ * The bars along an edge, from the outside in: in the order they were added, then each bar
+ * with `before` or `after` put next to the bar it names. A bar that names a bar not on this
+ * edge goes innermost.
+ */
+declare function barsOnEdge(data: LayoutData, edge: BarEdge): string[];
+/** The bars that ride along `host`, in the order they were added, nearest first. */
+declare function barsWith(data: LayoutData, host: string): string[];
+/**
+ * Every bar drawn along an edge, from the outside in: each bar on the edge, followed by the bars
+ * that ride along it (nearest first) and the bars that ride along those.
+ */
+declare function edgeStackOf(data: LayoutData, edge: BarEdge): string[];
+/** The bars floating at `position`, in the order they were added. */
+declare function barsFloating(data: LayoutData, position: FloatPosition): string[];
+/**
+ * Every bar drawn floating at `position`, from the viewer's edge in: each bar floating there,
+ * followed by the bars that ride along it, as {@link edgeStackOf} orders an edge.
+ */
+declare function floatStackOf(data: LayoutData, position: FloatPosition): string[];
+/** The bars over a selection of this kind, in the order they were added. */
+declare function barsAt(data: LayoutData, target: SelectionTarget): string[];
+/** Every mode of the layout's bars, once each, in bar order. */
+declare function modesOf(data: LayoutData): string[];
+/** The bars shown in a mode, in bar order. */
+declare function barsInMode(data: LayoutData, mode: string): string[];
+/** What {@link compileBar} leaves out. */
+interface CompileBarOptions {
+  /**
+   * Command ids to leave out, as if the bar didn't name them: a mode tab whose bars show nothing,
+   * a button whose menu is empty. With every mode tab left out, View goes too.
+   */
+  readonly omit?: ReadonlySet<string>;
+}
+/**
+ * A bar as the toolbar fits it, or `null` for a bar the layout doesn't have. Groups written as
+ * arrays and lone items get ids of their own (`start-0`, …); an item twice in one group shows
+ * once; a group with nothing left goes.
+ */
+declare function compileBar(data: LayoutData, id: string, options?: CompileBarOptions): BarSchema | null;
+/** When the document tabs show: as the layout says, else while more than one document is open. */
+declare function tabsOf(data: LayoutData): TabsVisibility;
+/** A menu section, read: its title and its command ids. */
+interface MenuSection {
+  readonly title?: string;
+  readonly titleKey?: string;
+  readonly items: readonly string[];
+}
+/** A menu's sections, or `null` for a menu the layout doesn't have. An empty section goes. */
+declare function menuOf(data: LayoutData, id: string): readonly MenuSection[] | null;
+/** What {@link omittedCommandsOf} reads of a command; plugin-commands' `ResolvedCommand` satisfies it. */
+interface OmissionCommand {
+  readonly visible: boolean;
+  readonly menu?: string;
+}
+/**
+ * The commands the bars leave out because what they lead to shows nothing: the tab of a mode
+ * whose bars have nothing visible ({@link hasVisibleUnits}: dependent groups alone don't count),
+ * and a button whose menu has nothing visible (or that the layout has no menu for). Sorted, so
+ * two equal results compare equal; pass it to {@link compileBar} as `omit`. Cheap to call on every change: what it reads of the layout is
+ * read once per layout data.
+ */
+declare function omittedCommandsOf(data: LayoutData, resolve: (id: string) => OmissionCommand | null): string[];
+//#endregion
+//#region src/layout-validate.d.ts
+/** What the viewer has, to check a layout's ids against. */
+interface LayoutKnownIds {
+  /**
+   * Every command id the viewer has. The ones the layout makes itself need not be listed: the
+   * mode tabs (`mode:view`, `mode:<mode>`) and the panel buttons (`panel:<id>`).
+   */
+  readonly commands: Iterable<string>;
+  /** Whether a command id exists that `commands` can't list, such as one of a family's. */
+  readonly hasCommand?: (id: string) => boolean;
+}
+/**
+ * Every problem with a layout, as sentences: what its edits couldn't do first, then what its
+ * data names that the viewer doesn't have. Empty when there is none.
+ */
+declare function validateLayout(layout: Layout | LayoutData, known: LayoutKnownIds): string[];
+//#endregion
+//#region src/suggestions.d.ts
+/**
+ * "Did you mean …?" for ids: the closest known id to one that doesn't exist,
+ * by edit distance, when it is close enough to be a typo.
+ */
+/**
+ * The number of single-character inserts, deletes, substitutions and swaps of two neighbours
+ * that turn `left` into `right`.
+ */
+declare function editDistance(left: string, right: string): number;
+/**
+ * The candidate closest to `id`, or `null` when none is within a typo's reach: at most a third
+ * of the id's length, and never more than 3 edits apart.
+ */
+declare function closestMatch(id: string, candidates: Iterable<string>): string | null;
+/** `' (did you mean "x"?)'` for the closest candidate, or `''` when there is none. */
+declare function didYouMean(id: string, candidates: Iterable<string>): string;
 //#endregion
 //#region src/solver.d.ts
 interface FitMetrics {
-  /** Width of unit `key` rendered at `variant`; undefined = not yet measured. */
+  /** Length of unit `key` rendered at `variant`; undefined = not yet measured. */
   unit(key: string, variant: string): number | undefined;
-  /** Width of group `id` rendered in its collapsed form ('menu' | 'select'). */
+  /** Length of group `id` rendered in its collapsed form ('menu' | 'select'). */
   groupCollapsed(groupId: string): number | undefined;
-  /** Width of group `id`'s disclosure trigger (shed groups only). */
+  /** Length of group `id`'s disclosure trigger (shed groups only). */
   groupTrigger(groupId: string): number | undefined;
-  /** Width of the overflow trigger button. */
+  /** Length of the overflow trigger button. */
   readonly overflowTrigger: number;
   /** Gap between adjacent visible units. */
   readonly gap: number;
-  /** Width of a derived separator between adjacent visible groups (with its gaps). */
+  /** Length of a derived separator between adjacent visible groups (with its gaps). */
   readonly separator: number;
 }
 type UnitAssignment = {
@@ -264,12 +557,13 @@ interface FitResult {
   readonly units: ReadonlyMap<string, UnitAssignment>;
   readonly groups: ReadonlyMap<string, GroupAssignment>;
   readonly hasOverflow: boolean;
-  /** Total visible width at this assignment (diagnostics + tests). */
-  readonly width: number;
+  /** Total visible length at this assignment (diagnostics + tests). */
+  readonly length: number;
   /** False when any consulted measurement was missing (treated as 0). */
   readonly complete: boolean;
 }
-declare function solve(bar: NormalizedBar, metrics: FitMetrics, containerWidth: number): FitResult;
+/** Fit `bar` into `containerLength`, the room along its axis. */
+declare function solve(bar: NormalizedBar, metrics: FitMetrics, containerLength: number): FitResult;
 //#endregion
 //#region src/projection.d.ts
 type OverflowRow =
@@ -302,8 +596,7 @@ type ResolveMenuTarget = (commandId: string) => {
 declare function projectOverflow(bar: NormalizedBar, fit: FitResult, resolve: ResolveMenuTarget): OverflowSection[];
 /**
  * The content of a group's disclosure trigger: its shed units, in bar order,
- * in menu form — same totality rules as the global overflow. This is v2's
- * hand-written `mode-tabs-overflow-menu`, derived.
+ * in menu form — same totality rules as the global overflow.
  */
 declare function projectShed(group: NormalizedGroup, fit: FitResult, resolve: ResolveMenuTarget): OverflowRow[];
 /** One strip group: a separator boundary, its visible commands in bar order. */
@@ -313,17 +606,188 @@ interface StripGroup {
   readonly commands: readonly string[];
 }
 /**
- * Strip projection — a bar projected for UN-measured rendering (a contextual
+ * Strip projection — a bar projected for un-measured rendering (a contextual
  * strip anchored to a selection has no fit pressure to solve). The schema
- * declares what COULD appear; `visible` (the command registry's runtime truth)
- * decides what DOES: hidden commands drop out, groups that empty out vanish,
- * and an all-hidden bar projects to [] — "render nothing" falls out. Custom
+ * declares what could appear; `visible` (the command registry's runtime truth)
+ * decides what does: hidden commands drop out, groups that empty out vanish,
+ * and an all-hidden bar projects to [] — "render nothing" falls out, as it
+ * does for a bar with only dependent groups left ({@link filterBar}). Custom
  * units project through their `terminal` command, same totality rule as the
  * overflow. Upgrading a strip to measured/overflowing rendering later is a
  * renderer swap (<Toolbar>), never a schema change.
  */
 declare function projectStrip(bar: NormalizedBar, visible: (command: string) => boolean): StripGroup[];
 //#endregion
+//#region src/toolbar-layout.d.ts
+/** What the layout reads of a resolved command; plugin-commands' `ResolvedCommand` satisfies it. */
+interface ToolbarCommand {
+  readonly id: string;
+  readonly visible: boolean;
+}
+/** A group folded into one control: a menu button, or a `<select>`. */
+interface CollapsedGroupView<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly id: string;
+  readonly labelKey?: string;
+  readonly collapse: 'menu' | 'select';
+  readonly role: 'buttons' | 'tabs';
+  /** The group's visible commands (a custom item through its terminal command), resolved live. */
+  readonly commands: readonly Command[];
+  execute(id: string): void;
+}
+/**
+ * The button inside a group that shed some of its items. `commands` is what
+ * sits behind it, in bar order, resolved live. In the measurement layer it is
+ * measured with the whole group behind it, so a trigger that shows a count
+ * ("+3") is budgeted at its widest.
+ */
+interface GroupDisclosureView<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly id: string;
+  readonly labelKey?: string;
+  readonly role: 'buttons' | 'tabs';
+  readonly commands: readonly Command[];
+  execute(id: string): void;
+}
+/** The "More" menu: what didn't fit, in sections, and the calls a menu needs. */
+interface OverflowMenuView<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly sections: readonly OverflowSection[];
+  readonly isOpen: boolean;
+  close(): void;
+  /** A row's command, resolved live, or `null` for an unknown id. */
+  resolve(id: string): Command | null;
+  execute(id: string): void;
+}
+/** What a custom item's renderer receives besides the item's variant. */
+interface CustomSlotCtx {
+  /** `'live'` in the visible row, `'measure'` in the hidden measurement layer. */
+  layer: 'live' | 'measure';
+  /**
+   * Report the item's length yourself (its width, or its height in a vertical
+   * bar), for content the measurement layer can't hold.
+   */
+  measure: (length: number) => void;
+}
+/**
+ * One thing in the toolbar. `key` is its identity in the live row, the same
+ * at every variant; `measureKey` is the key its length is reported under,
+ * unique across the whole toolbar. A `custom` part is the app's to draw;
+ * without a renderer for it, an adapter draws a native `<slot>` socket
+ * measured where it renders, and leaves it out of the measurement layer: only
+ * the first `<slot>` of a name gets the projected children.
+ */
+type ToolbarPart<Command extends ToolbarCommand = ToolbarCommand> = {
+  readonly kind: 'command';
+  readonly key: string;
+  readonly measureKey: string;
+  readonly command: Command;
+  readonly variant: string;
+  readonly run: () => void;
+} | {
+  readonly kind: 'custom';
+  readonly key: string;
+  readonly measureKey: string;
+  /** The item's name, from `custom(name, terminal)`. */
+  readonly name: string;
+  readonly variant: string;
+  /** The command it becomes in the "More" menu; drawn when no renderer draws the item. */
+  readonly terminal: Command | null;
+  readonly runTerminal: () => void;
+} | {
+  readonly kind: 'collapsed';
+  readonly key: string;
+  readonly measureKey: string;
+  readonly view: CollapsedGroupView<Command>;
+} | {
+  readonly kind: 'disclosure';
+  readonly key: string;
+  readonly measureKey: string;
+  readonly view: GroupDisclosureView<Command>;
+};
+/** A group in the live row: its visible parts. Every group but a section's first has a separator before it. */
+interface LiveGroup<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly id: string;
+  readonly parts: readonly ToolbarPart<Command>[];
+}
+/** A section of the live row (`start`, `center` or `end`), with only its visible groups. */
+interface LiveSection<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly name: 'start' | 'center' | 'end';
+  readonly groups: readonly LiveGroup<Command>[];
+}
+interface ToolbarLayout<Command extends ToolbarCommand = ToolbarCommand> {
+  /** Always the three sections, in order. */
+  readonly sections: readonly LiveSection<Command>[];
+  /**
+   * What the measurement layer draws, each reporting its length under its
+   * `measureKey`: every unit in every variant, each collapsible group folded,
+   * each shed group's trigger with the whole group behind it.
+   */
+  readonly measured: readonly ToolbarPart<Command>[];
+  readonly hasOverflow: boolean;
+  /** The "More" menu, derived from what didn't fit. */
+  readonly overflow: readonly OverflowSection[];
+}
+/** The keys a measurement layer reports lengths under; `@embedpdf/web`'s `toolbarMeasureKey` satisfies it. */
+interface ToolbarMeasureKeys {
+  unit(unitKey: string, variant: string): string;
+  group(groupId: string): string;
+  groupTrigger(groupId: string): string;
+}
+/** What {@link layoutToolbar} reads. */
+interface ToolbarLayoutInput<Command extends ToolbarCommand> {
+  /** The bar, from `normalizeBar`. */
+  readonly bar: NormalizedBar;
+  /** A command for the toolbar's document, or `null` for an id no plugin registered. */
+  readonly resolve: (id: string) => Command | null;
+  /** What an id no plugin registered draws as: a disabled command named by its id. */
+  readonly unregistered: (id: string) => Command;
+  /** Run a command for the toolbar's document. */
+  readonly execute: (id: string) => void;
+  /** Which menu a command opens, for the "More" menu's submenu rows. */
+  readonly menuTarget: ResolveMenuTarget;
+  /** The measured lengths, along the toolbar's axis. */
+  readonly metrics: FitMetrics;
+  /** The keys the measured lengths are reported under. */
+  readonly measureKey: ToolbarMeasureKeys;
+  /** The length the toolbar fills: its width, or its height when vertical. */
+  readonly containerLength: number;
+  /**
+   * Which way the toolbar runs. A vertical toolbar draws every command at
+   * `'icon'`, with no smaller step, and leaves its label to a tooltip. Default
+   * `'horizontal'`.
+   */
+  readonly orientation?: 'horizontal' | 'vertical';
+}
+/** Fit the bar into `containerLength` and describe what to draw. */
+declare function layoutToolbar<Command extends ToolbarCommand>(input: ToolbarLayoutInput<Command>): ToolbarLayout<Command>;
+/**
+ * The menu a default folded group or group trigger opens: one section of the
+ * group's commands, a radio group when the group is tabs.
+ */
+declare function groupMenuView<Command extends ToolbarCommand>(view: CollapsedGroupView<Command> | GroupDisclosureView<Command>, isOpen: boolean, close: () => void): OverflowMenuView<Command>;
+/** A group of a strip: its visible commands, in bar order. Groups are separator boundaries. */
+interface StripViewGroup<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly id: string;
+  readonly labelKey?: string;
+  readonly commands: readonly Command[];
+}
+/** A strip, resolved: only visible commands, only groups with one. */
+interface StripView<Command extends ToolbarCommand = ToolbarCommand> {
+  readonly groups: readonly StripViewGroup<Command>[];
+  /** Run a command for the strip's document. */
+  execute(id: string): void;
+}
+/**
+ * A bar as a strip shows it now (`projectStrip`), each command resolved: the
+ * schema says what could appear, each command's `visible` decides what does.
+ * Empty while nothing applies.
+ */
+declare function stripGroupsOf<Command extends ToolbarCommand>(bar: NormalizedBar, resolve: (id: string) => Command | null): StripViewGroup<Command>[];
+/**
+ * Whether two resolved strips show the same, group by group and command by
+ * command (`sameCommand` is plugin-commands' `resolvedCommandsEqual`): a
+ * strip's readers pass it on only when this is false.
+ */
+declare function sameStripGroups<Command extends ToolbarCommand>(left: readonly StripViewGroup<Command>[], right: readonly StripViewGroup<Command>[], sameCommand: (left: Command, right: Command) => boolean): boolean;
+//#endregion
 //#region src/shortcuts.d.ts
 /**
  * Shortcut parsing + matching — pure. No `navigator`: platform is an input
@@ -332,7 +796,7 @@ declare function projectStrip(bar: NormalizedBar, visible: (command: string) =>
  * Grammar: modifiers and one key joined by '+', e.g. 'Mod+K', 'Ctrl+=',
  * 'Shift+Alt+D', 'Meta+NumpadAdd'. 'Mod' is ⌘ on mac and Ctrl elsewhere.
  * Keys longer than one character (F1, Escape, NumpadAdd, ArrowLeft) match
- * `event.key` OR `event.code` case-insensitively, so numpad shortcuts work.
+ * `event.key` or `event.code` case-insensitively, so numpad shortcuts work.
  */
 interface ParsedShortcut {
   readonly key: string;
@@ -352,13 +816,70 @@ interface KeyStroke {
   readonly shiftKey: boolean;
 }
 declare function parseShortcut(shortcut: string): ParsedShortcut;
-declare function matchShortcut(parsed: ParsedShortcut, stroke: KeyStroke, opts: {
+declare function matchShortcut(parsed: ParsedShortcut, stroke: KeyStroke, options: {
+  isMac: boolean;
+}): boolean;
+/**
+ * Whether two shortcuts are pressed with the same keys on this platform: `'Mod+S'` and
+ * `'Ctrl+s'` are where `Mod` is Ctrl, and not on a Mac.
+ */
+declare function sameShortcut(left: string, right: string, options: {
   isMac: boolean;
 }): boolean;
-/** Display form for menu rows: '⌘K' on mac, 'Ctrl+K' elsewhere. */
-declare function formatShortcut(shortcut: string, opts: {
+/** A shortcut as a menu or a tooltip shows it: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+declare function formatShortcut(shortcut: string, options: {
   isMac: boolean;
 }): string;
 //#endregion
-export { type AddItemSpec, type BarChild, type BarGroup, type BarItem, type BarSchema, type BarSections, type ChromeHelpers, type ChromeSchema, type CustomItem, DEFAULT_IMPORTANCE, type FitMetrics, type FitResult, type FrameSchema, type GroupAssignment, type Importance, type KeyStroke, type MenuSchema, type MenuSection, type NormalizedBar, type NormalizedGroup, type NormalizedSection, type NormalizedUnit, type OverflowRow, type OverflowSection, PINNED, type ParsedShortcut, type ResolveMenuTarget, type StripGroup, type UnitAssignment, type Variant, addItem, chromeHelpers, custom, defineChrome, filterBar, formatShortcut, group, item, matchShortcut, normalizeBar, parseShortcut, projectOverflow, projectShed, projectStrip, removeItems, replaceItem, solve, validateChrome };
+//#region src/tree-keys.d.ts
+/**
+ * The keyboard of a tree view, as the ARIA tree pattern has it — pure.
+ * A view hands in the rows that show (in order, each with its depth, whether
+ * it has children and whether they show), the focused row and the key
+ * (`KeyboardEvent.key`); it gets back what the key does, and does it. A key
+ * that does nothing returns `null`, so the view lets the event go on.
+ *
+ *   ArrowDown, ArrowUp   the next, the previous row
+ *   ArrowRight           a collapsed parent expands; an expanded one moves to its first child
+ *   ArrowLeft            an expanded parent collapses; any other row moves to its parent
+ *   Home, End            the first, the last row
+ *   *                    every collapsed sibling of the focused row expands
+ *   Enter                the row activates
+ *   F2, Delete           the row is renamed or deleted, when the tree is editable
+ */
+/** A row as the keyboard sees it. */
+interface TreeKeyRow {
+  /** How deep it sits: 0 at the top level. */
+  readonly depth: number;
+  readonly hasChildren: boolean;
+  /** Whether its children show. */
+  readonly expanded: boolean;
+}
+/** What a key does, naming rows by their index in the rows handed in. */
+type TreeKeyAction = {
+  readonly type: 'focus';
+  readonly row: number;
+} | {
+  readonly type: 'expand';
+  readonly rows: readonly number[];
+} | {
+  readonly type: 'collapse';
+  readonly row: number;
+} | {
+  readonly type: 'activate';
+  readonly row: number;
+} | {
+  readonly type: 'rename';
+  readonly row: number;
+} | {
+  readonly type: 'delete';
+  readonly row: number;
+};
+interface TreeKeyOptions {
+  /** Whether F2 and Delete edit the tree. Off by default: a reader's tree only moves and opens. */
+  readonly editable?: boolean;
+}
+declare function treeKeyAction(rows: readonly TreeKeyRow[], focused: number, key: string, options?: TreeKeyOptions): TreeKeyAction | null;
+//#endregion
+export { type AddItemOptions, type BarChild, type BarEdge, type BarGroup, type BarItem, type BarPlace, type BarSchema, type BarSections, type CollapsedGroupView, type CompileBarOptions, type CustomItem, type CustomSlotCtx, DEFAULT_IMPORTANCE, EXPANDED_MIN_WIDTH_PX, FLOAT_POSITIONS, type FitMetrics, type FitResult, type FloatPosition, type GroupAssignment, type GroupDisclosureView, type Importance, type KeyStroke, type Layout, type LayoutBar, type LayoutCommandItem, type LayoutCustomItem, type LayoutData, type LayoutEnv, type LayoutFunction, type LayoutGroup, type LayoutGroupObject, type LayoutItem, type LayoutKnownIds, type LayoutMenu, type LayoutMenuSection, type LayoutOption, type LayoutPanel, type LayoutPanelPatch, type LayoutSection, type LiveGroup, type LiveSection, MEDIUM_MIN_WIDTH_PX, MODES_GROUP, type MenuSection, type NormalizedBar, type NormalizedGroup, type NormalizedSection, type NormalizedUnit, type OmissionCommand, type OverflowMenuView, type OverflowRow, type OverflowSection, PINNED, type PanelPresentation, type PanelPresentationBySize, type PanelWidth, type ParsedShortcut, type RemoveItemOptions, type ResolveMenuTarget, type SectionName, type SelectionTarget, type StripGroup, type StripView, type StripViewGroup, type TabsVisibility, type ToolbarCommand, type ToolbarLayout, type ToolbarLayoutInput, type ToolbarMeasureKeys, type ToolbarPart, type TreeKeyAction, type TreeKeyOptions, type TreeKeyRow, type UnitAssignment, VIEW_MODE_COMMAND, type Variant, type ViewerSize, barsAt, barsFloating, barsInMode, barsOnEdge, barsWith, closestMatch, commandOfUnit, compileBar, createLayout, custom, didYouMean, edgeOf, edgeStackOf, editDistance, filterBar, floatOf, floatStackOf, formatShortcut, group, groupMenuView, hasVisibleUnits, hostOf, isLayout, isStandaloneUnit, item, itemCommandOf, itemIdOf, layoutToolbar, matchShortcut, menuOf, modeCommandOf, modesOf, normalizeBar, omittedCommandsOf, panelCommandOf, panelPresentationsOf, panelWidthFieldsOf, parseShortcut, projectOverflow, projectShed, projectStrip, resolveLayout, sameLayoutEnv, sameShortcut, sameStripGroups, selectionOf, sizeOf, solve, stripGroupsOf, tabsOf, treeKeyAction, validateLayout };
 //# sourceMappingURL=index.d.cts.map