@paged-media/plugin-api 0.2.1-canary.0

package/dist/bundle.d.ts

@@ -0,0 +1,14 @@
+import type { BundleHost, Disposable } from "./host";
+import type { PluginManifest } from "./manifest";
+/** Returned by `activate`. The host tracks every facade registration
+ *  independently, so this handle only needs to release what the
+ *  bundle allocated OUTSIDE the host (timers, caches) — returning a
+ *  no-op disposer is legitimate. */
+export type BundleHandle = Disposable;
+/** A loadable plugin bundle: serializable identity + the activation
+ *  entry point. `defineBundle()` in `@paged-media/plugin-sdk` is the
+ *  ergonomic constructor. */
+export interface PagedBundle {
+    manifest: PluginManifest;
+    activate(host: BundleHost): BundleHandle;
+}

package/dist/contributions.d.ts

@@ -0,0 +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";

package/dist/editor.d.ts

@@ -0,0 +1,244 @@
+import type { ComponentType } from "react";
+import type { CollectionName, ContentSelection, DocumentMeta, ElementGeometryItem, ElementId, MainToWorkerKind, Mutation, PageId, PathAnchorsResult, SelectionMode, WorkerToMain } from "./wire";
+export interface Disposable {
+    dispose(): void;
+}
+export type DockEdge = "left" | "right" | "top" | "bottom" | "center";
+/** Enablement/visibility predicate. The string DSL form is inert
+ *  until the host grows an evaluator; the function form receives the
+ *  live editor handle. */
+export type VisibilityPredicate = string | ((state: unknown) => boolean);
+export type CssCursorToken = "default" | "crosshair" | "grab" | "grabbing" | "move" | "text" | "pointer" | "not-allowed" | "copy" | "cell" | "zoom-in" | "zoom-out" | "nwse-resize" | "nesw-resize" | "ew-resize" | "ns-resize";
+export type CursorSpec = {
+    kind: "css";
+    token: CssCursorToken;
+} | {
+    kind: "svg";
+    src: string;
+    hotspot: {
+        x: number;
+        y: number;
+    };
+};
+/** Why a handler is being deactivated: a real tool change ("switch")
+ *  commits/cancels in-flight state; a spring-load push/pop
+ *  ("suspend") must keep it. */
+export type DeactivateReason = "switch" | "suspend";
+/** A pointer event on the canvas overlay, already page-resolved and
+ *  camera-inverted by the host — handlers never touch camera math.
+ *  Coordinates are document points (pt). */
+export interface CanvasPointerEvent {
+    /** Page the pointer is over, or null on the pasteboard. */
+    pageId: string | null;
+    /** Page-local point in pt. null off-page. */
+    pagePoint: [number, number] | null;
+    /** Page-independent document point in pt. */
+    docPoint: [number, number];
+    modifiers: {
+        shift: boolean;
+        alt: boolean;
+        cmd: boolean;
+        ctrl: boolean;
+    };
+    /** Largest pointer delta this gesture, CSS px — click-vs-drag. */
+    maxDelta: number;
+    /** Mouse button (0 = primary). */
+    button: number;
+    /** Underlying DOM target — handlers may read `data-*` hooks. */
+    target: unknown;
+}
+/** Ephemeral overlay primitive published during a gesture. Kept
+ *  opaque so the contract is stable across host overlay growth. */
+export type OverlayPrimitive = Record<string, unknown>;
+export interface OverlayContext {
+    setPreview(primitives: readonly OverlayPrimitive[]): void;
+}
+/** The contract every tool's `gesture()` factory returns. Mutate only
+ *  through `paged.client` / the document surface — never by reaching
+ *  into model state. */
+export interface GestureHandler {
+    onActivate(paged: PagedEditor): void;
+    onDeactivate(reason: DeactivateReason): void;
+    onPointerDown(e: CanvasPointerEvent): void;
+    onPointerMove(e: CanvasPointerEvent): void;
+    onPointerUp(e: CanvasPointerEvent): void;
+    onKey?(e: KeyboardEvent): void;
+    cursorAt?(e: CanvasPointerEvent): CursorSpec | undefined;
+    renderOverlay?(ctx: OverlayContext): void;
+}
+export type ToolId = string;
+export type ToolGroupId = string;
+export type ToolSectionId = "selection" | "drawType" | "transform" | "modNav";
+export type ToolOptionField = {
+    kind: "number";
+    key: string;
+    label: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+} | {
+    kind: "toggle";
+    key: string;
+    label: string;
+} | {
+    kind: "select";
+    key: string;
+    label: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+};
+export interface ToolOptionsSpec {
+    toolId: string;
+    fields: ToolOptionField[];
+}
+export interface ToolContribution {
+    /** Stable id, `<namespace>.<tool>` — namespace-checked at register. */
+    id: ToolId;
+    title: string;
+    icon: string;
+    /** Single-key shortcut (`"p"`, `"shift+c"`). Wire it through the
+     *  SDK's `contributeTool` so the activation command + guard exist. */
+    shortcut?: string;
+    /** Flyout group — one rail slot; shared group = shared flyout. */
+    group: ToolGroupId;
+    section: ToolSectionId;
+    order?: number;
+    isGroupDefault?: boolean;
+    cursor?: CursorSpec;
+    /** Handler factory the host mounts when the tool activates. Absent
+     *  = rail data only (inert). */
+    gesture?: () => GestureHandler;
+    options?: ToolOptionsSpec;
+    when?: VisibilityPredicate;
+}
+export interface PanelApi {
+    id: string;
+}
+export interface PanelProps {
+    /** The live editor handle (cast to `PagedEditor`). */
+    paged: unknown;
+    api: PanelApi;
+}
+export interface PanelContribution {
+    id: string;
+    title: string;
+    component: ComponentType<PanelProps>;
+    defaultDock?: DockEdge;
+    defaultGroup?: string;
+    icon?: string;
+    when?: VisibilityPredicate;
+    closable?: boolean;
+    movable?: boolean;
+}
+export interface OverlayPageRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface OverlayProps {
+    paged: unknown;
+    /** Camera snapshot at the current frame. */
+    camera: {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /** Page rectangles in document space, in page-id order. */
+    pageRects: ReadonlyMap<PageId, OverlayPageRect>;
+}
+export interface OverlayContribution {
+    id: string;
+    render: ComponentType<OverlayProps>;
+    /** Z-order; higher renders on top. Default 100. */
+    z?: number;
+    when?: VisibilityPredicate;
+}
+export interface CommandContribution {
+    id: string;
+    title: string;
+    category?: string;
+    icon?: string;
+    handler: (paged: unknown, payload?: unknown) => unknown | Promise<unknown>;
+    when?: VisibilityPredicate;
+}
+export interface KeybindingContribution {
+    /** Lowercased combo: `"cmd+shift+h"`, `"p"`, `"escape"`. */
+    key: string;
+    command: string;
+    when?: VisibilityPredicate;
+}
+export interface ToolRegistry {
+    register(contribution: ToolContribution): Disposable;
+}
+export interface PanelRegistry {
+    register(contribution: PanelContribution): Disposable;
+}
+export interface CommandRegistry {
+    register(contribution: CommandContribution): Disposable;
+}
+export interface KeybindingRegistry {
+    register(contribution: KeybindingContribution): Disposable;
+}
+export interface OverlayRegistry {
+    register(contribution: OverlayContribution): Disposable;
+}
+export interface ShellRegistries {
+    tools: ToolRegistry;
+    panels: PanelRegistry;
+    commands: CommandRegistry;
+    keybindings: KeybindingRegistry;
+    overlays: OverlayRegistry;
+}
+export interface MarqueeRectPageLocal {
+    pageId: PageId;
+    /** `[top, left, bottom, right]` in page-local pt. */
+    rect: [number, number, number, number];
+}
+export interface ToolPreviewPolyline {
+    pageId: PageId;
+    points: ReadonlyArray<[number, number]>;
+    /** Draw the closing edge (pen/polygon previews). */
+    close?: boolean;
+}
+export type ToolPreviewShape = MarqueeRectPageLocal | ToolPreviewPolyline;
+export interface PagedClient {
+    mutate(mutation: Mutation): Promise<WorkerToMain>;
+    undo(): Promise<WorkerToMain>;
+    redo(): Promise<WorkerToMain>;
+    collection<T>(name: CollectionName): Promise<readonly T[]>;
+    documentMeta(): Promise<DocumentMeta>;
+    pathAnchors(id: ElementId): Promise<PathAnchorsResult | null>;
+    elementGeometry(ids: ElementId[]): Promise<ElementGeometryItem[]>;
+    setElementSelection(ids: ElementId[], mode: SelectionMode): Promise<ElementId[]>;
+    send(message: MainToWorkerKind): Promise<WorkerToMain>;
+    subscribe(listener: (msg: WorkerToMain) => void): () => void;
+}
+export interface PagedEditor {
+    client: PagedClient;
+    registries: ShellRegistries;
+    selection: {
+        elementSelection: ElementId[];
+        setElementSelection(ids: ElementId[]): void;
+        setElementGeometry(items: ElementGeometryItem[]): void;
+    };
+    camera: {
+        camera: {
+            scale: number;
+            tx: number;
+            ty: number;
+        };
+    };
+    overlaySignals: {
+        setToolPreview(value: ToolPreviewShape | null): void;
+    };
+    tool: {
+        setBaseTool(id: ToolId): void;
+    };
+    contentSelection: {
+        contentSelection: ContentSelection | null;
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,168 @@
+import type { CollectionName, DocumentMeta, ElementGeometryItem, ElementId, HitFilter, HitResult, Mutation, PageId, PathAnchorsResult, SceneTreeNode, SelectionMode } from "./wire";
+import type { CommandContribution, KeybindingContribution, OverlayContribution, PagedEditor, PanelContribution, ToolContribution, ToolPreviewShape } from "./editor";
+import type { PluginManifest } from "./manifest";
+/** Everything a bundle registers is disposable; the host ALSO tracks
+ *  it, so deactivation teardown is structural, not conventional. */
+export interface Disposable {
+    dispose(): void;
+}
+/** Namespaced logger; doubles as the console mirror of the
+ *  diagnostics channel. */
+export interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Reserved (P0 shell work, paged.draw B-02 / paged.web §8): an
+ *  edit-context claim — double-click entry on a content type, scoped
+ *  panel/tool sets. Throws PluginApiNotImplemented in v0. */
+export interface EditContextDescriptor {
+    type: string;
+    entry: "doubleClick" | "command";
+}
+/** Reserved (paged.web §9.1.2): a plugin-defined object type under
+ *  the metadata-plus-baked-fallback contract. Throws in v0. */
+export interface ObjectTypeDescriptor {
+    type: string;
+    /** What the baked IDML form degrades to without the plugin. */
+    bakedFallback: "group" | "rectangle" | "raster";
+}
+/**
+ * The contribution surface. Every method enforces the namespace rule
+ * (ids start with `<manifest.id>.`) and tracks the registration for
+ * automatic teardown on deactivate.
+ */
+export interface ContributionSurface {
+    tool(contribution: ToolContribution): Disposable;
+    panel(contribution: PanelContribution): Disposable;
+    command(contribution: CommandContribution): Disposable;
+    keybinding(contribution: KeybindingContribution): Disposable;
+    overlay(contribution: OverlayContribution): Disposable;
+    /** Reserved — throws PluginApiNotImplemented until edit contexts
+     *  land in the shell. Declared so manifests/docs can reference it. */
+    editContext(descriptor: EditContextDescriptor): Disposable;
+    /** Reserved — throws PluginApiNotImplemented (paged.web W1). */
+    objectType(descriptor: ObjectTypeDescriptor): Disposable;
+}
+/** Expected mutation failures are results, not throws — mirroring the
+ *  editor's mutate-never-throws convention. */
+export type MutationOutcome = {
+    applied: true;
+    createdId: ElementId | null;
+    pageIds: PageId[];
+} | {
+    applied: false;
+    error: unknown;
+};
+export interface DocumentChangeEvent {
+    kind: "mutationApplied" | "undoApplied" | "redoApplied";
+    pageIds: PageId[];
+}
+/**
+ * Read-broad / write-through-one-door. `mutate` is the single write
+ * path; undo/validation/collaboration semantics stay engine-owned.
+ * The future write-scope (edit-context subtree) attaches at this same
+ * chokepoint.
+ */
+export interface DocumentSurface {
+    mutate(mutation: Mutation): Promise<MutationOutcome>;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    collection<T>(name: CollectionName): Promise<readonly T[]>;
+    meta(): Promise<DocumentMeta>;
+    pathAnchors(id: ElementId): Promise<PathAnchorsResult | null>;
+    hitTest(pageId: PageId, point: [number, number], filter?: HitFilter): Promise<HitResult | null>;
+    elementGeometry(ids: ElementId[]): Promise<ElementGeometryItem[]>;
+    tree(): Promise<SceneTreeNode[]>;
+    onDidChange(listener: (e: DocumentChangeEvent) => void): Disposable;
+}
+export interface SelectionSurface {
+    get(): ElementId[];
+    set(ids: ElementId[], mode?: SelectionMode): Promise<ElementId[]>;
+    onDidChange(listener: (ids: ElementId[]) => void): Disposable;
+}
+export interface ViewportSurface {
+    /** Camera snapshot — scale + translation in CSS px. */
+    camera(): {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /** Screen px → document pt at the current zoom (the constant-
+     *  screen-tolerance idiom every tool needs). */
+    pxToPt(px: number): number;
+}
+/** The v0 overlay channel: the shared tool-preview signal (polyline /
+ *  rect). Retained plugin scene layers are the P2 channel — reserved,
+ *  not faked. */
+export interface OverlaySurface {
+    setToolPreview(shape: ToolPreviewShape | null): void;
+}
+/**
+ * Shell actions the HOST APP injects at `loadBundle` time (the
+ * cockpit owns panel placement; the SDK's adapter stays a pure
+ * function over the editor handle). When the host app provides no
+ * implementation, calls warn and no-op — probe with
+ * `host.supports("shell.openPanel@1")`.
+ */
+export interface ShellSurface {
+    /** Open a REGISTERED panel as the active dock tab (the
+     *  Window-menu / panel-rail path). */
+    openPanel(panelId: string): void;
+    closePanel(panelId: string): void;
+}
+/** Namespaced key-value persistence (`paged.plugin.<id>.*`), JSON
+ *  values. Backing is host-provided (localStorage in-process;
+ *  injectable for tests/headless). */
+export interface StorageSurface {
+    get<T>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+    keys(): string[];
+}
+export interface Diagnostic {
+    severity: "error" | "warning" | "info";
+    message: string;
+    /** Free-form origin, e.g. a file/frame/panel identifier. */
+    source?: string;
+    line?: number;
+    column?: number;
+}
+/** The diagnostics channel (paged.web §9.1.4): per-plugin keyed
+ *  diagnostic sets, console-mirrored in v0; the problems-panel UI
+ *  consumes the same store later. */
+export interface DiagnosticsSurface {
+    set(key: string, diagnostics: Diagnostic[]): void;
+    clear(key?: string): void;
+    get(key: string): Diagnostic[];
+    onDidChange(listener: (key: string) => void): Disposable;
+}
+/**
+ * What `activate(host)` receives. Types from `@paged-media/plugin-api`,
+ * values from here — never import host values into a bundle's module
+ * graph.
+ */
+export interface BundleHost {
+    /** The bundle's own manifest (read-only). */
+    readonly manifest: PluginManifest;
+    readonly log: PluginLogger;
+    readonly contribute: ContributionSurface;
+    readonly document: DocumentSurface;
+    readonly selection: SelectionSurface;
+    readonly viewport: ViewportSurface;
+    readonly overlay: OverlaySurface;
+    readonly shell: ShellSurface;
+    readonly storage: StorageSurface;
+    readonly diagnostics: DiagnosticsSurface;
+    /** Capability detection over version sniffing: feature strings of
+     *  the form `"area.member@major"` (see HOST_FEATURES in plugin-sdk). */
+    supports(feature: string): boolean;
+    /**
+     * The marked escape hatch (DESIGN.md §4.9): the raw editor handle,
+     * v0-only. Any use not reachable through a facade is a
+     * BREAKAGE_LOG entry — and this member does not survive the isolate
+     * boundary.
+     */
+    readonly editor: PagedEditor;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, } from "./manifest";
+export type { BundleHandle, PagedBundle } from "./bundle";
+export type { BundleHost, ContributionSurface, DocumentSurface, SelectionSurface, ViewportSurface, OverlaySurface, ShellSurface, StorageSurface, DiagnosticsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextDescriptor, ObjectTypeDescriptor, } from "./host";
+export type * from "./contributions";
+export type * from "./mutations";

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/manifest.d.ts

@@ -0,0 +1,60 @@
+/** 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`). */
+export type PluginId = string;
+export interface PluginManifest {
+    id: PluginId;
+    /** Human-readable name, e.g. "paged.draw". */
+    name: string;
+    /** Bundle semver. */
+    version: string;
+    /** Semver range against `@paged-media/plugin-api`. */
+    apiVersion: string;
+    publisher?: string;
+    capabilities?: PluginCapabilities;
+    contributes?: PluginContributions;
+}
+export interface PluginCapabilities {
+    /** read-broad / write-scoped is the intended default. */
+    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. */
+    rendering?: Array<"sceneLayer" | "overlay" | "hitTest">;
+    /** Edit-context content types the bundle claims (P0 shell work —
+     *  reserved, not yet wired). */
+    editContext?: string[];
+    network?: boolean;
+    clipboard?: "none" | "vector" | "full";
+}
+export interface PluginContributions {
+    /** Tool ids the bundle registers. Must be namespaced by `id`. */
+    tools?: string[];
+    /** Panel ids the bundle registers (expert-leaf React in v0) or
+     *  paths to `*.panel.json` prototypes (design specs, not yet
+     *  interpreted by the host). */
+    panels?: string[];
+    /** Command ids the bundle registers. Must be namespaced by `id`. */
+    commands?: string[];
+    /** Reserved for the P0 edit-context registry. `priority` (decision
+     *  Q12, 2026-06-06) reserves the multi-plugin contention shape NOW:
+     *  when two plugins claim one content type, runtime policy (ships
+     *  at P7) is user choice with a remembered per-content-type
+     *  default, first-party initially; higher priority orders the
+     *  choice list. First-installed-wins is rejected — install-order
+     *  nondeterminism is undebuggable. */
+    editContexts?: Array<{
+        type: string;
+        entry: "doubleClick" | "command";
+        priority?: number;
+    }>;
+    /** Reserved (paged.web §9.1.2): plugin-defined object types under
+     *  the metadata-plus-baked-fallback contract. */
+    objectTypes?: Array<{
+        type: string;
+        bakedFallback: "group" | "rectangle" | "raster";
+    }>;
+}

package/dist/mutations.d.ts

@@ -0,0 +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";