@paged-media/plugin-api 0.2.17-canary.0 → 0.2.19

package/dist/host.d.ts

@@ -334,6 +334,107 @@ export interface ImagesSurface {
      *  to the whole-image fallback lane). */
     claimImageResource(elementId: string, opts: ImageResourceClaimOptions): Disposable;
 }
+/** Options for `host.workers.spawn` (K-3). `module` is a bundle-relative
+ *  path the host resolves through the bundle's own asset base (the same
+ *  `/@fs/`-allowed sibling path the wasm artifacts use) — never an
+ *  arbitrary URL. `name` is an optional debug label. */
+export interface SpawnWorkerOptions {
+    /** Bundle-relative path to the worker module (an ES-module worker — JS
+     *  or wasm-bindgen worker glue). Resolved through the bundle's asset
+     *  base; a bundle can only spawn a module it ships. */
+    module: string;
+    /** Optional debug label (surfaced in the host log / devtools). */
+    name?: string;
+}
+/**
+ * A host-spawned, bundle-owned worker (K-3). Talk over `post`/`onMessage`
+ * (structured-clone, optional transfer); `allocateShared` hands back a
+ * host-budgeted `SharedArrayBuffer` (or `null` when SAB is unavailable or
+ * the bundle didn't declare `sharedMemory` / would exceed its budget).
+ * `terminate` stops the worker — and the host runs it automatically on
+ * bundle dispose, so a bundle that forgets to terminate still leaks
+ * nothing (the platform-honesty smoke test by construction).
+ */
+export interface BundleWorker {
+    /** Post a message to the worker (structured-clone; `transfer` moves
+     *  ownership of the listed transferables, e.g. an `ArrayBuffer`). */
+    post(message: unknown, transfer?: Transferable[]): void;
+    /** Subscribe to messages FROM the worker. Dispose to stop listening
+     *  (and free the listener); all subscriptions drop on `terminate`. */
+    onMessage(handler: (message: unknown) => void): Disposable;
+    /**
+     * Allocate a `SharedArrayBuffer` of `bytes` for zero-copy hand-off,
+     * host-budgeted against the per-bundle shared-memory ceiling. Returns
+     * `null` when the bundle did not declare `capabilities.workers.
+     * sharedMemory`, the environment is not cross-origin-isolated (SAB is
+     * unconstructible), or the request would exceed the budget — the
+     * honest, frequent answer. Pass the returned buffer through `post` to
+     * share it with the worker.
+     */
+    allocateShared(bytes: number): SharedArrayBuffer | null;
+    /** Stop the worker + drop its listeners. Idempotent; also run by the
+     *  host on bundle dispose. */
+    terminate(): void;
+}
+/**
+ * The capability-gated WORKER door (K-3 / S-07 / I-02). `spawn` resolves
+ * a bundle-relative `module`, constructs a host-owned `Worker`, and tracks
+ * it for automatic teardown. Always present — when the host injects no
+ * `WorkerBackend`, `spawn` REJECTS honestly (no worker realm to give) and
+ * `supports("workers@1")` is false. Capability-gated:
+ * `capabilities.workers` must be declared (the host gate throws on an
+ * undeclared spawn); the granted worker-count cap is
+ * `min(declared.max, hardwareConcurrency, 8)` (read it via `concurrency`).
+ */
+export interface WorkersSurface {
+    /** Spawn `opts.module` (a declared, bundle-relative path) as a
+     *  host-owned `BundleWorker`. Rejects when the use is undeclared
+     *  (capability gate), the host wired no backend, the count cap is
+     *  reached, or the module fails to resolve/construct. */
+    spawn(opts: SpawnWorkerOptions): Promise<BundleWorker>;
+    /** The granted worker-count cap (`min(declared.max, hardwareConcurrency,
+     *  8)`, or 0 when undeclared / no backend) — a bundle sizes its pool to
+     *  this rather than guessing. */
+    concurrency(): number;
+}
+/** The secret a `host.secrets.set` carries (D-11). v1 is a connection
+ *  string / token / password as a UTF-8 string — opaque to the contract;
+ *  the host stores it under the `ref` and injects it at attach/fetch time.
+ *  This is the ONLY place a secret value crosses the door, inbound; there
+ *  is no outbound read (no `get`). */
+export type SecretMaterial = string;
+/**
+ * The capability-gated, REFERENCE-ONLY credential store (D-11;
+ * rfc-credential-store). The plugin maps a source to a `credentialRef`
+ * string and asks the host to `set` (prompting the user), `exists`, or
+ * `forget` it — but it can NEVER read the secret back. `set` resolves once
+ * the host has stored the material (its backing decides whether to prompt;
+ * the editor reference backing PROMPTS — "via host UI only"). Always
+ * present — when the host injects no `SecretStoreBackend`, `set`/`forget`
+ * reject and `exists` answers `false` (the honest no-store door), and
+ * `supports("secrets@1")` is false. Capability-gated:
+ * `capabilities.secrets` must be declared (the host gate throws on an
+ * undeclared use).
+ *
+ * NOTE: this surface has NO `get`. That absence IS the contract (the
+ * trust line — secret bytes never enter the plugin realm); a `get` here
+ * would defeat the entire D-11 design.
+ */
+export interface SecretsSurface {
+    /** Store `secret` under `ref` (the editor backing PROMPTS the user — the
+     *  RFC's "via host UI only"). Rejects when undeclared (capability gate),
+     *  no backend is wired, or the user declines the prompt. The plugin
+     *  keeps only the `ref`. */
+    set(ref: string, secret: SecretMaterial): Promise<void>;
+    /** Does the host hold a secret under `ref`? `false` when none is stored
+     *  OR no backend is wired (the honest no-store answer). A bundle uses
+     *  this to decide whether a source still needs its credential entered. */
+    exists(ref: string): Promise<boolean>;
+    /** Forget the secret under `ref` (the source goes inert until re-entered
+     *  — the RFC's honest degradation). Idempotent; rejects only when the
+     *  door is undeclared (capability gate). A no-op when no backend wired. */
+    forget(ref: string): Promise<void>;
+}
 /** Expected mutation failures are results, not throws — mirroring the
  *  editor's mutate-never-throws convention. */
 export type MutationOutcome = {
@@ -765,6 +866,23 @@ export interface BundleHost {
      *  Disposable and `supports("rendering.resourceProvider@1")` is false.
      *  Capability-gated on `capabilities.rendering` ∋ `"resourceProvider"`. */
     readonly images: ImagesSurface;
+    /** The capability-gated WORKER door (K-3 / S-07 / I-02): spawn a
+     *  host-owned, bundle-owned worker (declared-only module, no ambient
+     *  authority) + allocate a host-budgeted `SharedArrayBuffer`. Always
+     *  present — when the host injects no `WorkerBackend`, `spawn` rejects
+     *  honestly, `concurrency()` is 0, and `supports("workers@1")` is false.
+     *  Capability-gated on `capabilities.workers`. The host facade tracks
+     *  every spawned worker for automatic teardown on bundle dispose. */
+    readonly workers: WorkersSurface;
+    /** The capability-gated, REFERENCE-ONLY CREDENTIAL STORE (D-11;
+     *  rfc-credential-store): `set` (host-UI-prompted) / `exists` / `forget`
+     *  a `credentialRef` — and DELIBERATELY NO `get` (secret bytes never
+     *  enter the plugin realm; the HOST injects them at the attach/fetch
+     *  door). Always present — when the host injects no `SecretStoreBackend`,
+     *  `set`/`forget` reject, `exists` is false, and `supports("secrets@1")`
+     *  is false (the honest no-store door). Capability-gated on
+     *  `capabilities.secrets`. */
+    readonly secrets: SecretsSurface;
     /** The capability-gated CLIPBOARD door (K-6 / S-14): read/write the
      *  SYSTEM clipboard with a rich `{ text?, tabular? }` payload (the
      *  sheets grid's range copy/paste interchange). Always present — when

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, } from "./manifest";
+export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, } from "./manifest";
 export type { BundleHandle, PagedBundle } from "./bundle";
-export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, FrameChainLink, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, StorageSurface, BlobSurface, BlobUsage, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, } from "./host";
+export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, FrameChainLink, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, StorageSurface, BlobSurface, BlobUsage, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, } from "./host";
 export type { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, } from "./panel-schema";
 export type { WidgetSurface, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, } from "./widgets";
 export type { AssetSurface, AssetKind, FontFaceAsset, FontFaceFormat, } from "./assets";

package/dist/manifest.d.ts

@@ -112,6 +112,66 @@ export interface PluginCapabilities {
      * JS. Threads/SharedArrayBuffer are OFF in v1.
      */
     wasm?: WasmArtifact[];
+    /**
+     * Worker spawn + SharedArrayBuffer reach the bundle declares (K-3 /
+     * S-07 / I-02). Gates `host.workers`: a bundle CANNOT spawn a worker
+     * without declaring it, and only modules listed under a declared path
+     * (bundle-relative, like the wasm artifacts) may be spawned — never an
+     * arbitrary URL. `max` is the worker-count ceiling the host grants
+     * (clamped to `min(declared, hardwareConcurrency, 8)`); `sharedMemory`
+     * declares `SharedArrayBuffer` use (gates `allocateShared`; absent ⇒
+     * message-copy only). Declaring `workers` is the prerequisite for the
+     * door (the host gate throws on an undeclared spawn).
+     *
+     * The worker gets NO ambient authority — no engine/DOM/network handle,
+     * only the bundle's already-gated JS talks to it; the SAB is a separate
+     * bundle-owned allocation, host-budgeted (a per-bundle shared-memory
+     * ceiling the host enforces, default 256 MiB, which a manifest
+     * `maxSharedBytes` may only TIGHTEN). v1 stance: honesty +
+     * accident-prevention, not a security boundary (the isolate migration
+     * is the real boundary). See the K-3 design note.
+     */
+    workers?: WorkersCapability;
+    /**
+     * The host CREDENTIAL-STORE door's grant (D-11; rfc-credential-store).
+     * Gates `host.secrets`: a bundle that does not declare `secrets` cannot
+     * reach the store (the host gate throws). `sources: true` is the v1
+     * grant — credentials for authenticated DB-attach / remote sources.
+     *
+     * The store is REFERENCE-ONLY and host-owned: a bundle holds
+     * `credentialRef` strings (e.g. `keychain:source-4`), NEVER secret
+     * material. The surface has `set` (host-UI-prompted) / `exists` /
+     * `forget` and DELIBERATELY NO `get` — secret bytes never enter the
+     * plugin realm. The plugin passes the ref to the host attach/fetch door
+     * and the HOST injects the connection string / Authorization header on
+     * its side of the wire (pairs with the D-03 consent door). See the RFC
+     * and DESIGN.md §16.
+     */
+    secrets?: SecretsCapability;
+}
+/** Credential-store declaration (D-11; rfc-credential-store). `sources`
+ *  gates the `host.secrets` door for authenticated DB-attach / remote
+ *  sources — the v1 (and only) grant. A closed vocabulary so the host can
+ *  reason about it; an absent/false `sources` denies the door. */
+export interface SecretsCapability {
+    /** Grant the credential store for data sources (DB-attach / remote). */
+    sources: boolean;
+}
+/** Worker spawn + SAB declaration (K-3 / S-07). `max` is the requested
+ *  worker-count ceiling (the host clamps to a hard cap); `sharedMemory`
+ *  declares `SharedArrayBuffer` use; `maxSharedBytes`, when present,
+ *  REQUESTS a per-bundle shared-memory ceiling — the host enforces the
+ *  stricter of it and its hard cap. */
+export interface WorkersCapability {
+    /** Worker-count ceiling the bundle requests; the host grants
+     *  `min(max, hardwareConcurrency, 8)`. */
+    max: number;
+    /** Declares `SharedArrayBuffer` use — gates `BundleWorker.allocateShared`.
+     *  Absent/false ⇒ message-copy only (`allocateShared` returns `null`). */
+    sharedMemory?: boolean;
+    /** Optional per-bundle shared-memory ceiling, in bytes. Tightens —
+     *  never widens — the host's hard cap (default 256 MiB). */
+    maxSharedBytes?: number;
 }
 /** Persistent binary-storage declaration (K-4 / S-08). `blob` gates the
  *  OPFS-backed `host.blob` byte store; `quotaBytes` requests a ceiling

package/dist/wire.d.ts

@@ -1,7 +1,7 @@
 // GENERATED — do not edit. Vendored verbatim from the published
 // @paged-media/canvas-wasm .d.ts (tsify output from paged-media/core,
 // MPL-2.0 OR PMEL). Sync: node scripts/sync-wire.mjs · Check: --check.
-// Synced from @paged-media/canvas-wasm@0.44.0
+// Synced from @paged-media/canvas-wasm@0.44.1
 /* tslint:disable */
 /* eslint-disable */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.17-canary.0",
+  "version": "0.2.19",
   "description": "The Paged plugin contract: manifest, bundle lifecycle, the BundleHost surface, and the contribution + engine wire types. Type-only.",
   "license": "MPL-2.0 OR LicenseRef-PMEL",
   "type": "module",

package/src/manifest.schema.json

@@ -135,6 +135,42 @@
             "full"
           ]
         },
