@paged-media/plugin-api 0.2.6-canary.0 → 0.2.9-canary.0

package/dist/manifest.d.ts

@@ -1,3 +1,4 @@
+import type { AssetKind } from "./assets";
 /** Reverse-DNS plugin identity, e.g. `media.paged.draw`. Doubles as
  *  the namespace prefix for every contribution id the bundle
  *  registers (`media.paged.draw.tool.pen`). */
@@ -15,20 +16,144 @@ export interface PluginManifest {
     contributes?: PluginContributions;
 }
 export interface PluginCapabilities {
-    /** read-broad / write-scoped is the intended default. */
+    /** read-broad / write-scoped is the intended default. Declaring
+     *  `document` is the PREREQUISITE for the document surface: a bundle
+     *  with no `document` capability cannot read OR write the document
+     *  (the host gate throws). `read` gates the read doors
+     *  (collection/meta/tree/pathAnchors/elementGeometry/getMetadata/
+     *  onDidChange); `write` gates the write doors (mutate/undo/redo/
+     *  setMetadata) AND `selection.set` (a document-level action). When
+     *  enforcement is on, an absent sub-field denies that direction. */
     document?: {
         read?: "broad" | "scoped";
         write?: "broad" | "scoped";
     };
     /** Render-pipeline surfaces the bundle uses. v0: `overlay` means
-     *  the shared TS overlay signals (tool previews); `sceneLayer` and
-     *  a host-side `hitTest` service are reserved for the P2 channel. */
+     *  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">;
+    /** The bundle registers keybindings directly via
+     *  `contribute.keybinding`. Keybindings have no id to list under
+     *  `contributes`, so this boolean is their declaration. v0 first-
+     *  party bundles let the HOST derive activation shortcuts from the
+     *  tool registry (B-15), so this stays `false`/absent for them; a
+     *  bundle that wires its OWN keybindings must declare it. */
+    keybindings?: boolean;
     /** Edit-context content types the bundle claims (P0 shell work —
      *  reserved, not yet wired). */
     editContext?: string[];
-    network?: boolean;
+    /**
+     * Asset-store reads the bundle uses (paged.web W-06). A closed array
+     * vocabulary: v1 has exactly `"fonts"` (gates `host.assets.getFontFace`
+     * — serving DOCUMENT font face bytes for `@font-face`). `"images"` is
+     * RESERVED for v2 and REJECTED by validation today (the door has no
+     * image read yet; accepting the declaration would claim a capability
+     * the host cannot honor). Declaring `"fonts"` is the prerequisite for
+     * the door (the host gate throws on an undeclared use). See
+     * DESIGN.md §13. */
+    assets?: AssetKind[];
+    /**
+     * Persistent BINARY storage the bundle uses (K-4 / S-08). The KV
+     * `host.storage` (localStorage JSON) is always available ungated; this
+     * capability gates the OPFS-backed `host.blob` byte store for payloads
+     * too large for KV (multi-MB workbook bytes, decode spill). Declaring
+     * `blob: true` is the prerequisite for every `host.blob` door (the host
+     * gate throws on an undeclared use). `quotaBytes`, when present,
+     * REQUESTS a ceiling — the host enforces the stricter of it and its
+     * hard per-plugin cap; `host.blob.usage()` reports the granted value.
+     */
+    storage?: StorageCapability;
+    /**
+     * Network reach the bundle declares (paged.data D-03; base-idea §11). The
+     * boolean form is the legacy shorthand (`true` = the bundle reaches the
+     * network, every origin still gated behind runtime consent; `false`/absent =
+     * no network). The object form declares a per-origin allow-list + a
+     * human-readable purpose the consent UI shows. Reach is NEVER silent: every
+     * origin is gated behind `host.network.requestConsent` (the visible
+     * data-source manifest), and a document does NOT fetch on open — external
+     * sources are inert until the user reviews + consents (base-idea §11). This
+     * is the OUTER bound; consent is the inner gate.
+     */
+    network?: boolean | NetworkCapability;
+    /**
+     * Data-provider roles (paged.data §7.1 / D-09): the neutral cross-plugin
+     * composition where one plugin PUBLISHES a resolved dataset and another
+     * CONSUMES it (e.g. a sheet sourced from a governed query) — they rendezvous
+     * ONLY at the core `host.dataProviders` registry, never by direct contact.
+     * `publish` = the categories this bundle may register providers in; `consume`
+     * = the categories it may discover + read. A bundle declaring neither role
+     * gets no surface.
+     */
+    dataProviders?: DataProvidersCapability;
     clipboard?: "none" | "vector" | "full";
+    /**
+     * Declared WebAssembly artifacts the bundle ships and loads at
+     * runtime (paged.web W-07 — e.g. a future HTML/CSS layout engine
+     * compiled to wasm). Capability-gated: a bundle CANNOT instantiate a
+     * module the host has not granted via the loader, and only the paths
+     * listed here are loadable (declared-only). See DESIGN.md §10 and
+     * `docs/wasm-packaging.md` for the budget rules and trust line.
+     *
+     * The wasm gets NO ambient authority: it has no direct engine/DOM/
+     * network handle and talks only through the bundle's already-gated
+     * JS. Threads/SharedArrayBuffer are OFF in v1.
+     */
+    wasm?: WasmArtifact[];
+}
+/** Persistent binary-storage declaration (K-4 / S-08). `blob` gates the
+ *  OPFS-backed `host.blob` byte store; `quotaBytes` requests a ceiling
+ *  (the host enforces the stricter of it and its hard per-plugin cap). */
+export interface StorageCapability {
+    blob?: boolean;
+    quotaBytes?: number;
+}
+/** A structured network declaration (paged.data D-03; base-idea §11). The
+ *  `origins` allow-list is the OUTER bound — the set of `scheme://host[:port]`
+ *  the bundle may EVER request; runtime per-origin consent is the inner gate.
+ *  The string `"consent"` means the bundle has no fixed list (author-supplied
+ *  sources) — every reach requires runtime consent and none is pre-allowed. */
+export interface NetworkCapability {
+    origins: string[] | "consent";
+    /** Human-readable reason shown in the consent UI / data-source manifest. */
+    purpose?: string;
+}
+/** Data-provider roles (paged.data §7.1 / D-09). Categories are a neutral, open
+ *  string vocabulary (`"dataset"`, …) — discovery is BY CATEGORY, never by
+ *  plugin identity. The PROVIDER and CONSUMER plugins each declare only their
+ *  own role; they never name or import each other (§2.1). */
+export interface DataProvidersCapability {
+    /** Categories this bundle MAY register providers in (the publish role). */
+    publish?: string[];
+    /** Categories this bundle MAY discover + read (the consume role). */
+    consume?: string[];
+}
+/** Purposes a bundle may declare for a shipped wasm module. A closed
+ *  vocabulary (like `rendering`) so the host can reason about grants;
+ *  unknown purposes are rejected at validation. v1:
+ *  - `layout`  — a foreign-document layout/measure engine (paged.web).
+ *  - `codec`   — encode/decode (image/font transforms).
+ *  - `compute` — generic pure computation with no special host role. */
+export type WasmPurpose = "layout" | "codec" | "compute";
+/** One declared wasm artifact. `path` is bundle-relative (no leading
+ *  slash, no `..`); `maxBytes`, when present, tightens — never widens —
+ *  the host's per-artifact ceiling (see the budget table in
+ *  `docs/wasm-packaging.md`). */
+export interface WasmArtifact {
+    /** Logical name the bundle passes to the host loader
+     *  (`loadBundleWasm(bundle, name)`). Unique within the manifest. */
+    name: string;
+    /** Bundle-relative path to the `.wasm` file. No leading `/`, no `..`
+     *  segment (path-traversal is rejected at validation). */
+    path: string;
+    /** Why the bundle ships this module — gates what the host grants. */
+    purpose: WasmPurpose;
+    /** Optional per-artifact byte ceiling the bundle self-imposes. Must
+     *  be ≤ the host's hard per-artifact ceiling; the loader enforces the
+     *  stricter of the two. */
+    maxBytes?: number;
 }
 export interface PluginContributions {
     /** Tool ids the bundle registers. Must be namespaced by `id`. */
@@ -57,4 +182,12 @@ export interface PluginContributions {
         type: string;
         bakedFallback: "group" | "rectangle" | "raster";
     }>;
+    /** Importer ids the bundle registers (K-2 / S-06). Must be namespaced
+     *  by `id`. The rich `ImporterContribution` (extensions, MIME, the
+     *  `import()` callback) is handed in at `host.contribute.importer(...)`
+     *  — the manifest only DECLARES which ids may register. */
+    importers?: string[];
+    /** Exporter ids the bundle registers (K-2 / S-06). Must be namespaced
+     *  by `id`. */
+    exporters?: string[];
 }

