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

package/dist/clipboard.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The canonical tabular interchange — a RECTANGULAR grid of cell DISPLAY
+ * strings (already number-formatted; the consumer owns re-parsing on
+ * paste). `rows[r][c]` is the display text of the cell at grid row `r`,
+ * column `c`. Ragged input is the producer's responsibility to
+ * rectangularize; the host does not pad. Serializable (plain strings), so
+ * the door proxies across the future isolate boundary unchanged.
+ */
+export interface TabularClipboard {
+    /** Row-major grid of cell display strings. `rows.length` = row count;
+     *  each inner array is one row's cells, left to right. */
+    rows: string[][];
+}
+/**
+ * A clipboard payload — a plain-text half and/or a tabular half. Both are
+ * optional: a text-only copy carries `text`; a grid copy carries BOTH
+ * (the `tabular` grid AND a TSV `text` fallback so a paste into a plain
+ * editor still lands something). On READ the host fills whichever halves
+ * it could recover from the system clipboard (`tabular` is reconstructed
+ * from TSV `text` when the platform offers no richer form).
+ */
+export interface ClipboardPayload {
+    /** Plain-text representation. For a grid copy this is the TSV fallback
+     *  (rows joined by `\t` within a row and `\n` between rows). */
+    text?: string;
+    /** The rich rectangular cell grid (the canonical interchange). Present
+     *  on a grid copy; absent for a plain-text copy. Gated on
+     *  `capabilities.clipboard: "full"` — a `"vector"` declaration sees the
+     *  `text` half only. */
+    tabular?: TabularClipboard;
+}
+/**
+ * The clipboard accessor a bundle reaches through `host.clipboard`. Two
+ * doors over the SYSTEM clipboard: `read` recovers a payload (or `null`
+ * when there is nothing readable / no backend wired), `write` puts a
+ * payload on the clipboard. Capability-gated on `capabilities.clipboard`
+ * (see the mapping above): `"full"` grants text + tabular, `"vector"`
+ * grants text only, `"none"`/absent denies. Probe
+ * `supports("clipboard@1")` to know whether a real system-clipboard
+ * backend is wired (false ⇒ `read` answers `null` and `write` no-ops).
+ */
+export interface ClipboardSurface {
+    /**
+     * Read the current clipboard payload, or `null` when there is nothing
+     * readable, the read is denied by the platform, or no backend is wired
+     * (the honest no-clipboard door). A `"vector"` declaration never
+     * receives the `tabular` half (only `text`).
+     */
+    read(): Promise<ClipboardPayload | null>;
+    /**
+     * Write a payload to the system clipboard. A `"vector"` declaration may
+     * only write `text` — a `tabular` half it supplies is DROPPED (the host
+     * logs once). With no backend wired this is a no-op (probe
+     * `supports("clipboard@1")` first). Never throws on a platform refusal:
+     * a denied write resolves without effect (the honest browser posture —
+     * the clipboard API rejects without a user gesture).
+     */
+    write(payload: ClipboardPayload): Promise<void>;
+}

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

