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

package/dist/contributions.d.ts

@@ -1 +1 @@
-export type { ShellRegistries, ToolRegistry, PanelRegistry, CommandRegistry, KeybindingRegistry, OverlayRegistry, EditContextRegistry, ObjectTypeRegistry, ImporterRegistry, ExporterRegistry, ToolContribution, ToolId, ToolGroupId, ToolSectionId, ToolOptionsSpec, ToolOptionField, CursorSpec, CssCursorToken, GestureHandler, CanvasPointerEvent, OverlayContext, OverlayPrimitive, DeactivateReason, PanelContribution, PanelProps, PanelApi, OverlayContribution, OverlayProps, OverlayPageRect, CommandContribution, KeybindingContribution, ImporterContribution, ImportRequest, ExporterContribution, ExportResult, DockEdge, VisibilityPredicate, PagedEditor, PagedClient, ToolPreviewShape, ToolPreviewPolyline, ToolPreviewPath, MarqueeRectPageLocal, } from "./editor";
+export type { ShellRegistries, ToolRegistry, PanelRegistry, CommandRegistry, KeybindingRegistry, OverlayRegistry, EditContextRegistry, ObjectTypeRegistry, ImporterRegistry, ExporterRegistry, ToolContribution, ToolId, ToolGroupId, ToolSectionId, ToolOptionsSpec, ToolOptionField, CursorSpec, CssCursorToken, GestureHandler, CanvasPointerEvent, OverlayContext, OverlayPrimitive, DeactivateReason, PanelContribution, PanelProps, PanelApi, OverlayContribution, OverlayProps, OverlayPageRect, CommandContribution, KeybindingContribution, ImporterContribution, ImportRequest, ExporterContribution, ExportResult, DockEdge, VisibilityPredicate, PagedEditor, PagedClient, ImageResourceClaim, ResourceTilesNeeded, ToolPreviewShape, ToolPreviewPolyline, ToolPreviewPath, MarqueeRectPageLocal, } from "./editor";

package/dist/editor.d.ts

@@ -1,6 +1,21 @@
 import type { ComponentType } from "react";
 import type { EditContextContribution, ObjectTypeContribution } from "./host";
-import type { CollectionName, ContentSelection, DocumentMeta, ElementGeometryItem, ElementId, MainToWorkerKind, Mutation, PageId, PathAnchorsResult, SceneLayer, SelectionMode, WorkerToMain } from "./wire";
+import type { CollectionName, ContentSelection, DocumentMeta, ElementGeometryItem, ElementId, MainToWorkerKind, Mutation, PageId, PathAnchorsResult, ProviderTileWire, ResourceTilesNeededWire, SceneLayer, SelectionMode, WorkerToMain } from "./wire";
+/** C-6 (I-06) — the editor-channel claim shape (the v44
+ *  `claimImageResource` payload, named for the `PagedEditor.images`
+ *  member). The SDK adapter derives it from
+ *  `ImageResourceClaimOptions` + the bundle-supplied revision. */
+export interface ImageResourceClaim {
+    imageId: string;
+    levels: number;
+    tileSize: number;
+    baseWidth: number;
+    baseHeight: number;
+    revision: number;
+}
+/** C-6 — the worker's tile-miss notification, as the editor channel
+ *  surfaces it (the v44 `resourceTilesNeeded` payload). */
+export type ResourceTilesNeeded = ResourceTilesNeededWire;
 export interface Disposable {
     dispose(): void;
 }
@@ -386,6 +401,23 @@ export interface PagedEditor {
         submit(elementId: string, layer: SceneLayer): Promise<void>;
         clear(elementId: string): Promise<void>;
     };
+    /** C-6 (I-06) — the renderer RESOURCE-PROVIDER channel. The editor
+     *  routes these to the canvas-wasm `claimImageResource` /
+     *  `submitResourceTiles` / `releaseImageResource` messages (the v44
+     *  wire) AND surfaces the worker's `resourceTilesNeeded` events
+     *  (`onResourceTilesNeeded`) so the SDK adapter can pull + submit the
+     *  tiles. `undefined` when the host build wires no resource channel
+     *  (headless / older editor); `host.images.claimImageResource()` then
+     *  warns + no-ops and `supports("rendering.resourceProvider@1")` is
+     *  false. All four members mirror the editor's CanvasClient surface. */
+    images?: {
+        claim(claim: ImageResourceClaim): Promise<void>;
+        release(imageId: string): Promise<void>;
+        submitTiles(imageId: string, level: number, tiles: ProviderTileWire[], generation: number): Promise<void>;
+        /** Subscribe to the worker's `resourceTilesNeeded` notifications
+         *  (worker → main). The returned function unsubscribes. */
+        onResourceTilesNeeded(listener: (need: ResourceTilesNeeded) => void): () => void;
+    };
     overlaySignals: {
         setToolPreview(value: ToolPreviewShape | null): void;
     };

package/dist/host.d.ts

@@ -275,6 +275,65 @@ export interface SceneLayerSurface extends Disposable {
      *  content). */
     clear(elementId: string): Promise<void>;
 }
