@paged-media/plugin-api 0.2.5-canary.0 → 0.2.8-canary.0

package/dist/assets.d.ts

@@ -0,0 +1,49 @@
+/** What `host.assets` can serve. v1: `"fonts"` only. `"images"` is
+ *  DECLARED-but-RESERVED for v2 (placed-image / URL-import bytes) — it
+ *  appears so the v2 direction is recorded, but `validate` REJECTS it
+ *  in a manifest today (the door has no `getImage`, so honoring the
+ *  declaration would be an honesty bug). */
+export type AssetKind = "fonts" | "images";
+/** Container/wrapper format of served font bytes — lets the consumer
+ *  pick the right `@font-face` `format(...)` hint. */
+export type FontFaceFormat = "truetype" | "opentype" | "woff" | "woff2";
+/**
+ * One resolved DOCUMENT font face — the bytes the engine already holds
+ * for a face the document loads/embeds (the same faces the `fonts`
+ * collection NAMES). `bytes` is the raw face file; `family`/`style`
+ * echo what the bytes actually resolve (host-canonical, which may
+ * differ in casing from the requested family). Serializable
+ * (`Uint8Array` clones 1:1), so the door proxies across the future
+ * isolate boundary unchanged.
+ */
+export interface FontFaceAsset {
+    /** The raw OpenType/TrueType/WOFF face bytes. */
+    bytes: Uint8Array;
+    /** Container format — the `@font-face` `format()` hint. */
+    format: FontFaceFormat;
+    /** The face's PostScript name when the host knows it. */
+    postscriptName?: string;
+    /** The family the bytes resolve (host-canonical casing). */
+    family: string;
+    /** The style the bytes resolve, when style-specific. */
+    style?: string;
+}
+/**
+ * The asset accessor a bundle reaches through `host.assets`. v1 has
+ * exactly ONE read: DOCUMENT-registered font face bytes by family
+ * (+ optional style). It is NOT an arbitrary filesystem/network
+ * reader — a bundle can only ask for a family the document already
+ * uses, and the host answers from what the document already has, or
+ * `null`. Capability-gated: `getFontFace` requires
+ * `capabilities.assets` ∋ `"fonts"` (the host gate throws in
+ * `'enforce'`, warns in `'warn'`).
+ */
+export interface AssetSurface {
+    /**
+     * Serve the bytes of a DOCUMENT font face, or `null` when the host
+     * has no bytes for it (an unregistered family, a face the host can't
+     * reach, or an over-budget face). NEVER fetches from the network —
+     * `null` over a live fetch keeps "render offline forever" honest.
+     */
+    getFontFace(family: string, style?: string): Promise<FontFaceAsset | null>;
+}

package/dist/contributions.d.ts

@@ -1 +1 @@
-export type { ShellRegistries, ToolRegistry, PanelRegistry, CommandRegistry, KeybindingRegistry, OverlayRegistry, ToolContribution, ToolId, ToolGroupId, ToolSectionId, ToolOptionsSpec, ToolOptionField, CursorSpec, CssCursorToken, GestureHandler, CanvasPointerEvent, OverlayContext, OverlayPrimitive, DeactivateReason, PanelContribution, PanelProps, PanelApi, OverlayContribution, OverlayProps, OverlayPageRect, CommandContribution, KeybindingContribution, DockEdge, VisibilityPredicate, PagedEditor, PagedClient, ToolPreviewShape, ToolPreviewPolyline, 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, ToolPreviewShape, ToolPreviewPolyline, ToolPreviewPath, MarqueeRectPageLocal, } from "./editor";

package/dist/editor.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from "react";
-import type { CollectionName, ContentSelection, DocumentMeta, ElementGeometryItem, ElementId, MainToWorkerKind, Mutation, PageId, PathAnchorsResult, SelectionMode, WorkerToMain } from "./wire";
+import type { EditContextContribution, ObjectTypeContribution } from "./host";
+import type { CollectionName, ContentSelection, DocumentMeta, ElementGeometryItem, ElementId, MainToWorkerKind, Mutation, PageId, PathAnchorsResult, SceneLayer, SelectionMode, WorkerToMain } from "./wire";
 export interface Disposable {
     dispose(): void;
 }