@@ -2,6 +2,7 @@ import type { CollectionName, DocumentMeta, ElementGeometryItem, ElementId, HitF
 import type { CommandContribution, ExporterContribution, ImporterContribution, KeybindingContribution, OverlayContribution, PagedEditor, PanelContribution, ToolContribution, ToolPreviewShape } from "./editor";
 import type { SceneLayer } from "./wire";
 import type { AssetSurface } from "./assets";
+import type { ClipboardSurface } from "./clipboard";
 import type { PluginManifest } from "./manifest";
 import type { SchemaPanelContribution } from "./panel-schema";
 import type { WidgetSurface } from "./widgets";
@@ -274,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 = {
@@ -696,6 +756,24 @@ 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
+     *  the host app injects no clipboard backend, `read` answers `null`,
+     *  `write` is a no-op, and `supports("clipboard@1")` is false (the
+     *  honest no-clipboard door). Capability-gated on
+     *  `capabilities.clipboard`: `"full"` grants text + tabular, `"vector"`
+     *  grants text only, `"none"`/absent denies. */
+    readonly clipboard: ClipboardSurface;
     /** Capability detection over version sniffing: feature strings of
      *  the form `"area.member@major"` (see HOST_FEATURES in plugin-sdk). */
     supports(feature: string): boolean;

package/dist/index.d.ts

@@ -1,8 +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-
@@ -88,6 +89,15 @@ export interface PluginCapabilities {
      * gets no surface.
      */
     dataProviders?: DataProvidersCapability;
+    /**
+     * The clipboard door's grant (K-6 / S-14). Gates `host.clipboard`:
+     * `"full"` grants BOTH the text and the rich `tabular` (cell-grid)
+     * payload — the sheets range copy/paste interchange; `"vector"` grants
+     * the `text` half only (a vector plugin copies a textual representation,
+     * not a cell grid — a `tabular` write is dropped); `"none"` (the
+     * default) / absent DENIES the door (read → `null`, write refused). See
+     * `clipboard.ts` for the surface + DESIGN.md for the trust line.
+     */
     clipboard?: "none" | "vector" | "full";
     /**
      * Declared WebAssembly artifacts the bundle ships and loads at

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.43.0
+// Synced from @paged-media/canvas-wasm@0.44.0
 /* tslint:disable */
 /* eslint-disable */
 
@@ -336,7 +336,7 @@ export type CaretDirection = "up" | "down";
 /**
  * Discriminated payload of a `WorkerToMain` message.
  */
-export type WorkerToMainKind = { kind: "ready"; payload: { protocol: ProtocolVersion } } | { kind: "documentLoaded"; payload: DocumentHandle } | { kind: "loadFailed"; payload: { error: LoadError } } | { kind: "mutationFailed"; payload: { error: WorkerError } } | { kind: "displayListReady"; payload: { pageId: PageId; lod: LodTier; commands: number; layoutGeneration: number; numberingGeneration: number } } | { kind: "hitResult"; payload: HitResult } | { kind: "pagesDirty"; payload: { pageIds: PageId[] } } | { kind: "storyDirty"; payload: { storyId: string } } | { kind: "warning"; payload: { kind: string; details: string } } | { kind: "stats"; payload: DocumentStats } | { kind: "snapshotReady"; payload: SnapshotPng } | { kind: "snapshotFailed"; payload: { error: SnapshotError } } | { kind: "mutationApplied"; payload: { clientSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; createdId?: ElementId | null; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null; reflow?: FrameReflowInfo | null } } | { kind: "selectionGeometry"; payload: { rects: SelectionRect[] } } | { kind: "caretGeometry"; payload: { caret: CaretGeometry | null } } | { kind: "caretNavResult"; payload: { offset?: number | null } } | { kind: "lineBoundsResult"; payload: { bounds?: LineBounds | null } } | { kind: "wordBoundsResult"; payload: { bounds?: WordBounds | null } } | { kind: "paragraphBoundsResult"; payload: { bounds?: ParagraphBounds | null } } | { kind: "undoApplied"; payload: { undoneSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null } } | { kind: "redoApplied"; payload: { redoneSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null } } | { kind: "fontRegistered"; payload: { family: string } } | { kind: "fontRegistryCleared" } | { kind: "colorProfileRegistered"; payload: { name: string } } | { kind: "elementSelectionApplied"; payload: { ids: ElementId[] } } | { kind: "marqueeHits"; payload: { ids: ElementId[] } } | { kind: "elementGeometry"; payload: { items: ElementGeometryItem[] } } | { kind: "groupLeaves"; payload: { ids: ElementId[] } } | { kind: "pathAnchors"; payload: { result: PathAnchorsResult | null } } | { kind: "nearestPathPoint"; payload: { result: NearestPathPointResult | null } } | { kind: "layers"; payload: { items: LayerSummary[] } } | { kind: "collectionReply"; payload: { name: CollectionName; items: any } } | { kind: "frameChainResult"; payload: { links: FrameChainLink[] } } | { kind: "documentPlaceholders"; payload: { items: PlaceholderItem[] } } | { kind: "placedAssetBytes"; payload: { elementId: string; found: boolean; uri: string; width: number; height: number; encoded: number[] } } | { kind: "fontFaceBytes"; payload: { found: boolean; family: string; style: string | null; postscriptName: string | null; format: string; bytes: number[] } } | { kind: "measureTextResult"; payload: { advance: number; ascender: number; descender: number } } | { kind: "sceneLayerApplied"; payload: { elementId: string; applied: boolean } } | { kind: "frameReflow"; payload: { frameId: string; contentBox: [number, number, number, number] } } | { kind: "documentMetaReply"; payload: { meta: DocumentMeta } } | { kind: "colorPreviewReply"; payload: { result: ColorPreview | null } } | { kind: "colorComputeReply"; payload: { rgbHex: string; cmyk: [number, number, number, number] | null; outOfGamut: boolean } } | { kind: "gradientDetailReply"; payload: { result: GradientDetail | null } } | { kind: "swatchLibraryExported"; payload: { aseBytes: number[] } } | { kind: "exportPdfBegun"; payload: { session: number; pageCount: number } } | { kind: "exportPdfProgress"; payload: { session: number; done: number; total: number } } | { kind: "pdfExported"; payload: { pdfBytes: number[]; diagnostics: string[]; findings?: PreflightFinding[] } } | { kind: "exportPdfCancelled"; payload: { session: number } } | { kind: "exportPdfFailed"; payload: { error: string } } | { kind: "idmlExported"; payload: { idmlBytes: number[] } } | { kind: "exportIdmlFailed"; payload: { error: string } } | { kind: "elementProperties"; payload: { result: ElementProperties | null } } | { kind: "sceneTree"; payload: { roots: SceneTreeNode[] } } | { kind: "scriptResult"; payload: { output: string[]; error: string | null; budgetKind?: ScriptBudgetKind } } | { kind: "gestureBegun"; payload: { handle: GestureHandle } } | { kind: "gestureUpdated"; payload: { handle: GestureHandle; pageIds: PageId[]; snapLines?: SnapLine[] } } | { kind: "gestureCommitted"; payload: { handle: GestureHandle; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats } } | { kind: "gestureCancelled"; payload: { handle: GestureHandle; pageIds: PageId[] } } | { kind: "gestureFailed"; payload: { error: GestureFailure } } | { kind: "attachReady"; payload: { gpuActive: boolean; sceneCacheBudget: number } } | { kind: "gestureSnapLines"; payload: { snapLines: SnapLine[] } } | { kind: "resolutionDone"; payload: ResolutionResult };
+export type WorkerToMainKind = { kind: "ready"; payload: { protocol: ProtocolVersion } } | { kind: "documentLoaded"; payload: DocumentHandle } | { kind: "loadFailed"; payload: { error: LoadError } } | { kind: "mutationFailed"; payload: { error: WorkerError } } | { kind: "displayListReady"; payload: { pageId: PageId; lod: LodTier; commands: number; layoutGeneration: number; numberingGeneration: number } } | { kind: "hitResult"; payload: HitResult } | { kind: "pagesDirty"; payload: { pageIds: PageId[] } } | { kind: "storyDirty"; payload: { storyId: string } } | { kind: "warning"; payload: { kind: string; details: string } } | { kind: "stats"; payload: DocumentStats } | { kind: "snapshotReady"; payload: SnapshotPng } | { kind: "snapshotFailed"; payload: { error: SnapshotError } } | { kind: "mutationApplied"; payload: { clientSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; createdId?: ElementId | null; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null; reflow?: FrameReflowInfo | null } } | { kind: "selectionGeometry"; payload: { rects: SelectionRect[] } } | { kind: "caretGeometry"; payload: { caret: CaretGeometry | null } } | { kind: "caretNavResult"; payload: { offset?: number | null } } | { kind: "lineBoundsResult"; payload: { bounds?: LineBounds | null } } | { kind: "wordBoundsResult"; payload: { bounds?: WordBounds | null } } | { kind: "paragraphBoundsResult"; payload: { bounds?: ParagraphBounds | null } } | { kind: "undoApplied"; payload: { undoneSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null } } | { kind: "redoApplied"; payload: { redoneSeq: number; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats; pageStructureChanged?: boolean; pageSizesPt?: [number, number][] | null } } | { kind: "fontRegistered"; payload: { family: string } } | { kind: "fontRegistryCleared" } | { kind: "colorProfileRegistered"; payload: { name: string } } | { kind: "elementSelectionApplied"; payload: { ids: ElementId[] } } | { kind: "marqueeHits"; payload: { ids: ElementId[] } } | { kind: "elementGeometry"; payload: { items: ElementGeometryItem[] } } | { kind: "groupLeaves"; payload: { ids: ElementId[] } } | { kind: "pathAnchors"; payload: { result: PathAnchorsResult | null } } | { kind: "nearestPathPoint"; payload: { result: NearestPathPointResult | null } } | { kind: "layers"; payload: { items: LayerSummary[] } } | { kind: "collectionReply"; payload: { name: CollectionName; items: any } } | { kind: "frameChainResult"; payload: { links: FrameChainLink[] } } | { kind: "documentPlaceholders"; payload: { items: PlaceholderItem[] } } | { kind: "placedAssetBytes"; payload: { elementId: string; found: boolean; uri: string; width: number; height: number; encoded: number[] } } | { kind: "fontFaceBytes"; payload: { found: boolean; family: string; style: string | null; postscriptName: string | null; format: string; bytes: number[] } } | { kind: "measureTextResult"; payload: { advance: number; ascender: number; descender: number } } | { kind: "sceneLayerApplied"; payload: { elementId: string; applied: boolean } } | { kind: "resourceClaimApplied"; payload: { imageId: string; applied: boolean; needed?: ResourceTilesNeededWire[] } } | { kind: "resourceTilesNeeded"; payload: ResourceTilesNeededWire } | { kind: "frameReflow"; payload: { frameId: string; contentBox: [number, number, number, number] } } | { kind: "documentMetaReply"; payload: { meta: DocumentMeta } } | { kind: "colorPreviewReply"; payload: { result: ColorPreview | null } } | { kind: "colorComputeReply"; payload: { rgbHex: string; cmyk: [number, number, number, number] | null; outOfGamut: boolean } } | { kind: "gradientDetailReply"; payload: { result: GradientDetail | null } } | { kind: "swatchLibraryExported"; payload: { aseBytes: number[] } } | { kind: "exportPdfBegun"; payload: { session: number; pageCount: number } } | { kind: "exportPdfProgress"; payload: { session: number; done: number; total: number } } | { kind: "pdfExported"; payload: { pdfBytes: number[]; diagnostics: string[]; findings?: PreflightFinding[] } } | { kind: "exportPdfCancelled"; payload: { session: number } } | { kind: "exportPdfFailed"; payload: { error: string } } | { kind: "idmlExported"; payload: { idmlBytes: number[] } } | { kind: "exportIdmlFailed"; payload: { error: string } } | { kind: "elementProperties"; payload: { result: ElementProperties | null } } | { kind: "sceneTree"; payload: { roots: SceneTreeNode[] } } | { kind: "scriptResult"; payload: { output: string[]; error: string | null; budgetKind?: ScriptBudgetKind } } | { kind: "gestureBegun"; payload: { handle: GestureHandle } } | { kind: "gestureUpdated"; payload: { handle: GestureHandle; pageIds: PageId[]; snapLines?: SnapLine[] } } | { kind: "gestureCommitted"; payload: { handle: GestureHandle; appliedSeq: number; pageIds: PageId[]; cacheStats: LayoutCacheStats } } | { kind: "gestureCancelled"; payload: { handle: GestureHandle; pageIds: PageId[] } } | { kind: "gestureFailed"; payload: { error: GestureFailure } } | { kind: "attachReady"; payload: { gpuActive: boolean; sceneCacheBudget: number } } | { kind: "gestureSnapLines"; payload: { snapLines: SnapLine[] } } | { kind: "resolutionDone"; payload: ResolutionResult };
 
 /**
  * Editor-ops — wire mirror of `paged_parse::GradientFeatherParams`.
@@ -1505,7 +1505,7 @@ export type Operation = { kind: "SetProperty"; node: NodeId; path: PropertyPath;
  * variants so e.g. `cmyk_icc_profile` becomes `cmykIccProfile` on
  * the wire — the TS protocol mirror locks the camelCase contract.
  */
-export type MainToWorkerKind = { kind: "hello" } | { kind: "loadDocument"; payload: { bytes: number[]; font?: number[] | null; cmykIccProfile?: number[] | null } } | { kind: "registerFont"; payload: { family: string; style?: string | null; bytes: number[] } } | { kind: "clearFontRegistry" } | { kind: "registerColorProfile"; payload: { name: string; bytes: number[] } } | { kind: "mutate"; payload: Mutation } | { kind: "requestPage"; payload: { pageId: PageId; lod: LodTier } } | { kind: "hitTest"; payload: { pageId: PageId; docPoint: [number, number]; filter: HitFilter } } | { kind: "requestSnapshot"; payload: { pageId: PageId; targetWidthPx: number; dpi?: number | null } } | { kind: "setSelection"; payload: { selection: ContentSelection | null } } | { kind: "requestSelectionGeometry"; payload: { selection: ContentSelection } } | { kind: "requestCaretGeometry"; payload: { selection: ContentSelection } } | { kind: "requestCaretNav"; payload: { storyId: string; offset: number; direction: CaretDirection; cell?: TextCellAddr | null } } | { kind: "requestLineBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "requestWordBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "requestParagraphBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "undo" } | { kind: "redo" } | { kind: "setElementSelection"; payload: { ids: ElementId[]; mode: SelectionMode } } | { kind: "requestMarqueeHits"; payload: { pageId: PageId; rect: [number, number, number, number] } } | { kind: "requestElementGeometry"; payload: { ids: ElementId[] } } | { kind: "requestGroupLeaves"; payload: { groupId: string } } | { kind: "requestPathAnchors"; payload: { id: ElementId } } | { kind: "requestNearestPathPoint"; payload: { id: ElementId; point: [number, number] } } | { kind: "requestLayers" } | { kind: "requestCollection"; payload: { name: CollectionName } } | { kind: "requestFrameChain"; payload: { storyId: string } } | { kind: "requestPlacedAssetBytes"; payload: { elementId: string } } | { kind: "requestFontFaceBytes"; payload: { family: string; style?: string | null } } | { kind: "requestMeasureText"; payload: { family: string; style?: string | null; text: string; sizePt: number } } | { kind: "submitSceneLayer"; payload: { elementId: string; layer: SceneLayer } } | { kind: "clearSceneLayer"; payload: { elementId: string } } | { kind: "requestDocumentMeta" } | { kind: "requestDocumentPlaceholders" } | { kind: "requestColorPreview"; payload: { swatchId: string } } | { kind: "requestColorCompute"; payload: { space: string; value: number[]; tint?: number | null; model?: string | null; alternateSpace?: string | null; alternateValue?: number[] | null } } | { kind: "requestGradientDetail"; payload: { gradientId: string } } | { kind: "exportSwatchLibrary"; payload: { groupId?: string | null } } | { kind: "executeScript"; payload: { source: string } } | { kind: "exportPdfBegin"; payload: { options: ExportPdfWireOptions } } | { kind: "exportPdfPage"; payload: { session: number } } | { kind: "exportPdfFinish"; payload: { session: number } } | { kind: "exportPdfCancel"; payload: { session: number } } | { kind: "exportIdml"; payload: {} } | { kind: "requestElementProperties"; payload: { id: ElementId } } | { kind: "requestSceneTree" } | { kind: "beginGesture"; payload: { nodes: ElementId[]; gesture: GestureType; anchor?: GestureAnchor | null; cameraScale?: number | null } } | { kind: "updateGesture"; payload: { handle: GestureHandle; delta: [number, number]; modifiers: GestureModifiers } } | { kind: "commitGesture"; payload: { handle: GestureHandle } } | { kind: "cancelGesture"; payload: { handle: GestureHandle } };
+export type MainToWorkerKind = { kind: "hello" } | { kind: "loadDocument"; payload: { bytes: number[]; font?: number[] | null; cmykIccProfile?: number[] | null } } | { kind: "registerFont"; payload: { family: string; style?: string | null; bytes: number[] } } | { kind: "clearFontRegistry" } | { kind: "registerColorProfile"; payload: { name: string; bytes: number[] } } | { kind: "mutate"; payload: Mutation } | { kind: "requestPage"; payload: { pageId: PageId; lod: LodTier } } | { kind: "hitTest"; payload: { pageId: PageId; docPoint: [number, number]; filter: HitFilter } } | { kind: "requestSnapshot"; payload: { pageId: PageId; targetWidthPx: number; dpi?: number | null } } | { kind: "setSelection"; payload: { selection: ContentSelection | null } } | { kind: "requestSelectionGeometry"; payload: { selection: ContentSelection } } | { kind: "requestCaretGeometry"; payload: { selection: ContentSelection } } | { kind: "requestCaretNav"; payload: { storyId: string; offset: number; direction: CaretDirection; cell?: TextCellAddr | null } } | { kind: "requestLineBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "requestWordBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "requestParagraphBounds"; payload: { storyId: string; offset: number; cell?: TextCellAddr | null } } | { kind: "undo" } | { kind: "redo" } | { kind: "setElementSelection"; payload: { ids: ElementId[]; mode: SelectionMode } } | { kind: "requestMarqueeHits"; payload: { pageId: PageId; rect: [number, number, number, number] } } | { kind: "requestElementGeometry"; payload: { ids: ElementId[] } } | { kind: "requestGroupLeaves"; payload: { groupId: string } } | { kind: "requestPathAnchors"; payload: { id: ElementId } } | { kind: "requestNearestPathPoint"; payload: { id: ElementId; point: [number, number] } } | { kind: "requestLayers" } | { kind: "requestCollection"; payload: { name: CollectionName } } | { kind: "requestFrameChain"; payload: { storyId: string } } | { kind: "requestPlacedAssetBytes"; payload: { elementId: string } } | { kind: "requestFontFaceBytes"; payload: { family: string; style?: string | null } } | { kind: "requestMeasureText"; payload: { family: string; style?: string | null; text: string; sizePt: number } } | { kind: "submitSceneLayer"; payload: { elementId: string; layer: SceneLayer } } | { kind: "clearSceneLayer"; payload: { elementId: string } } | { kind: "claimImageResource"; payload: { imageId: string; levels: number; tileSize: number; baseWidth: number; baseHeight: number; revision: number } } | { kind: "releaseImageResource"; payload: { imageId: string } } | { kind: "submitResourceTiles"; payload: { imageId: string; level: number; tiles: ProviderTileWire[]; generation: number } } | { kind: "requestDocumentMeta" } | { kind: "requestDocumentPlaceholders" } | { kind: "requestColorPreview"; payload: { swatchId: string } } | { kind: "requestColorCompute"; payload: { space: string; value: number[]; tint?: number | null; model?: string | null; alternateSpace?: string | null; alternateValue?: number[] | null } } | { kind: "requestGradientDetail"; payload: { gradientId: string } } | { kind: "exportSwatchLibrary"; payload: { groupId?: string | null } } | { kind: "executeScript"; payload: { source: string } } | { kind: "exportPdfBegin"; payload: { options: ExportPdfWireOptions } } | { kind: "exportPdfPage"; payload: { session: number } } | { kind: "exportPdfFinish"; payload: { session: number } } | { kind: "exportPdfCancel"; payload: { session: number } } | { kind: "exportIdml"; payload: {} } | { kind: "requestElementProperties"; payload: { id: ElementId } } | { kind: "requestSceneTree" } | { kind: "beginGesture"; payload: { nodes: ElementId[]; gesture: GestureType; anchor?: GestureAnchor | null; cameraScale?: number | null } } | { kind: "updateGesture"; payload: { handle: GestureHandle; delta: [number, number]; modifiers: GestureModifiers } } | { kind: "commitGesture"; payload: { handle: GestureHandle } } | { kind: "cancelGesture"; payload: { handle: GestureHandle } };
 
 /**
  * Track J — wire-shape mirror of `paged_parse::PathAnchor`. The
@@ -2064,6 +2064,50 @@ export interface PlaceholderItem {
     value: string | null;
 }
 
+/**
+ * v44 (C-6 / I-06) — one image\'s tile-miss request: the tiles a claimed
+ * image lacked at `level` during the last build. `tiles` are grid origins
+ * `[x, y]` in level-space px; `generation` is the pyramid revision the
+ * request was computed against (the host echoes it on submit so a stale
+ * reply is dropped).
+ */
+export interface ResourceTilesNeededWire {
+    imageId: string;
+    level: number;
+    tiles: [number, number][];
+    generation: number;
+}
+
+/**
+ * v44 (C-6 / I-06) — one pyramid tile on the wire. `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). The
+ * worker interns these into its budgeted LRU tile cache; the renderer\'s
+ * resource provider serves them back as `paged_renderer::ProviderTile`.
+ */
+export interface ProviderTileWire {
+    /**
+     * 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. Length must be `width*height*4`.
+     */
+    rgba: number[];
+}
+
 export interface CaretGeometry {
     pageId: PageId;
     frameId: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.14-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"
             ]
           }
         },