@paged-media/plugin-sdk 0.2.42-canary.0 → 0.2.45-canary.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PagedBundle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, MutationInput, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, OpenDocumentResult, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, EnteredEditContext, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome, BindingProviderHandle } from '@paged-media/plugin-api';
+import { PagedBundle, ParsedAddress, ElementId, MutationInput, MutationOutcome, ObjectErrorCode, ObjectKindInfo, PropertySchema, ObjectValue, ObjectOp, PagedEditor, ObjectsSurface, ObjectModelContribution, PartsSurface, PluginLogger, ObjectModelHandle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, OpenDocumentResult, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, EnteredEditContext, ValueType, ObjectCommandInfo, PropertyPath, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, PanelSchemaPropertyRow, PanelSchemaRow, PropertyFieldAddress, PanelSchema, ValueEdit, Address, ListEdit, StructEdit, ObjectWriteResult, BindingProviderHandle } from '@paged-media/plugin-api';
 import { ComponentType } from 'react';
 
 /**
@@ -9,6 +9,167 @@ import { ComponentType } from 'react';
  */
 declare function defineBundle(bundle: PagedBundle): PagedBundle;
 
+/** Parse an address (ADR 131); `null` when it is not one. Never throws. */
+declare function parseAddress(text: string): ParsedAddress | null;
+/** Format a parsed address in its CANONICAL form (aliases never emitted). */
+declare function formatAddress(a: ParsedAddress): string;
+/** Canonicalise an address string; `null` when it does not parse. */
+declare function normalizeAddress(text: string): string | null;
+/** The QUALIFIED kind an address belongs to for schema/routing purposes:
+ *  `frame` for every page item, `story` for ranges, `page` for `page:#n`,
+ *  `plugin:<id>/<kind>` for plugin objects. */
+declare function addressKindOf(a: ParsedAddress): string;
+/** The `ElementId` today's wire carries for an address, or `null` when the
+ *  wire has no form for it (layers, swatches, pages, the document… — the
+ *  forms core's `Set` will carry as strings). Tables and cells need their
+ *  owning story, which only a resolver knows: see core-objects.ts. */
+declare function toElementId(a: ParsedAddress): ElementId | null;
+/** The canonical address of a wire `ElementId` (total, ADR 131). */
+declare function fromElementId(id: ElementId): string;
+type SelectorHead = {
+    type: "address";
+    address: ParsedAddress;
+} | {
+    type: "kind";
+    kind: string;
+} | {
+    type: "any";
+};
+interface SelectorPredicate {
+    key: string;
+    op: "=" | "!=" | "^=" | "*=";
+    value: string;
+}
+interface SelectorStep {
+    /** How this step relates to the previous one (absent on the first). */
+    combinator?: "child" | "descendant";
+    head: SelectorHead;
+    predicates: SelectorPredicate[];
+    /** `:nth(n)`, 1-based. */
+    nth?: number;
+}
+interface ParsedSelector {
+    steps: SelectorStep[];
+}
+/** Parse a selector (ADR 131); `null` when it is not one. Never throws. */
+declare function parseSelector(text: string): ParsedSelector | null;
+
+/** A core write plan: the ops, or a typed refusal. */
+type CorePlan = {
+    ok: true;
+    mutations: MutationInput[];
+} | {
+    ok: false;
+    code: ObjectErrorCode;
+    reason: string;
+};
+/** A core `create` plan (protocol 71). `address` is the new object's
+ *  address when its id is known up front (a swatch, a style, a text
+ *  variable), else `$h:<handle>`; `resolve` names the object after the
+ *  commit (a minted page item, page or layer). `kind` is the SDK kind the
+ *  rows of later ops on `$h:<handle>` come from. */
+type CoreCreatePlan = {
+    ok: true;
+    mutations: MutationInput[];
+    kind: string;
+    address: string;
+    /** Props the create op does not carry: set on the new object. */
+    props?: Record<string, unknown>;
+    resolve?: (outcome: MutationOutcome) => Promise<string | null>;
+} | {
+    ok: false;
+    code: ObjectErrorCode;
+    reason: string;
+};
+/** The core backend the registry routes to. */
+interface CoreObjects {
+    /** The engine protocol this seam speaks, once known (feature-detected
+     *  on first use; the registry awaits it before reading rows). */
+    ready?(): Promise<number>;
+    kinds(): ObjectKindInfo[];
+    schema(kind: string): PropertySchema[];
+    get(a: ParsedAddress, path: string): Promise<ObjectValue>;
+    /** Plan a write (value already schema-validated). `kind` names the SDK
+     *  kind of a `$h:` handle address made earlier in the same batch. */
+    planSet(a: ParsedAddress, path: string, value: unknown, kind?: string): Promise<CorePlan>;
+    /** Plan a `create` of a core object (protocol 71). `handle` binds the
+     *  new object for later ops of the same batch. */
+    planCreate?(op: Extract<ObjectOp, {
+        op: "create";
+    }>, handle: string): Promise<CoreCreatePlan>;
+    /** Plan a `delete` of a core object. */
+    planDelete?(a: ParsedAddress): Promise<CorePlan>;
+    /** The wire `ElementId` of an address (labels go here). */
+    elementIdOf(a: ParsedAddress): Promise<ElementId | null>;
+    /** The `x-paged:` labels on a label HOST — a page item, a story (range),
+     *  a page or the document — as key → raw value; null when the address
+     *  is not a label host or does not exist. */
+    labelsOf(a: ParsedAddress): Promise<Record<string, string> | null>;
+    /** The mutation that sets (`value`) or clears (`null`) one plugin label
+     *  on a label host: `setPluginMetadata` (item / story), `setPageMetadata`
+     *  (page, protocol 70) or `setDocumentMetadata` (doc); null when the
+     *  address is not a label host. */
+    planLabel(a: ParsedAddress, key: string, value: string | null, caller: string): Promise<MutationInput | null>;
+    /** Evaluate core selector steps (no plugin steps). */
+    query(steps: readonly SelectorStep[]): Promise<string[]>;
+    /** Commit mutations as ONE engine mutation (a `batch` when > 1). */
+    commit(mutations: readonly MutationInput[]): Promise<MutationOutcome>;
+    /** Pre-71 only: remember a table's story (a `cell:` address carries
+     *  none; the old wire's `TableCell` id needs it). A no-op at 71. */
+    noteTableStory?(tableId: string, storyId: string): void;
+    /** Engine changes (mutation / undo / redo / load). */
+    onDidChange(listener: () => void): () => void;
+    /** Drop derived caches (a host that loads without a broadcast). */
+    invalidate(): void;
+    /** Release the engine subscription (a private, per-host backend). */
+    dispose(): void;
+}
+interface CreateCoreObjectsOptions {
+    /** The engine's protocol, when the caller knows it (skips the probe). */
+    protocol?: number | (() => number | undefined);
+}
+/** The first protocol with `Set` / `RequestGet` / `RequestQuery`. */
+declare const OBJECT_MODEL_PROTOCOL = 71;
+/**
+ * The core seam over a live engine. Feature-detects the engine protocol
+ * and delegates to the protocol-71 seam or the pre-71 table.
+ */
+declare function createCoreObjects(getEditor: () => PagedEditor, options?: CreateCoreObjectsOptions): CoreObjects;
+/** Every item kind word a selector may use for core frames. */
+declare const FRAME_KIND_WORDS: readonly string[];
+
+/** What a plugin host hands the registry at registration. */
+interface ObjectModelRegistration {
+    plugin: string;
+    model: ObjectModelContribution;
+    /** The plugin's OWN parts door — `state` writes land in its namespace. */
+    parts?: PartsSurface;
+    log?: PluginLogger;
+}
+/** The shared registry: the ungated `ObjectsSurface` (what the host app,
+ *  the harness and the CLI call) plus the adapter-side `register`. */
+interface ObjectRegistry extends ObjectsSurface {
+    register(registration: ObjectModelRegistration): ObjectModelHandle;
+    /** The core backend, when one is wired (null = plugin objects only). */
+    readonly core: CoreObjects | null;
+    /** A view of this registry whose writes report each engine commit they
+     *  make (its `appliedSeq`) to `note` — including the writes a plugin
+     *  command's handler makes, since an `invoke` through the view hands the
+     *  handler the same view. Writes through any other surface (a panel, a
+     *  UI edit made meanwhile) are never reported. The script bridge answers
+     *  a round through one, so the host can send exactly the script's own
+     *  writes as `HostObjectsResult.committed` (protocol 71). */
+    tracked(note: (appliedSeq: number) => void): ObjectsSurface;
+}
+interface CreateObjectRegistryOptions {
+    core?: CoreObjects | null;
+    log?: Pick<PluginLogger, "warn">;
+}
+/** Non-ASCII → `\uXXXX`, as InDesign keeps label values (survey,
+ *  2026-10-06); still valid JSON. */
+declare function escapeLabelValue(text: string): string;
+declare function createObjectRegistry(options?: CreateObjectRegistryOptions): ObjectRegistry;
+
 /** The implemented feature set — `host.supports()` answers from this,
  *  so docs/tests can't drift from code. Form: `"area.member@major"`. */
 declare const HOST_FEATURES: readonly string[];
