@openpen/module-api 1.0.0

package/src/types/control-bar-layout.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod'
+import type { Component } from 'vue'
+import type { LocaleMap } from '../locale'
+
+// ── Schema ────────────────────────────────────────────────────────────────
+
+export const GroupInsetSchema = z.object({
+  enabled: z.boolean(),
+  /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
+  color: z.string().optional(),
+})
+
+export const LayoutGroupSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/, 'Group id must be kebab-case'),
+  items: z.array(z.string()),
+  separator: z.enum(['auto', 'always', 'never']).optional(),
+  /**
+   * Optional inset rendering for this group. When `enabled: true`, the group
+   * MUST render with a visible bg + border + padding container (the design's
+   * "grouped tools" look) AND its inner items MUST shrink so the group's
+   * outer height matches an unwrapped 36px button — i.e. enabling inset
+   * MUST NOT increase control-bar height.
+   */
+  inset: GroupInsetSchema.optional(),
+})
+
+export const ControlBarLayoutSchema = z.object({
+  version: z.literal(1),
+  groups: z
+    .array(LayoutGroupSchema)
+    .refine((groups) => groups.some((g) => g.id === 'default'), {
+      message: "Layout must contain a 'default' group",
+    })
+    .refine(
+      (groups) => {
+        const ids = groups.map((g) => g.id)
+        return new Set(ids).size === ids.length
+      },
+      { message: 'Group ids must be unique' },
+    )
+    .refine(
+      (groups) => {
+        const allItems = groups.flatMap((g) => g.items)
+        return new Set(allItems).size === allItems.length
+      },
+      { message: 'Item ids must not appear in multiple groups' },
+    ),
+})
+
+// ── TypeScript types ──────────────────────────────────────────────────────
+
+export interface GroupInset {
+  enabled: boolean
+  /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
+  color?: string
+}
+
+export interface LayoutGroup {
+  id: string
+  items: string[]
+  separator?: 'auto' | 'always' | 'never'
+  /** When `enabled: true`, render the group with the visible "grouped tools" container. */
+  inset?: GroupInset
+}
+
+export interface ControlBarLayout {
+  version: 1
+  groups: LayoutGroup[]
+}
+
+// ── Contribution type ─────────────────────────────────────────────────────
+
+export interface ControlBarContribution {
+  /** Item id — MUST be globally unique across all modules. */
+  id: string
+  /** Vue component rendered for this item. */
+  component: Component
+  /**
+   * Preferred group id on first install.
+   * MUST NOT be 'default' (reserved).
+   * When omitted, item falls into the 'default' group.
+   */
+  defaultGroup?: string
+  /**
+   * Hints used when host auto-creates the defaultGroup.
+   * Ignored if the group already exists in the layout.
+   */
+  groupHint?: {
+    separator?: 'auto' | 'always' | 'never'
+    label?: string | LocaleMap
+  }
+}
+
+// ── Default layout ────────────────────────────────────────────────────────
+
+/** Baseline layout used on first launch: a single empty `'default'` group. */
+export const DEFAULT_CONTROL_BAR_LAYOUT: ControlBarLayout = {
+  version: 1,
+  groups: [{ id: 'default', items: [], separator: 'auto' }],
+}
+
+// ── Reconcile helpers ─────────────────────────────────────────────────────
+
+/**
+ * Apply L3a non-destructive repairs to a parsed layout:
+ * - Ensure 'default' group exists
+ * - Replace invalid separator values with 'auto'
+ * Returns the (possibly mutated copy) and whether any repair was made.
+ *
+ * @internal Host-only utility; not part of the plugin author API.
+ */
+export function repairLayoutL3a(layout: ControlBarLayout): {
+  layout: ControlBarLayout
+  repaired: boolean
+} {
+  let repaired = false
+  const groups = layout.groups.map((g) => {
+    if (g.separator !== undefined && !['auto', 'always', 'never'].includes(g.separator)) {
+      repaired = true
+      return { ...g, separator: 'auto' as const }
+    }
+    return g
+  })
+  if (!groups.some((g) => g.id === 'default')) {
+    groups.push({ id: 'default', items: [], separator: 'auto' })
+    repaired = true
+  }
+  return { layout: { ...layout, groups }, repaired }
+}
+
+/**
+ * Apply L3b potentially-destructive repairs:
+ * - De-duplicate item ids across groups (keep last occurrence)
+ * - Trim ghost ids when count ≥ 20 (noop — ghost trimming is a UX action)
+ * Returns the repaired layout and whether any repair was made.
+ *
+ * @internal Host-only utility; not part of the plugin author API.
+ */
+export function repairLayoutL3b(
+  layout: ControlBarLayout,
+  knownItemIds: Set<string>,
+): { layout: ControlBarLayout; repaired: boolean } {
+  let repaired = false
+  const seen = new Set<string>()
+  // Process groups in reverse so the last occurrence wins.
+  const reversedGroups = [...layout.groups].reverse()
+  const deduped = reversedGroups.map((g) => {
+    const items = g.items.filter((id) => {
+      if (seen.has(id)) {
+        repaired = true
+        return false
+      }
+      seen.add(id)
+      return true
+    })
+    return { ...g, items }
+  })
+  const groups = deduped.reverse()
+
+  // Count ghosts across layout
+  const totalItems = groups.flatMap((g) => g.items)
+  const ghostCount = totalItems.filter((id) => !knownItemIds.has(id)).length
+  if (ghostCount >= 20) {
+    repaired = true
+    // Remove ghosts from all groups
+    const cleaned = groups.map((g) => ({
+      ...g,
+      items: g.items.filter((id) => knownItemIds.has(id)),
+    }))
+    return { layout: { ...layout, groups: cleaned }, repaired }
+  }
+
+  return { layout: { ...layout, groups }, repaired }
+}