+        "workers": {
+          "type": "object",
+          "description": "Worker spawn + SharedArrayBuffer (K-3 / S-07 / I-02). 'max' is the worker-count ceiling requested (host clamps to min(declared, hardwareConcurrency, 8)); 'sharedMemory' declares SAB use (gates allocateShared); 'maxSharedBytes' requests a per-bundle shared-memory ceiling (host enforces the stricter of it and its 256 MiB default cap). Gates host.workers.",
+          "additionalProperties": false,
+          "required": [
+            "max"
+          ],
+          "properties": {
+            "max": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 8
+            },
+            "sharedMemory": {
+              "type": "boolean"
+            },
+            "maxSharedBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 268435456
+            }
+          }
+        },
+        "secrets": {
+          "type": "object",
+          "description": "Host credential-store door (D-11; rfc-credential-store). 'sources' grants host.secrets for authenticated DB-attach / remote sources. REFERENCE-ONLY + host-owned: plugins hold credentialRef strings, never secret material; the surface has set/exists/forget and NO get. Gates host.secrets.",
+          "additionalProperties": false,
+          "required": [
+            "sources"
+          ],
+          "properties": {
+            "sources": {
+              "type": "boolean"
+            }
+          }
+        },
         "wasm": {
           "type": "array",
           "description": "Declared WebAssembly artifacts the bundle ships and loads at runtime (capability-gated, declared-only, budgeted). See docs/wasm-packaging.md.",