@openpen/module-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 navishachiku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @openpen/module-api
+
+The public contract surface for **OpenPen modules** — both first-party (`src/core/modules/*`) and third-party plugins (`~/.openpen/plugins/*`).
+
+This is the **only** import path that built-in modules and plugins are allowed to use (apart from relative imports, `node:*`, and third-party npm packages). The boundary is enforced by `tests/unit/boundaries/*` in the OpenPen main repo.
+
+## Install
+
+```bash
+npm install @openpen/module-api zod
+```
+
+> **Import `z` from `@openpen/module-api`, not from `'zod'` directly.**
+> The build externalises `'zod'` — a direct `import { z } from 'zod'` in a
+> plugin file will fail at build time with an unresolved-import error. Use
+> `import { z } from '@openpen/module-api'` everywhere in your plugin.
+
+## Quick start
+
+```typescript
+import { defineModule, z } from '@openpen/module-api'
+
+export default defineModule({
+  id: 'my-module',
+  name: { en: 'My Module', 'zh-TW': '我的模組' },
+  settingsSchema: z.object({
+    enabled: z.boolean().default(true),
+  }),
+  contributes: {
+    tools: [
+      {
+        id: 'my-tool',
+        // ...
+      },
+    ],
+  },
+})
+```
+
+### `setup(ctx)` — Module initialisation
+
+`defineModule` supports an optional `setup(ctx: ModuleSetupContext)` hook, called once when the module loads. `ctx` provides:
+
+| Method | Description |
+|--------|-------------|
+| `ctx.getSettings<T>()` | Read this module's parsed settings (requires `settingsSchema` to be declared) |
+| `ctx.callMain(action, payload?)` | Call this module's main-side handler |
+| `ctx.onDispose(fn)` | Register a cleanup callback (called in reverse order when the module is unloaded) |
+| `ctx.notify(payload)` | Show a short-lived toast in the overlay window; returns `NotifyHandle` for early `dismiss()` |
+
+```typescript
+import { defineModule } from '@openpen/module-api'
+import type { NotifyPayload } from '@openpen/module-api'
+
+export default defineModule({
+  id: 'my-module',
+  name: { en: 'My Module' },
+  contributes: { /* ... */ },
+
+  setup(ctx) {
+    // Show a toast when the module finishes loading.
+    ctx.notify({
+      message: { en: 'My Module ready' },
+      variant: 'success',
+      duration: 1500,
+    })
+
+    // Release resources (timers, listeners, etc.) on unload.
+    const timer = setInterval(() => { /* ... */ }, 5000)
+    ctx.onDispose(() => clearInterval(timer))
+  },
+})
+```
+
+See [docs/reference/notify-api.md](../../docs/reference/notify-api.md).
+
+See the OpenPen [docs](https://github.com/openpen/openpen/blob/main/docs/README.md) for guides, slot catalogue, and UIKit reference.
+
+## Long-term stability of the UIKit
+
+The UIKit (`@openpen/module-api/uikit`) wraps a headless behaviour library
+internally. That library is an implementation detail — it is not part of the
+public API surface.
+
+If the underlying library is ever replaced, the host will follow a documented
+fallback order: Headless UI Vue → Ark UI → self-written primitives. The wrapper
+props, events, and slots documented here will remain stable across any such
+swap. Plugin authors who import only from `@openpen/module-api/uikit` will be
+unaffected. Authors who drop to the primitive layer (named primitive exports)
+will see a major-version bump and a small targeted port. Authors who bypass the
+UIKit entirely and import a headless library directly in their plugin's
+`package.json` are responsible for porting that surface themselves.
+
+This guarantee is why the wrapper layer is the recommended starting point for
+all plugin UI.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@openpen/module-api",
+  "version": "1.0.0",
+  "description": "OpenPen Module API — public contract for built-in modules and third-party plugins",
+  "author": "navishachiku <navishachiku@gmail.com>",
+  "homepage": "https://github.com/openpen-platform/openpen#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openpen-platform/openpen.git",
+    "directory": "packages/module-api"
+  },
+  "bugs": {
+    "url": "https://github.com/openpen-platform/openpen/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./uikit": {
+      "types": "./src/uikit/index.ts",
+      "import": "./src/uikit/index.ts"
+    },
+    "./uikit/tokens.css": "./src/uikit/tokens.css",
+    "./uikit/internal": {
+      "types": "./src/uikit/internal.ts",
+      "import": "./src/uikit/internal.ts"
+    },
+    "./host": {
+      "types": "./src/host/index.ts",
+      "import": "./src/host/index.ts"
+    }
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=9"
+  },
+  "keywords": ["openpen", "plugin", "module", "sdk"],
+  "dependencies": {
+    "reka-ui": "~2.9.6"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "zod": "^3.23.0"
+  }
+}

