@paged-media/plugin-sdk 0.2.6-canary.0 → 0.2.8-canary.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { PagedBundle, BundleHost, Disposable, ShellSurface, PagedEditor, PluginManifest, CanvasPointerEvent, Mutation, MutationOutcome, ToolContribution, PanelContribution } from '@paged-media/plugin-api';
+import { PagedBundle, FontFaceAsset, BundleHost, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, Disposable, ShellSurface, WidgetSurface, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome } from '@paged-media/plugin-api';
+import { ComponentType } from 'react';
 
 /**
  * Identity helper that pins a bundle to the `PagedBundle` contract
@@ -8,36 +9,6 @@ import { PagedBundle, BundleHost, Disposable, ShellSurface, PagedEditor, PluginM
  */
 declare function defineBundle(bundle: PagedBundle): PagedBundle;
 
-interface HarnessOptions {
-    /** IDML bytes to load into the headless document. */
-    idml?: Uint8Array;
-}
-/** Not implemented in API v0 — see module comment. */
-declare function createHeadlessHost(_options?: HarnessOptions): BundleHost;
-
-declare class DisposableStore implements Disposable {
-    private items;
-    private disposed;
-    get isDisposed(): boolean;
-    /** Track `d`; returns it for chaining. */
-    add<T extends Disposable>(d: T): T;
-    dispose(): void;
-}
-/** Wrap a plain cleanup function as a Disposable. */
-declare function toDisposable(fn: () => void): Disposable;
-
-/** The plugin API version this SDK implements. */
-declare const API_VERSION = "0.2.0";
-/**
- * Does `version` satisfy `range`? Supported forms:
- *   `*`            — anything
- *   `1.2.3` / `1.2`— exact (missing patch = 0)
- *   `^1.2.3`       — npm caret: same major, >= base (major > 0);
- *                    same major+minor, >= patch (major == 0 — the 0.x
- *                    rule: minors are breaking during incubation)
- */
-declare function satisfiesApiVersion(range: string, version?: string): boolean;
-
 /** 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[];
@@ -46,6 +17,27 @@ declare const HOST_FEATURES: readonly string[];
 declare class PluginApiNotImplemented extends Error {
     constructor(member: string, pointer: string);
 }
+/**
+ * Thrown (in `capabilityMode: 'enforce'`) when a bundle USES a host
+ * door it did not DECLARE in its manifest — the trust-line record's
+ * (W0.11) "manifest capabilities ENFORCED, not advisory" gate, applied
+ * at the chokepoint. Same loud-honesty style as the namespace gate: the
+ * message names the door, the missing declaration, and where to add it.
+ *
+ * v1 stance (in-process, no isolation): this is HONESTY +
+ * accident-prevention, not a security boundary — a bundle holding the
+ * raw `host.editor` handle can still bypass the facade. The error makes
+ * declaration↔use drift loud during dogfooding so the manifest stays a
+ * truthful description of what the bundle actually touches.
+ */
+declare class PluginCapabilityError extends Error {
+    /** The host door that was called (e.g. `"contribute.tool"`). */
+    readonly door: string;
+    /** The manifest declaration that would authorize it (e.g.
+     *  `'contributes.tools[] must include "media.paged.web.tool.pen"'`). */
+    readonly missingDeclaration: string;
+    constructor(door: string, missingDeclaration: string, pluginId: string);
+}
 /** Minimal storage backing so tests / headless hosts can inject one;
  *  defaults to localStorage when present, else an in-memory Map. */
 interface StorageBacking {
@@ -55,14 +47,168 @@ interface StorageBacking {
     /** All keys currently in the backing (unfiltered). */
     keys(): string[];
 }
+/** The host-provided network consent primitive (paged.data D-03; base-idea §11).
+ *  The editor owns the consent UI (the visible data-source manifest) and the
+ *  CSP `connect-src` enforcement; this hook is how the host adapter asks the
+ *  user. When absent, `host.network.requestConsent` DENIES every origin (the
+ *  honest no-consent posture) and `supports("network.consent@1")` is false. */
+interface ConsentBackend {
+    request(origins: readonly string[], purpose: string): Promise<ConsentResult>;
+}
+/**
+ * A host-side aggregator the editor injects to power a PROBLEMS PANEL
+ * (paged.web W-05): every `host.diagnostics.set/clear` is mirrored
+ * here keyed by `(bundleId, key)`, so one editor surface can list
+ * diagnostics across all loaded bundles. The per-bundle in-host store
+ * (`host.diagnostics.get`) is unchanged — this is a fan-out, not a
+ * replacement. `bundleId` lets the panel attribute + de-dupe and
+ * lets click-to-focus resolve the owning panel.
+ */
+interface DiagnosticsSink {
+    publish(bundleId: string, key: string, diagnostics: Diagnostic[]): void;
+    clear(bundleId: string, key?: string): void;
+}
+/** Asset-store budgets (W-06). The per-face cap mirrors the wasm lane's
+ *  per-artifact ceiling (DESIGN.md §10/§13.3) — a bundle can never be
+ *  handed an unbounded face buffer. The host facade refuses an
+ *  over-budget face (returns `null` + a `log.warn`). */
+declare const ASSET_BUDGETS: {
+    /** Largest font face the door will serve, in bytes (8 MiB). */
+    readonly maxFontFaceBytes: number;
+};
+/**
+ * The byte source the editor injects to back `host.assets` (W-06). The
+ * same injection shape as `widgets`/`diagnosticsSink`: a value the host
+ * app passes at `loadBundle` time. It serves the bytes the DOCUMENT
+ * already holds for a face — READ-ONLY, never a network fetch on the
+ * bundle's behalf (offline-forever, DESIGN.md §13.3). Returning `null`
+ * is the honest no-bytes answer (an unregistered family, or — in v1 of
+ * the editor adapter — every family, until the engine exposes a
+ * font-bytes read-back; DESIGN.md §13.4).
+ */
+interface BundleAssetProvider {
+    /** The bytes of a document font face, or `null` when the host has
+     *  none. Style-agnostic when `style` is omitted. */
+    getFontFace(family: string, style?: string): Promise<FontFaceAsset | null>;
+}
+/** Blob-store budgets (K-4 / S-08). The default per-plugin quota when a
+ *  manifest requests none; a manifest's `storage.quotaBytes` may only
+ *  TIGHTEN it (the adapter enforces the stricter). */
+declare const BLOB_BUDGETS: {
+    /** Default per-plugin blob ceiling, in bytes (64 MiB). */
+    readonly defaultQuotaBytes: number;
+};
+/**
+ * The backend the editor injects to back `host.blob` (K-4 / S-08): a
+ * RAW per-plugin byte store (OPFS in-browser; an in-memory map in the
+ * headless harness). The SDK adapter owns namespacing (passes the
+ * plugin id), the capability gate, and the quota — the backend only does
+ * scoped IO. Keys are opaque strings the adapter forwards verbatim.
+ */
+interface BlobStore {
+    write(pluginId: string, key: string, bytes: Uint8Array): Promise<void>;
+    read(pluginId: string, key: string): Promise<Uint8Array | null>;
+    delete(pluginId: string, key: string): Promise<void>;
+    keys(pluginId: string): Promise<string[]>;
+    /** Total bytes this plugin currently stores. */
+    used(pluginId: string): Promise<number>;
+}
+/** 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
+ *  rendezvous through it. The per-plugin capability gate lives in the host
+ *  surface; this backend is the neutral store + fan-out. */
+interface DataProviderBackend {
+    register(registration: DataProviderRegistration): DataProviderHandle;
+    discover(category?: string): readonly DataProviderInfo[];
+    get(id: string): Promise<DataProviderSnapshot | null>;
+    onDidChange(id: string, listener: (revision: string) => void): Disposable;
+}
+/** Build a shared in-memory data-provider registry (D-09). The editor holds ONE
+ *  and injects it into every `createBundleHost` call as `options.dataProviders`;
+ *  providers and consumers (different plugin hosts) meet through it. Reference
+ *  implementation — an RPC/isolate host swaps a proxy with the same contract. */
+declare function createDataProviderRegistry(): DataProviderBackend;
 interface CreateBundleHostOptions {
     storage?: StorageBacking;
+    /** Host-provided network consent (paged.data D-03; base-idea §11): the editor
+     *  injects the consent prompt + the data-source-manifest UI. When absent,
+     *  `host.network` denies every origin and `supports("network.consent@1")` is
+     *  false (the honest no-consent posture). */
+    consent?: ConsentBackend;
+    /** Host-provided SHARED 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 and a consumer rendezvous
+     *  through it. When absent, `host.dataProviders` discover() is empty +
+     *  register() is a no-op and `supports("dataProviders@1")` is false. */
+    dataProviders?: DataProviderBackend;
     /** Console sink override (tests). */
     console?: Pick<Console, "debug" | "info" | "warn" | "error">;
     /** Shell actions the HOST APP owns (the cockpit's panel placement).
      *  When absent, `host.shell` warns and no-ops, and
      *  `supports("shell.openPanel@1")` answers false. */
     shell?: ShellSurface;
+    /** Host-provided panel widgets (W-04): the real code editor lives in
+     *  the editor's UI package and is injected here. When absent,
+     *  `host.widgets` is the plain-textarea fallback and
+     *  `supports("widgets.codeEditor@1")` answers false. */
+    widgets?: WidgetSurface;
+    /** Host-provided SCHEMA-PANEL renderer (W3.1): the editor's
+     *  `SchemaPanelRenderer` that walks a `PanelSchema` through the
+     *  catalog + subscribes to the bundle's bindings. When absent,
+     *  `contribute.schemaPanel` registers a visible "needs a host
+     *  renderer" seam panel (never a throw, never fake UI) and
+     *  `supports("contribute.schemaPanel@1")` still answers true (the
+     *  door exists; only the rich rendering is host-injected). */
+    schemaPanelRenderer?: SchemaPanelRenderer;
+    /** Internal registration hook (the headless harness): called at the
+     *  moment a schema panel registers, with the verbatim contribution,
+     *  so the conformance log can record the SCHEMA assertably (the
+     *  registry only sees the synthesized React `PanelContribution`). The
+     *  returned disposer (if any) is tracked alongside the panel
+     *  registration. Not part of the public contract — a host-adapter
+     *  seam. */
+    onSchemaPanelRegistered?: (contribution: SchemaPanelContribution) => Disposable | void;
+    /** Internal registration hook (the headless harness, W3.2): called
+     *  when an EDIT CONTEXT registers (after the namespace + capability
+     *  gates pass), with the verbatim contribution, so the conformance log
+     *  can record it. When the editor provides no `editContexts` registry,
+     *  this is ALSO the recording stub's only consumer — the door no
+     *  longer throws, it records. Not part of the public contract. */
+    onEditContextRegistered?: (contribution: EditContextContribution) => Disposable | void;
+    /** Internal registration hook (the headless harness, W3.2): the
+     *  object-type analogue of `onEditContextRegistered`. */
+    onObjectTypeRegistered?: (contribution: ObjectTypeContribution) => Disposable | void;
+    /** Host-side problems-panel aggregator (W-05). When present,
+     *  `supports("diagnostics.publish@1")` answers true and every
+     *  `host.diagnostics.set/clear` fans out to it. */
+    diagnosticsSink?: DiagnosticsSink;
+    /** Host-provided ASSET byte source (W-06). When present,
+     *  `host.assets.getFontFace` serves DOCUMENT font face bytes through
+     *  it (capability-gated, budget-clamped) and
+     *  `supports("assets.fonts@1")` answers true. When absent, every
+     *  asset read answers `null` (the honest no-bytes door) and the
+     *  feature flag is false. */
+    assetSource?: BundleAssetProvider;
+    /** Host-provided BLOB backend (K-4 / S-08). When present,
+     *  `host.blob.*` persists per-plugin bytes through it (capability-
+     *  gated, quota-clamped) and `supports("storage.blob@1")` answers true.
+     *  When absent, reads answer empty and writes reject (the honest
+     *  no-store door). */
+    blobStore?: BlobStore;
+    /**
+     * How the host treats a declaration↔use mismatch — a bundle that
+     * USES a door (`contribute.tool`, `document.mutate`, …) it did not
+     * DECLARE in its manifest (trust-line W0.11). Defaults to
+     * `'enforce'`: the violating call throws `PluginCapabilityError`
+     * (contribution registrations) or returns a non-applied
+     * `MutationOutcome` for the write doors (mutate-never-throws). In
+     * `'warn'` mode the violation is logged through `host.log.warn`
+     * and the call proceeds — the migration escape hatch for a host
+     * that loads not-yet-adopted manifests. The namespace gate and the
+     * metadata-namespace gate are UNAFFECTED — they are always loud.
+     */
+    capabilityMode?: "enforce" | "warn";
 }
 interface BundleHostHandle {
     host: BundleHost;
@@ -71,6 +217,214 @@ interface BundleHostHandle {
 }
 declare function createBundleHost(getEditor: () => PagedEditor, manifest: PluginManifest, options?: CreateBundleHostOptions): BundleHostHandle;
 
+/** The published package the headless harness boots. */
+declare const CANVAS_WASM_PKG = "@paged-media/canvas-wasm";
+/**
+ * The wasm `CanvasWorker` surface the harness drives. A structural
+ * subset of the package's class — only the members the headless host
+ * needs. `handleMessage` is the JSON-envelope door; `loadDocumentDirect`
+ * is the binary side-channel for IDML bytes (the editor uses it to dodge
+ * the 8× `number[]` JSON inflation, and it is the only load path that
+ * does not require a `LoadDocument` envelope round-trip).
+ */
+interface HeadlessCanvasWorker {
+    readonly protocolVersion: number;
+    handleMessage(input: string): string;
+    loadDocumentDirect(seq: number, bytes: Uint8Array, font?: Uint8Array, cmykIccProfile?: Uint8Array): string;
+    runResolveJson(): string | undefined;
+    free(): void;
+}
+interface LoadedEngine {
+    worker: HeadlessCanvasWorker;
+    /** The resolved package version (`0.<protocol>.<patch>`). */
+    version: string;
+    /** The wasm's reported protocol (the package minor). */
+    protocolVersion: number;
+}
+interface LoadHeadlessEngineOptions {
+    /**
+     * Where to resolve `@paged-media/canvas-wasm` from. Defaults to this
+     * module's own resolution (the SDK's node_modules), then the editor's
+     * `packages/client` (the sibling-checkout dev luxury) — mirroring
+     * scripts/sync-wire.mjs so the loader and the wire stamp agree on
+     * WHICH installed package they describe.
+     */
+    resolveFrom?: string;
+    /**
+     * Override the expected protocol the booted wasm must report. Defaults
+     * to the protocol derived from the vendored wire stamp. A mismatch
+     * throws — never silently downgrades.
+     */
+    expectedProtocol?: number;
+}
+/** Extract `@<version>` from the vendored wire stamp, or null. Async:
+ *  the file read pulls `node:fs`, deferred so the browser barrel stays
+ *  import-safe (only the Node headless path ever calls this). */
+declare function readVendoredWireVersion(wireDtsPath?: string): Promise<string | null>;
+/** The package minor IS the wire protocol (`0.<protocol>.<patch>`). */
+declare function protocolFromVersion(version: string): number | null;
+/**
+ * Resolve the published package's loader JS + `_bg.wasm` on disk.
+ * Throws (never warn-skips) when the package cannot be resolved: a
+ * headless host with no engine behind it is the exact fiction the
+ * harness exists to prevent (B-13).
+ */
+declare function resolveCanvasWasm(resolveFrom?: string): Promise<{
+    loaderUrl: string;
+    wasmPath: string;
+    version: string;
+    dir: string;
+}>;
+/**
+ * Boot the published engine wasm in Node and return a `CanvasWorker`
+ * driving the editor's own dispatch. Asserts the booted protocol
+ * matches the vendored wire stamp.
+ */
+declare function loadHeadlessEngine(options?: LoadHeadlessEngineOptions): Promise<LoadedEngine>;
+
+/** One captured contribution — the assertable conformance log entry.
+ *  `kind` is the surface; `value` is the contribution object verbatim
+ *  (so a test can assert ids, titles, shortcuts, dock edges, …). */
+interface RecordedContribution {
+    kind: "tool" | "panel" | "schemaPanel" | "command" | "keybinding" | "overlay" | "editContext" | "objectType" | "importer" | "exporter";
+    id: string;
+    value: ToolContribution | PanelContribution | SchemaPanelContribution | CommandContribution | KeybindingContribution | OverlayContribution | EditContextContribution | ObjectTypeContribution | ImporterContribution | ExporterContribution;
+}
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore"> {
+}
+/** What `createHeadlessHost` resolves to: a real engine-backed host plus
+ *  the conformance affordances (load an IDML, read the contribution log,
+ *  load a bundle, dispose honestly). */
+interface HeadlessHost {
+    /** The BundleHost a bundle's `activate(host)` receives. */
+    readonly host: BundleHost;
+    /** The booted package version (`0.<protocol>.<patch>`). */
+    readonly engineVersion: string;
+    /** The wasm's reported protocol (the package minor). */
+    readonly protocolVersion: number;
+    /** Every contribution registered through `host.contribute.*`, in
+     *  registration order. Cleared structurally on dispose. */
+    readonly contributions: readonly RecordedContribution[];
+    /** Contributions of one surface (e.g. `tools()` for the rail). */
+    toolsContributed(): ToolContribution[];
+    panelsContributed(): PanelContribution[];
+    /** Declarative (schema) panels registered through
+     *  `contribute.schemaPanel` — the W3.1 surface, recorded verbatim. */
+    schemaPanelsContributed(): SchemaPanelContribution[];
+    /** Edit contexts registered through `contribute.editContext` — the
+     *  W3.2 surface (B-02), recorded verbatim (matcher fn included). */
+    editContextsContributed(): EditContextContribution[];
+    /** Object types registered through `contribute.objectType` — the W3.2
+     *  surface (W-03), recorded verbatim. */
+    objectTypesContributed(): ObjectTypeContribution[];
+    /** Document importers registered through `contribute.importer` (K-2 /
+     *  S-06), recorded verbatim (extensions + the `import()` callback). */
+    importersContributed(): ImporterContribution[];
+    /** Document exporters registered through `contribute.exporter` (K-2 /
+     *  S-06), recorded verbatim. */
+    exportersContributed(): ExporterContribution[];
+    /** The last tool preview a bundle pushed through
+     *  `host.overlay.setToolPreview` (B-07). There is no overlay SURFACE
+     *  headlessly, but the channel is RECORDED so conformance can assert a
+     *  pen/anchor handler emits the cubic `ToolPreviewPath` variant (true
+     *  Béziers) rather than a flattened polyline. `null` until set, and
+     *  reset to `null` when the bundle clears its preview. */
+    lastToolPreview(): ToolPreviewShape | null;
+    /** 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[]>;
+    /** 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()`. */
+    loadBundle(bundle: PagedBundle): Disposable;
+    /** Tear down: bundle teardown + facade teardown + free the wasm. The
+     *  honesty contract — after dispose the contribution log is empty and
+     *  the engine handle is released. */
+    dispose(): void;
+}
+/** Reserved alias kept for source/back-compat — see `createHeadlessHost`. */
+type HeadlessHostHandle = HeadlessHost;
+/**
+ * Build a headless, engine-backed `BundleHost`. Async because booting
+ * the wasm is async. The returned handle drives the conformance loop:
+ * load an IDML, activate a bundle, assert its contribution log, run real
+ * mutations, and dispose honestly.
+ *
+ * Resolves B-13 (RESOLVED + residuals — see module header). Replaces the
+ * v0 throw: the harness now stands on a real engine, so a bundle can no
+ * longer "pass against fiction".
+ */
+declare function createHeadlessHost(options?: HarnessOptions): Promise<HeadlessHost>;
+
+declare class DisposableStore implements Disposable {
+    private items;
+    private disposed;
+    get isDisposed(): boolean;
+    /** Track `d`; returns it for chaining. */
+    add<T extends Disposable>(d: T): T;
+    dispose(): void;
+}
+/** Wrap a plain cleanup function as a Disposable. */
+declare function toDisposable(fn: () => void): Disposable;
+
+/** The plugin API version this SDK implements. */
+declare const API_VERSION = "0.2.0";
+/**
+ * Does `version` satisfy `range`? Supported forms:
+ *   `*`            — anything
+ *   `1.2.3` / `1.2`— exact (missing patch = 0)
+ *   `^1.2.3`       — npm caret: same major, >= base (major > 0);
+ *                    same major+minor, >= patch (major == 0 — the 0.x
+ *                    rule: minors are breaking during incubation)
+ */
+declare function satisfiesApiVersion(range: string, version?: string): boolean;
+
+/** The default widget catalog: a textarea CodeEditor. Replaced wholesale
+ *  when the host app injects `widgets` into `createBundleHost`. */
+declare const FALLBACK_WIDGETS: WidgetSurface;
+
+/** One recorded `getFontFace` call. */
+interface RecordedFontFaceRequest {
+    family: string;
+    style?: string;
+}
+/** A seeded face the fake serves. `family` match is case-insensitive
+ *  (the document registry and CSS often differ only in casing). When
+ *  `style` is given on a seed, the request must match it; a seed with no
+ *  style answers any style request for that family. */
+interface SeededFace extends FontFaceAsset {
+    /** When set, the seed only answers a request for this exact style. */
+    matchStyle?: string;
+}
+interface RecordableAssetSource extends BundleAssetProvider {
+    /** Every `getFontFace` call, in order. */
+    readonly requests: readonly RecordedFontFaceRequest[];
+}
+/**
+ * Build a recordable, in-memory asset source from a set of seeded
+ * faces. Families match case-insensitively; a seed carrying
+ * `matchStyle` only answers that style. Unknown families resolve to
+ * `null` (the honest no-bytes answer). Every call is recorded.
+ */
+declare function createRecordableAssetSource(seeds?: readonly SeededFace[]): RecordableAssetSource;
+
+/**
+ * Resolve a schema visibility / enablement gate against a published-
+ * bindings LOOKUP — the host-side evaluation (B-01: a lookup, NOT an
+ * expression language). Rules:
+ *   · absent gate → `true` (always shown / enabled);
+ *   · literal boolean → itself;
+ *   · `{ bind }` → `Boolean(lookup(bind))`, a MISSING name reads
+ *     `false` (a visible seam, never a throw);
+ *   · `{ bind, negate: true }` → the inverse (the ONE transform — a
+ *     NOT, not a DSL).
+ * Shared by the editor's `SchemaPanelRenderer` and the conformance
+ * tests so the two can't drift.
+ */
+declare function resolveGate(gate: SchemaGate | undefined, lookup: (name: string) => unknown): boolean;
+/** Build the registry `component` for a schema panel. */
+declare function makeSchemaPanelComponent(contribution: SchemaPanelContribution, bindings: BindingsSurface, renderer: SchemaPanelRenderer | undefined): ComponentType<PanelProps>;
+
 interface LoadedBundle {
     readonly id: string;
     readonly active: boolean;
@@ -78,6 +432,81 @@ interface LoadedBundle {
 }
 declare function loadBundle(getEditor: () => PagedEditor, bundle: PagedBundle, options?: CreateBundleHostOptions): LoadedBundle;
 
+/** WASM packaging budgets (v1). Rationale in docs/wasm-packaging.md.
+ *  KEEP IN SYNC with plugin-cli's WASM_MAX_* and the schema's `maxBytes`
+ *  maximum — the CLI hand-mirrors the contract. */
+declare const WASM_BUDGETS: {
+    /** Hard per-artifact byte ceiling. A release-optimised wasm layout
+     *  engine (Blitz-class) lands in the low-single-digit MiB; 8 MiB
+     *  rejects an accidentally-bundled debug build while leaving headroom
+     *  for one real engine. A manifest `maxBytes` may only TIGHTEN this. */
+    readonly maxArtifactBytes: number;
+    /** Total declared wasm across one bundle. Bounds a bundle that ships
+     *  several modules (engine + a codec, say). */
+    readonly maxTotalBytes: number;
+    /** Wall-clock budget for fetch + compile + instantiate. Protects the
+     *  editor's main flow from a pathological module; advisory, the loader
+     *  aborts with a clear error when exceeded. */
+    readonly loadTimeBudgetMs: 3000;
+    /** Linear-memory growth ceiling, in 64 KiB wasm pages (4096 = 256 MiB).
+     *  Passed as `WebAssembly.Memory({ maximum })` when the host owns the
+     *  memory; a per-page layout pass should sit far under this. */
+    readonly maxMemoryPages: 4096;
+};
+/** A loaded bundle wasm module + the resources the host owns for it. */
+interface LoadedBundleWasm {
+    /** The artifact descriptor it was loaded from. */
+    artifact: WasmArtifact;
+    module: WebAssembly.Module;
+    instance: WebAssembly.Instance;
+    /** The host-owned, non-shared memory the module was given (when the
+     *  host provided one — see `provideMemory`). */
+    memory?: WebAssembly.Memory;
+    /** Compiled byte length (post-budget-check, for telemetry). */
+    byteLength: number;
+}
+/** How the loader reads a bundle-relative asset. The host supplies this
+ *  (a URL fetch rooted at the bundle's asset base in the browser; a file
+ *  read in Node/tests). The loader passes ONLY the declared `path`. */
+type BundleAssetSource = (path: string) => Promise<Uint8Array> | Uint8Array;
+interface LoadBundleWasmOptions {
+    /** Reads the declared artifact's bytes (required). */
+    assetSource: BundleAssetSource;
+    /**
+     * The host grant. A wasm artifact loads only if the host has granted
+     * it — `"*"` grants all declared artifacts; a `Set`/array grants by
+     * name. ABSENT means NO grant (refuse): wasm is opt-in, never ambient.
+     */
+    grant?: "*" | ReadonlyArray<string> | ReadonlySet<string>;
+    /**
+     * Import object handed to the module at instantiation. The loader adds
+     * NOTHING implicitly — if `provideMemory` is true and the imports omit
+     * `env.memory`, a host-owned bounded `WebAssembly.Memory` is injected;
+     * otherwise the module is on its own (no ambient engine/DOM/network).
+     */
+    imports?: WebAssembly.Imports;
+    /**
+     * When true (default), the loader owns linear memory: it creates a
+     * non-shared `WebAssembly.Memory` bounded by `maxMemoryPages` and
+     * injects it as `imports.env.memory` if not already present. Set false
+     * to let a module declare its own (still non-shared) memory.
+     */
+    provideMemory?: boolean;
+    /** Initial pages for the host-owned memory (default 16 = 1 MiB). */
+    initialMemoryPages?: number;
+    /** Override the load-time budget (ms). */
+    loadTimeBudgetMs?: number;
+    /** Clock injection for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Load a bundle-declared wasm artifact, enforcing declared-only access,
+ * the host grant, and the v1 budgets. Resolves to the instantiated
+ * module; rejects (loudly) on an undeclared name, a missing grant, an
+ * over-budget artifact, or a load-time overrun.
+ */
+declare function loadBundleWasm(bundle: PagedBundle, name: string, options: LoadBundleWasmOptions): Promise<LoadedBundleWasm>;
+
 declare const CLICK_DRAG_THRESHOLD_PX = 4;
 /** A drag anchored to the page under the pointer at pointer-down. */
 interface PageDrag {
@@ -104,5 +533,24 @@ declare function commitAndSelect(paged: PagedEditor, mutation: Mutation, label:
 declare function contributeTool(host: BundleHost, tool: ToolContribution): Disposable;
 
 declare function contributePanel(host: BundleHost, panel: PanelContribution): Disposable;
+/** Register a DECLARATIVE panel (W3.1, B-01): the host renders the
+ *  schema from the catalog and subscribes to this bundle's published
+ *  bindings (`host.bindings`) for visibility/enablement. No React
+ *  crosses the boundary — the isolate-ready panel form. Same namespace
+ *  + capability gate as `contributePanel` (`contributes.panels[]` must
+ *  list the id). */
+declare function contributeSchemaPanel(host: BundleHost, panel: SchemaPanelContribution): Disposable;
+
+/** 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
+ *  write-scope, Esc pops. Capability-gated on `contributes.editContexts`.
+ */
+declare function contributeEditContext(host: BundleHost, contribution: EditContextContribution): Disposable;
+/** Register an OBJECT TYPE (W-03): a plugin-defined object (a webFrame
+ *  is a rectangle with attached source metadata). A double-click on a
+ *  matching element enters its `editContextType` instead of group
+ *  descent. Capability-gated on `contributes.objectTypes`. */
+declare function contributeObjectType(host: BundleHost, contribution: ObjectTypeContribution): Disposable;
 
-export { API_VERSION, type BundleHostHandle, CLICK_DRAG_THRESHOLD_PX, type CreateBundleHostOptions, DisposableStore, HOST_FEATURES, type HarnessOptions, type LoadedBundle, type PageDrag, PluginApiNotImplemented, type StorageBacking, beginPageDrag, commitAndSelect, contributePanel, contributeTool, createBundleHost, createHeadlessHost, defineBundle, endLocalFor, loadBundle, pxToPt, satisfiesApiVersion, toDisposable };
+export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type SeededFace, type StorageBacking, WASM_BUDGETS, beginPageDrag, commitAndSelect, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };