@openpen/module-api 1.0.0

package/src/inject-keys.ts

@@ -0,0 +1,143 @@
+/**
+ * Vue InjectionKey symbols that host code provides and module components inject.
+ *
+ * Module components MUST NOT import host composables directly (boundary rule).
+ * Instead, the host provides these contexts via Vue's provide/inject, and
+ * modules reference the keys via this file (part of the public SDK surface).
+ */
+import type { InjectionKey, Ref } from 'vue'
+import type { StrokeColor } from './types/tool'
+
+// ── Stroke Style ─────────────────────────────────────────────────────────────
+
+/**
+ * Provides read + write access to the global stroke style state.
+ * Provided by App.vue (root); available in all renderer windows.
+ *
+ * Module components: inject via `inject(STROKE_STYLE_CONTEXT_KEY)`.
+ */
+export interface StrokeStyleContext {
+  lineWidth: Readonly<Ref<number>>
+  color: Readonly<Ref<StrokeColor>>
+  setLineWidth: (w: number) => void
+  setColor: (c: StrokeColor) => void
+}
+
+export const STROKE_STYLE_CONTEXT_KEY: InjectionKey<StrokeStyleContext> =
+  Symbol('openpen.strokeStyleContext')
+
+// ── Snap Edge ────────────────────────────────────────────────────────────────
+
+/**
+ * Which side of the screen workArea the floating ball is anchored to.
+ *
+ * - 'left'   → ball anchored on the left edge  (vbar-left layout)
+ * - 'right'  → ball anchored on the right edge (vbar-right layout)
+ * - 'top'    → ball anchored on the top edge   (horizontal bar, top)
+ * - 'bottom' → ball anchored on the bottom edge (horizontal bar, bottom)
+ * - null     → not snapped (free-floating or horizontal default)
+ *
+ * Consumers that need a ready-to-use popup direction (the opposite of the
+ * snap edge) should inject POPOVER_PLACEMENT_HINT_KEY instead — it encodes
+ * the two-tier UX rule (snap edge → midline fallback) so individual components
+ * do not have to replicate the logic.
+ *
+ * Use IS_VERTICAL_KEY for orientation checks (vbar vs horizontal); this key
+ * is null in vbar-free mode where no edge is snapped.
+ */
+export type SnapEdge = 'left' | 'right' | 'top' | 'bottom' | null
+
+export const SNAP_EDGE_KEY: InjectionKey<Readonly<Ref<SnapEdge>>> =
+  Symbol('openpen.snapEdge')
+
+// ── Vertical Layout ──────────────────────────────────────────────────────────
+
+/**
+ * True for any vertical layout (vbar-left / vbar-right / vbar-free). Use
+ * this for orientation; SNAP_EDGE_KEY is edge-specific and null in vbar-free.
+ */
+export const IS_VERTICAL_KEY: InjectionKey<Readonly<Ref<boolean>>> =
+  Symbol('openpen.isVertical')
+
+// ── Modal Manager ─────────────────────────────────────────────────────────────
+
+/**
+ * Programmatic open / close for modals registered via `ui.modals` slot.
+ * Provided by ModalStack.vue.
+ *
+ * Module control-bar buttons call `open(id)` to show their modal.
+ * Modal components call `isOpen(id)` to control their own visibility.
+ */
+export interface ModalManager {
+  /** Open the modal with the given id. Closes any currently-open modal first. */
+  open: (id: string) => void
+  /** Close the modal with the given id. No-op if it is not open. */
+  close: (id: string) => void
+  /** Returns true if the modal with the given id is currently open. */
+  isOpen: (id: string) => boolean
+}
+
+export const MODAL_MANAGER_KEY: InjectionKey<ModalManager> =
+  Symbol('openpen.modalManager')
+
+// ── Control Bar Layout Context ───────────────────────────────────────────────
+
+/**
+ * Reference to the `.control-bar-wrapper` element. Provided by ControlBar.vue.
+ * Module components that open anchor-relative popups teleport into this element.
+ */
+export const WRAPPER_EL_KEY: InjectionKey<Readonly<Ref<HTMLElement | null>>> =
+  Symbol('openpen.wrapperEl')
+
+/**
+ * Reference to the `.control-bar` element. Provided by ControlBar.vue.
+ * Module components use this as the anchor for popup positioning.
+ */
+export const ANCHOR_EL_KEY: InjectionKey<Readonly<Ref<HTMLElement | null>>> =
+  Symbol('openpen.anchorEl')
+
+// ── Control Bar Animating ──────────────────────────────────────────────────────
+
+/**
+ * Reactive flag that is `true` while the ControlBar is running a scaleY
+ * animation (expand 350ms / collapse 250ms / snap 250ms).
+ *
+ * Provided by ControlBar.vue as `readonly(animating)`.
+ * AppPopover (and any other UIKit wrapper) watches this and auto-closes
+ * when it becomes true, avoiding floating-ui position drift during animation.
+ */
+export const CONTROL_BAR_ANIMATING_KEY: InjectionKey<Readonly<Ref<boolean>>> =
+  Symbol('openpen:control-bar-animating')
+
+// ── Host Dialog Presence ─────────────────────────────────────────────────────
+
+/**
+ * Reference-counted open-dialog count. Hosts inject this to render their
+ * own "locked" state when > 0 — a transparent overlay window can't use a
+ * dim/blur dialog backdrop without rendering as an isolated dark patch.
+ */
+export const HOST_DIALOG_OPEN_COUNT_KEY: InjectionKey<Ref<number>> =
+  Symbol('openpen:hostDialogOpenCount')
+
+// ── Popover Placement Hint ────────────────────────────────────────────────────
+
+/**
+ * Deliberate UX rule for initial popover placement direction.
+ *
+ * Encodes which side of the trigger the popover should prefer to open on,
+ * based on two rules applied in priority order:
+ *   1. Snap edge: opening away from the snapped edge (e.g. snap-left → 'right').
+ *   2. Screen midline (when no snap edge): opening toward the side with more space
+ *      on the relevant axis (horizontal bar → top/bottom; vertical bar → left/right).
+ *
+ * The floating-ui flip middleware handles secondary overflow; this hint is the
+ * proactive first choice so the popover starts on the correct side without
+ * requiring a layout-measurement round-trip.
+ *
+ * Provided by ControlBar.vue; injected by AppPopover.vue.
+ * Plugin authors do not need to consume this key directly.
+ */
+export type PopoverPlacementHint = 'top' | 'bottom' | 'left' | 'right'
+
+export const POPOVER_PLACEMENT_HINT_KEY: InjectionKey<Readonly<Ref<PopoverPlacementHint>>> =
+  Symbol('openpen:popoverPlacementHint')