@@ -273,6 +434,18 @@ interface DocumentsBackend {
         };
     }): Promise<OpenDocumentResult>;
 }
+/**
+ * v70 — the backend the editor injects to back `host.viewport`'s page
+ * members. The editor owns the camera and the page layout, so it answers
+ * which page is active and moves the camera to one. No backend →
+ * `goToPage` answers false, `activePage` null, the event never fires and
+ * `supports("viewport.pages@1")` is false.
+ */
+interface PagesBackend {
+    goToPage(pageId: string, fit: "page" | "width"): boolean | Promise<boolean>;
+    activePage(): string | null;
+    onDidChangeActivePage(listener: (pageId: string | null) => void): () => void;
+}
 /** The SHARED cross-plugin data-provider registry (paged.data §7.1 / D-09). The
  *  editor creates ONE (`createDataProviderRegistry`) and injects the SAME
  *  instance into every plugin host, so a provider plugin and a consumer plugin
@@ -408,6 +581,13 @@ interface CreateBundleHostOptions {
      *  (nothing would ever consult the provider) and
      *  `supports("bindings.provider@1")` is false. */
     bindingProviders?: BindingProviderBackend;
+    /** Host-provided SHARED OBJECT REGISTRY (ADR 323): the editor / headless
+     *  host / Node CLI creates ONE (`createObjectRegistry({ core:
+     *  createCoreObjects(getEditor) })`) and injects the SAME instance into
+     *  every plugin host, so `host.objects` routes across bundles. When
+     *  absent, the host builds a PRIVATE registry (core + this bundle's own
+     *  kinds) and `supports("objects.shared@1")` is false. */
+    objects?: ObjectRegistry;
     /** Console sink override.
      *
      *  Originally a test hook, and now ALSO the production capture point: the
@@ -431,6 +611,11 @@ interface CreateBundleHostOptions {
      *  `host.widgets` is the plain-textarea fallback and
      *  `supports("widgets.codeEditor@1")` answers false. */
     widgets?: Partial<WidgetSurface>;