+/** One pyramid tile the bundle's `source` callback returns (C-6). `rgba`
+ *  is tightly packed RGBA8 (`width*height*4` bytes, row-major); `[x, y]`
+ *  is the tile's origin in LEVEL-space px (the provider's grid origin at
+ *  that mip level). Returning `null` is the honest "no pixels for this
+ *  tile yet" answer — the renderer keeps the best cached/fallback level. */
+export interface TileBytes {
+    /** Tile origin x in level-space px. */
+    x: number;
+    /** Tile origin y in level-space px. */
+    y: number;
+    /** Pixel width of the buffer. */
+    width: number;
+    /** Pixel height of the buffer. */
+    height: number;
+    /** Tightly packed RGBA8, row-major (`width*height*4` bytes). */
+    rgba: Uint8Array;
+}
+/** What `host.images.claimImageResource` is handed (C-6). The first four
+ *  fields describe the provider-owned pyramid; `source` serves a tile,
+ *  `revision` is a monotonic damage signal (bump it and the renderer
+ *  re-pulls — same etag discipline as the data provider). */
+export interface ImageResourceClaimOptions {
+    /** Number of mip levels the provider serves (0 = full res; each level
+     *  halves). */
+    levels: number;
+    /** Tile edge in level-space px (the grid step). */
+    tileSize: number;
+    /** Natural pixel width of the level-0 image. */
+    baseWidth: number;
+    /** Natural pixel height of the level-0 image. */
+    baseHeight: number;
+    /** Serve one tile at pyramid `level` whose origin is `(x, y)` in
+     *  level-space px, or `null` when the provider has no pixels for it
+     *  yet (the renderer holds the fallback level). Invoked by the SDK
+     *  adapter for each tile the renderer reports needing. */
+    source(level: number, x: number, y: number): Promise<TileBytes | null>;
+    /** The current content revision — a monotonic counter the SDK sends
+     *  on claim; bump the value your closure returns and re-claim (or rely
+     *  on the renderer's damage) to invalidate. */
+    revision(): number;
+}
+/**
+ * The renderer resource-provider door (C-6 / I-06). A bundle claims a
+ * placed image's tiled mip pyramid; the renderer pulls tiles at the
+ * level its current scale needs. The SDK adapter owns the
+ * needed → source → submit plumbing (the bundle supplies only the
+ * `source` + `revision` callbacks). Always present — when the host wires
+ * no resource channel, `claimImageResource` warns + returns an inert
+ * Disposable and `supports("rendering.resourceProvider@1")` is false (the
+ * honest no-provider door). Capability-gated: `capabilities.rendering`
+ * must include `"resourceProvider"`.
+ */
+export interface ImagesSurface {
+    /** Claim `elementId`'s image resource (the v44 wire's `image_id`). The
+     *  renderer registers the claim and pulls tiles as it composites;
+     *  disposing the returned handle releases the claim (the renderer drops
+     *  to the whole-image fallback lane). */
+    claimImageResource(elementId: string, opts: ImageResourceClaimOptions): Disposable;
+}
 /** Expected mutation failures are results, not throws — mirroring the
  *  editor's mutate-never-throws convention. */
 export type MutationOutcome = {
@@ -697,6 +756,15 @@ export interface BundleHost {
      *  `supports("assets.fonts@1")` is false. Capability-gated:
      *  `getFontFace` requires `capabilities.assets` ∋ `"fonts"`. */
     readonly assets: AssetSurface;
+    /** The capability-gated RENDERER RESOURCE-PROVIDER door (C-6 / I-06):
+     *  claim a placed image's tiled mip pyramid so the renderer pulls tiles
+     *  at the level its current scale needs (the v44 wire). The SDK adapter
+     *  owns the needed → source → submit plumbing; the bundle supplies the
+     *  `source` + `revision` callbacks. Always present — when the host wires
+     *  no resource channel, `claimImageResource` warns + returns an inert
+     *  Disposable and `supports("rendering.resourceProvider@1")` is false.
+     *  Capability-gated on `capabilities.rendering` ∋ `"resourceProvider"`. */
+    readonly images: ImagesSurface;
     /** 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,9 +1,10 @@
 export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, } from "./manifest";
 export type { BundleHandle, PagedBundle } from "./bundle";
-export type { BundleHost, ContributionSurface, SceneLayerSurface, 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, 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";
+export type { ProviderTileWire } from "./wire";
 export type { ClipboardSurface, ClipboardPayload, TabularClipboard, } from "./clipboard";
 export type * from "./contributions";
 export type * from "./mutations";

package/dist/manifest.d.ts

@@ -28,13 +28,14 @@ export interface PluginCapabilities {
         read?: "broad" | "scoped";
         write?: "broad" | "scoped";
     };
-    /** Render-pipeline surfaces the bundle uses. v0: `overlay` means
-     *  the shared TS overlay signals (tool previews) AND
-     *  `contribute.overlay`; `hitTest` gates `document.hitTest`;
-     *  `sceneLayer` is reserved for the P2 channel. Declaring a surface
-     *  is the prerequisite for the matching door (the host gate throws
-     *  on an undeclared use). */
-    rendering?: Array<"sceneLayer" | "overlay" | "hitTest">;
+    /** Render-pipeline surfaces the bundle uses. `overlay` means the
+     *  shared TS overlay signals (tool previews) AND `contribute.overlay`;
+     *  `hitTest` gates `document.hitTest`; `sceneLayer` gates the in-frame
+     *  `contribute.sceneLayer()` channel (C-1); `resourceProvider` gates
+     *  the renderer pyramid-tile door `host.images.claimImageResource`
+     *  (C-6 / I-06). Declaring a surface is the prerequisite for the
+     *  matching door (the host gate throws on an undeclared use). */
+    rendering?: Array<"sceneLayer" | "overlay" | "hitTest" | "resourceProvider">;
     /** The bundle registers keybindings directly via
      *  `contribute.keybinding`. Keybindings have no id to list under
      *  `contributes`, so this boolean is their declaration. v0 first-

package/package.json

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

@@ -59,7 +59,8 @@
             "enum": [
               "sceneLayer",
               "overlay",
-              "hitTest"
+              "hitTest",
+              "resourceProvider"
             ]
           }
         },