@openpen/module-api 1.1.1 → 1.3.0

package/dist/cursors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Cursor compilation + sanitisation helpers shared by host runtime and
+ * plugin SDK.
+ *
+ * Three closure layers gate every cursor entry before it reaches
+ * `v-html`: R1–R12 shape validation here, DOMPurify content sanitisation
+ * inside compileCursor, and a deep-clone + freeze in the contribution
+ * store. Removing any one of them re-opens an attack surface the others
+ * cannot close.
+ */
+import type { CursorContribution, CursorSpec, Hotspot } from './types/contributions';
+export interface CompiledCursor {
+    /** Sanitised SVG / HTML fragment to mount as `innerHTML` on the cursor element. */
+    svgMarkup: string;
+    /** Hotspot offset, in CSS pixels relative to the markup's top-left. */
+    hotspot: Hotspot;
+    /** CSS keyword fallback retained for legacy callers. */
+    fallbackCssKeyword: string;
+}
+export interface CursorResolutionContext {
+    /**
+     * Hostname-encoded plugin id (`@acme/x` → `acme.x`) used to assemble
+     * `openpen-plugin://<hostname>/<path>` URLs for relative-path specs.
+     * Undefined for built-in modules — path-form specs without a hostname
+     * resolve to `null` (host falls back to its default cursor).
+     */
+    pluginHostname?: string;
+    /** Injection point for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * W3C CSS UI Level 3 cursor keywords. The legacy `cursor: string` form
+ * MUST match one of these (case-insensitive after trim); everything else
+ * is rejected by R2 / R12.
+ */
+export declare const SAFE_CURSOR_KEYWORDS: ReadonlySet<string>;
+export declare function isSafeRelativePath(p: unknown): p is string;
+export declare function pluginHostname(moduleId: string): string;
+export declare function pluginAssetUrl(moduleId: string, relativePath: string): string;
+/**
+ * Sanitise SVG markup before it reaches `v-html`. Rationale for each
+ * flag: `USE_PROFILES: { svg: true }` covers script tags, on* handlers,
+ * and javascript: hrefs; `FORBID_TAGS: ['foreignObject']` closes the
+ * mXSS escape hatch the SVG profile alone does not; turning off
+ * `ALLOW_UNKNOWN_PROTOCOLS` blocks `<use href="data:...">` and friends.
+ */
+export declare function sanitizeSvgMarkup(raw: string): string;
+/**
+ * Convert a frozen, shape-validated CursorContribution.cursor into render
+ * data ready for `v-html`. Returns `null` for legacy keyword strings
+ * (caller falls back to the host default cursor) and for any spec the
+ * sanitiser empties out completely.
+ *
+ * Async because path-form SVG specs are fetched through `openpen-plugin://`
+ * at compile time; inline + PNG branches resolve synchronously inside the
+ * returned Promise.
+ */
+export declare function compileCursor(spec: CursorSpec, context?: CursorResolutionContext): Promise<CompiledCursor | null>;
+export type CursorSanitizeRule = 'R1' | 'R2' | 'R3' | 'R4' | 'R5' | 'R6' | 'R7' | 'R8' | 'R9' | 'R10' | 'R11' | 'R12';
+export interface CursorSanitizeDiagnostic {
+    /** Contribution id, or `'<unknown>'` if `id` was missing / invalid. */
+    id: string;
+    rule: CursorSanitizeRule;
+    reason: string;
+}
+export interface CursorSanitizeOptions {
+    /**
+     * Built-in modules (host bundle) cannot use path forms because they
+     * have no `openpen-plugin://<hostname>` namespace. R7 / R10 reject
+     * such contributions for built-ins.
+     */
+    isBuiltin?: boolean;
+}
+export interface CursorSanitizeResult {
+    cleaned: CursorContribution[];
+    diagnostics: CursorSanitizeDiagnostic[];
+}
+/**
+ * Shape-validate raw cursor contributions before they reach the
+ * contribution-store. This is the R1–R12 gate; SVG markup content is
+ * sanitised later inside {@link compileCursor} via DOMPurify.
+ */
+export declare function sanitizeCursorContributions(cursors: unknown, options?: CursorSanitizeOptions): CursorSanitizeResult;

package/dist/define-module.d.ts

@@ -0,0 +1,17 @@
+import type { OpenPenModule } from './types/module';
+/**
+ * Identity helper for declaring an OpenPen module with full type
+ * inference and runtime sanity checks. Throws `Error` (preflight) when:
+ *
+ *   - `id` is missing or has invalid characters
+ *   - `contributes` is missing entirely
+ *   - `contributes` has no contribution fields
+ *   - `contributes` references a slot key not in the catalogue
+ *
+ * This is intentionally a small surface — full validation
+ * (id collisions across modules, slot quota, settingsSchema parse, etc.)
+ * happens later in the host app's `module-validator`. This helper
+ * catches the obvious developer mistakes at the module's own boundary
+ * so errors surface in the module's repo, not deep inside OpenPen.
+ */
+export declare function defineModule<TModule extends OpenPenModule>(spec: TModule): TModule;

package/dist/host/color-utils.d.ts

@@ -0,0 +1,11 @@
+import type { ModuleHost } from './types';
+type Utils = ModuleHost['colorUtils'];
+export declare const resolveColorStyle: Utils['resolveColorStyle'];
+export declare const hexToRgb: Utils['hexToRgb'];
+export declare const rgbToHex: Utils['rgbToHex'];
+export declare const hsvToRgb: Utils['hsvToRgb'];
+export declare const rgbToHsv: Utils['rgbToHsv'];
+export declare const hexToHsv: Utils['hexToHsv'];
+export declare const hsvToHex: Utils['hsvToHex'];
+export declare const isValidHex: Utils['isValidHex'];
+export {};

package/{src/host/event-bus.ts → dist/host/event-bus.d.ts}

@@ -1,9 +1,10 @@
 /**
  * @openpen/module-api/host — Domain Event Bus
  *
- * Re-exports the renderer-side event-bus emit/on so module components
- * can publish and subscribe without reaching into host runtime internals.
- * The bus is a process-local pub/sub for cross-module coordination.
+ * Proxies the renderer-side event-bus emit/on through the host registry so
+ * module components can publish and subscribe without reaching into host
+ * runtime internals. The bus is a process-local pub/sub for cross-module
+ * coordination.
  *
  * **Host-emitted events (consume via `on(name, cb)`):**
  *
@@ -33,5 +34,6 @@
  * }
  * ```
  */
-
-export { emit, on } from '../../../../src/core/runtime/event-bus'
+import type { ModuleHost } from './types';
+export declare const emit: ModuleHost['emit'];
+export declare const on: ModuleHost['on'];

package/dist/host/host-commands.d.ts

@@ -0,0 +1 @@
+export declare const hostCommands: import("./types").HostCommandsAPI;

package/dist/host/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @openpen/module-api/host — Host Services Sub-module
+ *
+ * Exposes host shared services to module components via a clean sub-path
+ * export. Module code MUST import from here instead of using cross-layer
+ * '../../../' relative imports into src/composables or src/services.
+ *
+ * Module code MUST import from `@openpen/module-api/host` instead of
+ * using cross-layer relative imports into src/.
+ *
+ * Design principle: this sub-module MUST NOT leak host internal
+ * implementation types. All types are OpenPen SDK types (from ../types/).
+ */
+export { useStrokeStyle } from './stroke-style';
+export type { StrokeColor } from './stroke-style';
+export { resolveColorStyle, hexToRgb, rgbToHex, hsvToRgb, rgbToHsv, hexToHsv, hsvToHex, isValidHex, } from './color-utils';
+export { getAllStrokes, removeStrokeById, pushCommand, commitStroke } from './stroke-store';
+export type { Stroke } from './stroke-store';
+export { usePopupAnchor, calculatePopupAnchor } from './popup-anchor';
+export { usePassthroughGuard } from './passthrough';
+export { hostCommands } from './host-commands';
+export { emit, on } from './event-bus';
+export { getSlotEntries } from './slot-entries';
+export { setModuleContext, clearModuleContext } from './module-context-registry';

package/dist/host/index.js

@@ -0,0 +1,51 @@
+import { _useHost } from "./registry.js";
+import { u } from "../_chunks/passthrough-DKU7JYuQ.js";
+import { c, s } from "../_chunks/module-context-registry-Cn1IWYu9.js";
+const useStrokeStyle = () => _useHost().useStrokeStyle();
+const resolveColorStyle = (ctx, color, startPoint, endPoint) => _useHost().colorUtils.resolveColorStyle(ctx, color, startPoint, endPoint);
+const hexToRgb = (hex) => _useHost().colorUtils.hexToRgb(hex);
+const rgbToHex = (r, g, b) => _useHost().colorUtils.rgbToHex(r, g, b);
+const hsvToRgb = (h, s2, v) => _useHost().colorUtils.hsvToRgb(h, s2, v);
+const rgbToHsv = (r, g, b) => _useHost().colorUtils.rgbToHsv(r, g, b);
+const hexToHsv = (hex) => _useHost().colorUtils.hexToHsv(hex);
+const hsvToHex = (h, s2, v) => _useHost().colorUtils.hsvToHex(h, s2, v);
+const isValidHex = (hex) => _useHost().colorUtils.isValidHex(hex);
+const getAllStrokes = () => _useHost().getAllStrokes();
+const removeStrokeById = (id) => _useHost().removeStrokeById(id);
+const pushCommand = (command) => _useHost().pushCommand(command);
+const commitStroke = (stroke) => _useHost().commitStroke(stroke);
+const usePopupAnchor = (options) => _useHost().usePopupAnchor(options);
+const calculatePopupAnchor = (options) => _useHost().calculatePopupAnchor(options);
+const hostCommands = new Proxy({}, {
+  get(_target, prop) {
+    return Reflect.get(_useHost().hostCommands, prop);
+  }
+});
+const emit = (event, payload) => _useHost().emit(event, payload);
+const on = (event, handler) => _useHost().on(event, handler);
+const getSlotEntries = (slotKey) => _useHost().getSlotEntries(slotKey);
+export {
+  calculatePopupAnchor,
+  c as clearModuleContext,
+  commitStroke,
+  emit,
+  getAllStrokes,
+  getSlotEntries,
+  hexToHsv,
+  hexToRgb,
+  hostCommands,
+  hsvToHex,
+  hsvToRgb,
+  isValidHex,
+  on,
+  pushCommand,
+  removeStrokeById,
+  resolveColorStyle,
+  rgbToHex,
+  rgbToHsv,
+  s as setModuleContext,
+  u as usePassthroughGuard,
+  usePopupAnchor,
+  useStrokeStyle
+};
+//# sourceMappingURL=index.js.map

package/dist/host/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/host/stroke-style.ts","../../src/host/color-utils.ts","../../src/host/stroke-store.ts","../../src/host/popup-anchor.ts","../../src/host/host-commands.ts","../../src/host/event-bus.ts","../../src/host/slot-entries.ts"],"sourcesContent":["/**\n * @openpen/module-api/host — Stroke Style\n *\n * Proxies the useStrokeStyle composable through the host registry so\n * module components can read + write the global stroke style without\n * reaching past the package boundary. The reactive refs returned by\n * useStrokeStyle stay live across the proxy because the host registry\n * returns the singleton refs the host owns.\n *\n * initStrokeStyleFromSettings is host-boot-only and intentionally\n * NOT exposed here.\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const useStrokeStyle: ModuleHost['useStrokeStyle'] = () =>\n  _useHost().useStrokeStyle()\n\n// Re-export the StrokeColor type via the public SDK types (not host internals).\nexport type { StrokeColor } from '../types/tool'\n","/**\n * @openpen/module-api/host — Color Utilities\n *\n * Proxies color manipulation helpers through the host registry. These\n * helpers are pure functions (no host state), so a future refactor MAY\n * lift the implementations into this package itself; for now they flow\n * through injection for consistency with the rest of the host surface.\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\ntype Utils = ModuleHost['colorUtils']\n\nexport const resolveColorStyle: Utils['resolveColorStyle'] = (ctx, color, startPoint, endPoint) =>\n  _useHost().colorUtils.resolveColorStyle(ctx, color, startPoint, endPoint)\n\nexport const hexToRgb: Utils['hexToRgb'] = (hex) =>\n  _useHost().colorUtils.hexToRgb(hex)\n\nexport const rgbToHex: Utils['rgbToHex'] = (r, g, b) =>\n  _useHost().colorUtils.rgbToHex(r, g, b)\n\nexport const hsvToRgb: Utils['hsvToRgb'] = (h, s, v) =>\n  _useHost().colorUtils.hsvToRgb(h, s, v)\n\nexport const rgbToHsv: Utils['rgbToHsv'] = (r, g, b) =>\n  _useHost().colorUtils.rgbToHsv(r, g, b)\n\nexport const hexToHsv: Utils['hexToHsv'] = (hex) =>\n  _useHost().colorUtils.hexToHsv(hex)\n\nexport const hsvToHex: Utils['hsvToHex'] = (h, s, v) =>\n  _useHost().colorUtils.hsvToHex(h, s, v)\n\nexport const isValidHex: Utils['isValidHex'] = (hex) =>\n  _useHost().colorUtils.isValidHex(hex)\n","/**\n * @openpen/module-api/host — Stroke Store\n *\n * Proxies the stroke store read + history APIs through the host registry.\n * The exposed surface:\n *   - getAllStrokes / removeStrokeById / pushCommand: read + history access\n *     required by stroke-eraser (and similar tools).\n *   - commitStroke: atomic add + ADD_STROKE history + redraw for async-placement\n *     tools (e.g. text) that finalise a stroke outside the synchronous\n *     onPointerUp return. Not idempotent — calling it twice appends twice.\n *\n * Host-internal state mutation helpers (clearAll, addStroke, undo, redo)\n * are intentionally NOT exposed here — modules must use hostCommands for\n * undo/redo and canvas clear.\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const getAllStrokes: ModuleHost['getAllStrokes'] = () =>\n  _useHost().getAllStrokes()\n\nexport const removeStrokeById: ModuleHost['removeStrokeById'] = (id) =>\n  _useHost().removeStrokeById(id)\n\nexport const pushCommand: ModuleHost['pushCommand'] = (command) =>\n  _useHost().pushCommand(command)\n\nexport const commitStroke: ModuleHost['commitStroke'] = (stroke) =>\n  _useHost().commitStroke(stroke)\n\n// Re-export Stroke type via the public SDK types, not host internals.\nexport type { Stroke } from '../types/tool'\n","/**\n * @openpen/module-api/host — Popup Anchor\n *\n * Proxies the `usePopupAnchor` composable and the `calculatePopupAnchor`\n * pure helper through the host registry so module components can position\n * popups relative to anchor elements without reaching past the package\n * boundary.\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const usePopupAnchor: ModuleHost['usePopupAnchor'] = (options) =>\n  _useHost().usePopupAnchor(options)\n\nexport const calculatePopupAnchor: ModuleHost['calculatePopupAnchor'] = (options) =>\n  _useHost().calculatePopupAnchor(options)\n","/**\n * @openpen/module-api/host — Host Commands\n *\n * Proxies hostCommands through the host registry so module components\n * can trigger host infrastructure actions (pin toggle, canvas clear,\n * undo/redo, drawing mode toggle) without reaching past the package\n * boundary. The exported object is a Proxy so every property access\n * fetches the live `hostCommands` from the registered host.\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const hostCommands = new Proxy({} as ModuleHost['hostCommands'], {\n  get(_target, prop) {\n    return Reflect.get(_useHost().hostCommands as object, prop)\n  },\n})\n","/**\n * @openpen/module-api/host — Domain Event Bus\n *\n * Proxies the renderer-side event-bus emit/on through the host registry so\n * module components can publish and subscribe without reaching into host\n * runtime internals. The bus is a process-local pub/sub for cross-module\n * coordination.\n *\n * **Host-emitted events (consume via `on(name, cb)`):**\n *\n * | Event name                | Payload shape                                   | Fires when                                                           |\n * |---------------------------|-------------------------------------------------|----------------------------------------------------------------------|\n * | `'tool-changed'`          | `{ tool: string } & Partial<ToolConfig>`        | The active drawing tool changes (user click, IPC, or shortcut)       |\n * | `'stroke-style-changed'`  | `{ color?: StrokeColor; lineWidth?: number }`   | Color or stroke width changes                                        |\n * | `'canvas-redraw-requested'` | (no payload)                                  | A module wants the canvas to repaint (eraser, transformer, etc.)     |\n *\n * **Module-emitted events:** modules MAY emit any event name they\n * choose; the bus is namespace-free. Use a prefix (e.g. `'my-plugin:'`)\n * to avoid colliding with another module's events.\n *\n * `on(name, cb)` returns an unsubscribe function — register it via\n * `ctx.onDispose(unsubscribe)` so the listener is cleaned up when the\n * module unloads.\n *\n * @example\n * ```ts\n * import { on } from '@openpen/module-api/host'\n *\n * setup(ctx) {\n *   const off = on('tool-changed', (payload) => {\n *     console.log('tool now', payload.tool)\n *   })\n *   ctx.onDispose(off)\n * }\n * ```\n */\n\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const emit: ModuleHost['emit'] = (event, payload) =>\n  _useHost().emit(event, payload)\n\nexport const on: ModuleHost['on'] = (event, handler) =>\n  _useHost().on(event, handler)\n","/**\n * @openpen/module-api/host — Slot Entries Reader\n *\n * Proxies getSlotEntries through the host registry so module components\n * can render UI driven by other modules' contributions to the same slot\n * (for example, the shape-picker rendering all canvas.shapes contributions).\n */\nimport { _useHost } from './registry'\nimport type { ModuleHost } from './types'\n\nexport const getSlotEntries: ModuleHost['getSlotEntries'] = <T = unknown>(slotKey: string) =>\n  _useHost().getSlotEntries<T>(slotKey)\n"],"names":["s"],"mappings":";;;AAeO,MAAM,iBAA+C,MAC1D,SAAA,EAAW,eAAA;ACHN,MAAM,oBAAgD,CAAC,KAAK,OAAO,YAAY,aACpF,WAAW,WAAW,kBAAkB,KAAK,OAAO,YAAY,QAAQ;AAEnE,MAAM,WAA8B,CAAC,QAC1C,WAAW,WAAW,SAAS,GAAG;AAE7B,MAAM,WAA8B,CAAC,GAAG,GAAG,MAChD,WAAW,WAAW,SAAS,GAAG,GAAG,CAAC;AAEjC,MAAM,WAA8B,CAAC,GAAGA,IAAG,MAChD,WAAW,WAAW,SAAS,GAAGA,IAAG,CAAC;AAEjC,MAAM,WAA8B,CAAC,GAAG,GAAG,MAChD,WAAW,WAAW,SAAS,GAAG,GAAG,CAAC;AAEjC,MAAM,WAA8B,CAAC,QAC1C,WAAW,WAAW,SAAS,GAAG;AAE7B,MAAM,WAA8B,CAAC,GAAGA,IAAG,MAChD,WAAW,WAAW,SAAS,GAAGA,IAAG,CAAC;AAEjC,MAAM,aAAkC,CAAC,QAC9C,WAAW,WAAW,WAAW,GAAG;ACjB/B,MAAM,gBAA6C,MACxD,SAAA,EAAW,cAAA;AAEN,MAAM,mBAAmD,CAAC,OAC/D,SAAA,EAAW,iBAAiB,EAAE;AAEzB,MAAM,cAAyC,CAAC,YACrD,SAAA,EAAW,YAAY,OAAO;AAEzB,MAAM,eAA2C,CAAC,WACvD,SAAA,EAAW,aAAa,MAAM;ACjBzB,MAAM,iBAA+C,CAAC,YAC3D,SAAA,EAAW,eAAe,OAAO;AAE5B,MAAM,uBAA2D,CAAC,YACvE,SAAA,EAAW,qBAAqB,OAAO;ACHlC,MAAM,eAAe,IAAI,MAAM,IAAkC;AAAA,EACtE,IAAI,SAAS,MAAM;AACjB,WAAO,QAAQ,IAAI,SAAA,EAAW,cAAwB,IAAI;AAAA,EAC5D;AACF,CAAC;ACwBM,MAAM,OAA2B,CAAC,OAAO,YAC9C,WAAW,KAAK,OAAO,OAAO;AAEzB,MAAM,KAAuB,CAAC,OAAO,YAC1C,WAAW,GAAG,OAAO,OAAO;AClCvB,MAAM,iBAA+C,CAAc,YACxE,SAAA,EAAW,eAAkB,OAAO;"}

package/{src/host/module-context-registry.ts → dist/host/module-context-registry.d.ts}

@@ -9,26 +9,12 @@
  * Module code MUST NOT import from this file directly — use
  * `useModuleContext` from `@openpen/module-api` instead.
  */
-import type { ModuleSetupContext } from '../types/module'
-
-const registry = new Map<string, ModuleSetupContext>()
-
+import type { ModuleSetupContext } from '../types/module';
 /** Register (or replace) the context for a module. Called by module-loader before setup(). */
-export function setModuleContext(moduleId: string, ctx: ModuleSetupContext): void {
-  registry.set(moduleId, ctx)
-}
-
+export declare function setModuleContext(moduleId: string, ctx: ModuleSetupContext): void;
 /** Remove the context for a module. Called by module-loader in rollbackModule(). */
-export function clearModuleContext(moduleId: string): void {
-  registry.delete(moduleId)
-}
-
+export declare function clearModuleContext(moduleId: string): void;
 /** Look up the context for a module. Returns undefined if not registered. */
-export function getModuleContext(moduleId: string): ModuleSetupContext | undefined {
-  return registry.get(moduleId)
-}
-
+export declare function getModuleContext(moduleId: string): ModuleSetupContext | undefined;
 /** Resets the entire registry. Test-only — do not call in production code. */
-export function resetModuleContextRegistryForTest(): void {
-  registry.clear()
-}
+export declare function resetModuleContextRegistryForTest(): void;

package/dist/host/passthrough.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleHost } from './types';
+export declare const usePassthroughGuard: ModuleHost['usePassthroughGuard'];