package/src/types/module.ts

@@ -0,0 +1,225 @@
+import type { z } from 'zod'
+import type { ModuleContributions } from './contributions'
+import type { NotifyPayload, NotifyHandle } from './notification'
+import type { LocaleMap } from '../locale'
+
+/**
+ * Public contract that every OpenPen module — first-party (`src/core/modules/*`)
+ * and third-party plugin alike — must satisfy.
+ *
+ * Modules express their behaviour entirely via `contributes` and
+ * (optionally) `setup`. They never touch host-app internals directly:
+ * cross-module communication goes through declared contribution slots
+ * and the domain event bus.
+ */
+export interface OpenPenModule {
+  /** Globally unique kebab-case id. Subject to {@link import('../validation').MODULE_ID_RE}. */
+  id: string
+
+  /**
+   * i18n-independent display metadata. Used as a fallback layer in the
+   * Settings UI when the module's `contributes.locales` entries are not
+   * registered (e.g. the module is disabled and its contributions are not
+   * wired into the host). The runtime i18n contribution is always preferred
+   * as the primary source; this field is only consulted on a cache miss.
+   *
+   * Values are `LocaleMap` (`Record<string, string>`) keyed by BCP-47 tag.
+   * Resolution follows the same order as `resolveLabel`: exact tag → language
+   * prefix → `'en'` fallback → first declared value.
+   */
+  metadata?: {
+    name: LocaleMap
+    description?: LocaleMap
+  }
+
+  /**
+   * SemVer string. **Required for plugins** — the host validator
+   * rejects any non-built-in module whose `version` is missing or
+   * empty with a `'missing-version'` ValidationError, so a plugin
+   * with no version never finishes loading.
+   *
+   * Built-in modules (those bundled with the host under
+   * `src/core/modules/`) MAY omit it and inherit the host version;
+   * the type stays optional only to accommodate that case.
+   */
+  version?: string
+
+  /**
+   * Minimum OpenPen app version this module requires (semver).
+   *
+   * Validated at load time by the host: a plugin whose `minAppVersion`
+   * exceeds the running host version is skipped with a console warning.
+   * Set this to `"1.0.0"` (or omit it) for broad v1.x compatibility.
+   */
+  minAppVersion?: string
+
+  /**
+   * One-shot initialisation, called after manifest validation and
+   * before contributions are wired into the host. Use this for things
+   * that need to happen exactly once, like seeding default settings or
+   * subscribing to long-running event streams.
+   */
+  setup?: (ctx: ModuleSetupContext) => void | Promise<void>
+
+  /** At least one field on this object is required (enforced by `defineModule`). */
+  contributes?: ModuleContributions
+
+  /**
+   * Zod schema for this module's user-facing settings. The host renders
+   * the settings form from this schema and persists the parsed value
+   * under `config.json.modules[id]`. The same schema validates writes
+   * made via `ctx.updateSettings()`; writes that fail validation reject
+   * with the underlying `ZodError`.
+   *
+   * Modules that intend to call `ctx.updateSettings()` MUST declare
+   * this field; calling `updateSettings` without a schema throws at
+   * runtime so the missing contract surfaces during development.
+   */
+  settingsSchema?: z.ZodType
+
+  /**
+   * Settings schema version. Increment when the schema's shape changes
+   * in a way that needs migration (renames, removals, or restructuring).
+   * Pure additive changes (new keys with `.default()` values) do not
+   * require a bump — Zod's defaults fill in on parse.
+   *
+   * Defaults to `1` if omitted. The host persists the version under
+   * `config.json.moduleMeta[id].schemaVersion` (separate from the data
+   * blob) so plugins never see this sentinel in their settings object.
+   */
+  settingsVersion?: number
+
+  /**
+   * Optional migration hook run before `settingsSchema` parses persisted
+   * data. Called when the stored `schemaVersion` is less than the
+   * module's `settingsVersion`. Receives the stored version + raw data
+   * blob; returns the migrated blob, which is then validated by
+   * `settingsSchema` and persisted at the new version.
+   *
+   * Use this for renames, removals, or restructuring. For pure additive
+   * changes (new keys), Zod's `.default()` covers it — no migrate hook
+   * needed.
+   *
+   * @example
+   * migrate(stored, data) {
+   *   if (stored < 2 && 'oldName' in data) {
+   *     data.newName = data.oldName
+   *     delete data.oldName
+   *   }
+   *   return data
+   * }
+   */
+  migrate?: (
+    storedVersion: number,
+    data: Record<string, unknown>
+  ) => Record<string, unknown>
+}
+
+/**
+ * Runtime context handed to `setup()`. Intentionally narrow — modules
+ * that need more capabilities should declare them via contribution
+ * slots so the dependency is visible at validation time.
+ */
+export interface ModuleSetupContext {
+  /** This module's id, for logging / error messages. */
+  moduleId: string
+  /** Currently active locale, e.g. 'zh-TW'. Read-only. */
+  locale: string
+  /**
+   * Returns this module's current settings — a live in-memory snapshot
+   * already validated by `settingsSchema`. Synchronous and zero-I/O:
+   * the host hydrates the cache before `setup()` is called and updates
+   * it in-place after every successful `updateSettings()`.
+   *
+   * Generic `T` should match the inferred type of your `settingsSchema`
+   * (use `z.infer<typeof MySchema>` at the call site).
+   *
+   * @example
+   * const settings = ctx.getSettings<z.infer<typeof MySchema>>()
+   */
+  getSettings: <T = unknown>() => T
+
+  /**
+   * Shallow-merges `patch` into this module's settings, validates the
+   * result against `settingsSchema` (Zod), and persists to `config.json`.
+   * Resolves once the write is durable; rejects with the underlying
+   * `ZodError` if the merged object fails validation (no I/O happens
+   * on validation failure).
+   *
+   * The in-memory snapshot returned by `getSettings()` is updated
+   * before the Promise resolves; subscribers registered via
+   * `onSettingsChange()` then fire with the new snapshot.
+   *
+   * Note on nested objects: the merge is shallow. Updating a nested
+   * object replaces it entirely — spread the existing nested value
+   * yourself if you only want to change one inner field:
+   *
+   * ```ts
+   * const cur = ctx.getSettings<MySettings>()
+   * await ctx.updateSettings({ colors: { ...cur.colors, primary: '#0f0' } })
+   * ```
+   *
+   * Throws synchronously if the module did not declare `settingsSchema`.
+   */
+  updateSettings: <T = unknown>(patch: Partial<T>) => Promise<void>
+
+  /**
+   * Subscribe to settings changes for this module. The callback fires
+   * after every successful `updateSettings()` — including writes that
+   * originated from the host's settings panel — with the fresh,
+   * already-validated snapshot.
+   *
+   * Returns an unsubscribe function. The host also calls it
+   * automatically when the module is rolled back, so manual cleanup
+   * is only needed if you want to stop listening sooner than
+   * module dispose.
+   *
+   * @example
+   * const stop = ctx.onSettingsChange<MySettings>((s) => {
+   *   redrawWithColor(s.primary)
+   * })
+   */
+  onSettingsChange: <T = unknown>(cb: (settings: T) => void) => () => void
+
+  /**
+   * Invoke one of THIS module's main-side handlers (declared via
+   * `contributes.mainHandlers`). The moduleId is captured by the host
+   * so plugins cannot reach into other modules' handlers — use this
+   * helper rather than the lower-level `openPenApi.moduleCall`.
+   *
+   * Returns whatever the handler returns (typed by the caller).
+   */
+  callMain: <T = unknown>(action: string, payload?: unknown) => Promise<T>
+  /**
+   * Register a cleanup callback. Called in reverse registration order
+   * when the module is unloaded (hot-reload, user-disable, or app quit).
+   * Use this to cancel timers, remove listeners, or release resources
+   * that `setup()` acquired.
+   */
+  onDispose: (fn: () => void | Promise<void>) => void
+  /**
+   * Shows a short-lived toast notification in the overlay window.
+   * Visibility and position are controlled by the user's settings.
+   * Returns a NotifyHandle for early dismissal.
+   */
+  notify: (payload: NotifyPayload) => NotifyHandle
+
+  /**
+   * Resolves an i18n key for this module to the current-locale string.
+   *
+   * The key is automatically namespaced as `${moduleId}.${key}`, matching
+   * the dictionary structure registered via `contributes.locales` (the host
+   * merges each locale dict into the global vue-i18n instance under the
+   * module's id namespace).
+   *
+   * Aligned with VS Code's `vscode.l10n.t()` convention:
+   * ```typescript
+   * ctx.t('notif.start')
+   * ctx.t('notif.greeting', { name: 'Alice' })  // dict entry: 'Hello {name}'
+   * ```
+   *
+   * When a key has no matching translation the namespaced key string is
+   * returned (vue-i18n's default missing-key behaviour).
+   */
+  t: (key: string, params?: Record<string, unknown>) => string
+}