package/dist/mutations.d.ts

@@ -1 +1 @@
-export type { ElementId, PageId, NodeId, NodeSpec, Mutation, Operation, PropertyPath, Value, PathAnchorSpec, PathAnchorTriple, PathAnchorsResult, PathPointAddress, PathPointRole, PathfinderKind, HitFilter, HitResult, CollectionName, DocumentMeta, ElementGeometryItem, SceneTreeNode, SelectionMode, ContentSelection, MainToWorker, MainToWorkerKind, WorkerToMain, GestureType, GestureHandle, GestureModifiers, SwatchSpec, GradientSpec, GradientStopSpec, SwatchSummary, GradientSummary, LayerSummary, } from "./wire";
+export type { ElementId, PageId, NodeId, NodeSpec, Mutation, Operation, PropertyPath, Value, PathAnchorSpec, PathAnchorTriple, PathAnchorsResult, PathPointAddress, PathPointRole, PathfinderKind, HitFilter, HitResult, CollectionName, DocumentMeta, ElementGeometryItem, SceneTreeNode, SelectionMode, ContentSelection, MainToWorker, MainToWorkerKind, WorkerToMain, SceneLayer, SceneItem, ScenePathSeg, ScenePaint, GestureType, GestureHandle, GestureModifiers, SwatchSpec, GradientSpec, GradientStopSpec, SwatchSummary, GradientSummary, LayerSummary, } from "./wire";