package/src/locale.ts

@@ -0,0 +1,52 @@
+/**
+ * Convert a scoped module id to a vue-i18n-safe namespace key.
+ *
+ * vue-i18n uses `.` as path separator, so a raw id like `@openpen/freehand`
+ * would be misinterpreted as a three-level path `['@openpen', 'freehand']`.
+ * Stripping `@` and replacing `/` with `.` produces `openpen.freehand`,
+ * which resolves correctly as a two-level namespace.
+ *
+ * @example
+ * sanitizeIdForI18n('@openpen/freehand') // 'openpen.freehand'
+ * sanitizeIdForI18n('@alice/todo')       // 'alice.todo'
+ */
+export function sanitizeIdForI18n(moduleId: string): string {
+  return moduleId.replace(/^@/, '').replace(/\//g, '.')
+}
+
+/**
+ * Maps a BCP-47 locale tag (e.g. `'en'`, `'zh-TW'`) to a localised string.
+ *
+ * Modules use this to declare i18n display names without coupling
+ * themselves to the host app's i18n framework. The OpenPen registry
+ * resolves the value at render time based on the active locale.
+ */
+export type LocaleMap = Record<string, string>
+
+/**
+ * Resolve a `string | LocaleMap` to a single string for a given locale.
+ *
+ * Resolution order (first match wins):
+ *   1. Plain string → returned as-is
+ *   2. Exact tag match (e.g. `'zh-TW'`)
+ *   3. Language prefix match (e.g. `'zh'` for `'zh-Hans-CN'`)
+ *   4. English fallback (`'en'`)
+ *   5. First declared value in the map
+ *   6. Empty string (only when the map is `{}`)
+ */
+export function resolveLabel(
+  input: string | LocaleMap,
+  locale: string
+): string {
+  if (typeof input === 'string') return input
+
+  if (input[locale] !== undefined) return input[locale]
+
+  const lang = locale.split('-')[0]
+  if (lang !== locale && input[lang] !== undefined) return input[lang]
+
+  if (input.en !== undefined) return input.en
+
+  const first = Object.values(input)[0]
+  return first ?? ''
+}

package/src/slots.ts

@@ -0,0 +1,135 @@
+/**
+ * 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',
+}

package/src/types/contributions.ts

@@ -0,0 +1,298 @@
+import type { Component } from 'vue'
+import type { LocaleMap } from '../locale'
+import type { Stroke, Tool } from './tool'
+import type { ControlBarContribution } from './control-bar-layout'
+
+export type { ControlBarContribution }
+
+/**
+ * The shape of `OpenPenModule.contributes`. Every field is optional;
+ * `defineModule` requires at least one field to be present and rejects
+ * any unknown field at module-author boundary time.
+ *
+ * Each field corresponds to a slot in {@link import('../slots').ALL_SLOTS}.
+ * The mapping from camelCase field name to dotted slot id lives in
+ * `CONTRIBUTION_KEY_TO_SLOT_ID`.
+ */
+export interface ModuleContributions {
+  // ── Canvas ──────────────────────────────────────────────────────────────
+  tools?: ToolContribution[]
+  shapes?: ShapeContribution[]
+  strokeStyle?: StrokeStyleContribution
+  historyCommands?: HistoryCommandContribution[]
+  backgroundLayers?: CanvasLayerContribution[]
+  overlayLayers?: CanvasLayerContribution[]
+  htmlOverlays?: HtmlOverlayContribution[]
+  /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+  strokeTransformers?: StrokeTransformerContribution[]
+
+  // ── UI ──────────────────────────────────────────────────────────────────
+  controlBar?: ControlBarContribution[]
+  settingsTabs?: SettingsTabContribution[]
+  settingsPanels?: SettingsPanelContribution[]
+  cursors?: CursorContribution[]
+  status?: StatusContribution[]
+  modals?: ModalContribution[]
+  trayMenu?: TrayMenuContribution[]
+  /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+  contextMenu?: ContextMenuContribution[]
+  /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+  themeTokens?: ThemeTokenContribution
+
+  // ── System ──────────────────────────────────────────────────────────────
+  shortcuts?: ShortcutContribution[]
+  windowBehaviors?: WindowBehaviorContribution[]
+  locales?: LocaleContribution
+  events?: EventSubscriptionContribution[]
+  lifecycle?: LifecycleContribution
+  storage?: StorageContribution
+  mainHandlers?: MainHandlerContribution
+  /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+  fileDrop?: FileDropContribution[]
+}
+
+// ════════════════════════════════════════════════════════════════════════
+// Below: per-slot contribution shapes. These are the locked public-facing
+// names referenced by docs and the validator; their internals can extend
+// without breaking modules.
+// ════════════════════════════════════════════════════════════════════════
+
+/**
+ * Drawing tool driven by pointer events. Implements the full `Tool`
+ * interface (onPointerDown / Move / Up) plus optional metadata for
+ * the toolbar UI and an optional `renderStroke` for tools whose
+ * strokes need custom redraw semantics (shapes, erasers, anything
+ * beyond a simple polyline).
+ */
+export interface ToolContribution extends Tool {
+  id: string
+  label?: string | LocaleMap
+  /**
+   * SVG markup string for this tool's icon in the control-bar button.
+   *
+   * The host renders tool icons via `v-html`, so only raw SVG strings are
+   * accepted (not Vue components or CSS class names). Recommended size is
+   * `width="16" height="16"` with `stroke="currentColor"` so the icon
+   * inherits the button's colour automatically.
+   *
+   * @example
+   * icon: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 17c3-3 6-6 9-3s6 0 9-3"/></svg>'
+   *
+   * Note: built-in tools (freehand, line, eraser) use their own Vue button
+   * components rather than this field — `icon` is the lightweight path for
+   * plugin-contributed tools that do not need a custom button component.
+   */
+  icon?: string
+  /**
+   * Custom redraw renderer. When omitted, canvas-engine falls back
+   * to a polyline render through `stroke.points` — sufficient for
+   * freehand- and line-style tools.
+   */
+  renderStroke?: (canvasCtx: CanvasRenderingContext2D, stroke: Stroke) => void
+}
+
+/** Shape primitive used by the shape tool. */
+export interface ShapeContribution {
+  id: string
+  label?: string | LocaleMap
+  /**
+   * Vue component or SVG string for the shape icon in control-bar / sub-panel.
+   * Host renders via `<component :is="icon">`.
+   * Component icons MAY accept an optional `filled?: boolean` prop —
+   * the host passes the current fill-toggle state so icons can mirror it
+   * (e.g. solid vs outline rendering). Plugin icons that ignore the prop
+   * still work; they just won't reflect fill state visually.
+   */
+  icon?: Component | string
+  draw: (...args: unknown[]) => void
+}
+
+/**
+ * Stroke style writer. Modules declare which keys of the shared
+ * stroke style store they write to; collision detection happens at
+ * module-validator time.
+ */
+export interface StrokeStyleContribution {
+  /** Keys this module writes (e.g. `['lineWidth']`, `['color']`). */
+  provides: string[]
+}
+
+/**
+ * Undo/redo command handler for the `canvas.history.commands` slot.
+ *
+ * The host calls `undo` / `redo` with whatever `payload` was stored when the
+ * command was pushed onto the history stack. The contributing module decides
+ * the payload shape — the host treats it as `unknown` and passes it through
+ * without inspection.
+ */
+export interface HistoryCommandContribution {
+  type: string
+  undo: (payload: unknown) => void
+  redo: (payload: unknown) => void
+}
+
+export interface CanvasLayerContribution {
+  id: string
+  /** Render priority within the layer; higher = drawn later (on top). */
+  order?: number
+  render: (ctx: CanvasRenderingContext2D) => void
+}
+
+export interface HtmlOverlayContribution {
+  id: string
+  component: Component
+}
+
+export interface StrokeTransformerContribution {
+  id: string
+  /** Receives a stroke, returns a transformed stroke. Slot ⏳ reserved. */
+  transform: (stroke: unknown) => unknown
+}
+
+export interface SettingsTabContribution {
+  id: string
+  label: string | LocaleMap
+  component: Component
+}
+
+export interface SettingsPanelContribution {
+  id: string
+  label: string | LocaleMap
+  component: Component
+}
+
+export interface CursorContribution {
+  id: string
+  /** CSS cursor value or a data URL. */
+  cursor: string
+}
+
+export interface StatusContribution {
+  id: string
+  component: Component
+}
+
+export interface ModalContribution {
+  id: string
+  component: Component
+}
+
+export interface TrayMenuContribution {
+  id: string
+  label: string | LocaleMap
+  click: () => void
+}
+
+export interface ContextMenuContribution {
+  id: string
+  label: string | LocaleMap
+  /** Where the menu may appear; runtime filters by context at open time. */
+  context: 'canvas' | 'toolbar' | 'tray'
+  click: () => void
+}
+
+/**
+ * CSS custom property contributions for the `ui.theme.tokens` slot.
+ *
+ * Keys are CSS custom property names (e.g. `'--my-plugin-accent'`).
+ * Values are CSS color or length values (e.g. `'#ff6600'`, `'4px'`).
+ * The host merges all contributions into `:root` at startup.
+ */
+export type ThemeTokenContribution = Record<string, string>
+
+export interface ShortcutContribution {
+  id: string
+  /** Accelerator string; tinykeys-style or Electron globalShortcut format. */
+  keys: string
+  /** `'global'` registers OS-wide; `'drawing'` only when overlay is active. */
+  scope: 'global' | 'drawing'
+  handler: () => void
+  /** Human-readable name. Omit to hide this shortcut from the user-visible shortcuts list. */
+  label?: string | LocaleMap
+  /** Optional secondary description shown below the label in the shortcuts settings panel. */
+  sublabel?: string | LocaleMap
+  /** When true, the user can rebind this key. The chosen key is persisted under `config.json → customShortcuts`. */
+  userCustomizable?: boolean
+}
+
+export interface WindowBehaviorContribution {
+  id: string
+  /** Reserved — concrete behaviour API not yet defined. */
+  [key: string]: unknown
+}
+
+/** Leaf or branch in a locale dictionary. Leaves must be strings. */
+type LocaleDictValue = string | LocaleDict
+
+/**
+ * Recursive locale dictionary.
+ * Leaves are translated strings; branches are nested sub-dictionaries.
+ * Use the `interface` form (not `type`) to allow self-reference without
+ * triggering TypeScript's circular-type restrictions.
+ */
+interface LocaleDict {
+  [key: string]: LocaleDictValue
+}
+
+/**
+ * A locale dictionary keyed by BCP-47 tag (e.g. `'en'`, `'zh-Hant'`).
+ *
+ * Values are per-locale message dictionaries. Supports both flat and nested
+ * layouts — vue-i18n treats `.` in ctx.t(key) as a nested path separator,
+ * so keys like `'notif.ready'` must use a nested object dict
+ * `{ notif: { ready: '...' } }`, not a flat key `{ 'notif.ready': '...' }`.
+ *
+ * Non-string leaves are rejected at compile time; use ctx.t() to resolve
+ * keys to strings before passing them to runtime APIs.
+ */
+export type LocaleContribution = Record<string, LocaleDict>
+
+/**
+ * Subscription to a named domain event on the `system.events` slot.
+ *
+ * `event` must match the event name emitted by another module (or the host)
+ * via `system.events`. The host routes each emitted event to all registered
+ * handlers whose `event` string matches.
+ */
+export interface EventSubscriptionContribution {
+  event: string
+  handler: (payload: unknown) => void
+}
+
+/**
+ * App lifecycle hooks for the `system.lifecycle` slot.
+ *
+ * Call order: `setup` (from `OpenPenModule.setup`) → `onReady` (host fully
+ * booted) → `onSuspend` (overlay hidden) → `onQuit` (app shutting down).
+ * All hooks may return a Promise; the host awaits each before advancing.
+ */
+export interface LifecycleContribution {
+  onReady?: () => void | Promise<void>
+  onSuspend?: () => void | Promise<void>
+  onQuit?: () => void | Promise<void>
+}
+
+/**
+ * Marker that this module wants an isolated storage area at
+ * `~/.openpen/plugins/<id>/data/`. Capacity / quota policy is defined
+ * by the host runtime.
+ */
+export interface StorageContribution {
+  /** If true, the host pre-creates the data directory at module load. */
+  preCreate?: boolean
+}
+
+/**
+ * Map of action name to async handler. Routed from the renderer via
+ * `window.openPenApi.moduleCall(moduleId, action, payload)`.
+ */
+export type MainHandlerContribution = Record<
+  string,
+  (payload: unknown) => unknown | Promise<unknown>
+>
+
+export interface FileDropContribution {
+  /** MIME types this handler accepts (e.g. `['image/png']`). */
+  accept: string[]
+  handle: (files: File[]) => void | Promise<void>
+}