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

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { PagedBundle, BundleHost, Disposable, ShellSurface, PagedEditor, PluginManifest, CanvasPointerEvent, Mutation, MutationOutcome, ToolContribution, PanelContribution } from '@paged-media/plugin-api';
+
+/**
+ * Identity helper that pins a bundle to the `PagedBundle` contract
+ * with full inference — the `defineConfig` idiom. Exists so bundle
+ * authors get contract errors at the definition site, not at the
+ * host's load site.
+ */
+declare function defineBundle(bundle: PagedBundle): PagedBundle;
+
+interface HarnessOptions {
+    /** IDML bytes to load into the headless document. */
+    idml?: Uint8Array;
+}
+/** Not implemented in API v0 — see module comment. */
+declare function createHeadlessHost(_options?: HarnessOptions): BundleHost;
+
+declare class DisposableStore implements Disposable {
+    private items;
+    private disposed;
+    get isDisposed(): boolean;
+    /** Track `d`; returns it for chaining. */
+    add<T extends Disposable>(d: T): T;
+    dispose(): void;
+}
+/** Wrap a plain cleanup function as a Disposable. */
+declare function toDisposable(fn: () => void): Disposable;
+
+/** The plugin API version this SDK implements. */
+declare const API_VERSION = "0.2.0";
+/**
+ * Does `version` satisfy `range`? Supported forms:
+ *   `*`            — anything
+ *   `1.2.3` / `1.2`— exact (missing patch = 0)
+ *   `^1.2.3`       — npm caret: same major, >= base (major > 0);
+ *                    same major+minor, >= patch (major == 0 — the 0.x
+ *                    rule: minors are breaking during incubation)
+ */
+declare function satisfiesApiVersion(range: string, version?: string): boolean;
+
+/** The implemented feature set — `host.supports()` answers from this,
+ *  so docs/tests can't drift from code. Form: `"area.member@major"`. */
+declare const HOST_FEATURES: readonly string[];
+/** Thrown by reserved surface members — a visible seam, never
+ *  fake-interactive. */
+declare class PluginApiNotImplemented extends Error {
+    constructor(member: string, pointer: string);
+}
+/** Minimal storage backing so tests / headless hosts can inject one;
+ *  defaults to localStorage when present, else an in-memory Map. */
+interface StorageBacking {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    /** All keys currently in the backing (unfiltered). */
+    keys(): string[];
+}
+interface CreateBundleHostOptions {
+    storage?: StorageBacking;
+    /** Console sink override (tests). */
+    console?: Pick<Console, "debug" | "info" | "warn" | "error">;
+    /** Shell actions the HOST APP owns (the cockpit's panel placement).
+     *  When absent, `host.shell` warns and no-ops, and
+     *  `supports("shell.openPanel@1")` answers false. */
+    shell?: ShellSurface;
+}
+interface BundleHostHandle {
+    host: BundleHost;
+    /** Tears down every registration made through the host's facades. */
+    dispose(): void;
+}
+declare function createBundleHost(getEditor: () => PagedEditor, manifest: PluginManifest, options?: CreateBundleHostOptions): BundleHostHandle;
+
+interface LoadedBundle {
+    readonly id: string;
+    readonly active: boolean;
+    dispose(): void;
+}
+declare function loadBundle(getEditor: () => PagedEditor, bundle: PagedBundle, options?: CreateBundleHostOptions): LoadedBundle;
+
+declare const CLICK_DRAG_THRESHOLD_PX = 4;
+/** A drag anchored to the page under the pointer at pointer-down. */
+interface PageDrag {
+    pageId: string;
+    /** Page origin in document pt (docPoint − pagePoint at down). */
+    pageOrigin: [number, number];
+    /** Pointer-down position in page-local pt. */
+    startLocal: [number, number];
+}
+declare function beginPageDrag(e: CanvasPointerEvent): PageDrag | null;
+/** Current pointer position in the START page's local coordinates. */
+declare function endLocalFor(drag: PageDrag, e: CanvasPointerEvent): [number, number];
+/** Screen px → document pt at `scale`, the constant-screen-tolerance
+ *  idiom. Falls back to 1:1 when the camera hasn't initialised. */
+declare function pxToPt(scale: number, px: number): number;
+/**
+ * Fire a mutation and select the element the engine reports as
+ * created, so a fresh shape immediately carries selection chrome —
+ * the post-insert flow every drawing tool wants. Failures resolve
+ * (never throw); the outcome is returned for optional handling.
+ */
+declare function commitAndSelect(paged: PagedEditor, mutation: Mutation, label: string): Promise<MutationOutcome>;
+
+declare function contributeTool(host: BundleHost, tool: ToolContribution): Disposable;
+
+declare function contributePanel(host: BundleHost, panel: PanelContribution): Disposable;
+
+export { API_VERSION, type BundleHostHandle, CLICK_DRAG_THRESHOLD_PX, type CreateBundleHostOptions, DisposableStore, HOST_FEATURES, type HarnessOptions, type LoadedBundle, type PageDrag, PluginApiNotImplemented, type StorageBacking, beginPageDrag, commitAndSelect, contributePanel, contributeTool, createBundleHost, createHeadlessHost, defineBundle, endLocalFor, loadBundle, pxToPt, satisfiesApiVersion, toDisposable };