package/dist/panel-schema.d.ts

@@ -0,0 +1,92 @@
+import type { ComponentType } from "react";
+import type { BindingsSurface } from "./host";
+import type { PropertyPath, Value } from "./wire";
+export type WidgetValueBinding = {
+    kind: "literal";
+    value: Value;
+} | {
+    kind: "selectionProperty";
+    /** Which selection surface to address (defaults to `"element"`). */
+    scope?: "element" | "content";
+    /** The PropertyPath the widget reads from + commits to. */
+    path: PropertyPath;
+    /** Optional unit coercion on read + write (`pt` / `px` / `%`). */
+    coerce?: "pt" | "px" | "%";
+};
+export interface BindingRef {
+    /** The published binding name to look up (`host.bindings.publish`). */
+    bind: string;
+    /** Invert the looked-up boolean. The only transform — NOT a DSL. */
+    negate?: boolean;
+}
+/** A visibility / enablement gate: either a static literal or a
+ *  lookup of a published plugin binding. Absent = always shown /
+ *  enabled. A non-boolean published value is coerced with `Boolean()`
+ *  (and a missing name reads as `false` — a visible seam, never a
+ *  throw). */
+export type SchemaGate = boolean | BindingRef;
+export interface PanelSchemaRow {
+    /** Catalog widget id (a curated primitive-leaf id the host
+     *  registered). An unknown id renders a visible "unknown widget"
+     *  placeholder, not a throw. */
+    widget: string;
+    /** Static props forwarded to the leaf (label, options, placeholder,
+     *  …). Must match the leaf's declared `PropSchema`; unknown keys are
+     *  ignored by the leaf. */
+    props?: Record<string, unknown>;
+    /** The widget's primary value binding — the §11.5 ceiling
+     *  (`literal | selectionProperty`). Absent = a layout-only / display
+     *  leaf (label, section). */
+    value?: WidgetValueBinding;
+    /** Show the row only when this gate is truthy. Absent = always. */
+    visible?: SchemaGate;
+    /** Enable the row's control only when this gate is truthy. Absent =
+     *  always enabled (subject to the widget's own no-write-path
+     *  disable). */
+    enabled?: SchemaGate;
+}
+export interface PanelSchemaSection {
+    /** Section title (the kicker / disclosure header). Absent = an
+     *  untitled flat group. */
+    title?: string;
+    /** Render as a collapsible disclosure (the catalog section's
+     *  `collapsible` chrome). */
+    collapsible?: boolean;
+    rows: PanelSchemaRow[];
+    /** Hide the entire section (title + rows) on this gate. */
+    visible?: SchemaGate;
+}
+export interface PanelSchema {
+    /** Stable id, `<namespace>.<panel>` — namespace-checked at register
+     *  exactly like a React panel. */
+    id: string;
+    title: string;
+    icon?: string;
+    defaultDock?: "left" | "right" | "top" | "bottom" | "center";
+    defaultGroup?: string;
+    sections: PanelSchemaSection[];
+}
+/** A panel contribution that is a declarative SCHEMA rather than an
+ *  expert-leaf React component. The host renders it from the catalog
+ *  and subscribes to the bundle's published bindings. Carries no
+ *  React — the isolate-ready panel form. */
+export interface SchemaPanelContribution {
+    id: string;
+    title: string;
+    icon?: string;
+    defaultDock?: "left" | "right" | "top" | "bottom" | "center";
+    defaultGroup?: string;
+    /** The declarative body (sections/rows/widgets from the catalog). */
+    schema: PanelSchema;
+    closable?: boolean;
+    movable?: boolean;
+}
+export interface SchemaPanelRendererProps {
+    schema: PanelSchema;
+    /** The bundle's published-bindings surface — the renderer subscribes
+     *  to it so `visible`/`enabled` gates react to plugin state. */
+    bindings: BindingsSurface;
+}
+/** The host-injected schema-panel renderer (React). Resolves a schema
+ *  through the host's catalog + the bundle's bindings. */
+export type SchemaPanelRenderer = ComponentType<SchemaPanelRendererProps>;