package/dist/host/popup-anchor.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleHost } from './types';
+export declare const usePopupAnchor: ModuleHost['usePopupAnchor'];
+export declare const calculatePopupAnchor: ModuleHost['calculatePopupAnchor'];

package/dist/host/registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @openpen/module-api/host — Host runtime registry
+ *
+ * The host (OpenPen renderer process) calls `registerHost(impl)` once at
+ * boot to inject its concrete implementation of the `ModuleHost` contract.
+ * Module / plugin code consumes the surface through the proxy exports in
+ * `./index.ts`, which fetch the registered implementation via `_useHost()`.
+ *
+ * This file is intentionally **not** re-exported from the package's `.`
+ * entry. The renderer host imports it via the `@openpen/module-api/host/registry`
+ * subpath; plugin code MUST NOT import from this path.
+ *
+ * The pattern follows the same dependency direction as VS Code's extension
+ * host, Figma's plugin sandbox, Obsidian's plugin API, and Penpot's plugin
+ * types: the SDK package owns the contract, the host injects the runtime.
+ */
+import type { ModuleHost } from './types';
+/**
+ * Inject the host's concrete `ModuleHost` implementation. **MUST** be called
+ * exactly once, at app boot in `src/main.ts`, before any module/plugin code
+ * imports from `@openpen/module-api/host`.
+ *
+ * @throws if called more than once.
+ */
+export declare function registerHost(impl: ModuleHost): void;
+/**
+ * Internal: fetch the registered host implementation. Called by every proxy
+ * in `./index.ts`. Plugin / module code MUST NOT import this directly —
+ * use the proxies instead.
+ *
+ * @throws if `registerHost()` has not been called yet (fail-fast: catches
+ * boot-order bugs before silent state corruption).
+ */
+export declare function _useHost(): ModuleHost;
+/**
+ * Test-only: clears the registered host so a fresh `registerHost()` call
+ * can be made in the next test. MUST NOT be called from production code.
+ */
+export declare function _resetHostRegistryForTest(): void;