package/src/define-module.ts

@@ -0,0 +1,55 @@
+import { isValidModuleId } from './validation'
+import { CONTRIBUTION_KEY_TO_SLOT_ID } from './slots'
+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 function defineModule<TModule extends OpenPenModule>(
+  spec: TModule
+): TModule {
+  if (!isValidModuleId(spec.id)) {
+    throw new Error(
+      `[@openpen/module-api] Invalid module id: ${JSON.stringify(spec.id)}. ` +
+        `Module ids must use \`@scope/name\` format with lowercase ASCII alphanumeric + hyphen, ` +
+        `max 39 chars per segment (e.g. \`@alice/my-plugin\`).`
+    )
+  }
+
+  if (!spec.contributes || typeof spec.contributes !== 'object') {
+    throw new Error(
+      `[@openpen/module-api] Module "${spec.id}" must declare a non-empty 'contributes' object.`
+    )
+  }
+
+  const keys = Object.keys(spec.contributes)
+  if (keys.length === 0) {
+    throw new Error(
+      `[@openpen/module-api] Module "${spec.id}" must contribute to at least one slot. ` +
+        `Add at least one field to 'contributes' (e.g. 'tools', 'settingsTabs', 'shortcuts').`
+    )
+  }
+
+  for (const key of keys) {
+    if (!(key in CONTRIBUTION_KEY_TO_SLOT_ID)) {
+      throw new Error(
+        `[@openpen/module-api] Module "${spec.id}" contributes to unknown slot key '${key}'. ` +
+          `Known keys: ${Object.keys(CONTRIBUTION_KEY_TO_SLOT_ID).sort().join(', ')}.`
+      )
+    }
+  }
+
+  return spec
+}

package/src/host/color-utils.ts

@@ -0,0 +1,18 @@
+/**
+ * @openpen/module-api/host — Color Utilities
+ *
+ * Re-exports color helpers that module components need for rendering.
+ * The canvas-rendering helper resolveColorStyle and the color manipulation
+ * utilities are exposed here so modules don't need cross-layer imports.
+ */
+
+export {
+  resolveColorStyle,
+  hexToRgb,
+  rgbToHex,
+  hsvToRgb,
+  rgbToHsv,
+  hexToHsv,
+  hsvToHex,
+  isValidHex,
+} from '../../../../src/services/color-utils'

package/src/host/event-bus.ts

@@ -0,0 +1,37 @@
+/**
+ * @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.
+ *
+ * **Host-emitted events (consume via `on(name, cb)`):**
+ *
+ * | Event name                | Payload shape                                   | Fires when                                                           |
+ * |---------------------------|-------------------------------------------------|----------------------------------------------------------------------|
+ * | `'tool-changed'`          | `{ tool: string } & Partial<ToolConfig>`        | The active drawing tool changes (user click, IPC, or shortcut)       |
+ * | `'stroke-style-changed'`  | `{ color?: StrokeColor; lineWidth?: number }`   | Color or stroke width changes                                        |
+ * | `'canvas-redraw-requested'` | (no payload)                                  | A module wants the canvas to repaint (eraser, transformer, etc.)     |
+ *
+ * **Module-emitted events:** modules MAY emit any event name they
+ * choose; the bus is namespace-free. Use a prefix (e.g. `'my-plugin:'`)
+ * to avoid colliding with another module's events.
+ *
+ * `on(name, cb)` returns an unsubscribe function — register it via
+ * `ctx.onDispose(unsubscribe)` so the listener is cleaned up when the
+ * module unloads.
+ *
+ * @example
+ * ```ts
+ * import { on } from '@openpen/module-api/host'
+ *
+ * setup(ctx) {
+ *   const off = on('tool-changed', (payload) => {
+ *     console.log('tool now', payload.tool)
+ *   })
+ *   ctx.onDispose(off)
+ * }
+ * ```
+ */
+
+export { emit, on } from '../../../../src/core/runtime/event-bus'