package/dist/widgets.d.ts

@@ -0,0 +1,48 @@
+import type { ComponentType } from "react";
+/** Languages the host code editor highlights. `text` = no
+ *  highlighting (line numbers + gutter only). Additive: a host MAY
+ *  accept more, but only these are contract-guaranteed. */
+export type CodeEditorLanguage = "html" | "css" | "text";
+/** A per-line marker rendered in the editor's diagnostics gutter and,
+ *  where the host supports it, as an inline squiggle. Structurally a
+ *  subset of `Diagnostic` (host.ts) — `line` is 1-based. */
+export interface CodeEditorDiagnostic {
+    severity: "error" | "warning" | "info";
+    message: string;
+    /** 1-based line the marker attaches to. Out-of-range = clamped. */
+    line: number;
+}
+/**
+ * Props the host code-editor widget accepts. Controlled: the bundle
+ * owns `value` and applies `onChange`. The widget never mutates the
+ * document — it is a pure text surface (the panel persists through
+ * `host.document`/`host.storage` as it already does for a textarea).
+ */
+export interface CodeEditorProps {
+    value: string;
+    onChange(next: string): void;
+    /** Syntax-highlight language; default `"text"`. */
+    language?: CodeEditorLanguage;
+    /** Per-line markers (squiggles + gutter dots). */
+    diagnostics?: readonly CodeEditorDiagnostic[];
+    /** Non-editable view (still highlighted + line-numbered). */
+    readOnly?: boolean;
+    /** Min editor height in CSS px (the widget grows with content). */
+    minHeight?: number;
+    /** Accessible label / test hook passthrough (`data-*` is host'd). */
+    ariaLabel?: string;
+}
+/**
+ * The widget catalog the host injects. Members are React component
+ * TYPES (the knowingly-non-clonable exit, same class as panel
+ * components — DESIGN.md §6): they live in the host's UI package and
+ * are handed to in-process bundles. Across the future isolate boundary
+ * a widget is addressed by a serializable descriptor instead; that is
+ * a second `WidgetSurface` implementation, not a contract change.
+ */
+export interface WidgetSurface {
+    /** The line-numbered, syntax-highlighting, diagnostics-gutter source
+     *  editor. Always present: a plain-textarea fallback stands in when
+     *  the host app injects no real widget catalog. */
+    readonly CodeEditor: ComponentType<CodeEditorProps>;
+}