@openpen/module-api 1.1.1 → 1.3.0

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

@@ -1,174 +0,0 @@
-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

@@ -1,225 +0,0 @@
-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/tool.ts

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

@@ -1,131 +0,0 @@
-<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>