@openpen/module-api 1.1.1 → 1.3.0

package/dist/slots.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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/slots/index.md`. */
+    description: string;
+}
+/**
+ * v1 active slots (16). Wired through to runtime adapters.
+ */
+export declare const V1_ACTIVE_SLOTS: readonly SlotDefinition[];
+/**
+ * v1 reserved slots. Registrations pass validation but no runtime
+ * adapter is active yet.
+ */
+export declare const V1_RESERVED_SLOTS: readonly SlotDefinition[];
+/**
+ * All slots (active + reserved). Source of truth for validation.
+ */
+export declare const ALL_SLOTS: readonly SlotDefinition[];
+/** Returns `true` when `id` matches a slot in {@link ALL_SLOTS} (active or reserved). */
+export declare function isKnownSlot(id: string): boolean;
+/**
+ * Returns the {@link SlotDefinition} for a known slot id, or `undefined` if
+ * the id is not registered in {@link ALL_SLOTS}.
+ */
+export declare function getSlot(id: string): SlotDefinition | undefined;
+/**
+ * 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 declare const CONTRIBUTION_KEY_TO_SLOT_ID: Record<string, string>;

package/dist/types/contributions.d.ts

@@ -0,0 +1,288 @@
+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 {
+    tools?: ToolContribution[];
+    shapes?: ShapeContribution[];
+    strokeStyle?: StrokeStyleContribution;
+    historyCommands?: HistoryCommandContribution[];
+    backgroundLayers?: CanvasLayerContribution[];
+    overlayLayers?: CanvasLayerContribution[];
+    htmlOverlays?: HtmlOverlayContribution[];
+    /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+    strokeTransformers?: StrokeTransformerContribution[];
+    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;
+    shortcuts?: ShortcutContribution[];
+    windowBehaviors?: WindowBehaviorContribution[];
+    locales?: LocaleContribution;
+    events?: EventSubscriptionContribution[];
+    lifecycle?: LifecycleContribution;
+    storage?: StorageContribution;
+    mainHandlers?: MainHandlerContribution;
+    /** ⏳ Reserved slot — accepts registrations, adapter not yet wired. */
+    fileDrop?: FileDropContribution[];
+}
+/**
+ * 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;
+}
+/** Hotspot offset in CSS pixels relative to the cursor image's top-left. */
+export interface Hotspot {
+    x: number;
+    y: number;
+}
+/**
+ * Vector cursor: inline SVG markup OR a plugin-internal relative path
+ * to a `.svg` file. URL-shaped strings, absolute paths, and `..` segments
+ * are rejected at contribution-validation time.
+ */
+export interface SvgCursorSpec {
+    svg: string;
+    hotspot?: Hotspot;
+    /** CSS keyword fallback for legacy / non-overlay contexts. Defaults to `'crosshair'`. */
+    fallback?: string;
+}
+/**
+ * Raster cursor: plugin-internal relative path to a `.png` file. Inline
+ * form is not supported — PNG payload comes through `openpen-plugin://`.
+ */
+export interface PngCursorSpec {
+    png: string;
+    hotspot?: Hotspot;
+    fallback?: string;
+}
+/**
+ * Cursor specification. The legacy `string` form must be one of the
+ * whitelisted CSS keywords (see `SAFE_CURSOR_KEYWORDS` in cursors.ts);
+ * any string containing `url(` / `image-set(` / `-webkit-image-set(` is
+ * rejected to keep the asset trust boundary closed.
+ */
+export type CursorSpec = string | SvgCursorSpec | PngCursorSpec;
+export interface CursorContribution {
+    id: string;
+    cursor: CursorSpec;
+}
+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>;
+}

package/dist/types/control-bar-layout.d.ts

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+import type { Component } from 'vue';
+import type { LocaleMap } from '../locale';
+export declare const GroupInsetSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
+    color: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    color?: string | undefined;
+}, {
+    enabled: boolean;
+    color?: string | undefined;
+}>;
+export declare const LayoutGroupSchema: z.ZodObject<{
+    id: z.ZodString;
+    items: z.ZodArray<z.ZodString, "many">;
+    separator: z.ZodOptional<z.ZodEnum<["auto", "always", "never"]>>;
+    /**
+     * 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: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
+        color: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        color?: string | undefined;
+    }, {
+        enabled: boolean;
+        color?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    items: string[];
+    separator?: "never" | "auto" | "always" | undefined;
+    inset?: {
+        enabled: boolean;
+        color?: string | undefined;
+    } | undefined;
+}, {
+    id: string;
+    items: string[];
+    separator?: "never" | "auto" | "always" | undefined;
+    inset?: {
+        enabled: boolean;
+        color?: string | undefined;
+    } | undefined;
+}>;
+export declare const ControlBarLayoutSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    groups: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        items: z.ZodArray<z.ZodString, "many">;
+        separator: z.ZodOptional<z.ZodEnum<["auto", "always", "never"]>>;
+        /**
+         * 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: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
+            color: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            color?: string | undefined;
+        }, {
+            enabled: boolean;
+            color?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }, {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }>, "many">, {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[], {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[]>, {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[], {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[]>, {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[], {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[]>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    groups: {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[];
+}, {
+    version: 1;
+    groups: {
+        id: string;
+        items: string[];
+        separator?: "never" | "auto" | "always" | undefined;
+        inset?: {
+            enabled: boolean;
+            color?: string | undefined;
+        } | undefined;
+    }[];
+}>;
+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[];
+}
+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;
+    };
+}
+/** Baseline layout used on first launch: a single empty `'default'` group. */
+export declare const DEFAULT_CONTROL_BAR_LAYOUT: ControlBarLayout;
+/**
+ * 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 declare function repairLayoutL3a(layout: ControlBarLayout): {
+    layout: ControlBarLayout;
+    repaired: boolean;
+};
+/**
+ * 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 declare function repairLayoutL3b(layout: ControlBarLayout, knownItemIds: Set<string>): {
+    layout: ControlBarLayout;
+    repaired: boolean;
+};