package/src/types/notification.ts

@@ -0,0 +1,40 @@
+/**
+ * notification.ts — NotifyPayload and NotifyHandle type definitions.
+ *
+ * Used by callers of ctx.notify(payload); NotificationService implements
+ * the host-side logic.
+ *
+ * Runtime messages (notify / status text, etc.) are always resolved to a
+ * plain string via ctx.t(key) before being passed in. LocaleMap is reserved
+ * for module manifest metadata (name, description, contribution label),
+ * following the VS Code package.nls.json / JetBrains plugin.xml convention.
+ */
+
+/**
+ * Input payload for ctx.notify().
+ *
+ * **Overlay-window only.** Toasts render via the host's
+ * NotificationLayer, which is mounted exclusively in the overlay
+ * window. Calls made while the overlay is not the active context
+ * silently no-op (no error, no queue persistence). See
+ * `docs/reference/notify-api.md` → "When does the toast appear?"
+ * for guidance on choosing notify() versus your own UI surface.
+ */
+export interface NotifyPayload {
+  /** Required. Already-resolved plain string; use ctx.t(key) for i18n. */
+  message: string
+  /** Subtitle text. Already-resolved plain string, e.g. "Press again to exit". */
+  description?: string
+  /** Inline SVG string, same convention as ToolContribution.icon. */
+  icon?: string
+  /** Semantic colour variant. Defaults to 'default'. */
+  variant?: 'default' | 'success' | 'warning' | 'danger'
+  /** Auto-dismiss delay in milliseconds. Defaults to 1800. */
+  duration?: number
+}
+
+/** Return value of ctx.notify(), allowing early dismissal. */
+export interface NotifyHandle {
+  /** Immediately closes this notification. */
+  dismiss(): void
+}

