@embedpdf/viewer-chrome 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.d.ts

@@ -1,21 +1,114 @@
-import { defaultChrome } from "./chrome.js";
+import { defaultLayout } from "./chrome.js";
 import { defaultCommands } from "./commands.js";
 import { ReactNode } from "react";
-import { CapabilityToken, CapabilityToken as CapabilityToken$1, DocInfo, DocumentsCapability, DocumentsCapability as DocumentsCapability$1, DocumentsToken, Engine, Engine as Engine$1, EngineFactory, EngineFactory as EngineFactory$1, InitialDocument, InitialDocument as InitialDocument$1, Kernel, Unsubscribe, Unsubscribe as Unsubscribe$1 } from "@embedpdf/react/runtime";
-import { StageToken } from "@embedpdf/react/stage";
-import { InteractionToken } from "@embedpdf/react/interaction";
-import { SelectionToken } from "@embedpdf/react/selection";
-import { AnnotationToken } from "@embedpdf/react/annotation";
-import { StampToken } from "@embedpdf/react/stamp";
-import { RedactionToken } from "@embedpdf/react/redaction";
-import { FormToken } from "@embedpdf/react/form";
-import { Mark, SignFieldInput, SignatureMode, SignatureMode as SignatureMode$1, SignatureToken, SignerPort, SignerPort as SignerPort$1, TrustPort, TrustPort as TrustPort$1, createTestSigner, indexedDbKeyStore, memoryKeyStore, personalSigner, remoteSigner, webCryptoSigner } from "@embedpdf/react/signature";
-import { SearchToken } from "@embedpdf/react/search";
-import { I18nToken, TranslationDictionary } from "@embedpdf/react/i18n";
-import { CommandDef, CommandDef as CommandDef$1, CommandsToken, ResolvedCommand, ResolvedCommand as ResolvedCommand$1 } from "@embedpdf/react/commands";
-import { ShellToken } from "@embedpdf/react/shell";
-import { AddItemSpec, BarChild, BarGroup, BarItem, BarSchema, BarSchema as BarSchema$1, BarSections, ChromeHelpers, ChromeHelpers as ChromeHelpers$1, ChromeSchema, ChromeSchema as ChromeSchema$1, CustomItem, Importance, MenuSchema, MenuSchema as MenuSchema$1, MenuSection, Variant, addItem, chromeHelpers, custom, defineChrome, group, item, removeItems, replaceItem, validateChrome } from "@embedpdf/react/toolbar";
-import { MetadataToken } from "@embedpdf/react/metadata";
+import { CapabilityToken, CapabilityToken as CapabilityToken$1, DocumentInfo, DocumentsCapability, DocumentsCapability as DocumentsCapability$1, DocumentsToken, Engine, Engine as Engine$1, EngineFactory, EngineFactory as EngineFactory$1, Identity, Identity as Identity$1, InitialDocument, InitialDocument as InitialDocument$1, Kernel, Unsubscribe, Unsubscribe as Unsubscribe$1 } from "@embedpdf/react/runtime";
+import { StageCapability, StageToken, stagePlugin } from "@embedpdf/react/stage";
+import { RenderCapability, RenderToken, renderPlugin } from "@embedpdf/react/render";
+import { PageEditCapability, PageEditToken } from "@embedpdf/react/page-edit";
+import { MetadataCapability, MetadataToken } from "@embedpdf/react/metadata";
+import { InteractionCapability, InteractionToken, interactionPlugin } from "@embedpdf/react/interaction";
+import { SelectionCapability, SelectionToken, selectionPlugin } from "@embedpdf/react/selection";
+import { AnnotationCapability, AnnotationToken, annotationPlugin } from "@embedpdf/react/annotation";
+import { StampCapability, StampToken, stampPlugin } from "@embedpdf/react/stamp";
+import { MeasurementCapability, MeasurementCapability as MeasurementCapability$1, MeasurementConfig, MeasurementToken, ScaleChangeReport, measurementPlugin } from "@embedpdf/react/measurement";
+import { RedactionCapability, RedactionToken, redactionPlugin } from "@embedpdf/react/redaction";
+import { ActionsCapability, ActionsToken, actionsPlugin } from "@embedpdf/react/actions";
+import { FormCapability, FormToken, formPlugin } from "@embedpdf/react/form";
+import { Mark, SignFieldInput, SignatureCapability, SignatureMode, SignatureToken, SignerPort, TrustPort, createTestSigner, indexedDbKeyStore, memoryKeyStore, personalSigner, remoteSigner, signaturePlugin, webCryptoSigner } from "@embedpdf/react/signature";
+import { LinkCapability, LinkToken } from "@embedpdf/react/link";
+import { SearchCapability, SearchToken, searchPlugin } from "@embedpdf/react/search";
+import { I18nCapability, I18nToken, TranslationDictionary, i18nPlugin } from "@embedpdf/react/i18n";
+import { CommandDef as CommandDef$1, CommandsCapability, CommandsCapability as CommandsCapability$1, CommandsToken, IconAccent, NotAllowedMode, NotAllowedMode as NotAllowedMode$1, ResolvedCommand, commandsPlugin } from "@embedpdf/react/commands";
+import { ShellCapability, ShellToken } from "@embedpdf/react/shell";
+import { AddItemOptions, BarEdge, BarPlace, FloatPosition, Importance, Layout, LayoutBar, LayoutCommandItem, LayoutCustomItem, LayoutData, LayoutData as LayoutData$1, LayoutEnv, LayoutFunction, LayoutGroup, LayoutGroupObject, LayoutItem, LayoutMenu, LayoutMenuSection, LayoutOption, LayoutOption as LayoutOption$1, LayoutPanel, LayoutPanelPatch, LayoutSection, PanelPresentation, PanelPresentationBySize, PanelWidth, RemoveItemOptions, SectionName, SelectionTarget, TabsVisibility, Variant, ViewerSize, ViewerSize as ViewerSize$1, createLayout } from "@embedpdf/core-ui";
+import "@embedpdf/react/toolbar";
+//#region src/handle.d.ts
+/** Each plugin's API, by the plugin's name: what `viewer.get(name)` returns. */
+interface ViewerPlugins {
+  readonly stage: StageCapability;
+  /** The thumbnails panel's Stage: a second lens over the same document. */
+  readonly thumbnails: StageCapability;
+  readonly render: RenderCapability;
+  readonly link: LinkCapability;
+  readonly selection: SelectionCapability;
+  readonly search: SearchCapability;
+  readonly annotation: AnnotationCapability;
+  readonly stamp: StampCapability;
+  readonly measurement: MeasurementCapability$1;
+  readonly redaction: RedactionCapability;
+  readonly form: FormCapability;
+  readonly signature: SignatureCapability;
+  readonly pageEdit: PageEditCapability;
+  /** The document's title, author and your own fields; `ensureLoaded()` reads them. */
+  readonly metadata: MetadataCapability;
+  readonly actions: ActionsCapability;
+  readonly documents: DocumentsCapability$1;
+  readonly interaction: InteractionCapability;
+  readonly commands: CommandsCapability$1;
+  readonly shell: ShellCapability;
+  readonly i18n: I18nCapability;
+}
+/** A plugin's name, as `viewer.get()` and the `plugins` config take it. */
+type PluginName = keyof ViewerPlugins;
+/**
+ * The viewer's plugins by name: the names `get()` takes, the same as the `plugins` config's.
+ * Only plugins the viewer registers are here, so every name resolves.
+ */
+declare const VIEWER_PLUGINS: { readonly [Name in PluginName]: CapabilityToken$1<ViewerPlugins[Name]>; };
+/** `get`/`tryGet` bound to one document (see {@link Viewer.forDocument}). */
+interface ScopedViewer {
+  /**
+   * A plugin's API, by its name (`'search'`) or its token (`SearchToken`). Throws when the
+   * viewer has no such plugin, when the plugin belongs to a document and none is open, and
+   * `instance-closed` once the viewer is done.
+   */
+  get<Name extends PluginName>(name: Name): ViewerPlugins[Name];
+  get<Capability>(token: CapabilityToken$1<Capability>): Capability;
+  /**
+   * Like `get`, but `null` when the plugin isn't available: none by that name, no document, one
+   * still opening, or the viewer is done.
+   */
+  tryGet<Name extends PluginName>(name: Name): ViewerPlugins[Name] | null;
+  tryGet<Capability>(token: CapabilityToken$1<Capability>): Capability | null;
+}
+/** The viewer, from code: `element.viewer`, and what `onReady` gets. */
+interface Viewer extends ScopedViewer {
+  /** The documents: open, close, switch, download, and their events. `get('documents')`. */
+  readonly documents: DocumentsCapability$1;
+  /** The commands: run one, read one, turn features on and off, and their events. `get('commands')`. */
+  readonly commands: CommandsCapability$1;
+  /** `get`/`tryGet` for one document, whether it's the active one or not. */
+  forDocument(documentId: string): ScopedViewer;
+  /**
+   * Run `read` on every change in the viewer, and call `onChange` when what it returns changed
+   * (`isEqual`, default `Object.is`: capability getters return the same object until their value
+   * changes, so identity works). Returns a function that stops it.
+   */
+  watch<T>(read: () => T, onChange: (value: T, previous: T) => void, isEqual?: (left: T, right: T) => boolean): Unsubscribe$1;
+}
+/** The plugins a viewer resolves by name: {@link VIEWER_PLUGINS}, or more. */
+type PluginTokens = Readonly<Record<string, CapabilityToken$1<unknown>>>;
+/** A `viewer`, and the end of its life. */
+interface ViewerLifetime {
+  readonly viewer: Viewer;
+  /**
+   * The viewer it reaches is gone: every listener added through the `viewer` stops, and every
+   * call refuses with `instance-closed`. Idempotent.
+   */
+  dispose(): void;
+}
+/**
+ * Make the `viewer` from a live kernel; `plugins` are the names its `get()` takes.
+ *
+ * Every API the `viewer` hands out (`get()`, `documents`, `commands`) is the plugin's own
+ * capability seen through a lens that ends with the viewer: while it lives, every member is the
+ * capability's; once {@link ViewerLifetime.dispose} runs, the listeners and registrations made
+ * through it are removed, a read (`get*`, `list*`, `is*`, `has*`, `can*`) throws
+ * `instance-closed`, every other call returns a promise that rejects with it, and a new
+ * subscription does nothing.
+ */
+declare function createViewer(kernel: Kernel, plugins: PluginTokens): ViewerLifetime;
+//#endregion
 //#region src/ui/icons.d.ts
 type PathSpec = string | {
   d: string;
@@ -25,101 +118,438 @@ type PathSpec = string | {
   /** Stroke paint: a slot name = that accent color (currentColor when
    *  the accent is absent). */
   stroke?: 'primary' | 'secondary';
+  strokeWidth?: number;
+  strokeDasharray?: string;
+  strokeOpacity?: number;
+  fillOpacity?: number;
+};
+/** An icon's path data: a string is one path, an array several. */
+type IconPaths = string | readonly PathSpec[];
+/**
+ * An icon of yours: 24 × 24 path data drawn as a line (Tabler and Lucide icons paste in as
+ * they are), or `{ paths, fill: true }` to fill the paths instead of drawing their outline.
+ */
+type IconDef = IconPaths | {
+  readonly paths: IconPaths;
+  readonly fill?: boolean;
 };
-/** A registrable icon: 24×24 stroke path data (Tabler/Lucide-style), exactly
- *  the shape of the built-in set — user icons are not a lesser kind. */
-type IconDef = readonly PathSpec[];
-declare const ICON_PATHS: Record<string, readonly PathSpec[]>;
+declare const ICON_PATHS: {
+  ruler: string[];
+  distance: ({
+    d: string;
+    stroke: "primary";
+    strokeDasharray: string;
+    fill?: undefined;
+    fillOpacity?: undefined;
+  } | {
+    d: string;
+    stroke: "primary";
+    fill: "primary";
+    fillOpacity: number;
+    strokeDasharray?: undefined;
+  })[];
+  perimeter: PathSpec[];
+  area: PathSpec[];
+  alertTriangle: string[];
+  alignBottom: string[];
+  alignCenter: string[];
+  alignLeft: string[];
+  alignMiddle: string[];
+  alignRight: string[];
+  alignTop: string[];
+  arrowBackUp: string[];
+  arrowForwardUp: string[];
+  bold: string[];
+  book: string[];
+  book2: string[];
+  calibrate: string[];
+  callout: ({
+    d: string;
+    stroke: "primary";
+    fill: "secondary";
+  } | {
+    d: string;
+    stroke: "primary";
+    fill?: undefined;
+  })[];
+  check: string[];
+  chevronDown: string[];
+  chevronLeft: string[];
+  chevronRight: string[];
+  circle: {
+    d: string;
+    stroke: "primary";
+    fill: "secondary";
+  }[];
+  comment: string[];
+  copy: string[];
+  deviceFloppy: string[];
+  dots: string[];
+  doublePage: string[];
+  download: string[];
+  externalLink: string[];
+  eye: string[];
+  file: string[];
+  fileImport: string[];
+  fitToPage: string[];
+  fitToWidth: string[];
+  formButton: string[];
+  formCheckbox: string[];
+  formDesign: string[];
+  formListbox: string[];
+  formRadio: (string | {
+    d: string;
+    fill: true;
+  })[];
+  formSelect: string[];
+  formTextfield: string[];
+  freeText: {
+    d: string;
+    stroke: "primary";
+  }[];
+  fullscreen: string[];
+  fullscreenExit: string[];
+  group: string[];
+  hand: string[];
+  highlight: (string | {
+    d: string;
+    fill: "primary";
+  })[];
+  horizontal: string[];
+  inkHighlighter: (string | {
+    d: string;
+    stroke: "primary";
+    fill: "primary";
+  })[];
+  insertText: {
+    d: string;
+    stroke: "primary";
+  }[];
+  italic: string[];
+  line: {
+    d: string;
+    stroke: "primary";
+  }[];
+  lineArrow: {
+    d: string;
+    stroke: "primary";
+  }[];
+  link: string[];
+  linkOff: string[];
+  listTree: string[];
+  lock: string[];
+  marqueeSelect: string[];
+  menu: string[];
+  message: string[];
+  palette: string[];
+  paperclip: string[];
+  pencilMarker: (string | {
+    d: string;
+    stroke: "primary";
+  })[];
+  photo: string[];
+  plus: string[];
+  pointer: string[];
+  polygon: {
+    d: string;
+    stroke: "primary";
+    fill: "secondary";
+  }[];
+  print: string[];
+  redact: string[];
+  redactArea: string[];
+  redactCombined: string[];
+  redactionSidebar: string[];
+  replaceText: {
+    d: string;
+    stroke: "primary";
+  }[];
+  rotateClockwise: string[];
+  rotateCounterClockwise: string[];
+  rubberStamp: string[];
+  rubberStampPlus: string[];
+  save: string[];
+  screenshot: string[];
+  search: string[];
+  settings: string[];
+  sidebar: string[];
+  signature: string[];
+  singlePage: string[];
+  square: {
+    d: string;
+    stroke: "primary";
+    fill: "secondary";
+  }[];
+  squares: string[];
+  squiggly: (string | {
+    d: string;
+    stroke: "primary";
+  })[];
+  strikethrough: (string | {
+    d: string;
+    stroke: "primary";
+  })[];
+  text: string[];
+  trash: string[];
+  underline: (string | {
+    d: string;
+    stroke: "primary";
+  })[];
+  ungroup: string[];
+  unlock: string[];
+  updateScale: string[];
+  vertical: string[];
+  viewSettings: string[];
+  widgetEdit: string[];
+  x: string[];
+  zigzag: {
+    d: string;
+    stroke: "primary";
+  }[];
+  zoomIn: string[];
+  zoomInArea: string[];
+  zoomOut: string[];
+};
+/** The name of one of the viewer's own icons. */
+type IconName = keyof typeof ICON_PATHS;
 //#endregion
-//#region src/config-context.d.ts
-interface StampsCustomization {
-  /** `false`: no built-in library. A string: URL template with `{locale}`. */
-  readonly defaultLibrary?: false | string;
-  /** Library kinds the stamps sidebar lists. Default `['stamps']`. */
-  readonly sidebar?: ReadonlyArray<string>;
-  /** Quick marks in the Insert toolbar: asset ids (`library:name`) from any
-   *  library, or one library's whole set. Default none. */
-  readonly toolbar?: ReadonlyArray<string> | {
-    readonly library: string;
-  };
-}
-interface SignaturesCustomization {
-  /** Which marks a person keeps. Default both. */
-  readonly kinds?: ReadonlyArray<'signature' | 'initials'>;
-  /** `'one'`: a single person per browser (no "new signature" once one exists). Default `'many'`. */
-  readonly libraries?: 'one' | 'many';
-  /** What placing a mark on a field does; default `sign` with a signer, else `visual`. */
-  readonly mode?: SignatureMode$1;
-  /** The key holder — `webCryptoSigner`, `remoteSigner`, `personalSigner`, or a thunk resolving one per signing. */
-  readonly signer?: SignerPort$1 | (() => Promise<SignerPort$1>);
-  /** Trust anchors for validation; none → verdicts top out at "valid, signer unknown". */
-  readonly trust?: TrustPort$1;
-  /** Offer a certification (first signature, DocMDP) in the sign dialog. Default false. */
-  readonly allowCertify?: boolean;
-  /** Script faces for typed marks: registered on the viewer's engine on first use. */
-  readonly fonts?: ReadonlyArray<{
-    readonly key: string;
-    readonly url: string;
-    readonly label: string;
-  }>;
-}
-/** A font for free-text annotations beyond the standard 14. */
-interface AnnotationFontSpec {
-  /** The stable id a free-text `fontFamily` carries — the engine key AND the
-   *  CSS family the live editor renders with. Not one of the 14 standard names. */
+//#region src/config/viewer-commands.d.ts
+/** What a command's functions get: its document, any plugin by its name or token, and the viewer. */
+interface CommandContext extends ScopedViewer {
+  /** The document it's for: the one named, else the active one; `null` with none open. */
+  readonly documentId: string | null;
+  /** What the caller passed: `execute(id, { args })`. */
+  readonly args?: unknown;
+  /** Fires when the caller cancels `execute()`: pass it on to the calls `run` makes. */
+  readonly signal?: AbortSignal;
+  /** The viewer, as `onReady` gets it. */
+  readonly viewer: Viewer;
+}
+/**
+ * A command, as the `commands` config takes it: the headless command, its functions getting
+ * {@link CommandContext}. With a built-in command's id it changes that one, field by field.
+ */
+interface CommandDef extends Omit<CommandDef$1, 'icon' | 'iconAccent' | 'allowed' | 'enabled' | 'active' | 'visible' | 'run'> {
+  /** An icon's name: one of the viewer's, or one of yours (`icons`). */
+  readonly icon?: IconName | (string & {});
+  /** Colors for the icon, read from live state like `active`. */
+  readonly iconAccent?: (context: CommandContext) => IconAccent | null;
+  /** Whether the session may run it, from the plugins' `can*` checks. Prefer `requires`. */
+  readonly allowed?: (context: CommandContext) => boolean;
+  /** When it can run. When it can't, its button is greyed out. Default: always. */
+  readonly enabled?: (context: CommandContext) => boolean;
+  /** When it shows as pressed, or checked in a menu. */
+  readonly active?: (context: CommandContext) => boolean;
+  /** When it shows at all. Default: always. */
+  readonly visible?: (context: CommandContext) => boolean;
+  /** What it does; `execute()` resolves once it has. Not needed for a `menu` or `panel`. */
+  readonly run?: (context: CommandContext) => void | Promise<unknown>;
+}
+//#endregion
+//#region src/plugin-settings.d.ts
+/** What a plugin factory takes, or `never` for a factory that takes nothing. */
+type ConfigOf<Factory extends (...args: never[]) => unknown> = Parameters<Factory> extends [] ? never : NonNullable<Parameters<Factory>[0]>;
+/** What the viewer adds to the stamp plugin's settings, for its own panel and toolbar. Read once. */
+interface ViewerStampSettings {
+  /**
+   * Where the standard stamps come from: `true`, the copy that ships inside your build (a lazy
+   * chunk, loaded when the stamps panel first opens); a URL with a `{locale}` slot, used exactly
+   * as given; `false`, none and no request. Default `true`.
+   */
+  readonly standard?: boolean | string;
+  /**
+   * Stamps shown as buttons in the Insert toolbar, each as `library:name`: `standard` is the
+   * standard stamps (`'standard:Approved'`), any other library goes by its id. Default none.
+   */
+  readonly quick?: readonly string[];
+  /** The kinds of library the stamps panel lists. Default `['stamps']`. */
+  readonly sidebar?: readonly string[];
+}
+/**
+ * A font for typed signatures: its TrueType or OpenType file, from `url` or as `data`, read and
+ * registered on the engine the first time someone types a mark in the signature maker.
+ */
+interface SignatureFont {
+  /** The engine's key for it. */
   readonly key: string;
-  /** Where the TTF/OTF bytes come from (same-origin or CORS-enabled). */
-  readonly url: string;
-  /** The picker's label. */
+  /** What the font picker shows. */
   readonly label: string;
-  /** Family / style refinements for fallback matching; inferred from the file
-   *  when omitted. */
+  /** Where the file comes from (same-origin or CORS-enabled). */
+  readonly url?: string;
+  /** The file's bytes, in place of `url`. */
+  readonly data?: Uint8Array | ArrayBuffer;
+}
+/** What the viewer adds to the signature plugin's settings, for its own panel and dialogs. Read once. */
+interface ViewerSignatureSettings {
+  /** Which marks people keep. Default both. */
+  readonly kinds?: readonly ('signature' | 'initials')[];
+  /** Fonts for typed signatures, in the order the maker offers them. Default three handwriting fonts. */
+  readonly fonts?: readonly SignatureFont[];
+  /** `'one'`: a single person per browser, so no new person once one exists. Default `'many'`. */
+  readonly libraries?: 'one' | 'many';
+}
+/** The settings each built-in plugin takes in `plugins`: what its factory takes. */
+interface BuiltInSettings {
+  readonly stage: Omit<ConfigOf<typeof stagePlugin>, 'id' | 'token'>;
+  readonly thumbnails: Omit<ConfigOf<typeof stagePlugin>, 'id' | 'token'>;
+  readonly render: ConfigOf<typeof renderPlugin>;
+  readonly link: never;
+  readonly selection: ConfigOf<typeof selectionPlugin>;
+  readonly search: ConfigOf<typeof searchPlugin>;
+  readonly annotation: ConfigOf<typeof annotationPlugin>;
+  readonly stamp: ConfigOf<typeof stampPlugin> & ViewerStampSettings;
+  readonly measurement: ConfigOf<typeof measurementPlugin>;
+  readonly redaction: ConfigOf<typeof redactionPlugin>;
+  readonly form: ConfigOf<typeof formPlugin>;
+  readonly signature: ConfigOf<typeof signaturePlugin> & ViewerSignatureSettings;
+  readonly pageEdit: never;
+  readonly metadata: never;
+  readonly actions: ConfigOf<typeof actionsPlugin>;
+  readonly documents: never;
+  readonly interaction: ConfigOf<typeof interactionPlugin>;
+  readonly commands: ConfigOf<typeof commandsPlugin>;
+  readonly shell: never;
+  readonly i18n: ConfigOf<typeof i18nPlugin>;
+}
+/** A built-in plugin's settings, as its page in the headless docs lists them. */
+type PluginSettings<Name extends PluginName> = BuiltInSettings[Name];
+/**
+ * The `plugins` config: a built-in plugin's settings under its name (`stage: { spread: 'odd' }`),
+ * and a plugin of your own as its definition under a name of your choice
+ * (`analytics: analyticsPlugin()`), which `viewer.get('analytics')` then finds.
+ */
+type ViewerPluginsConfig = { readonly [Name in PluginName]?: PluginSettings<Name>; } & {
+  readonly [name: string]: object | undefined;
+};
+//#endregion
+//#region src/config-context.d.ts
+/**
+ * A font beyond the standard 14, for the engine: what `engine.fonts` lists. The style panel
+ * offers it for text boxes, once it's registered on the engine and mounted for the live editor.
+ */
+interface ViewerFont {
+  /** The id a free-text `fontFamily` carries, and the engine's key for it. Not one of the 14 standard names. */
+  readonly key: string;
+  /** Where the TTF or OTF file comes from (same-origin or CORS-enabled). */
+  readonly url?: string;
+  /** The file's bytes, in place of `url`. */
+  readonly data?: Uint8Array | ArrayBuffer;
+  /** The family's name, which the style panel shows (else the key); inferred from the file when left out. */
   readonly familyName?: string;
   readonly weight?: number;
   readonly italic?: boolean;
 }
-interface AnnotationsCustomization {
-  /**
-   * Fonts the free-text style panel offers beyond the standard 14. Each is
-   * fetched once when the viewer mounts, registered on the viewer's engine
-   * under its `key`, and mounted as a `@font-face` of the same name — so the
-   * DOM editor shows the face the appearance stream will bake. A font whose
-   * URL fails is skipped with a console warning. On the cloud engine (no
-   * `engine.fonts`) they are not offered: fonts there are a server policy.
-   */
-  readonly fonts?: ReadonlyArray<AnnotationFontSpec>;
+/** What `onPanelResize` hears: the panel, and the width the user gave it. */
+interface PanelResizeEvent {
+  /** The panel's id. */
+  readonly id: string;
+  /** Its width now, in px. */
+  readonly width: number;
 }
 //#endregion
-//#region src/handle.d.ts
-/** `get`/`tryGet` bound to one document (see {@link ViewerHandle.forDocument}). */
-interface ScopedViewerHandle {
-  get<T>(token: CapabilityToken$1<T>): T;
-  tryGet<T>(token: CapabilityToken$1<T>): T | null;
+//#region src/features.d.ts
+/** Every built-in feature and its parts: the names `disable` takes, as All features lists them. */
+declare const FEATURE_PARTS: {
+  readonly annotations: readonly ["highlight", "markup", "drawing", "text", "notes", "links"];
+  readonly shapes: readonly [];
+  readonly stamps: readonly [];
+  readonly comments: readonly ["writing"];
+  readonly forms: readonly ["filling", "building"];
+  readonly signatures: readonly ["signing", "checking"];
+  readonly redaction: readonly [];
+  readonly measurement: readonly [];
+  readonly pages: readonly [];
+  readonly attachments: readonly ["adding"];
+  readonly text: readonly ["selection", "copy"];
+  readonly search: readonly [];
+  readonly thumbnails: readonly [];
+  readonly outline: readonly [];
+  readonly documents: readonly ["open", "download", "print", "tabs"];
+};
+type FeatureParts = typeof FEATURE_PARTS;
+/** A built-in feature, or a part of one: `'annotations'`, `'annotations.highlight'`. */
+type Feature = { [Name in keyof FeatureParts]: Name | `${Name}.${FeatureParts[Name][number]}`; }[keyof FeatureParts];
+/** What `readOnly` keeps on: every feature it would turn off, minus these. */
+interface ReadOnlyExceptions {
+  readonly except: readonly (Feature | (string & {}))[];
 }
-interface ViewerHandle extends ScopedViewerHandle {
-  /** The document registry — the tab model: list/open/close/setActive/…. */
-  readonly documents: DocumentsCapability$1;
-  /** `get`/`tryGet` with document-scoped tokens bound to `documentId`
-   *  instead of the active document. */
-  forDocument(documentId: string): ScopedViewerHandle;
-  /**
-   * Re-run `select` on every kernel change; call `cb` when the selected value
-   * really changed (`isEqual`, default `Object.is` — capability getters return
-   * stable references between model changes, so identity works). Returns the
-   * unsubscribe. This is the ONLY reactivity primitive; DOM events on the
-   * element are sugar over it.
-   */
-  watch<T>(select: () => T, cb: (value: T, previous: T) => void, isEqual?: (a: T, b: T) => boolean): Unsubscribe$1;
-  execute(id: string, documentId?: string): void;
-  resolve(id: string, documentId?: string): ResolvedCommand$1 | null;
-  /** `watch` sugar for one command's resolved state (label/icon/enabled/active). */
-  watchCommand(id: string, cb: (cmd: ResolvedCommand$1 | null) => void): Unsubscribe$1;
-}
-declare function createViewerHandle(kernel: Kernel): ViewerHandle;
 //#endregion
 //#region src/ui/theme.d.ts
 type ThemeMode = 'light' | 'dark';
 type ThemePreference = ThemeMode | 'system';
+/**
+ * The viewer's look, by name: each is the CSS variable `--epdf-<name>`, which the chrome's
+ * stylesheet declares with a default for each mode and mixes every other shade from.
+ */
+declare const THEME_TOKENS: readonly ["accent", "background", "surface", "surface-raised", "text", "text-muted", "border", "hover", "canvas", "radius", "font"];
+/** A token's name: `surface` is the CSS variable `--epdf-surface`. */
+type ThemeToken = (typeof THEME_TOKENS)[number];
+/** Token values by name, each a CSS value: `{ surface: '#fbfaf7', radius: '2px' }`. */
+type ThemeTokens = { readonly [Name in ThemeToken]?: string; };
+interface ThemeConfig {
+  /** 'system' (default) follows the OS. */
+  preference?: ThemePreference;
+  /** The accent color in both modes: the same as `tokens.accent`, which wins when both are set. */
+  accent?: string;
+  /** Token values for both modes, over the viewer's defaults. */
+  tokens?: ThemeTokens;
+  /** Token values for dark mode only, over `tokens`. */
+  dark?: ThemeTokens;
+}
+/** Normalize the shorthand — deliveries use this to read one shape. */
+declare const themeConfigOf: (theme: ThemePreference | ThemeConfig | undefined) => ThemeConfig;
+/**
+ * The CSS that applies a theme's tokens on the viewer's root (`root`, a selector), for a sheet
+ * after the chrome's: its tokens win over the defaults in both modes by coming later, and its
+ * dark ones win in dark by naming the class too. A value is a default only: the page's own
+ * `--epdf-*` variable still wins, read on the host as the chrome's stylesheet does. Empty when
+ * the theme sets no token.
+ */
+declare function themeTokenCss(theme: ThemePreference | ThemeConfig | undefined, root: string): string;
+//#endregion
+//#region src/ui/placed-components.d.ts
+interface PlacedComponentBase {
+  /** The element in the page. */
+  readonly host: HTMLElement;
+  /** Its shadow root, where the viewer draws it. */
+  readonly root: ShadowRoot;
+  /** An icon by name, the viewer's or yours. */
+  readonly icon: string | null;
+  /** Its name, for its tooltip and screen readers. */
+  readonly label: string | null;
+}
+/** `<epdf-button>`: a command's button, or one with an icon and a label of your own. */
+interface PlacedButton extends PlacedComponentBase {
+  readonly kind: 'button';
+  readonly command: string | null;
+}
+/** `<epdf-menu>`: a button that opens a menu of its rows. */
+interface PlacedMenu extends PlacedComponentBase {
+  readonly kind: 'menu';
+  readonly items: readonly PlacedMenuItem[];
+}
+/** `<epdf-menu-item>`: a row, a command's or one with an icon and text of your own. */
+interface PlacedMenuItem {
+  readonly command: string | null;
+  readonly icon: string | null;
+  /** Its text; a command's label when it has none. */
+  readonly label: string;
+  /** Says the row was picked (the element's `select` event). */
+  readonly select: () => void;
+}
+type PlacedComponent = PlacedButton | PlacedMenu;
+/** The viewer's own components placed in one viewer. */
+interface PlacedComponents {
+  /** Every one placed, in the order they were placed. */
+  list(): readonly PlacedComponent[];
+  /** Calls `listener` whenever the list changes. */
+  subscribe(listener: () => void): () => void;
+  /** Places a component, or replaces the one with the same `host`. */
+  place(component: PlacedComponent): void;
+  /** Takes the component of `host` away. */
+  remove(host: HTMLElement): void;
+}
+declare function createPlacedComponents(): PlacedComponents;
 //#endregion
 //#region src/viewer.d.ts
 /**
@@ -127,50 +557,85 @@ type ThemePreference = ThemeMode | 'system';
  * framework wrapper. See README.md for the ladder this implements.
  */
 interface ViewerCustomization {
-  /** ADDITIVE over the default vocabulary; a colliding id overrides. */
-  commands?: readonly CommandDef$1[];
-  /** ADDITIVE 24×24 stroke icons by name; a colliding name overrides. */
+  /**
+   * Your commands, beside the built-in ones. One with a built-in id changes that one, field by
+   * field: what it leaves out stays. A shortcut of yours wins over a built-in one with the same
+   * keys.
+   */
+  commands?: readonly CommandDef[];
+  /** Your icons by name: 24×24 path data. One with a built-in icon's name replaces it. */
   icons?: Readonly<Record<string, IconDef>>;
-  /** Per-locale translation overrides/additions; dotted keys expand. A code
-   *  with no built-in pack becomes a new locale (falls back to English). */
+  /**
+   * Words by language code, over the viewer's own: a built-in button's label under its command's
+   * id (`'document:download'`), your own keys (`labelKey`, `titleKey`), dotted keys expanded. A
+   * code the viewer has no language for becomes one, falling back to English, and reads right to
+   * left when its code's script does (`fa`, `ur`).
+   */
   strings?: Readonly<Record<string, TranslationDictionary>>;
-  /** 'auto' (default) negotiates from the browser languages. */
+  /** 'auto' (default) negotiates from the browser languages. Follows its prop. */
   locale?: 'auto' | (string & {});
-  /** Feature gating: a disabled category vanishes from every surface. */
-  disabledCategories?: readonly string[];
-  /** The structure — a value you OWN: the default (pass nothing), a transform
-   *  of it, or your own schema. Never merged. */
-  chrome?: ChromeSchema$1 | ((base: ChromeSchema$1, helpers: ChromeHelpers$1) => ChromeSchema$1);
-  /** The stamps sidebar's built-in library. `false`: none (air-gapped, no
-   *  request). A string: a URL template with a `{locale}` slot for a
-   *  self-hosted copy of `@embedpdf/default-stamps`. Default: the copy that
-   *  ships with the viewer, as a lazy chunk of your own build — no CDN. */
-  stamps?: StampsCustomization;
-  /** Digital signatures: the signer, trust anchors, the mode (sign / visual /
-   *  ask), which marks a person keeps, and script faces for typed marks. With
-   *  no signer, a mark placed on a field is drawn in without sealing. */
-  signatures?: SignaturesCustomization;
-  /** Annotations: fonts the free-text style panel offers beyond the standard
-   *  14 — fetched, registered on the engine and mounted for the live editor. */
-  annotations?: AnnotationsCustomization;
-  /** Light/dark preference (string shorthand), or the full theme config with
-   *  `--ep-*` token overrides. Tokens are applied by the DELIVERY (the custom
-   *  element adopts them into its shadow root); direct consumers of this
-   *  package set the `--ep-*` variables in their own CSS instead. */
+  /**
+   * What this viewer doesn't have, everywhere at once: features (`'annotations'`), their parts
+   * (`'annotations.highlight'`) and single commands (`'tool:highlight'`: a name with a colon).
+   * Follows its prop.
+   */
+  disable?: readonly (Feature | (string & {}))[];
+  /**
+   * Every feature that changes the document off, or all of them but `except`, on top of
+   * `disable`. Only the interface: plugins keep working for your code. Follows its prop.
+   */
+  readOnly?: boolean | ReadOnlyExceptions;
+  /**
+   * What the user may do: the permissions the engine checks on every call, from a button or
+   * from code. Left out, they may do everything. Documents opened after a change use the new one.
+   */
+  scope?: readonly string[];
+  /** Who the user is: the author of what they write. */
+  identity?: Identity$1;
+  /** What the scope doesn't allow: `'hide'` it (default), or `'disable'` it with the reason. */
+  notAllowed?: NotAllowedMode$1;
+  /**
+   * Where every toolbar, button, menu and panel goes: a layout of your own, or a function that
+   * gets the default layout and the viewer's env (`size`, `width`, `touch`, `dir`) and returns
+   * yours. The function runs again when the env changes. Never merged.
+   */
+  layout?: LayoutOption$1;
+  /**
+   * Each plugin's settings, by the plugin's name, as its page in the headless docs lists them
+   * (`stage: { spread: 'odd' }`), over the viewer's own; and a plugin of your own as its
+   * definition (`analytics: analyticsPlugin()`), which `viewer.get('analytics')` then finds.
+   * Where the viewer's own keys set a plugin's settings too, both count and each only takes
+   * away: the plugin's `disabledCategories` and `disabledCommands` add to what `disable` and
+   * `readOnly` turn off, and its `editable` and `fillable` keep only what both allow. A list of
+   * definitions (`annotation.tools`, `commands.commands`, `i18n.locales`) adds to the viewer's.
+   * The language is `locale`'s, and `notAllowed`, when given, wins over the plugin's. `stamp`
+   * and `signature` also take settings only the viewer has: the standard and quick stamps, and
+   * which marks people keep and their fonts. Read once.
+   */
+  plugins?: ViewerPluginsConfig;
+  /** Light/dark preference (string shorthand), or the full theme config: the
+   *  accent and the other tokens. Tokens are applied by the delivery (the
+   *  custom element adopts them into its shadow root); direct
+   *  consumers of this package set the `--epdf-*` variables in their own CSS
+   *  instead. Follows its prop. */
   theme?: ThemePreference | ThemeConfig;
+  /**
+   * Called with the `viewer` once it's live, before any document has opened: capabilities
+   * resolve from then on, and document-scoped calls wait for their document. Read once.
+   */
+  onReady?: (viewer: Viewer) => void;
+  /**
+   * Called with the active document's id whenever it changes: the first document that opens,
+   * a switch to another tab, and `null` once the last one closes. Read once.
+   */
+  onDocumentChange?: (documentId: string | null) => void;
+  /**
+   * Called when the user has resized a panel, with its id and new width in px: once a drag of
+   * its edge ends, and on each arrow key there. Keep the width to start the panel at it next
+   * time (`layout.panel(id, { width: { initial } })`). Read once.
+   */
+  onPanelResize?: (event: PanelResizeEvent) => void;
 }
-/** Token overrides — names WITHOUT the `--ep-` prefix ('accent', 'surface'…). */
-type ThemeTokens = Readonly<Record<string, string>>;
-interface ThemeConfig {
-  /** 'system' (default) follows the OS. */
-  preference?: ThemePreference;
-  /** Applied in BOTH modes (a later sheet: wins over the defaults). */
-  tokens?: ThemeTokens;
-  /** Dark-mode-only overrides, applied over `tokens`. */
-  dark?: ThemeTokens;
-}
-/** Normalize the shorthand — deliveries use this to read one shape. */
-declare const themeConfigOf: (theme: ThemePreference | ThemeConfig | undefined) => ThemeConfig;
 interface FullViewerProps extends ViewerCustomization {
   /** Instance (borrowed) or thunk (viewer-owned) — the Viewer's own contract. */
   engine: Engine$1 | EngineFactory$1;
@@ -178,17 +643,45 @@ interface FullViewerProps extends ViewerCustomization {
   initialDocuments?: InitialDocument$1[];
   /** Shown while the workspace boots. Default: a translated pulse line. */
   fallback?: ReactNode;
-  /** Where the theme's `.dark` class goes — a DELIVERY concern, not user
+  /** Where the theme's `.dark` class goes — a delivery concern, not user
    *  config: the custom element passes its shadow wrapper so theming never
    *  touches the host page. Default: document.documentElement. */
   themeTarget?: HTMLElement | null;
-  /** Called once the workspace kernel is live, with the viewer handle — the
-   *  DRIVE surface (`el.viewer` on the custom element, `onReady` on the
-   *  wrappers). Capabilities resolve from the moment this fires; document-
-   *  scoped calls simply await their document. */
-  onViewer?: (viewer: ViewerHandle) => void;
+  /**
+   * The viewer's own components placed in the page (`<epdf-button>`, `<epdf-menu>`), which the
+   * viewer draws — a delivery concern: the custom element passes the ones inside it.
+   */
+  components?: PlacedComponents;
+  /**
+   * Fonts beyond the standard 14 for the engine (a delivery's `engine.fonts`): each is read
+   * once, registered on a local engine and mounted for the live text editor, and the style
+   * panel offers it. A cloud engine's fonts are its server's, so none are offered there.
+   */
+  fonts?: readonly ViewerFont[];
 }
-declare function FullViewer({ engine, initialDocuments, fallback, commands, icons, strings, locale, disabledCategories, chrome, stamps, signatures, annotations, theme, themeTarget, onViewer }: FullViewerProps): import("react/jsx-runtime").JSX.Element;
+declare function FullViewer({ engine, initialDocuments, fallback, commands, icons, strings, locale, disable, readOnly, scope, identity, notAllowed, layout, plugins: pluginsConfig, fonts, theme, themeTarget, components, onReady, onDocumentChange, onPanelResize }: FullViewerProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/ui/item-context.d.ts
+/** The place of the bar an item sits in: an edge, floating over the pages, or over a selection. */
+type ToolbarItemEdge = 'top' | 'bottom' | 'start' | 'end' | 'float' | 'selection';
+/** Where your own toolbar item sits. */
+interface ToolbarItemContext {
+  /** Which way the bar runs. */
+  readonly orientation: 'horizontal' | 'vertical';
+  /** The bar's place. */
+  readonly edge: ToolbarItemEdge;
+  /** Which of the item's `variants` the toolbar picked, or null for an item without its own. */
+  readonly variant: string | null;
+  /** The viewer's size. */
+  readonly size: ViewerSize$1;
+}
+/** The attribute each field of a {@link ToolbarItemContext} is written to. */
+declare const TOOLBAR_ITEM_CONTEXT_ATTRIBUTES: {
+  readonly orientation: "data-orientation";
+  readonly edge: "data-edge";
+  readonly variant: "data-variant";
+  readonly size: "data-size";
+};
 //#endregion
-export { type AddItemSpec, type AnnotationFontSpec, AnnotationToken, type AnnotationsCustomization, type BarChild, type BarGroup, type BarItem, type BarSchema, type BarSections, type CapabilityToken, type ChromeHelpers, type ChromeSchema, type CommandDef, CommandsToken, type CustomItem, type DocInfo, type DocumentsCapability, DocumentsToken, type Engine, type EngineFactory, FormToken, FullViewer, type FullViewerProps, I18nToken, type IconDef, type Importance, type InitialDocument, InteractionToken, type Mark, type MenuSchema, type MenuSection, MetadataToken, type PathSpec, RedactionToken, type ResolvedCommand, type ScopedViewerHandle, SearchToken, SelectionToken, ShellToken, type SignFieldInput, type SignatureMode, SignatureToken, type SignaturesCustomization, type SignerPort, StageToken, StampToken, type StampsCustomization, type ThemeConfig, type ThemeMode, type ThemePreference, type ThemeTokens, type TrustPort, type Unsubscribe, type Variant, type ViewerCustomization, type ViewerHandle, addItem, chromeHelpers, createTestSigner, createViewerHandle, custom, defaultChrome, defaultCommands, ICON_PATHS as defaultIcons, defineChrome, group, indexedDbKeyStore, item, memoryKeyStore, personalSigner, remoteSigner, removeItems, replaceItem, themeConfigOf, validateChrome, webCryptoSigner };
+export { ActionsToken, type AddItemOptions, AnnotationToken, type BarEdge, type BarPlace, type CapabilityToken, type CommandContext, type CommandDef, type CommandsCapability, CommandsToken, type DocumentInfo, type DocumentsCapability, DocumentsToken, type Engine, type EngineFactory, type Feature, type FloatPosition, FormToken, FullViewer, type FullViewerProps, I18nToken, type IconDef, type IconName, type IconPaths, type Identity, type Importance, type InitialDocument, InteractionToken, type Layout, type LayoutBar, type LayoutCommandItem, type LayoutCustomItem, type LayoutData, type LayoutEnv, type LayoutFunction, type LayoutGroup, type LayoutGroupObject, type LayoutItem, type LayoutMenu, type LayoutMenuSection, type LayoutOption, type LayoutPanel, type LayoutPanelPatch, type LayoutSection, LinkToken, type Mark, type MeasurementCapability, type MeasurementConfig, MeasurementToken, MetadataToken, type NotAllowedMode, PageEditToken, type PanelPresentation, type PanelPresentationBySize, type PanelResizeEvent, type PanelWidth, type PathSpec, type PlacedButton, type PlacedComponent, type PlacedComponents, type PlacedMenu, type PlacedMenuItem, type PluginName, type PluginSettings, type PluginTokens, type ReadOnlyExceptions, RedactionToken, type RemoveItemOptions, RenderToken, type ResolvedCommand, type ScaleChangeReport, type ScopedViewer, SearchToken, type SectionName, type SelectionTarget, SelectionToken, ShellToken, type SignFieldInput, type SignatureFont, type SignatureMode, SignatureToken, type SignerPort, StageToken, StampToken, THEME_TOKENS, TOOLBAR_ITEM_CONTEXT_ATTRIBUTES, type TabsVisibility, type ThemeConfig, type ThemeMode, type ThemePreference, type ThemeToken, type ThemeTokens, type ToolbarItemContext, type ToolbarItemEdge, type TrustPort, type Unsubscribe, VIEWER_PLUGINS, type Variant, type Viewer, type ViewerCustomization, type ViewerFont, type ViewerLifetime, type ViewerPlugins, type ViewerPluginsConfig, type ViewerSignatureSettings, type ViewerSize, type ViewerStampSettings, createLayout, createPlacedComponents, createTestSigner, createViewer, defaultCommands, ICON_PATHS as defaultIcons, defaultLayout, indexedDbKeyStore, memoryKeyStore, personalSigner, remoteSigner, themeConfigOf, themeTokenCss, webCryptoSigner };
 //# sourceMappingURL=index.d.ts.map