package/dist/index.js

@@ -0,0 +1,539 @@
+// src/define-bundle.ts
+function defineBundle(bundle) {
+  return bundle;
+}
+
+// src/harness.ts
+function createHeadlessHost(_options) {
+  throw new Error(
+    "@paged-media/plugin-sdk: the headless harness is not implemented yet (tracked in plugin-draw/BREAKAGE_LOG.md). Run bundles inside the editor app, or unit-test their machines (pure, host-free) instead."
+  );
+}
+
+// src/disposables.ts
+var DisposableStore = class {
+  items = [];
+  disposed = false;
+  get isDisposed() {
+    return this.disposed;
+  }
+  /** Track `d`; returns it for chaining. */
+  add(d) {
+    if (this.disposed) {
+      d.dispose();
+      return d;
+    }
+    this.items.push(d);
+    return d;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (let i = this.items.length - 1; i >= 0; i--) {
+      try {
+        this.items[i].dispose();
+      } catch {
+      }
+    }
+    this.items = [];
+  }
+};
+function toDisposable(fn) {
+  let done = false;
+  return {
+    dispose() {
+      if (done) return;
+      done = true;
+      fn();
+    }
+  };
+}
+
+// src/version.ts
+var API_VERSION = "0.2.0";
+function parse(v) {
+  const m = /^(\d+)\.(\d+)(?:\.(\d+))?$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3] ?? "0")];
+}
+function satisfiesApiVersion(range, version = API_VERSION) {
+  const r = range.trim();
+  if (r === "*") return true;
+  const v = parse(version);
+  if (!v) return false;
+  if (r.startsWith("^")) {
+    const base = parse(r.slice(1));
+    if (!base) return false;
+    if (base[0] > 0) {
+      if (v[0] !== base[0]) return false;
+      if (v[1] !== base[1]) return v[1] > base[1];
+      return v[2] >= base[2];
+    }
+    return v[0] === 0 && v[1] === base[1] && v[2] >= base[2];
+  }
+  const exact = parse(r);
+  if (!exact) return false;
+  return v[0] === exact[0] && v[1] === exact[1] && v[2] === exact[2];
+}
+
+// src/host-impl.ts
+var HOST_FEATURES = [
+  "contribute.tool@1",
+  "contribute.panel@1",
+  "contribute.command@1",
+  "contribute.keybinding@1",
+  "contribute.overlay@1",
+  "document.mutate@1",
+  "document.undo@1",
+  "document.collection@1",
+  "document.meta@1",
+  "document.pathAnchors@1",
+  "document.hitTest@1",
+  "document.elementGeometry@1",
+  "document.tree@1",
+  "document.onDidChange@1",
+  "selection@1",
+  "viewport@1",
+  "overlay.toolPreview@1",
+  "storage@1",
+  "diagnostics@1"
+];
+var PluginApiNotImplemented = class extends Error {
+  constructor(member, pointer) {
+    super(
+      `plugin-api: ${member} is reserved and not implemented in v0 (${pointer})`
+    );
+    this.name = "PluginApiNotImplemented";
+  }
+};
+function defaultStorageBacking() {
+  const ls = globalThis.localStorage;
+  if (ls) {
+    return {
+      getItem: (k) => ls.getItem(k),
+      setItem: (k, v) => ls.setItem(k, v),
+      removeItem: (k) => ls.removeItem(k),
+      keys: () => {
+        const out = [];
+        for (let i = 0; i < ls.length; i++) {
+          const k = ls.key(i);
+          if (k !== null) out.push(k);
+        }
+        return out;
+      }
+    };
+  }
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem: (k) => map.get(k) ?? null,
+    setItem: (k, v) => void map.set(k, v),
+    removeItem: (k) => void map.delete(k),
+    keys: () => Array.from(map.keys())
+  };
+}
+function createBundleHost(getEditor, manifest, options) {
+  const store = new DisposableStore();
+  const sink = options?.console ?? console;
+  const ns = `${manifest.id}.`;
+  const tag = `[${manifest.id}]`;
+  const assertNamespaced = (id, kind) => {
+    if (!id.startsWith(ns)) {
+      throw new Error(
+        `plugin-api: ${kind} id "${id}" must be namespaced under "${ns}" (the manifest id) \u2014 the namespace rule is where capability enforcement attaches`
+      );
+    }
+  };
+  const log = {
+    debug: (m, ...a) => sink.debug(`${tag} ${m}`, ...a),
+    info: (m, ...a) => sink.info(`${tag} ${m}`, ...a),
+    warn: (m, ...a) => sink.warn(`${tag} ${m}`, ...a),
+    error: (m, ...a) => sink.error(`${tag} ${m}`, ...a)
+  };
+  const contribute = {
+    tool(c) {
+      assertNamespaced(c.id, "tool");
+      return store.add(getEditor().registries.tools.register(c));
+    },
+    panel(c) {
+      assertNamespaced(c.id, "panel");
+      return store.add(getEditor().registries.panels.register(c));
+    },
+    command(c) {
+      assertNamespaced(c.id, "command");
+      return store.add(getEditor().registries.commands.register(c));
+    },
+    keybinding(c) {
+      return store.add(getEditor().registries.keybindings.register(c));
+    },
+    overlay(c) {
+      assertNamespaced(c.id, "overlay");
+      return store.add(getEditor().registries.overlays.register(c));
+    },
+    editContext() {
+      throw new PluginApiNotImplemented(
+        "contribute.editContext",
+        "P0 shell work \u2014 plugin-draw/BREAKAGE_LOG.md B-02"
+      );
+    },
+    objectType() {
+      throw new PluginApiNotImplemented(
+        "contribute.objectType",
+        "paged.web W1 \u2014 base-idea \xA79.1.2"
+      );
+    }
+  };
+  const document = {
+    async mutate(mutation) {
+      try {
+        const reply = await getEditor().client.mutate(mutation);
+        if (reply.kind === "mutationApplied") {
+          return {
+            applied: true,
+            createdId: reply.payload.createdId ?? null,
+            pageIds: reply.payload.pageIds
+          };
+        }
+        return {
+          applied: false,
+          error: reply.kind === "mutationFailed" ? reply.payload : reply
+        };
+      } catch (error) {
+        return { applied: false, error };
+      }
+    },
+    async undo() {
+      await getEditor().client.undo();
+    },
+    async redo() {
+      await getEditor().client.redo();
+    },
+    collection(name) {
+      return getEditor().client.collection(name);
+    },
+    meta() {
+      return getEditor().client.documentMeta();
+    },
+    pathAnchors(id) {
+      return getEditor().client.pathAnchors(id).catch(() => null);
+    },
+    async hitTest(pageId, point, filter = "any") {
+      try {
+        const reply = await getEditor().client.send({
+          kind: "hitTest",
+          payload: { pageId, docPoint: point, filter }
+        });
+        return reply.kind === "hitResult" ? reply.payload : null;
+      } catch {
+        return null;
+      }
+    },
+    elementGeometry(ids) {
+      return getEditor().client.elementGeometry(ids);
+    },
+    async tree() {
+      const reply = await getEditor().client.send({
+        kind: "requestSceneTree"
+      });
+      return reply.kind === "sceneTree" ? reply.payload.roots : [];
+    },
+    onDidChange(listener) {
+      const off = getEditor().client.subscribe((msg) => {
+        if (msg.kind === "mutationApplied" || msg.kind === "undoApplied" || msg.kind === "redoApplied") {
+          listener({ kind: msg.kind, pageIds: msg.payload.pageIds });
+        }
+      });
+      return store.add(toDisposable(off));
+    }
+  };
+  const selection = {
+    get() {
+      return getEditor().selection.elementSelection;
+    },
+    async set(ids, mode = "replace") {
+      const editor = getEditor();
+      const applied = await editor.client.setElementSelection(ids, mode);
+      editor.selection.setElementSelection(applied);
+      return applied;
+    },
+    onDidChange(listener) {
+      const off = getEditor().client.subscribe((msg) => {
+        if (msg.kind === "elementSelectionApplied") {
+          listener(msg.payload.ids);
+        }
+      });
+      return store.add(toDisposable(off));
+    }
+  };
+  const viewport = {
+    camera() {
+      const cam = getEditor().camera.camera;
+      return { scale: cam.scale, tx: cam.tx, ty: cam.ty };
+    },
+    pxToPt(px) {
+      const scale = getEditor().camera.camera.scale;
+      return px / (scale > 0 ? scale : 1);
+    }
+  };
+  const overlay = {
+    setToolPreview(shape) {
+      getEditor().overlaySignals.setToolPreview(shape);
+    }
+  };
+  const backing = options?.storage ?? defaultStorageBacking();
+  const prefix = `paged.plugin.${manifest.id}.`;
+  const storage = {
+    get(key) {
+      const raw = backing.getItem(prefix + key);
+      if (raw === null) return void 0;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return void 0;
+      }
+    },
+    set(key, value) {
+      backing.setItem(prefix + key, JSON.stringify(value));
+    },
+    delete(key) {
+      backing.removeItem(prefix + key);
+    },
+    keys() {
+      return backing.keys().filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+    }
+  };
+  const diagnosticStore = /* @__PURE__ */ new Map();
+  const diagnosticListeners = /* @__PURE__ */ new Set();
+  const emitDiagnostics = (key) => {
+    for (const l of diagnosticListeners) l(key);
+  };
+  const diagnostics = {
+    set(key, items) {
+      diagnosticStore.set(key, items);
+      for (const d of items) {
+        const line = `${tag} ${key}: ${d.message}` + (d.line !== void 0 ? ` (${d.source ?? ""}:${d.line})` : "");
+        if (d.severity === "error") sink.error(line);
+        else if (d.severity === "warning") sink.warn(line);
+        else sink.info(line);
+      }
+      emitDiagnostics(key);
+    },
+    clear(key) {
+      if (key !== void 0) diagnosticStore.delete(key);
+      else diagnosticStore.clear();
+      emitDiagnostics(key ?? "");
+    },
+    get(key) {
+      return diagnosticStore.get(key) ?? [];
+    },
+    onDidChange(listener) {
+      diagnosticListeners.add(listener);
+      return store.add(toDisposable(() => diagnosticListeners.delete(listener)));
+    }
+  };
+  const shell = options?.shell ?? {
+    openPanel(panelId) {
+      log.warn(
+        `shell.openPanel("${panelId}") ignored \u2014 the host app provided no shell actions (probe with supports("shell.openPanel@1"))`
+      );
+    },
+    closePanel() {
+    }
+  };
+  const featureSet = new Set(HOST_FEATURES);
+  if (options?.shell) {
+    featureSet.add("shell.openPanel@1");
+  }
+  const host = {
+    manifest,
+    log,
+    contribute,
+    document,
+    selection,
+    viewport,
+    overlay,
+    shell,
+    storage,
+    diagnostics,
+    supports: (feature) => featureSet.has(feature),
+    get editor() {
+      return getEditor();
+    }
+  };
+  return {
+    host,
+    dispose() {
+      store.dispose();
+    }
+  };
+}
+
+// src/load.ts
+var ID_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
+function loadBundle(getEditor, bundle, options) {
+  const { manifest } = bundle;
+  if (!ID_PATTERN.test(manifest.id)) {
+    throw new Error(
+      `loadBundle: manifest id "${manifest.id}" is not reverse-DNS (expected e.g. "media.paged.draw")`
+    );
+  }
+  if (!satisfiesApiVersion(manifest.apiVersion)) {
+    throw new Error(
+      `loadBundle: ${manifest.id}@${manifest.version} requires plugin-api "${manifest.apiVersion}", host implements ${API_VERSION}`
+    );
+  }
+  const { host, dispose: disposeHost } = createBundleHost(
+    getEditor,
+    manifest,
+    options
+  );
+  const handle = bundle.activate(host);
+  let active = true;
+  return {
+    id: manifest.id,
+    get active() {
+      return active;
+    },
+    dispose() {
+      if (!active) return;
+      active = false;
+      try {
+        handle.dispose();
+      } finally {
+        disposeHost();
+      }
+    }
+  };
+}
+
+// src/gestures.ts
+var CLICK_DRAG_THRESHOLD_PX = 4;
+function beginPageDrag(e) {
+  if (e.button !== 0 || !e.pageId || !e.pagePoint) return null;
+  return {
+    pageId: e.pageId,
+    pageOrigin: [
+      e.docPoint[0] - e.pagePoint[0],
+      e.docPoint[1] - e.pagePoint[1]
+    ],
+    startLocal: e.pagePoint
+  };
+}
+function endLocalFor(drag, e) {
+  return [
+    e.docPoint[0] - drag.pageOrigin[0],
+    e.docPoint[1] - drag.pageOrigin[1]
+  ];
+}
+function pxToPt(scale, px) {
+  return px / (scale > 0 ? scale : 1);
+}
+async function commitAndSelect(paged, mutation, label) {
+  try {
+    const reply = await paged.client.mutate(mutation);
+    if (reply.kind !== "mutationApplied") {
+      const error = reply.kind === "mutationFailed" ? reply.payload : reply;
+      console.warn(`${label} rejected by engine:`, JSON.stringify(error));
+      return { applied: false, error };
+    }
+    const createdId = reply.payload.createdId ?? null;
+    if (createdId) {
+      try {
+        const ids = await paged.client.setElementSelection(
+          [createdId],
+          "replace"
+        );
+        paged.selection.setElementSelection(ids);
+        const items = await paged.client.elementGeometry(ids);
+        paged.selection.setElementGeometry(items);
+      } catch {
+      }
+    }
+    return {
+      applied: true,
+      createdId,
+      pageIds: reply.payload.pageIds
+    };
+  } catch (error) {
+    console.warn(`${label} failed:`, error);
+    return { applied: false, error };
+  }
+}
+
+// src/tools.ts
+function contentSelectionInactive(state) {
+  const editor = state;
+  return editor?.contentSelection?.contentSelection == null;
+}
+function contributeTool(host, tool) {
+  const store = new DisposableStore();
+  store.add(host.contribute.tool(tool));
+  const commandId = `${tool.id}.activate`;
+  store.add(
+    host.contribute.command({
+      id: commandId,
+      title: `Tool: ${tool.title}`,
+      category: "Tools",
+      icon: tool.icon,
+      handler: (paged) => {
+        paged.tool.setBaseTool(tool.id);
+      }
+    })
+  );
+  if (tool.shortcut) {
+    store.add(
+      host.contribute.keybinding({
+        key: tool.shortcut,
+        command: commandId,
+        when: contentSelectionInactive
+      })
+    );
+  }
+  return store;
+}
+
+// src/panels.ts
+function contributePanel(host, panel) {
+  const store = new DisposableStore();
+  store.add(host.contribute.panel(panel));
+  store.add(
+    host.contribute.command({
+      id: `${panel.id}.show`,
+      title: `Show: ${panel.title}`,
+      category: "View",
+      icon: panel.icon,
+      handler: () => {
+        host.shell.openPanel(panel.id);
+      }
+    })
+  );
+  store.add(
+    host.contribute.command({
+      id: `${panel.id}.hide`,
+      title: `Hide: ${panel.title}`,
+      category: "View",
+      handler: () => {
+        host.shell.closePanel(panel.id);
+      }
+    })
+  );
+  return store;
+}
+export {
+  API_VERSION,
+  CLICK_DRAG_THRESHOLD_PX,
+  DisposableStore,
+  HOST_FEATURES,
+  PluginApiNotImplemented,
+  beginPageDrag,
+  commitAndSelect,
+  contributePanel,
+  contributeTool,
+  createBundleHost,
+  createHeadlessHost,
+  defineBundle,
+  endLocalFor,
+  loadBundle,
+  pxToPt,
+  satisfiesApiVersion,
+  toDisposable
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@paged-media/plugin-sdk",
+  "version": "0.2.1-canary.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@paged-media/plugin-api": "0.2.1-canary.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "description": "The Paged plugin runtime: loadBundle, the in-process BundleHost adapter, the gesture kit, and version negotiation.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paged-media/plugin-sdk.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "canary"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist --clean"
+  }
+}