package/src/host/host-commands.ts

@@ -0,0 +1,9 @@
+/**
+ * @openpen/module-api/host — Host Commands
+ *
+ * Re-exports hostCommands for module components that need to trigger
+ * host infrastructure actions (pin toggle, canvas clear, undo/redo,
+ * drawing mode toggle).
+ */
+
+export { hostCommands } from '../../../../src/services/host-commands'

package/src/host/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @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/).
+ */
+
+// ── Stroke Style ──────────────────────────────────────────────────────────────
+export { useStrokeStyle } from './stroke-style'
+export type { StrokeColor } from './stroke-style'
+
+// ── Color Utilities ───────────────────────────────────────────────────────────
+export {
+  resolveColorStyle,
+  hexToRgb,
+  rgbToHex,
+  hsvToRgb,
+  rgbToHsv,
+  hexToHsv,
+  hsvToHex,
+  isValidHex,
+} from './color-utils'
+
+// ── Stroke Store ──────────────────────────────────────────────────────────────
+export { getAllStrokes, removeStrokeById, pushCommand } from './stroke-store'
+export type { Stroke } from './stroke-store'
+
+// ── Popup Anchor ──────────────────────────────────────────────────────────────
+export { usePopupAnchor, calculatePopupAnchor } from './popup-anchor'
+
+// ── Passthrough Guard ─────────────────────────────────────────────────────────
+export { usePassthroughGuard } from './passthrough'
+
+// ── Host Commands ─────────────────────────────────────────────────────────────
+export { hostCommands } from './host-commands'
+
+// ── Event Bus ─────────────────────────────────────────────────────────────────
+export { emit, on } from './event-bus'
+
+// ── Slot Entries ──────────────────────────────────────────────────────────────
+export { getSlotEntries } from './slot-entries'
+
+// ── Module Context Registry ───────────────────────────────────────────────────
+// Used by the renderer host (module-loader.ts) to populate/clear the registry
+// that backs `useModuleContext`. Plugin code MUST NOT import these directly.
+export { setModuleContext, clearModuleContext } from './module-context-registry'

package/src/host/module-context-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Host-side registry that backs `useModuleContext`.
+ *
+ * The renderer host (module-loader.ts) writes to this registry via
+ * `setModuleContext` / `clearModuleContext` immediately around each
+ * module's `setup()` call. Plugin-authored Vue components then read
+ * from it via the public `useModuleContext` composable.
+ *
+ * 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>()
+
+/** 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)
+}
+
+/** Remove the context for a module. Called by module-loader in rollbackModule(). */
+export function clearModuleContext(moduleId: string): void {
+  registry.delete(moduleId)
+}
+
+/** Look up the context for a module. Returns undefined if not registered. */
+export function getModuleContext(moduleId: string): ModuleSetupContext | undefined {
+  return registry.get(moduleId)
+}
+
+/** Resets the entire registry. Test-only — do not call in production code. */
+export function resetModuleContextRegistryForTest(): void {
+  registry.clear()
+}

package/src/host/passthrough.ts

@@ -0,0 +1,10 @@
+/**
+ * @openpen/module-api/host — Passthrough Guard
+ *
+ * Re-exports usePassthroughGuard so module components (and UIKit wrappers)
+ * can import from @openpen/module-api/host without cross-layer imports.
+ *
+ * Exposed here so module code can import without cross-layer relative paths.
+ */
+
+export { usePassthroughGuard } from '../../../../src/composables/usePassthroughGuard'

package/src/host/popup-anchor.ts

@@ -0,0 +1,14 @@
+/**
+ * @openpen/module-api/host — Popup Anchor
+ *
+ * Re-exports the usePopupAnchor composable and its pure helper
+ * calculatePopupAnchor for module components that need anchor-relative
+ * popup positioning.
+ *
+ * Exposed here so module code can import without cross-layer relative paths.
+ */
+
+export {
+  usePopupAnchor,
+  calculatePopupAnchor,
+} from '../../../../src/composables/usePopupAnchor'

package/src/host/slot-entries.ts

@@ -0,0 +1,9 @@
+/**
+ * @openpen/module-api/host — Slot Entries Reader
+ *
+ * Re-exports getSlotEntries so module components can render UI driven
+ * by other modules' contributions to the same slot (for example,
+ * the shape-picker rendering all canvas.shapes contributions).
+ */
+
+export { getSlotEntries } from '../../../../src/core/runtime/contribution-store'