@@ -46,6 +47,26 @@ export interface CanvasPointerEvent {
     button: number;
     /** Underlying DOM target — handlers may read `data-*` hooks. */
     target: unknown;
+    /**
+     * Pointer-Events normalized pressure, 0..1 (B-08). Browser
+     * semantics are preserved verbatim: a pen reports its physical
+     * pressure; a mouse reports `0` with no button and `0.5` while a
+     * button is held; touch reports `0`/`0.5` likewise. The host reads
+     * `PointerEvent.pressure` straight through, so a stylus drives
+     * variable-width strokes (§13.12, Tier B) once the renderer can
+     * consume a pressure profile. Defaults to `0.5` on synthetic
+     * events that omit it.
+     */
+    pressure: number;
+    /** Pen tilt around the X axis, −90..90 deg (Pointer Events). `0`
+     *  for mouse/touch and pens without tilt support. */
+    tiltX: number;
+    /** Pen tilt around the Y axis, −90..90 deg (Pointer Events). `0`
+     *  for mouse/touch and pens without tilt support. */
+    tiltY: number;
+    /** Originating device class (Pointer Events `pointerType`). Lets a
+     *  tool branch stylus-only behaviour. Defaults to `"mouse"`. */
+    pointerType: "mouse" | "pen" | "touch";
 }
 /** Ephemeral overlay primitive published during a gesture. Kept
  *  opaque so the contract is stable across host overlay growth. */
@@ -175,6 +196,53 @@ export interface KeybindingContribution {
     command: string;
     when?: VisibilityPredicate;
 }
+/** A file handed to an importer — bytes already read at the host boundary
+ *  (the contract never leaks a DOM `File`, so a bundle stays environment-
+ *  agnostic / isolate-ready). */
+export interface ImportRequest {
+    /** Original file name incl. extension (e.g. `"budget.xlsx"`). */
+    name: string;
+    /** The file's raw bytes. */
+    bytes: Uint8Array;
+    /** MIME type the host reported (may be `""` when the OS gave none). */
+    mimeType: string;
+}
+export interface ImporterContribution {
+    /** Stable id, `<namespace>.<importer>` — namespace-checked at register. */
+    id: string;
+    /** Human label for the Open/Import UI (e.g. `"Spreadsheet"`). */
+    title: string;
+    /** Extensions this importer handles, leading dot, lowercased
+     *  (`[".xlsx"]`). The host matches an opened file by extension first. */
+    extensions: readonly string[];
+    /** MIME types this importer also matches (optional; feeds the file
+     *  picker's `accept` and a secondary match when the extension is
+     *  ambiguous). */
+    mimeTypes?: readonly string[];
+    /** Handle an opened file. The importer drives the host through its own
+     *  surfaces (load into an engine, lower into the document, …); it does
+     *  not return a document. Async so it can boot wasm / await mutations. */
+    import(file: ImportRequest): void | Promise<void>;
+}
+/** What an exporter yields — bytes plus the suggested download name. */
+export interface ExportResult {
+    bytes: Uint8Array;
+    /** Suggested file name (the host may still let the user rename). */
+    fileName: string;
+}
+export interface ExporterContribution {
+    /** Stable id, `<namespace>.<exporter>` — namespace-checked at register. */
+    id: string;
+    /** Human label for the Export UI (e.g. `"Workbook (.xlsx)"`). */
+    title: string;
+    /** The extension the produced file carries, leading dot (`".xlsx"`). */
+    extension: string;
+    /** MIME type to stamp on the produced blob (optional). */
+    mimeType?: string;
+    /** Produce the bytes to save, or null to abort silently (nothing to
+     *  export). Async so it can pull from a wasm engine. */
+    export(): Promise<ExportResult | null> | ExportResult | null;
+}
 export interface ToolRegistry {
     register(contribution: ToolContribution): Disposable;
 }