package/dist/host/registry.js

@@ -0,0 +1,37 @@
+const HOST_STORE_KEY = Symbol.for("openpen.module-api.host-store");
+function getStore() {
+  const g = globalThis;
+  let store = g[HOST_STORE_KEY];
+  if (!store) {
+    store = { registered: null };
+    g[HOST_STORE_KEY] = store;
+  }
+  return store;
+}
+function registerHost(impl) {
+  const store = getStore();
+  if (store.registered !== null) {
+    throw new Error(
+      "@openpen/module-api/host: registerHost called more than once. The host MUST register exactly once at boot."
+    );
+  }
+  store.registered = impl;
+}
+function _useHost() {
+  const store = getStore();
+  if (store.registered === null) {
+    throw new Error(
+      "@openpen/module-api/host: host not registered. Call registerHost() at app boot (src/main.ts) before any module or plugin code imports from this subpath."
+    );
+  }
+  return store.registered;
+}
+function _resetHostRegistryForTest() {
+  getStore().registered = null;
+}
+export {
+  _resetHostRegistryForTest,
+  _useHost,
+  registerHost
+};
+//# sourceMappingURL=registry.js.map

package/dist/host/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sources":["../../src/host/registry.ts"],"sourcesContent":["/**\n * @openpen/module-api/host — Host runtime registry\n *\n * The host (OpenPen renderer process) calls `registerHost(impl)` once at\n * boot to inject its concrete implementation of the `ModuleHost` contract.\n * Module / plugin code consumes the surface through the proxy exports in\n * `./index.ts`, which fetch the registered implementation via `_useHost()`.\n *\n * This file is intentionally **not** re-exported from the package's `.`\n * entry. The renderer host imports it via the `@openpen/module-api/host/registry`\n * subpath; plugin code MUST NOT import from this path.\n *\n * The pattern follows the same dependency direction as VS Code's extension\n * host, Figma's plugin sandbox, Obsidian's plugin API, and Penpot's plugin\n * types: the SDK package owns the contract, the host injects the runtime.\n */\nimport type { ModuleHost } from './types'\n\n/**\n * Module-scope state cannot live as a top-level `let` because production\n * bundles can load this file more than once (main app bundle + runtime\n * uikit bundle each carry their own copy when the host subpath is not\n * externalized in the import-map). Multiple copies of the module each get\n * their own `let registered`, so `registerHost()` writes one slot and\n * `_useHost()` reads the other — both raise the unregistered-host error.\n *\n * Stash the slot on globalThis under a unique Symbol so every copy of this\n * file resolves to the same store. Vue uses the same trick for shared\n * globals across bundlers (see VUE_OPTIONS_API symbol in @vue/runtime-core).\n */\ninterface HostStore {\n  registered: ModuleHost | null\n}\n\nconst HOST_STORE_KEY = Symbol.for('openpen.module-api.host-store') as unknown as PropertyKey\n\nfunction getStore(): HostStore {\n  type GlobalWithStore = typeof globalThis & { [k: PropertyKey]: HostStore | undefined }\n  const g = globalThis as GlobalWithStore\n  let store = g[HOST_STORE_KEY]\n  if (!store) {\n    store = { registered: null }\n    g[HOST_STORE_KEY] = store\n  }\n  return store\n}\n\n/**\n * Inject the host's concrete `ModuleHost` implementation. **MUST** be called\n * exactly once, at app boot in `src/main.ts`, before any module/plugin code\n * imports from `@openpen/module-api/host`.\n *\n * @throws if called more than once.\n */\nexport function registerHost(impl: ModuleHost): void {\n  const store = getStore()\n  if (store.registered !== null) {\n    throw new Error(\n      '@openpen/module-api/host: registerHost called more than once. ' +\n      'The host MUST register exactly once at boot.',\n    )\n  }\n  store.registered = impl\n}\n\n/**\n * Internal: fetch the registered host implementation. Called by every proxy\n * in `./index.ts`. Plugin / module code MUST NOT import this directly —\n * use the proxies instead.\n *\n * @throws if `registerHost()` has not been called yet (fail-fast: catches\n * boot-order bugs before silent state corruption).\n */\nexport function _useHost(): ModuleHost {\n  const store = getStore()\n  if (store.registered === null) {\n    throw new Error(\n      '@openpen/module-api/host: host not registered. ' +\n      'Call registerHost() at app boot (src/main.ts) before any module ' +\n      'or plugin code imports from this subpath.',\n    )\n  }\n  return store.registered\n}\n\n/**\n * Test-only: clears the registered host so a fresh `registerHost()` call\n * can be made in the next test. MUST NOT be called from production code.\n */\nexport function _resetHostRegistryForTest(): void {\n  getStore().registered = null\n}\n"],"names":[],"mappings":"AAkCA,MAAM,iBAAiB,OAAO,IAAI,+BAA+B;AAEjE,SAAS,WAAsB;AAE7B,QAAM,IAAI;AACV,MAAI,QAAQ,EAAE,cAAc;AAC5B,MAAI,CAAC,OAAO;AACV,YAAQ,EAAE,YAAY,KAAA;AACtB,MAAE,cAAc,IAAI;AAAA,EACtB;AACA,SAAO;AACT;AASO,SAAS,aAAa,MAAwB;AACnD,QAAM,QAAQ,SAAA;AACd,MAAI,MAAM,eAAe,MAAM;AAC7B,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAGJ;AACA,QAAM,aAAa;AACrB;AAUO,SAAS,WAAuB;AACrC,QAAM,QAAQ,SAAA;AACd,MAAI,MAAM,eAAe,MAAM;AAC7B,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAIJ;AACA,SAAO,MAAM;AACf;AAMO,SAAS,4BAAkC;AAChD,WAAA,EAAW,aAAa;AAC1B;"}

