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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, } from "./manifest";
+export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, GpuCapability, } from "./manifest";
 export type { BundleHandle, PagedBundle } from "./bundle";
 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";

package/dist/manifest.d.ts

@@ -148,6 +148,38 @@ export interface PluginCapabilities {
      * and DESIGN.md §16.
      */
     secrets?: SecretsCapability;
+    /**
+     * GPU (WebGPU) usage the bundle declares (I-07 / C-1 Stage B — the
+     * buildable, realm-local half; ADR-018). DECLARE-ONLY: this does NOT hand
+     * the bundle a `GPUDevice` (the bundle already has `navigator.gpu` in its
+     * own JS realm — paged.image's Engine-B drives WebGPU there today). It
+     * LEGITIMIZES that usage within the capability contract so the host can
+     * surface "this plugin uses the GPU" to the user, exactly as the wasm
+     * artifacts are declare-only.
+     *
+     * `realm: "bundle"` is the ONLY value that validates today: the plugin uses
+     * WebGPU in its OWN realm (no host involvement, no zero-copy composite into
+     * the page scene). `realm: "shared"` is RESERVED in the vocabulary for the
+     * future host-device-sharing path (a host-blessed `GPUDevice` + a
+     * `SceneItem::Texture` zero-copy composite) and is REJECTED by validation —
+     * that path is blocked on TWO walls (Vello has no external-texture import;
+     * WebGPU can't transfer a device across the render-worker/main-thread realm
+     * boundary) and stays deferred record-only (ADR-018). There is NO
+     * `requestGpuDevice` / device surface; adding one would be a fake.
+     */
+    gpu?: GpuCapability;
+}
+/** WebGPU usage declaration (I-07 / C-1 Stage B realm-local; ADR-018).
+ *  DECLARE-ONLY — no device is handed to the bundle. `realm: "bundle"` is the
+ *  only value validation accepts today (the plugin uses WebGPU in its own JS
+ *  realm); `realm: "shared"` is reserved for the future host-device-sharing
+ *  path and rejected until the zero-copy walls lift. A closed vocabulary so
+ *  the host can reason about the grant. */
+export interface GpuCapability {
+    /** `"bundle"` — the plugin uses WebGPU in its own JS realm (the only value
+     *  accepted today). `"shared"` is reserved for future host-device-sharing
+     *  (currently rejected by validation). */
+    realm: "bundle" | "shared";
 }
 /** Credential-store declaration (D-11; rfc-credential-store). `sources`
  *  gates the `host.secrets` door for authenticated DB-attach / remote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.19-canary.0",
+  "version": "0.2.20-canary.0",
   "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

@@ -171,6 +171,19 @@
             }
           }
         },
+        "gpu": {
+          "type": "object",
+          "description": "WebGPU usage declaration (I-07 / C-1 Stage B realm-local; ADR-018). DECLARE-ONLY: no GPUDevice is handed to the bundle — it legitimizes the realm-local WebGPU usage the bundle already does in its own JS realm (paged.image Engine-B). realm:\"bundle\" is the only value accepted today; realm:\"shared\" (future host-device-sharing) is reserved and REJECTED until the zero-copy walls lift. No requestGpuDevice surface exists.",
+          "additionalProperties": false,
+          "required": [
+            "realm"
+          ],
+          "properties": {
+            "realm": {
+              "const": "bundle"
+            }
+          }
+        },
         "wasm": {
           "type": "array",
           "description": "Declared WebAssembly artifacts the bundle ships and loads at runtime (capability-gated, declared-only, budgeted). See docs/wasm-packaging.md.",