@@ -190,12 +258,46 @@ export interface KeybindingRegistry {
 export interface OverlayRegistry {
     register(contribution: OverlayContribution): Disposable;
 }
+/** W3.2 — the edit-context registry (the shell owns the stack + chrome
+ *  + write-scope; this narrow contract is just the registration door).
+ *  The contribution type lives in ./host (the bundle-facing surface). */
+export interface EditContextRegistry {
+    register(contribution: EditContextContribution): Disposable;
+}
+/** W3.2 — the object-type registry (the shell owns hit-routing; a
+ *  matching element's double-click enters its `editContextType`). */
+export interface ObjectTypeRegistry {
+    register(contribution: ObjectTypeContribution): Disposable;
+}
+/** K-2 / S-06 — the document-importer registry (the shell owns file→plugin
+ *  routing in the open/drag-drop flow). Narrow: `register` only. */
+export interface ImporterRegistry {
+    register(contribution: ImporterContribution): Disposable;
+}
+/** K-2 / S-06 — the document-exporter registry (the export UI lists the
+ *  registered exporters and pulls bytes on demand). */
+export interface ExporterRegistry {
+    register(contribution: ExporterContribution): Disposable;
+}
 export interface ShellRegistries {
     tools: ToolRegistry;
     panels: PanelRegistry;
     commands: CommandRegistry;
     keybindings: KeybindingRegistry;
     overlays: OverlayRegistry;
+    /** W3.2 — edit contexts (B-02). Narrow: `register` only. Optional on
+     *  the contract so a host that hasn't wired the registry yet stays
+     *  assignable; the SDK adapter falls back to a recording stub. */
+    editContexts?: EditContextRegistry;
+    /** W3.2 — object types (W-03). Optional for the same reason. */
+    objectTypes?: ObjectTypeRegistry;
+    /** K-2 / S-06 — document importers (file → plugin). Optional on the
+     *  contract so a host that hasn't wired the registry stays assignable;
+     *  the SDK adapter falls back to a tracked no-op (the headless harness
+     *  injects a recording registry). */
+    importers?: ImporterRegistry;
+    /** K-2 / S-06 — document exporters (plugin → file). Optional likewise. */
+    exporters?: ExporterRegistry;
 }
 export interface MarqueeRectPageLocal {
     pageId: PageId;
@@ -208,7 +310,35 @@ export interface ToolPreviewPolyline {
     /** Draw the closing edge (pen/polygon previews). */
     close?: boolean;
 }
-export type ToolPreviewShape = MarqueeRectPageLocal | ToolPreviewPolyline;
+/**
+ * A path/cubic tool preview (B-07). Where `ToolPreviewPolyline` forces
+ * an in-progress pen run to FLATTEN its cubics (sampling artefacts at
+ * high zoom, wasted work per pointermove), this variant carries the
+ * true anchor/handle form so the host renders real Béziers — one SVG
+ * `<path>` of `C` commands, exact at any zoom.
+ *
+ * `anchors` is the engine's `PathAnchorSpec` form (on-curve `anchor` +
+ * incoming `left` + outgoing `right` handles, IDML `PathPointType`
+ * semantics — structurally `draw-tools`' `AnchorTriple` and what
+ * `insertPath` consumes, so the same run feeds both preview and
+ * commit). `close` draws the closing cubic back to anchor 0. `dashed`
+ * selects the dashed-vs-solid stroke from the shared preview vocabulary
+ * (solid by default, matching the rubber-band family).
+ */
+export interface ToolPreviewPath {
+    pageId: PageId;
+    /** Cubic anchors in page-local pt (the `PathAnchorSpec` shape). */
+    anchors: ReadonlyArray<{
+        anchor: [number, number];
+        left: [number, number];
+        right: [number, number];
+    }>;
+    /** Close the contour (draw the cubic from the last anchor back to 0). */
+    close?: boolean;
+    /** Dashed stroke instead of the default solid (preview vocabulary). */
+    dashed?: boolean;
+}
+export type ToolPreviewShape = MarqueeRectPageLocal | ToolPreviewPolyline | ToolPreviewPath;
 export interface PagedClient {
     mutate(mutation: Mutation): Promise<WorkerToMain>;
     undo(): Promise<WorkerToMain>;
@@ -236,6 +366,26 @@ export interface PagedEditor {
             ty: number;
         };
     };
+    /** S-13 font measurement — the editor routes this to the canvas-wasm
+     *  `CanvasWorker.measureText` query (async across the worker boundary).
+     *  `undefined` when the host build wires no shaper (headless / older
+     *  editor); the host surface then falls back to an estimate. */
+    text?: {
+        measure(family: string, style: string | null, text: string, sizePt: number): Promise<{
+            advance: number;
+            ascender: number;
+            descender: number;
+        }>;
+    };
+    /** C-1 — in-frame plugin scene layers. The editor routes these to the
+     *  canvas-wasm `submitSceneLayer` / `clearSceneLayer` channel (async,
+     *  across the worker boundary). `undefined` when the host build wires no
+     *  scene channel (headless / older editor); `host.contribute.sceneLayer()`
+     *  then warns + no-ops and `supports("rendering.sceneLayer@1")` is false. */
+    sceneLayers?: {
+        submit(elementId: string, layer: SceneLayer): Promise<void>;
+        clear(elementId: string): Promise<void>;
+    };
     overlaySignals: {
         setToolPreview(value: ToolPreviewShape | null): void;
     };