package/src/host/stroke-store.ts

@@ -0,0 +1,20 @@
+/**
+ * @openpen/module-api/host — Stroke Store
+ *
+ * Re-exports the stroke store APIs that module tools need.
+ * Only the minimum surface required by stroke-eraser (and similar tools)
+ * is exposed: getAllStrokes, removeStrokeById, pushCommand.
+ *
+ * Host-internal state mutation helpers (clearAll, addStroke, undo, redo)
+ * are intentionally NOT exported — modules must use hostCommands for
+ * undo/redo and canvas clear.
+ */
+
+export {
+  getAllStrokes,
+  removeStrokeById,
+  pushCommand,
+} from '../../../../src/services/stroke-store'
+
+// Re-export Stroke type via the public SDK types, not host internals.
+export type { Stroke } from '../types/tool'

package/src/host/stroke-style.ts

@@ -0,0 +1,15 @@
+/**
+ * @openpen/module-api/host — Stroke Style
+ *
+ * Re-exports the public API of the host useStrokeStyle composable.
+ * Module components MUST import from here, not from src/composables directly.
+ *
+ * Exposed here so module components can access it without cross-layer imports.
+ */
+
+// Re-export the public API functions that modules need.
+// initStrokeStyleFromSettings is host-boot-only and intentionally NOT exported here.
+export { useStrokeStyle } from '../../../../src/composables/useStrokeStyle'
+
+// Re-export the StrokeColor type via the public SDK types (not host internals).
+export type { StrokeColor } from '../types/tool'

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * @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.
+ */
+
+// Core helpers
+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'
+
+// Slot catalogue
+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'
+
+// Tool primitives (Point, Stroke, StrokeStyle, Tool, …)
+export type {
+  Point,
+  StrokeColor,
+  StrokeStyle,
+  Stroke,
+  PointerModifiers,
+  Tool,
+} from './types/tool'
+
+// Control bar layout types + helpers
+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'
+
+// Notification types
+export type { NotifyPayload, NotifyHandle } from './types/notification'
+
+// Module + Contribution types
+export type { OpenPenModule, ModuleSetupContext } from './types/module'
+export type {
+  ModuleContributions,
+  ToolContribution,
+  ShapeContribution,
+  StrokeStyleContribution,
+  HistoryCommandContribution,
+  CanvasLayerContribution,
+  HtmlOverlayContribution,
+  StrokeTransformerContribution,
+  SettingsTabContribution,
+  SettingsPanelContribution,
+  CursorContribution,
+  StatusContribution,
+  ModalContribution,
+  TrayMenuContribution,
+  ContextMenuContribution,
+  ThemeTokenContribution,
+  ShortcutContribution,
+  WindowBehaviorContribution,
+  LocaleContribution,
+  EventSubscriptionContribution,
+  LifecycleContribution,
+  StorageContribution,
+  MainHandlerContribution,
+  FileDropContribution,
+} from './types/contributions'
+
+// Host ↔ module inject keys (Vue provide/inject bridge)
+export {
+  STROKE_STYLE_CONTEXT_KEY,
+  SNAP_EDGE_KEY,
+  IS_VERTICAL_KEY,
+  MODAL_MANAGER_KEY,
+  WRAPPER_EL_KEY,
+  ANCHOR_EL_KEY,
+  CONTROL_BAR_ANIMATING_KEY,
+  HOST_DIALOG_OPEN_COUNT_KEY,
+  POPOVER_PLACEMENT_HINT_KEY,
+} from './inject-keys'
+export type { StrokeStyleContext, SnapEdge, ModalManager, PopoverPlacementHint } from './inject-keys'
+
+// Re-export zod so modules don't need a separate import path.
+export { z } from 'zod'
+
+// Host-internal registry writers — re-exported here so the host's module
+// loader pulls them through the SAME externalised entry point
+// (`@openpen/module-api`, runtime bundle: openpen-runtime/module-api.js)
+// that `useModuleContext` reads from. Importing them via
+// `@openpen/module-api/host` instead would inline a duplicate
+// module-context-registry into the host bundle, breaking state-sharing
+// between writers and readers in production builds (see
+// project_dev_prod_parity.md). Plugin authors MUST NOT use these.
+export { setModuleContext, clearModuleContext } from './host/module-context-registry'