package/src/types/tool.ts

@@ -0,0 +1,82 @@
+/**
+ * Public Tool / Stroke / Point primitives shared by host code and
+ * every module / plugin. Declared inside @openpen/module-api so
+ * third parties don't need to import host internals to type their
+ * `canvas.tools` contributions.
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+/** Solid color or linear gradient between two stops. */
+export type StrokeColor =
+  | string
+  | { type: 'linear'; from: string; to: string }
+
+export interface StrokeStyle {
+  color: StrokeColor
+  lineWidth: number
+  lineCap: CanvasLineCap
+  lineJoin: CanvasLineJoin
+}
+
+export interface Stroke {
+  id: string
+  /** Id of the tool that produced this stroke (matches a ToolContribution.id). */
+  tool: string
+  points: Point[]
+  style: StrokeStyle
+  /**
+   * Tool-specific extra state. Tools MAY store arbitrary keys here during
+   * `onPointerDown` / `onPointerMove` / `onPointerUp`; those keys survive
+   * into `renderStroke(stroke, canvasCtx)` calls so the renderer can read
+   * them back.
+   *
+   * The host treats extra keys as `unknown` — type-cast at the read site is
+   * the plugin author's responsibility (TypeScript cannot infer the shape).
+   *
+   * @example
+   * // Store during onPointerUp:
+   * const stroke: Stroke = { id, tool: 'my-tool', points, style, opacity: 0.5 }
+   *
+   * // Read back in renderStroke:
+   * const opacity = (stroke.opacity as number) ?? 1
+   * canvasCtx.globalAlpha = opacity
+   */
+  [key: string]: unknown
+}
+
+export interface PointerModifiers {
+  shiftKey?: boolean
+}
+
+export interface Tool {
+  onPointerDown(
+    canvasCtx: CanvasRenderingContext2D,
+    point: Point,
+    style: StrokeStyle
+  ): void
+  /**
+   * Returns `true` when the engine should perform a full redraw
+   * (e.g. stroke-eraser removed an existing stroke). Otherwise `void`.
+   */
+  onPointerMove(
+    canvasCtx: CanvasRenderingContext2D,
+    point: Point,
+    modifiers?: PointerModifiers
+  ): void | boolean
+  /**
+   * Returns the finished `Stroke` to push into the store, or `null`
+   * to discard (e.g. an eraser that doesn't accumulate state).
+   */
+  onPointerUp(
+    canvasCtx: CanvasRenderingContext2D,
+    point: Point,
+    modifiers?: PointerModifiers
+  ): Stroke | null
+  /** When true, canvas-engine clears + redraws all strokes before each move. */
+  needsPreviewRedraw?: boolean
+  renderPreview?(canvasCtx: CanvasRenderingContext2D): void
+}