package/dist/host/slot-entries.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleHost } from './types';
+export declare const getSlotEntries: ModuleHost['getSlotEntries'];

package/dist/host/stroke-store.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleHost } from './types';
+export declare const getAllStrokes: ModuleHost['getAllStrokes'];
+export declare const removeStrokeById: ModuleHost['removeStrokeById'];
+export declare const pushCommand: ModuleHost['pushCommand'];
+export declare const commitStroke: ModuleHost['commitStroke'];
+export type { Stroke } from '../types/tool';

package/dist/host/stroke-style.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleHost } from './types';
+export declare const useStrokeStyle: ModuleHost['useStrokeStyle'];
+export type { StrokeColor } from '../types/tool';

package/dist/host/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @openpen/module-api/host — Host interface contract
+ *
+ * Defines the surface the host (OpenPen renderer process) MUST implement
+ * and inject via `registerHost()`. Module / plugin code consumes this surface
+ * through the proxy exports in `./index.ts`, never importing this file
+ * directly.
+ *
+ * This file MUST NOT import from outside `packages/module-api/src/`; the
+ * point of the contract is that the SDK package owns the shape independent
+ * of host implementation paths. Cross-boundary imports here would prevent
+ * clean .d.ts emission (TS6059) when the package is built for publishing.
+ */
+import type { Ref, ComputedRef } from 'vue';
+import type { Stroke, StrokeColor } from '../types/tool';
+import type { SnapEdge } from '../inject-keys';
+/**
+ * Discriminated union for `pushCommand`. Modules wrap their state changes in
+ * one of these so the host can undo / redo them through `hostCommands.history`.
+ */
+type StrokeAddCommand = {
+    type: 'ADD_STROKE';
+    stroke: Stroke;
+};
+type StrokeRemoveCommand = {
+    type: 'REMOVE_STROKE';
+    stroke: Stroke;
+};
+type StrokeClearAllCommand = {
+    type: 'CLEAR_ALL';
+    strokes: Stroke[];
+};
+export type HistoryCommand = StrokeAddCommand | StrokeRemoveCommand | StrokeClearAllCommand;
+/** Slot-entry shape returned by `getSlotEntries`. */
+export interface ContributionEntry<T = unknown> {
+    /** Module that registered this contribution. */
+    moduleId: string;
+    /** Slot-specific contribution payload (typed by consumer). */
+    contribution: T;
+}
+/**
+ * Color manipulation helpers. Pure functions, no host state.
+ *
+ * NOTE: These pure helpers are exposed via injection for symmetry with the
+ * rest of the host surface; a later refactor MAY lift them into the package
+ * itself once the host-inversion is settled.
+ */
+export interface ColorUtilsAPI {
+    /**
+     * Resolve a `StrokeColor` to a canvas-compatible style value, expanding
+     * linear-gradient descriptors via the provided context + endpoints.
+     */
+    resolveColorStyle: (ctx: CanvasRenderingContext2D, color: StrokeColor, startPoint: {
+        x: number;
+        y: number;
+    }, endPoint: {
+        x: number;
+        y: number;
+    }) => string | CanvasGradient;
+    hexToRgb: (hex: string) => [number, number, number];
+    rgbToHex: (r: number, g: number, b: number) => string;
+    hsvToRgb: (h: number, s: number, v: number) => [number, number, number];
+    rgbToHsv: (r: number, g: number, b: number) => [number, number, number];
+    hexToHsv: (hex: string) => [number, number, number];
+    hsvToHex: (h: number, s: number, v: number) => string;
+    isValidHex: (hex: string) => boolean;
+}
+/** Imperative actions modules invoke against host infrastructure. */
+export interface HostCommandsAPI {
+    controlBar: {
+        togglePin: () => void;
+    };
+    canvas: {
+        clear: () => void;
+    };
+    history: {
+        undo: () => void;
+        redo: () => void;
+    };
+    app: {
+        toggleDrawingMode: () => void;
+        setDrawingMode: (enabled: boolean) => void;
+    };
+}
+/** Return shape of `useStrokeStyle()`. */
+export interface StrokeStyleAPI {
+    color: Readonly<Ref<StrokeColor>>;
+    lineWidth: Readonly<Ref<number>>;
+    setColor: (color: StrokeColor) => void;
+    setLineWidth: (w: number) => void;
+}
+export type PopupPlacement = 'below' | 'above' | 'left' | 'right';
+export type PopupArrowDir = 'up' | 'down' | 'left' | 'right';
+type RefOrComputed<T> = Ref<T> | ComputedRef<T>;
+export interface UsePopupAnchorOptions {
+    triggerEl: RefOrComputed<HTMLElement | null>;
+    anchorEl?: RefOrComputed<HTMLElement | null>;
+    wrapperEl: RefOrComputed<HTMLElement | null>;
+    snapEdge: RefOrComputed<SnapEdge>;
+    popupEl?: RefOrComputed<HTMLElement | null>;
+    popupHeight: number | RefOrComputed<number>;
+    popupWidth: number | RefOrComputed<number>;
+    gap?: number;
+    safeMargin?: number;
+    arrowInset?: number;
+}
+export interface UsePopupAnchorAPI {
+    popupStyle: Readonly<Ref<Record<string, string>>>;
+    arrowDir: Readonly<Ref<PopupArrowDir>>;
+    arrowOffset: Readonly<Ref<string>>;
+    placement: Readonly<Ref<PopupPlacement>>;
+    updatePosition: () => void;
+}
+export interface PopupRect {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+export interface CalculatePopupAnchorOptions {
+    triggerRect: PopupRect;
+    anchorRect?: PopupRect;
+    wrapperRect: PopupRect;
+    snapEdge: SnapEdge;
+    popupHeight?: number;
+    popupWidth?: number;
+    gap?: number;
+    arrowInset?: number;
+    safeMargin?: number;
+    availableSpace?: {
+        above: number;
+        below: number;
+        left: number;
+        right: number;
+    };
+}
+export interface CalculatePopupAnchorResult {
+    placement: PopupPlacement;
+    arrowDir: PopupArrowDir;
+    arrowOffset: string;
+    popupStyle: Record<string, string>;
+}
+/**
+ * The shape OpenPen's renderer process implements and registers at boot via
+ * `registerHost(impl)`. All `@openpen/module-api/host` exports proxy through
+ * `_useHost()` to fetch the registered implementation lazily.
+ */
+export interface ModuleHost {
+    emit: (event: string, payload?: unknown) => void;
+    on: (event: string, handler: (payload: unknown) => void) => () => void;
+    getAllStrokes: () => Stroke[];
+    removeStrokeById: (id: string) => boolean;
+    pushCommand: (command: HistoryCommand) => void;
+    /**
+     * Atomically commit a finished stroke: append it to the store, record an
+     * ADD_STROKE history command, and request a canvas redraw. The commit path
+     * for tools that produce strokes outside the synchronous pointer-up return
+     * (e.g. async-placement tools that finalise after a deferred interaction).
+     *
+     * Semantically equivalent to the host's synchronous onPointerUp commit and
+     * fully participates in undo/redo. NOT idempotent: calling it twice with the
+     * same stroke appends two strokes and two history entries. The stroke shape
+     * is the caller's responsibility — v1 is full-trust and performs no sanitize.
+     */
+    commitStroke: (stroke: Stroke) => void;
+    hostCommands: HostCommandsAPI;
+    colorUtils: ColorUtilsAPI;
+    useStrokeStyle: () => StrokeStyleAPI;
+    usePopupAnchor: (options: UsePopupAnchorOptions) => UsePopupAnchorAPI;
+    calculatePopupAnchor: (options: CalculatePopupAnchorOptions) => CalculatePopupAnchorResult;
+    usePassthroughGuard: (target?: string | Ref<HTMLElement | null>) => void;
+    getSlotEntries: <T = unknown>(slotKey: string) => Readonly<Ref<readonly ContributionEntry<T>[]>>;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @openpen/module-api — public contract surface for OpenPen modules.
+ *
+ * This is the **only** import path that built-in modules and plugins
+ * are allowed to use, alongside relative imports, `node:*`, and
+ * third-party npm packages. Boundary tests in the OpenPen main repo
+ * enforce this rule on `src/core/modules/**` and on plugin code.
+ */
+export { defineModule } from './define-module';
+export { useModuleContext } from './use-module-context';
+export { isValidModuleId, MODULE_ID_RE } from './validation';
+export { resolveLabel, sanitizeIdForI18n } from './locale';
+export type { LocaleMap } from './locale';
+export { ALL_SLOTS, V1_ACTIVE_SLOTS, V1_RESERVED_SLOTS, CONTRIBUTION_KEY_TO_SLOT_ID, isKnownSlot, getSlot, } from './slots';
+export type { SlotDefinition, SlotCategory, SlotStatus } from './slots';
+export type { Point, StrokeColor, StrokeStyle, Stroke, PointerModifiers, Tool, } from './types/tool';
+export { resolveStrokeColor } from './types/tool';
+export type { ControlBarLayout, LayoutGroup, GroupInset, ControlBarContribution } from './types/control-bar-layout';
+export { ControlBarLayoutSchema, LayoutGroupSchema, GroupInsetSchema, DEFAULT_CONTROL_BAR_LAYOUT, repairLayoutL3a, repairLayoutL3b, } from './types/control-bar-layout';
+export type { NotifyPayload, NotifyHandle } from './types/notification';
+export type { OpenPenModule, ModuleSetupContext } from './types/module';
+export type { ModuleContributions, ToolContribution, ShapeContribution, StrokeStyleContribution, HistoryCommandContribution, CanvasLayerContribution, HtmlOverlayContribution, StrokeTransformerContribution, SettingsTabContribution, SettingsPanelContribution, CursorContribution, CursorSpec, SvgCursorSpec, PngCursorSpec, Hotspot, StatusContribution, ModalContribution, TrayMenuContribution, ContextMenuContribution, ThemeTokenContribution, ShortcutContribution, WindowBehaviorContribution, LocaleContribution, EventSubscriptionContribution, LifecycleContribution, StorageContribution, MainHandlerContribution, FileDropContribution, } from './types/contributions';
+export { STROKE_STYLE_CONTEXT_KEY, SNAP_EDGE_KEY, IS_VERTICAL_KEY, MODAL_MANAGER_KEY, WRAPPER_EL_KEY, ANCHOR_EL_KEY, CONTROL_BAR_ANIMATING_KEY, TOOLTIP_FLIP_DOWN_KEY, HOST_DIALOG_OPEN_COUNT_KEY, POPOVER_PLACEMENT_HINT_KEY, ACTIVE_TOOL_KEY, } from './inject-keys';
+export type { StrokeStyleContext, SnapEdge, ModalManager, PopoverPlacementHint } from './inject-keys';
+export { compileCursor, sanitizeSvgMarkup, sanitizeCursorContributions, isSafeRelativePath, pluginHostname, pluginAssetUrl, SAFE_CURSOR_KEYWORDS, } from './cursors';
+export type { CompiledCursor, CursorResolutionContext, CursorSanitizeRule, CursorSanitizeDiagnostic, CursorSanitizeOptions, CursorSanitizeResult, } from './cursors';
+export { z } from 'zod';
+export { setModuleContext, clearModuleContext } from './host/module-context-registry';