+    /** §12.8 — the host's `PropertyField` (and its schema-panel property
+     *  rows) render LIST and STRUCT values with `items` / `fields`, editing
+     *  through `editValue`. Makes `supports("widgets.propertyField.values@1")`
+     *  true (only together with `widgets.PropertyField`). */
+    propertyFieldValues?: boolean;
     /** The host's will-save registry. When absent, `document.onWillSave`
      *  holds listeners that never run and `supports("document.onWillSave@1")`
      *  is false. */
@@ -515,6 +700,10 @@ interface CreateBundleHostOptions {
      *  `supports("documents.exportPaged@1")` / `supports("documents.open@1")`
      *  answer true. When absent, both doors reject. */
     documents?: DocumentsBackend;
+    /** v70 — page navigation for `host.viewport` (`goToPage`,
+     *  `activePage`, `onDidChangeActivePage`). When present,
+     *  `supports("viewport.pages@1")` is true. */
+    pages?: PagesBackend;
     /** Host-provided WORKER backend (K-3 / S-07 / I-02). When present,
      *  `host.workers.spawn` resolves a declared bundle-relative module +
      *  constructs a host-owned `Worker` through it (capability-gated,
@@ -552,6 +741,75 @@ interface BundleHostHandle {
 }
 declare function createBundleHost(getEditor: () => PagedEditor, manifest: PluginManifest, options?: CreateBundleHostOptions): BundleHostHandle;
 
+/** One call a suspended script makes (core `HostObjectCall`). */
+type HostObjectCall = {
+    op: "get";
+    address: string;
+    path: string;
+} | {
+    op: "batch";
+    ops: unknown[];
+} | {
+    op: "query";
+    selector: string;
+} | {
+    op: "schema";
+    target: string;
+}
+/** A typed command (`paged.invoke`): `core.<op>` or a plugin's. */
+ | {
+    op: "invoke";
+    id: string;
+    args?: unknown;
+}
+/** The typed commands on offer (`paged.commands`), optionally one owner's. */
+ | {
+    op: "commands";
+    owner?: string;
+};
+/** The answer to one call (core `HostObjectAnswer`). */
+interface HostObjectAnswer {
+    value?: unknown;
+    error?: {
+        code: string;
+        reason: string;
+        index?: number;
+    } | null;
+}
+interface ScriptRunResult {
+    output: string[];
+    error: string | null;
+    budgetKind?: string | null;
+    /** Host round trips the script took (0 = it never touched a plugin). */
+    hostRounds: number;
+}
+/** A request/reply door onto the engine (`client.send`). */
+type ScriptSend = (message: {
+    kind: string;
+    payload: unknown;
+}) => Promise<{
+    kind: string;
+    payload?: any;
+}>;
+/** Answer a suspended script's calls through the object registry, one
+ *  answer per call, in order. Never throws: a failure is the answer's
+ *  `error` (the script sees an exception carrying its `code`). */
+declare function answerHostObjects(objects: ObjectsSurface, calls: readonly HostObjectCall[]): Promise<HostObjectAnswer[]>;
+/** {@link answerHostObjects}, plus `committed`: the engine `appliedSeq` of
+ *  every write made ANSWERING these calls (a batch that committed). The
+ *  host sends it as `HostObjectsResult.committed` — protocol 71 folds only
+ *  a script session's own undo records, so without it a script's plugin
+ *  write would be a separate undo step; a write made by anyone else
+ *  while the script waits is never listed and stays its own step. */
+declare function answerHostObjectsRound(objects: ObjectsSurface, calls: readonly HostObjectCall[]): Promise<{
+    answers: HostObjectAnswer[];
+    committed: number[];
+}>;
+/** Run a script whose `plugin:` calls are answered by `objects`. */
+declare function runScriptWithObjects(send: ScriptSend, objects: ObjectsSurface | null, source: string, options?: {
+    budget?: unknown;
+}): Promise<ScriptRunResult>;
+
 /** The published package the headless harness boots. */
 declare const CANVAS_WASM_PKG = "@paged-media/canvas-wasm";
 /**
@@ -633,7 +891,7 @@ interface RecordedContribution {
     id: string;
     value: ToolContribution | PanelContribution | SchemaPanelContribution | CommandContribution | KeybindingContribution | OverlayContribution | EditContextContribution | ObjectTypeContribution | ImporterContribution | ExporterContribution;
 }
-interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets" | "bindingProviders" | "willSave" | "toolSettings"> {
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets" | "bindingProviders" | "dataProviders" | "objects" | "willSave" | "toolSettings"> {
     /** D-27 — back `host.text` with the ENGINE's shaper
      *  (`CanvasWorker.measureText`, the one the editor's worker calls)
      *  instead of the estimate, so `measureString` / `measureStrings`
@@ -739,6 +997,22 @@ interface HeadlessHost {
      *  that a path it does not declare comes back as a typed refusal to
      *  fall through to core). */
     readonly bindingProviders: BindingProviderBackend;
+    /** ADR 323 — the SHARED object registry every bundle host here routes
+     *  through (core addresses over this engine + every loaded bundle's
+     *  kinds). The ungated host side: what the Node CLI, a Boa bridge or a
+     *  conformance test calls. */
+    readonly objects: ObjectRegistry;
+    /** Run a `paged.*` Boa script against the loaded document with the
+     *  async host bridge armed (ADR 323, engine protocol 71): its `plugin:`
+     *  addresses are answered by `objects`, so core and plugin writes of one
+     *  script land as ONE undo step. */
+    runScript(source: string, options?: {
+        budget?: unknown;
+    }): Promise<ScriptRunResult>;
+    /** The SHARED data-provider registry (D-09) injected into every bundle
+     *  host here, so a provider bundle and a consumer bundle rendezvous
+     *  headlessly and `supports("dataProviders@1")` is true. */
+    readonly dataProviders: DataProviderBackend;
     /** The will-save registry this host injected: `fire()` runs every
      *  bundle's `document.onWillSave` listener and awaits them, as a save
      *  would. */
@@ -749,6 +1023,21 @@ interface HeadlessHost {
     /** Load an IDML package into the headless document. Resolves to the
      *  loaded page ids (or throws on a parse failure). */
     load(idml: Uint8Array): Promise<string[]>;
+    /** ADR 324 — the core EXPORT door the Node CLI (and a conformance test)
+     *  calls: the active document as `.paged` (`exportPaged`), `.idml`
+     *  (`exportIdml`, `linkBase` for relative links) or PDF (the
+     *  `exportPdfBegin` → one `exportPdfPage` per page → `exportPdfFinish`
+     *  loop the editor's client drives; `pdf` is the wire's
+     *  `ExportPdfWireOptions`). Rejects with the engine's error. Plugin
+     *  formats go through `exportersContributed()`. */
+    exportDocument(format: "paged" | "idml" | "pdf", options?: {
+        pdf?: Record<string, unknown>;
+        linkBase?: string | null;
+    }): Promise<{
+        bytes: Uint8Array;
+        diagnostics: string[];
+        lost?: string[];
+    }>;
     /** D-26 — every document a bundle opened through `host.documents.open`,
      *  in order (declined opens are not listed). */
     openedDocuments(): ReadonlyArray<{
@@ -756,9 +1045,11 @@ interface HeadlessHost {
         requester: string;
         pageIds: string[];
     }>;
-    /** Activate a bundle against this host (apiVersion-negotiated). The
-     *  returned disposer runs the bundle's teardown; the host's own
-     *  facade teardown runs on `dispose()`. */
+    /** Activate a bundle against this host (apiVersion-negotiated). Several
+     *  bundles may be loaded at once (each gets its own host bound to its
+     *  manifest; they meet through the shared registries — objects, data
+     *  providers, binding providers). `host` is the LAST loaded bundle's.
+     *  The returned disposer runs that bundle's teardown. */
     loadBundle(bundle: PagedBundle): Disposable;
     /** Tear down: bundle teardown + facade teardown + free the wasm. The
      *  honesty contract — after dispose the contribution log is empty and
@@ -802,6 +1093,168 @@ declare const API_VERSION = "0.2.0";
  */
 declare function satisfiesApiVersion(range: string, version?: string): boolean;
 
+declare const VALUE_TYPE_KINDS: readonly ["bool", "number", "length", "color", "enum", "text", "ref", "bounds", "transform", "point", "bytes", "asset", "list", "map", "struct"];
+/** Why `t` is not a well-formed `ValueType`, or null. */
+declare function checkValueType(t: unknown, at?: string): string | null;
+/**
+ * Path grammar of a schema ROW: dotted identifiers, each optionally
+ * followed by bracket segments. `[]` makes an INDEXED row (`points[]`,
+ * `points[].anchor`, `ranges[][]`) that stands for every `points[3]` /
+ * `cells[B4]` a caller names; its type is the type of ONE item at that
+ * index. A concrete index (`colorize[0]`) is an ordinary row and wins
+ * over the indexed one.
+ */
+declare const ROW_PATH: RegExp;
+/** The row path a concrete path resolves to: every `[<index>]` becomes
+ *  `[]` (`points[3].anchor` → `points[].anchor`). Bracket contents may be
+ *  any text without `]` (a list index, a map key such as `x-paged:oid`). */
+declare function rowPathOf(path: string): string;
+/** Find the row for a concrete path: exact first, then its indexed form. */
+declare function findRow<R extends {
+    path: string;
+}>(rows: ReadonlyMap<string, R>, path: string): R | null;
+/** Why a schema row list is unusable (empty, malformed, duplicate path). */
+declare function checkSchemaRows(rows: unknown): string | null;
+/** Why `value` does not satisfy `type` (and the row's range / nullable), or
+ *  null when it does. */
+declare function validateValue(type: ValueType, value: unknown, row?: Pick<PropertySchema, "nullable" | "range">, at?: string): string | null;
+/** Bytes → the `data:` URI core reads an asset back as (the MIME typed by
+ *  the bytes' magic, the same table core uses; otherwise
+ *  `application/octet-stream`). */
+declare function assetFromBytes(bytes: Uint8Array | ArrayBuffer): string;
+/**
+ * Fill struct DEFAULTS into a value that already validated: a missing
+ * field with a `default` gets it (recursively, also inside lists and
+ * maps); optional fields stay absent. An `asset` given as bytes is
+ * encoded to its `data:` URI. Returns a new value; the input is
+ * not mutated.
+ */
+declare function applyDefaults(type: ValueType, value: unknown): unknown;
+/** Parse a length with an optional unit (`"3mm"`, `"12"`, `"0.5in"`) into
+ *  points; null when it is not one. */
+declare function parseLength(text: string): number | null;
+/**
+ * EXPLICIT coercion of a loosely typed input (a CLI argument, a CSV cell)
+ * to `type`. Returns `{ ok: true, value }` or `{ ok: false, reason }`; the
+ * coerced value is then checked with `validateValue` as usual. Values that
+ * already have the right shape pass through unchanged.
+ */
+declare function coerceValue(type: ValueType, input: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+
+/** An engine error text → the refusal code it means. */
+declare function codeOfEngineError(text: string): ObjectErrorCode;
+
+/** The command id prefix: `core.insertTable`. */
+declare const CORE_COMMAND_PREFIX = "core.";
+/** Wire ops that are NOT typed commands, each with the reason. */
+declare const CORE_COMMAND_EXCLUSIONS: Readonly<Record<string, string>>;
+/** What a creating command makes. `element`: the engine mints it (reported
+ *  in `minted`, bindable by handle) — `multi` mints one per `elementIds`
+ *  entry; `page` / `layer`: found by diffing the page / layer list;
+ *  `named`: the address follows from the args. The Rust side of this table
+ *  is paged-canvas `created_element_id` (and `duplicate_roots`). */
+type Creates = {
+    by: "element";
+    kind: "frame" | "table";
+    multi?: true;
+} | {
+    by: "page";
+} | {
+    by: "layer";
+} | {
+    by: "named";
+    address: (args: Record<string, unknown>) => string | null;
+};
+declare const CORE_COMMAND_CREATES: Readonly<Record<string, Creates>>;
+/** The ops that are typed commands, in wire order. */
+declare const CORE_COMMAND_OPS: readonly string[];
+/** The typed command list (static: it is the vendored wire's). */
+declare function coreCommandInfos(): ObjectCommandInfo[];
+declare const isCoreCommand: (id: string) => boolean;
+
+interface CoreWireOpRow {
+    args: Extract<ValueType, {
+        kind: "struct";
+    }>;
+    nullFill: readonly string[];
+}
+declare const CORE_WIRE_OPS: Readonly<Record<string, CoreWireOpRow>>;
+
+type CorePathScope = "frame" | "story" | "cell" | "table" | "layer" | "page";
+interface CorePathRow {
+    scope: CorePathScope;
+    /** The wire `Value` variant a write carries. */
+    wire: string;
+    type?: ValueType;
+    inferred?: true;
+    readOnly?: true;
+}
+declare const OP: {
+    readonly op: true;
+};
+/** A path the pre-71 wire does not carry: only the protocol-71 seam reaches it. */
+declare const V71: {
+    readonly since: 71;
+};
+declare const CORE_PATHS: Record<PropertyPath, CorePathRow | typeof OP | typeof V71>;
+/** The catalog's advertised ALIASES (Boa names) → the wire path, mirrored
+ *  from `catalog.json` `pathAliases`. Accepted on input, never listed. */
+declare const CORE_PATH_ALIASES: Readonly<Record<string, PropertyPath>>;
+/** One `propertySchemas` row as core's catalog publishes it (protocol 71). */
+interface CoreCatalogRow {
+    addressKind: string;
+    appliesTo?: readonly string[];
+    path: string;
+    type: {
+        kind: string;
+        unit?: string;
+        members?: readonly string[];
+        to?: string;
+        of?: string;
+        shape?: string;
+    };
+    wire: string;
+    nullable?: boolean;
+    range?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    };
+    default?: unknown;
+    access?: "readWrite" | "readOnly" | "derived";
+    virtual?: {
+        op: string;
+        field?: string;
+        clearOp?: string;
+    } | null;
+    bindable?: boolean;
+}
+/** A normalised core row: the SDK schema row, the wire `Value` variant a
+ *  write carries, and the CORE address kind the row belongs to (the SDK
+ *  folds `storyRange` into `story` and `group` into `frame`). */
+interface CoreRow71 {
+    schema: PropertySchema;
+    wire: string;
+    coreKind: string;
+    /** Not in core's catalog: typed from the interim table (CORE_ROWLESS_PATHS). */
+    inferred?: true;
+}
+/** Core's catalog type → the SDK's `ValueType`; null for an OPERATION row
+ *  (path-point edits, outline / offset / simplify): those are geometry
+ *  ops, not values, and stay reachable as a raw wire `{ type, value }`. */
+declare function normalizeCoreType(t: CoreCatalogRow["type"]): ValueType | null;
+/** The raw rows of the vendored catalog (empty before protocol 71). */
+declare const CORE_CATALOG_ROWS: readonly CoreCatalogRow[];
+/** SDK kind → path → normalised row, from the vendored catalog. Indexed
+ *  core paths (`labels[key]`, `rows[i].height`) become `[]` rows. */
+declare function coreSchema71(): ReadonlyMap<string, ReadonlyMap<string, CoreRow71>>;
+
 /** The default widget catalog: a textarea CodeEditor and a native colour
  *  input. Each member is replaced by the one the host app injects through
  *  `createBundleHost({ widgets })`; members it omits keep the fallback. */
@@ -994,6 +1447,108 @@ declare function contributePanel(host: BundleHost, panel: PanelContribution): Di
  *  list the id). */
 declare function contributeSchemaPanel(host: BundleHost, panel: SchemaPanelContribution): Disposable;
 
+/** Is this row an object-model property row (the property row)? */
+declare function isPropertyRow(row: PanelSchemaRow): row is PanelSchemaPropertyRow;
+/** Options shared by the row builders (everything but `field`/`path`/`address`). */
+type PropertyRowOptions = Omit<PanelSchemaPropertyRow, "field" | "path" | "address">;
+/** One property row. */
+declare function propertyRow(path: string, address: PropertyFieldAddress, opts?: PropertyRowOptions): PanelSchemaPropertyRow;
+/** Rows for several paths of one kind, in order. `labels` maps a path to
+ *  its row label (absent = the schema row's title). */
+declare function propertyRows(kind: string, paths: readonly string[], address: PropertyFieldAddress, opts?: {
+    labels?: Readonly<Record<string, string>>;
+    row?: (path: string) => PropertyRowOptions;
+}): PanelSchemaPropertyRow[];
+/** Every property row of a schema, with where it sits. */
+declare function propertyRowsOf(schema: PanelSchema): Array<{
+    section: number;
+    row: number;
+    field: PanelSchemaPropertyRow;
+}>;
+interface PanelSchemaIssue {
+    /** `sections[1].rows[3]` — where the problem is. */
+    at: string;
+    message: string;
+}
+interface ValidatePanelSchemaOptions {
+    /** The schema rows of a qualified kind (`plugin:<id>/<kind>`), or
+     *  `undefined` when unknown. With it, every property row's path is
+     *  checked against its kind's schema. */
+    schemaOf?: (kind: string) => readonly PropertySchema[] | undefined;
+    /** The bundle's plugin id: a `plugin:` kind or address of ANOTHER plugin
+     *  is then reported (a panel edits its own objects or core's). */
+    pluginId?: string;
+}
+/** The qualified kind a selector selects (its last step's head), if any. */
+declare function selectorKind(selector: string): string | null;
+/**
+ * Every problem in a panel schema, as data. An empty list = it renders as
+ * declared. Checks the property rows in full (address form, kind,
+ * path against `schemaOf`) and the v1 rows' one structural rule (a
+ * non-empty widget id).
+ */
+declare function validatePanelSchema(schema: PanelSchema, opts?: ValidatePanelSchemaOptions): PanelSchemaIssue[];
+
+type Ok<T> = {
+    ok: true;
+} & T;
+type No = {
+    ok: false;
+    code: ObjectErrorCode;
+    reason: string;
+};
+/** The value a new item / an unset field starts from: a struct's field
+ *  defaults (required fields without one get their type's default,
+ *  optional ones stay absent), an enum's first member, 0, "", false, [],
+ *  `Color/Black` for a colour, the zero point / identity transform. */
+declare function defaultValueOf(type: ValueType, row?: Pick<PropertySchema, "default" | "range">): unknown;
+/**
+ * Apply one edit to a value of `type` (a list, or a struct for
+ * `fieldSet`). Pure; the result is validated against `type`.
+ */
+declare function applyValueEdit(current: unknown, edit: ValueEdit, type: ValueType): Ok<{
+    value: unknown;
+}> | No;
+type Reader = Pick<ObjectsSurface, "get" | "schema">;
+/**
+ * Lower one edit of `path` on every target to `set` ops (read, apply,
+ * set). Each target is edited from its OWN current value, so a multi-
+ * selection stays per-object. Refusals are typed; no op is produced
+ * unless every target accepts the edit.
+ */
+declare function planValueEdit(objects: Reader, addresses: readonly Address[], path: string, edit: ValueEdit): Promise<Ok<{
+    ops: ObjectOp[];
+}> | No>;
+/** {@link planValueEdit}, then ONE `batch` (one undo step). */
+declare function editValue(objects: Reader & Pick<ObjectsSurface, "batch">, addresses: readonly Address[], path: string, edit: ListEdit | StructEdit, opts?: {
+    label?: string;
+}): Promise<ObjectWriteResult>;
+
+interface ObjectListRow {
+    selfId: Address;
+    name: string;
+    secondary?: string;
+}
+interface PublishObjectListOptions {
+    /** Binding the rows are published under (the list row's `items.bind`). */
+    rows: string;
+    /** Binding holding the chosen address (the list row's
+     *  `selectionBinding`, the property rows' `{ bind }`). */
+    select: string;
+    /** The selector to list, from the selection's addresses; `null` = no
+     *  list (empty rows). E.g. `(sel) => sel.length === 1 ? `${sel[0]} > plugin:x/layer` : null`. */
+    selector(selection: readonly Address[]): string | null;
+    /** Path read for the row label (default `name`; the address id else). */
+    labelPath?: string;
+    /** Path read for the secondary line. */
+    secondaryPath?: string;
+}
+/** Publish the list and keep it live. Dispose to stop. */
+declare function publishObjectList(host: BundleHost, opts: PublishObjectListOptions): Disposable & {
+    /** Re-read now (resolves when published). */
+    refresh(): Promise<void>;
+};
+
 /** Register an EDIT CONTEXT (B-02): a content type that, on
  *  double-click (or programmatically), pushes a scoped context —
  *  restricted tools, emphasized panels, breadcrumb, narrowed
@@ -1021,4 +1576,4 @@ declare function contributeObjectType(host: BundleHost, contribution: ObjectType
  */
 declare function contributeBindingProvider(host: BundleHost, contextType: string, provider: BindingProvider): BindingProviderHandle;
 
-export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BindingProviderBackend, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ClipboardBackend, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, type DocumentsBackend, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type SecretStoreBackend, type SeededFace, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type ToolSettingsBackend, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, beginPageDrag, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBindingProviderRegistry, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, inMemoryToolSettings, inMemoryWillSave, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };
+export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BindingProviderBackend, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, CORE_CATALOG_ROWS, CORE_COMMAND_CREATES, CORE_COMMAND_EXCLUSIONS, CORE_COMMAND_OPS, CORE_COMMAND_PREFIX, CORE_PATHS, CORE_PATH_ALIASES, CORE_WIRE_OPS, type ClipboardBackend, type ConsentBackend, type CoreCatalogRow, type CoreCreatePlan, type CoreObjects, type CorePathRow, type CorePathScope, type CorePlan, type CoreRow71, type CoreWireOpRow, type CreateBundleHostOptions, type CreateCoreObjectsOptions, type CreateObjectRegistryOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, type DocumentsBackend, FALLBACK_WIDGETS, FRAME_KIND_WORDS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type HostObjectAnswer, type HostObjectCall, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, OBJECT_MODEL_PROTOCOL, type ObjectListRow, type ObjectModelRegistration, type ObjectRegistry, type PageDrag, type PagesBackend, type PanelSchemaIssue, type ParsedSelector, PluginApiNotImplemented, PluginCapabilityError, type PropertyRowOptions, type PublishObjectListOptions, ROW_PATH, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type ScriptRunResult, type ScriptSend, type SecretStoreBackend, type SeededFace, type SelectorHead, type SelectorPredicate, type SelectorStep, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type ToolSettingsBackend, VALUE_TYPE_KINDS, type ValidatePanelSchemaOptions, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, addressKindOf, answerHostObjects, answerHostObjectsRound, applyDefaults, applyValueEdit, assetFromBytes, beginPageDrag, checkSchemaRows, checkValueType, codeOfEngineError, coerceValue, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, coreCommandInfos, coreSchema71, createBindingProviderRegistry, createBundleHost, createCoreObjects, createDataProviderRegistry, createHeadlessHost, createObjectRegistry, createRecordableAssetSource, defaultValueOf, defineBundle, editValue, endLocalFor, escapeLabelValue, findRow, formatAddress, fromElementId, inMemoryToolSettings, inMemoryWillSave, isCoreCommand, isPropertyRow, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, normalizeAddress, normalizeCoreType, parseAddress, parseLength, parseSelector, planValueEdit, propertyRow, propertyRows, propertyRowsOf, protocolFromVersion, publishObjectList, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, rowPathOf, runScriptWithObjects, satisfiesApiVersion, selectorKind, toDisposable, toElementId, validatePanelSchema, validateValue };