package/src/uikit/components/AppBanner.vue

@@ -0,0 +1,131 @@
+<script setup lang="ts">
+/**
+ * AppBanner — High-level wrapper (Layer 1).
+ *
+ * Presents info / warning / success / error status messages using the
+ * --openpen-color-state-* design tokens. The icon is auto-rendered based on
+ * the variant; message content goes in the default slot; optional inline action
+ * buttons (e.g. restart / dismiss) go in the `#actions` slot.
+ *
+ * Inline mode (compact single-line) is enabled via the `inline` prop and is
+ * suited for form validation feedback and status lines inside dialogs.
+ */
+
+export type BannerVariant = 'info' | 'warning' | 'success' | 'error'
+
+withDefaults(defineProps<{
+  variant: BannerVariant
+  /** Compact single-line layout: smaller padding, vertically centered. */
+  inline?: boolean
+}>(), { inline: false })
+</script>
+
+<template>
+  <div
+    :class="['app-banner', `app-banner-${variant}`, { 'app-banner-inline': inline }]"
+    :role="variant === 'error' ? 'alert' : 'status'"
+  >
+    <span class="app-banner-icon" aria-hidden="true">
+      <!-- info -->
+      <svg v-if="variant === 'info'" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/>
+      </svg>
+      <!-- warning -->
+      <svg v-else-if="variant === 'warning'" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/>
+      </svg>
+      <!-- success -->
+      <svg v-else-if="variant === 'success'" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/>
+      </svg>
+      <!-- error -->
+      <svg v-else width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/>
+      </svg>
+    </span>
+
+    <span class="app-banner-body"><slot /></span>
+
+    <span v-if="$slots.actions" class="app-banner-actions">
+      <slot name="actions" />
+    </span>
+  </div>
+</template>
+
+<style scoped>
+.app-banner {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 10px 14px;
+  border-radius: var(--openpen-radius-md, 10px);
+  border: 1px solid;
+  font-size: 13px;
+  line-height: 1.55;
+}
+
+.app-banner-inline {
+  padding: 7px 12px;
+  align-items: center;
+  font-size: 12px;
+}
+
+.app-banner-icon {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  margin-top: 1px;
+}
+
+.app-banner-inline .app-banner-icon { margin-top: 0; }
+
+.app-banner-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.app-banner-actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+  margin-left: auto;
+}
+
+/* Variants */
+.app-banner-info {
+  background: var(--openpen-color-state-info-bg);
+  border-color: var(--openpen-color-state-info-border);
+  color: var(--openpen-color-state-info-text);
+}
+.app-banner-info .app-banner-icon {
+  color: var(--openpen-color-state-info-icon);
+}
+
+.app-banner-warning {
+  background: var(--openpen-color-state-warning-bg);
+  border-color: var(--openpen-color-state-warning-border);
+  color: var(--openpen-color-state-warning-text);
+}
+.app-banner-warning .app-banner-icon {
+  color: var(--openpen-color-state-warning-icon);
+}
+
+.app-banner-success {
+  background: var(--openpen-color-state-success-bg);
+  border-color: var(--openpen-color-state-success-border);
+  color: var(--openpen-color-state-success-text);
+}
+.app-banner-success .app-banner-icon {
+  color: var(--openpen-color-state-success-icon);
+}
+
+.app-banner-error {
+  background: var(--openpen-color-state-error-bg);
+  border-color: var(--openpen-color-state-error-border);
+  color: var(--openpen-color-state-error-text);
+}
+.app-banner-error .app-banner-icon {
+  color: var(--openpen-color-state-error-icon);
+}
+</style>