@openpen/module-api 1.1.0 → 1.2.0

package/src/host/index.ts

@@ -1,53 +0,0 @@
-/**
- * @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/passthrough.ts

@@ -1,10 +0,0 @@
-/**
- * @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

@@ -1,14 +0,0 @@
-/**
- * @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

@@ -1,9 +0,0 @@
-/**
- * @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

@@ -1,20 +0,0 @@
-/**
- * @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

@@ -1,15 +0,0 @@
-/**
- * @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

@@ -1,131 +0,0 @@
-/**
- * @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,
-  CursorSpec,
-  SvgCursorSpec,
-  PngCursorSpec,
-  Hotspot,
-  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,
-  ACTIVE_TOOL_KEY,
-} from './inject-keys'
-export type { StrokeStyleContext, SnapEdge, ModalManager, PopoverPlacementHint } from './inject-keys'
-
-// Cursor compilation + sanitisation (used by host runtime; helpers
-// re-exported so plugins can validate cursor specs in their own tests).
-export {
-  compileCursor,
-  sanitizeSvgMarkup,
-  sanitizeCursorContributions,
-  isSafeRelativePath,
-  pluginHostname,
-  pluginAssetUrl,
-  SAFE_CURSOR_KEYWORDS,
-} from './cursors'
-export type {
-  CompiledCursor,
-  CursorResolutionContext,
-  CursorSanitizeRule,
-  CursorSanitizeDiagnostic,
-  CursorSanitizeOptions,
-  CursorSanitizeResult,
-} from './cursors'
-
-// 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'

package/src/slots.ts

@@ -1,135 +0,0 @@
-/**
- * OpenPen Contribution Slot catalogue.
- *
- * Slots are the only places where modules can affect the host app.
- * Adding a slot is an architectural change — it usually requires a
- * new adapter on the OpenPen side and a minor version bump of this
- * package. Removing a slot is a breaking change.
- *
- * `status: 'v1'` slots are wired through to runtime adapters.
- * `status: 'reserved'` slots accept registrations and pass validation;
- * no runtime adapter is active yet so contributions are stored but
- * inert. Forward-compatible: modules can ship against reserved slots
- * without any plugin-side changes once an adapter lands.
- */
-
-export type SlotCategory = 'canvas' | 'ui' | 'system'
-export type SlotStatus = 'v1' | 'reserved'
-
-export interface SlotDefinition {
-  /** Dotted slot id, e.g. `'canvas.tools'`. */
-  id: string
-  /** Implementation status — see file header. */
-  status: SlotStatus
-  /** High-level grouping for documentation and UI. */
-  category: SlotCategory
-  /** One-sentence purpose, shown in `docs/reference/slots.md`. */
-  description: string
-}
-
-/**
- * v1 active slots (16). Wired through to runtime adapters.
- */
-export const V1_ACTIVE_SLOTS: readonly SlotDefinition[] = [
-  // Canvas
-  { id: 'canvas.tools', status: 'v1', category: 'canvas', description: 'Drawing tools driven by pointer events.' },
-  { id: 'canvas.shapes', status: 'v1', category: 'canvas', description: 'Shape primitives consumed by the shape tool.' },
-  { id: 'canvas.stroke.style', status: 'v1', category: 'canvas', description: 'Writers into the shared stroke style store.' },
-  { id: 'canvas.layers.background', status: 'v1', category: 'canvas', description: 'Render below strokes (grids, watermarks).' },
-  { id: 'canvas.layers.overlay', status: 'v1', category: 'canvas', description: 'Render above strokes (rulers, guides).' },
-  { id: 'canvas.html.overlay', status: 'v1', category: 'canvas', description: 'Mount HTML elements above the canvas (text, stickers).' },
-  // UI
-  { id: 'ui.control-bar', status: 'v1', category: 'ui', description: 'Control bar item slot (groups and ordering managed by layout config).' },
-  { id: 'ui.settings.tabs', status: 'v1', category: 'ui', description: 'Tabs in the settings window.' },
-  { id: 'ui.settings.panels', status: 'v1', category: 'ui', description: 'Sections inside the Features settings tab, grouped by module.' },
-  { id: 'ui.cursors', status: 'v1', category: 'ui', description: 'Drawing-mode cursor styles.' },
-  { id: 'ui.status', status: 'v1', category: 'ui', description: 'Ephemeral status badges on the control bar.' },
-  { id: 'ui.modals', status: 'v1', category: 'ui', description: 'Registered modals managed by the global modal stack.' },
-  // System
-  { id: 'system.shortcuts', status: 'v1', category: 'system', description: 'Global and drawing-mode keyboard shortcuts.' },
-  { id: 'system.locales', status: 'v1', category: 'system', description: 'i18n dictionary contributions.' },
-  { id: 'system.main.handlers', status: 'v1', category: 'system', description: 'Node-side IPC handlers for main process capabilities.' },
-  { id: 'system.events', status: 'v1', category: 'system', description: 'Subscribers and emitters on the domain event bus.' },
-  { id: 'system.lifecycle', status: 'v1', category: 'system', description: 'App lifecycle hooks (onReady / onSuspend / onQuit).' },
-] as const
-
-/**
- * v1 reserved slots. Registrations pass validation but no runtime
- * adapter is active yet.
- */
-export const V1_RESERVED_SLOTS: readonly SlotDefinition[] = [
-  { id: 'canvas.history.commands', status: 'reserved', category: 'canvas', description: 'Undo/redo history commands. Adapter not yet active; built-in command types are used internally.' },
-  { id: 'canvas.stroke.transformers', status: 'reserved', category: 'canvas', description: 'Post-process strokes after creation (smooth, simplify).' },
-  { id: 'ui.tray.menu', status: 'reserved', category: 'ui', description: 'System tray menu items. Adapter not yet active.' },
-  { id: 'ui.context.menu', status: 'reserved', category: 'ui', description: 'Right-click context menu items on canvas / control bar.' },
-  { id: 'ui.theme.tokens', status: 'reserved', category: 'ui', description: 'CSS custom property contributions (colour swatches, spacing tokens).' },
-  { id: 'system.window.behaviors', status: 'reserved', category: 'system', description: 'Window behavior customizations. Adapter not yet active.' },
-  { id: 'system.storage', status: 'reserved', category: 'system', description: 'Per-plugin isolated storage at ~/.openpen/plugins/<id>/data/. Adapter not yet active; first real consumer will drive the storage backend design.' },
-  { id: 'system.file.drop', status: 'reserved', category: 'system', description: 'Handlers for files dropped onto the canvas.' },
-] as const
-
-/**
- * All slots (active + reserved). Source of truth for validation.
- */
-export const ALL_SLOTS: readonly SlotDefinition[] = [
-  ...V1_ACTIVE_SLOTS,
-  ...V1_RESERVED_SLOTS,
-]
-
-const SLOT_BY_ID = new Map<string, SlotDefinition>(
-  ALL_SLOTS.map((s) => [s.id, s])
-)
-
-/** Returns `true` when `id` matches a slot in {@link ALL_SLOTS} (active or reserved). */
-export function isKnownSlot(id: string): boolean {
-  return SLOT_BY_ID.has(id)
-}
-
-/**
- * Returns the {@link SlotDefinition} for a known slot id, or `undefined` if
- * the id is not registered in {@link ALL_SLOTS}.
- */
-export function getSlot(id: string): SlotDefinition | undefined {
-  return SLOT_BY_ID.get(id)
-}
-
-/**
- * Mapping from `contributes` field name (camelCase) to slot id (dotted).
- *
- * Modules express contributions via the ergonomic camelCase keys on
- * `contributes` (e.g. `historyCommands`); the validator maps them
- * back to slot ids (`canvas.history.commands`) before checking against
- * `ALL_SLOTS`.
- *
- * Adding a new field here is part of adding a new slot.
- */
-export const CONTRIBUTION_KEY_TO_SLOT_ID: Record<string, string> = {
-  // Canvas
-  tools: 'canvas.tools',
-  shapes: 'canvas.shapes',
-  strokeStyle: 'canvas.stroke.style',
-  historyCommands: 'canvas.history.commands',
-  backgroundLayers: 'canvas.layers.background',
-  overlayLayers: 'canvas.layers.overlay',
-  htmlOverlays: 'canvas.html.overlay',
-  strokeTransformers: 'canvas.stroke.transformers',
-  // UI
-  controlBar: 'ui.control-bar',
-  settingsTabs: 'ui.settings.tabs',
-  settingsPanels: 'ui.settings.panels',
-  cursors: 'ui.cursors',
-  status: 'ui.status',
-  modals: 'ui.modals',
-  trayMenu: 'ui.tray.menu',
-  contextMenu: 'ui.context.menu',
-  themeTokens: 'ui.theme.tokens',
-  // System
-  shortcuts: 'system.shortcuts',
-  windowBehaviors: 'system.window.behaviors',
-  locales: 'system.locales',
-  events: 'system.events',
-  lifecycle: 'system.lifecycle',
-  storage: 'system.storage',
-  mainHandlers: 'system.main.handlers',
-  fileDrop: 'system.file.drop',
-}