@openpen/module-api 1.1.1 → 1.2.0

package/dist/index.js

@@ -0,0 +1,349 @@
+import { C as CONTRIBUTION_KEY_TO_SLOT_ID } from "./_chunks/inject-keys-CRXCpN-M.js";
+import { A, a, b, c, d, D, G, H, I, L, M, P, S, e, T, V, f, W, g, i, r, h } from "./_chunks/inject-keys-CRXCpN-M.js";
+import { g as getModuleContext } from "./_chunks/module-context-registry-Cn1IWYu9.js";
+import { c as c2, s } from "./_chunks/module-context-registry-Cn1IWYu9.js";
+import DOMPurify from "dompurify";
+import { z } from "zod";
+const MODULE_ID_RE = /^@([a-z0-9][a-z0-9-]{0,38})\/([a-z0-9][a-z0-9-]{0,38})$/;
+function isValidModuleId(id) {
+  return typeof id === "string" && id.length > 0 && MODULE_ID_RE.test(id);
+}
+function defineModule(spec) {
+  if (!isValidModuleId(spec.id)) {
+    throw new Error(
+      `[@openpen/module-api] Invalid module id: ${JSON.stringify(spec.id)}. Module ids must use \`@scope/name\` format with lowercase ASCII alphanumeric + hyphen, max 39 chars per segment (e.g. \`@alice/my-plugin\`).`
+    );
+  }
+  if (!spec.contributes || typeof spec.contributes !== "object") {
+    throw new Error(
+      `[@openpen/module-api] Module "${spec.id}" must declare a non-empty 'contributes' object.`
+    );
+  }
+  const keys = Object.keys(spec.contributes);
+  if (keys.length === 0) {
+    throw new Error(
+      `[@openpen/module-api] Module "${spec.id}" must contribute to at least one slot. Add at least one field to 'contributes' (e.g. 'tools', 'settingsTabs', 'shortcuts').`
+    );
+  }
+  for (const key of keys) {
+    if (!(key in CONTRIBUTION_KEY_TO_SLOT_ID)) {
+      throw new Error(
+        `[@openpen/module-api] Module "${spec.id}" contributes to unknown slot key '${key}'. Known keys: ${Object.keys(CONTRIBUTION_KEY_TO_SLOT_ID).sort().join(", ")}.`
+      );
+    }
+  }
+  return spec;
+}
+function useModuleContext(moduleId) {
+  const ctx = getModuleContext(moduleId);
+  if (!ctx) {
+    throw new Error(
+      `[module-api] useModuleContext("${moduleId}") was called but no module is currently registered under that id. This usually means: (a) the moduleId string does not match the id passed to defineModule, or (b) the composable was called before the module's setup() ran (do not call useModuleContext at module top-level — call it inside a component's setup() or onMounted()).`
+    );
+  }
+  return ctx;
+}
+function sanitizeIdForI18n(moduleId) {
+  return moduleId.replace(/^@/, "").replace(/\//g, ".");
+}
+function resolveLabel(input, locale) {
+  if (typeof input === "string") return input;
+  if (input[locale] !== void 0) return input[locale];
+  const lang = locale.split("-")[0];
+  if (lang !== locale && input[lang] !== void 0) return input[lang];
+  if (input.en !== void 0) return input.en;
+  const first = Object.values(input)[0];
+  return first ?? "";
+}
+function resolveStrokeColor(color) {
+  return typeof color === "string" ? color : color.from;
+}
+const SAFE_CURSOR_KEYWORDS = /* @__PURE__ */ new Set([
+  "auto",
+  "default",
+  "none",
+  "context-menu",
+  "help",
+  "pointer",
+  "progress",
+  "wait",
+  "cell",
+  "crosshair",
+  "text",
+  "vertical-text",
+  "alias",
+  "copy",
+  "move",
+  "no-drop",
+  "not-allowed",
+  "grab",
+  "grabbing",
+  "e-resize",
+  "n-resize",
+  "ne-resize",
+  "nw-resize",
+  "s-resize",
+  "se-resize",
+  "sw-resize",
+  "w-resize",
+  "ew-resize",
+  "ns-resize",
+  "nesw-resize",
+  "nwse-resize",
+  "col-resize",
+  "row-resize",
+  "all-scroll",
+  "zoom-in",
+  "zoom-out"
+]);
+const FORBIDDEN_CSS_LOAD_PATTERN = /url\s*\(|image-set\s*\(|-webkit-image-set\s*\(/i;
+const DEFAULT_FALLBACK_KEYWORD = "crosshair";
+function isSafeRelativePath(p) {
+  if (typeof p !== "string" || p.length === 0) return false;
+  if (p.includes(":")) return false;
+  if (p.startsWith("/")) return false;
+  for (const seg of p.split("/")) {
+    if (seg === "" || seg === "..") return false;
+  }
+  return true;
+}
+function pluginHostname(moduleId) {
+  return moduleId.replace(/^@/, "").replace(/\//g, ".");
+}
+function pluginAssetUrl(moduleId, relativePath) {
+  if (!isSafeRelativePath(relativePath)) {
+    throw new Error(`Unsafe asset path: ${relativePath}`);
+  }
+  return `openpen-plugin://${pluginHostname(moduleId)}/${relativePath}`;
+}
+function sanitizeSvgMarkup(raw) {
+  return DOMPurify.sanitize(raw, {
+    USE_PROFILES: { svg: true },
+    FORBID_TAGS: ["foreignObject"],
+    // Cursor SVGs use presentation attributes (fill/stroke/etc.), never
+    // inline `style`. Forbidding it strips legacy `expression()` CSS
+    // smuggling vectors (S7) without touching anything we draw.
+    FORBID_ATTR: ["style"],
+    ALLOW_UNKNOWN_PROTOCOLS: false
+  });
+}
+function resolveHotspot(spec) {
+  const h2 = spec.hotspot;
+  if (!h2 || typeof h2 !== "object") return { x: 0, y: 0 };
+  const x = typeof h2.x === "number" && Number.isFinite(h2.x) ? h2.x : 0;
+  const y = typeof h2.y === "number" && Number.isFinite(h2.y) ? h2.y : 0;
+  return { x, y };
+}
+function resolveFallback(spec) {
+  return typeof spec.fallback === "string" && spec.fallback.length > 0 ? spec.fallback : DEFAULT_FALLBACK_KEYWORD;
+}
+function escapeHtmlAttr(s2) {
+  return s2.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+async function compileCursor(spec, context = {}) {
+  if (typeof spec === "string") return null;
+  if (!spec || typeof spec !== "object") return null;
+  if ("svg" in spec && typeof spec.svg === "string") {
+    const hotspot = resolveHotspot(spec);
+    const fallbackCssKeyword = resolveFallback(spec);
+    const trimmed = spec.svg.trim();
+    if (trimmed.startsWith("<")) {
+      const sanitised = sanitizeSvgMarkup(trimmed);
+      if (!sanitised) return null;
+      return { svgMarkup: sanitised, hotspot, fallbackCssKeyword };
+    }
+    if (!context.pluginHostname || !isSafeRelativePath(trimmed)) return null;
+    const url = `openpen-plugin://${context.pluginHostname}/${trimmed}`;
+    const fetchImpl = context.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : void 0);
+    if (!fetchImpl) return null;
+    try {
+      const resp = await fetchImpl(url);
+      if (!resp.ok) return null;
+      const raw = await resp.text();
+      const sanitised = sanitizeSvgMarkup(raw);
+      if (!sanitised) return null;
+      return { svgMarkup: sanitised, hotspot, fallbackCssKeyword };
+    } catch {
+      return null;
+    }
+  }
+  if ("png" in spec && typeof spec.png === "string") {
+    const hotspot = resolveHotspot(spec);
+    const fallbackCssKeyword = resolveFallback(spec);
+    const trimmed = spec.png.trim();
+    if (!context.pluginHostname || !isSafeRelativePath(trimmed)) return null;
+    const url = escapeHtmlAttr(`openpen-plugin://${context.pluginHostname}/${trimmed}`);
+    const svgMarkup = `<img src="${url}" alt="" style="display:block;max-width:64px;max-height:64px;" />`;
+    return { svgMarkup, hotspot, fallbackCssKeyword };
+  }
+  return null;
+}
+function sanitizeCursorContributions(cursors, options = {}) {
+  const cleaned = [];
+  const diagnostics = [];
+  if (!Array.isArray(cursors)) return { cleaned, diagnostics };
+  for (const raw of cursors) {
+    if (raw === null || typeof raw !== "object") {
+      diagnostics.push({ id: "<unknown>", rule: "R1", reason: "contribution is not an object" });
+      continue;
+    }
+    const entry = raw;
+    const id = typeof entry.id === "string" && entry.id.length > 0 ? entry.id : "<unknown>";
+    if (id === "<unknown>") {
+      diagnostics.push({ id, rule: "R1", reason: "missing or empty `id`" });
+      continue;
+    }
+    const { cursor } = entry;
+    if (typeof cursor === "string") {
+      const trimmedLower = cursor.trim().toLowerCase();
+      if (FORBIDDEN_CSS_LOAD_PATTERN.test(trimmedLower)) {
+        diagnostics.push({
+          id,
+          rule: "R12",
+          reason: "string contains url() / image-set() / -webkit-image-set(); loads external resource"
+        });
+        continue;
+      }
+      if (!SAFE_CURSOR_KEYWORDS.has(trimmedLower)) {
+        diagnostics.push({
+          id,
+          rule: "R2",
+          reason: `string '${trimmedLower}' is not in the safe CSS cursor keyword whitelist`
+        });
+        continue;
+      }
+      cleaned.push({ id, cursor: trimmedLower });
+      continue;
+    }
+    if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) {
+      diagnostics.push({ id, rule: "R1", reason: "cursor field is neither string nor plain object" });
+      continue;
+    }
+    const cursorObj = cursor;
+    const hasSvg = Object.prototype.hasOwnProperty.call(cursorObj, "svg");
+    const hasPng = Object.prototype.hasOwnProperty.call(cursorObj, "png");
+    if (!hasSvg && !hasPng) {
+      diagnostics.push({ id, rule: "R3", reason: "cursor object has neither `svg` nor `png` key" });
+      continue;
+    }
+    if (hasSvg && hasPng) {
+      diagnostics.push({ id, rule: "R4", reason: "cursor object has both `svg` and `png` keys (ambiguous)" });
+      continue;
+    }
+    if (hasSvg) {
+      const svg = cursorObj.svg;
+      if (typeof svg !== "string") {
+        diagnostics.push({ id, rule: "R5", reason: "`svg` value is not a string" });
+        continue;
+      }
+      const trimmed = svg.trim();
+      const isInline = trimmed.startsWith("<");
+      if (!isInline) {
+        if (!isSafeRelativePath(trimmed)) {
+          diagnostics.push({
+            id,
+            rule: "R6",
+            reason: "`svg` value is non-inline and not a safe relative path"
+          });
+          continue;
+        }
+        if (options.isBuiltin) {
+          diagnostics.push({
+            id,
+            rule: "R7",
+            reason: "built-in modules cannot use path-form `svg` (no openpen-plugin hostname)"
+          });
+          continue;
+        }
+      }
+    }
+    if (hasPng) {
+      const png = cursorObj.png;
+      if (typeof png !== "string") {
+        diagnostics.push({ id, rule: "R8", reason: "`png` value is not a string" });
+        continue;
+      }
+      if (!isSafeRelativePath(png.trim())) {
+        diagnostics.push({
+          id,
+          rule: "R9",
+          reason: "`png` value is not a safe relative path"
+        });
+        continue;
+      }
+      if (options.isBuiltin) {
+        diagnostics.push({
+          id,
+          rule: "R10",
+          reason: "built-in modules cannot use `png` (no openpen-plugin hostname)"
+        });
+        continue;
+      }
+    }
+    if (cursorObj.hotspot !== void 0) {
+      const h2 = cursorObj.hotspot;
+      const valid = h2 !== null && typeof h2 === "object" && typeof h2.x === "number" && Number.isFinite(h2.x) && h2.x >= 0 && typeof h2.y === "number" && Number.isFinite(h2.y) && h2.y >= 0;
+      if (!valid) {
+        diagnostics.push({
+          id,
+          rule: "R11",
+          reason: "`hotspot` must be `{ x: number ≥ 0, y: number ≥ 0 }`"
+        });
+        continue;
+      }
+    }
+    const cleanedCursor = hasSvg ? { svg: cursorObj.svg.trim() } : { png: cursorObj.png.trim() };
+    if (cursorObj.hotspot !== void 0) {
+      const h2 = cursorObj.hotspot;
+      cleanedCursor.hotspot = { x: h2.x, y: h2.y };
+    }
+    if (typeof cursorObj.fallback === "string") {
+      cleanedCursor.fallback = cursorObj.fallback;
+    }
+    cleaned.push({ id, cursor: cleanedCursor });
+  }
+  return { cleaned, diagnostics };
+}
+export {
+  A as ACTIVE_TOOL_KEY,
+  a as ALL_SLOTS,
+  b as ANCHOR_EL_KEY,
+  CONTRIBUTION_KEY_TO_SLOT_ID,
+  c as CONTROL_BAR_ANIMATING_KEY,
+  d as ControlBarLayoutSchema,
+  D as DEFAULT_CONTROL_BAR_LAYOUT,
+  G as GroupInsetSchema,
+  H as HOST_DIALOG_OPEN_COUNT_KEY,
+  I as IS_VERTICAL_KEY,
+  L as LayoutGroupSchema,
+  M as MODAL_MANAGER_KEY,
+  MODULE_ID_RE,
+  P as POPOVER_PLACEMENT_HINT_KEY,
+  SAFE_CURSOR_KEYWORDS,
+  S as SNAP_EDGE_KEY,
+  e as STROKE_STYLE_CONTEXT_KEY,
+  T as TOOLTIP_FLIP_DOWN_KEY,
+  V as V1_ACTIVE_SLOTS,
+  f as V1_RESERVED_SLOTS,
+  W as WRAPPER_EL_KEY,
+  c2 as clearModuleContext,
+  compileCursor,
+  defineModule,
+  g as getSlot,
+  i as isKnownSlot,
+  isSafeRelativePath,
+  isValidModuleId,
+  pluginAssetUrl,
+  pluginHostname,
+  r as repairLayoutL3a,
+  h as repairLayoutL3b,
+  resolveLabel,
+  resolveStrokeColor,
+  sanitizeCursorContributions,
+  sanitizeIdForI18n,
+  sanitizeSvgMarkup,
+  s as setModuleContext,
+  useModuleContext,
+  z
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/validation.ts","../src/define-module.ts","../src/use-module-context.ts","../src/locale.ts","../src/types/tool.ts","../src/cursors.ts"],"sourcesContent":["/**\n * Scoped module / plugin ID format: `@scope/name`\n *\n * Rules:\n * - Must start with `@`\n * - scope: lowercase ASCII alphanumeric + hyphen, starts with letter or digit,\n *   max 39 chars (mirrors GitHub username/org limits)\n * - Single `/` separator\n * - name: same charset and length limit as scope\n *\n * The same regex is used by the OpenPen CLI (`openpen-cli`) and the\n * main process plugin loader, so plugin IDs round-trip safely between\n * `plugin.json`, filesystem paths under `~/.openpen/plugins/@scope/name/`,\n * and registry lookups.\n */\nexport const MODULE_ID_RE =\n  /^@([a-z0-9][a-z0-9-]{0,38})\\/([a-z0-9][a-z0-9-]{0,38})$/\n\n/**\n * Returns `true` when `id` is a non-empty string that satisfies\n * {@link MODULE_ID_RE}; acts as a type guard narrowing `unknown` → `string`.\n *\n * @example\n * isValidModuleId('@openpen/freehand') // true\n * isValidModuleId('@alice/todo-app')   // true\n * isValidModuleId('freehand')          // false — must be scoped @scope/name\n * isValidModuleId('')                  // false — empty string rejected\n */\nexport function isValidModuleId(id: unknown): id is string {\n  return typeof id === 'string' && id.length > 0 && MODULE_ID_RE.test(id)\n}\n","import { isValidModuleId } from './validation'\nimport { CONTRIBUTION_KEY_TO_SLOT_ID } from './slots'\nimport type { OpenPenModule } from './types/module'\n\n/**\n * Identity helper for declaring an OpenPen module with full type\n * inference and runtime sanity checks. Throws `Error` (preflight) when:\n *\n *   - `id` is missing or has invalid characters\n *   - `contributes` is missing entirely\n *   - `contributes` has no contribution fields\n *   - `contributes` references a slot key not in the catalogue\n *\n * This is intentionally a small surface — full validation\n * (id collisions across modules, slot quota, settingsSchema parse, etc.)\n * happens later in the host app's `module-validator`. This helper\n * catches the obvious developer mistakes at the module's own boundary\n * so errors surface in the module's repo, not deep inside OpenPen.\n */\nexport function defineModule<TModule extends OpenPenModule>(\n  spec: TModule\n): TModule {\n  if (!isValidModuleId(spec.id)) {\n    throw new Error(\n      `[@openpen/module-api] Invalid module id: ${JSON.stringify(spec.id)}. ` +\n        `Module ids must use \\`@scope/name\\` format with lowercase ASCII alphanumeric + hyphen, ` +\n        `max 39 chars per segment (e.g. \\`@alice/my-plugin\\`).`\n    )\n  }\n\n  if (!spec.contributes || typeof spec.contributes !== 'object') {\n    throw new Error(\n      `[@openpen/module-api] Module \"${spec.id}\" must declare a non-empty 'contributes' object.`\n    )\n  }\n\n  const keys = Object.keys(spec.contributes)\n  if (keys.length === 0) {\n    throw new Error(\n      `[@openpen/module-api] Module \"${spec.id}\" must contribute to at least one slot. ` +\n        `Add at least one field to 'contributes' (e.g. 'tools', 'settingsTabs', 'shortcuts').`\n    )\n  }\n\n  for (const key of keys) {\n    if (!(key in CONTRIBUTION_KEY_TO_SLOT_ID)) {\n      throw new Error(\n        `[@openpen/module-api] Module \"${spec.id}\" contributes to unknown slot key '${key}'. ` +\n          `Known keys: ${Object.keys(CONTRIBUTION_KEY_TO_SLOT_ID).sort().join(', ')}.`\n      )\n    }\n  }\n\n  return spec\n}\n","import { getModuleContext } from './host/module-context-registry'\nimport type { ModuleSetupContext } from './types/module'\n\n/**\n * Returns the `ModuleSetupContext` that was constructed for `moduleId` by\n * the host runtime. Call this inside a Vue component's `<script setup>` (or\n * `setup()`) to access `ctx.getSettings`, `ctx.updateSettings`,\n * `ctx.onSettingsChange`, `ctx.notify`, and all other context methods from\n * within a component tree — without having to prop-drill or provide/inject\n * the context object manually.\n *\n * @throws If `moduleId` is not currently registered (module not yet loaded,\n * already rolled back, or the id string doesn't match `defineModule({ id })`).\n *\n * @example\n * ```ts\n * // MySettingsPanel.vue\n * import { useModuleContext } from '@openpen/module-api'\n * import { onMounted, onUnmounted, ref } from 'vue'\n * import { z } from 'zod'\n *\n * const MySchema = z.object({ color: z.string().default('#fff') })\n * type MySettings = z.infer<typeof MySchema>\n *\n * const ctx = useModuleContext('my-plugin')\n * const color = ref(ctx.getSettings<MySettings>().color)\n *\n * let unsubscribe: (() => void) | null = null\n * onMounted(() => {\n *   unsubscribe = ctx.onSettingsChange<MySettings>((s) => { color.value = s.color })\n * })\n * onUnmounted(() => unsubscribe?.())\n *\n * async function changeColor(next: string) {\n *   await ctx.updateSettings<MySettings>({ color: next })\n * }\n * ```\n */\nexport function useModuleContext(moduleId: string): ModuleSetupContext {\n  const ctx = getModuleContext(moduleId)\n  if (!ctx) {\n    throw new Error(\n      `[module-api] useModuleContext(\"${moduleId}\") was called but no module is currently registered under that id. ` +\n      `This usually means: (a) the moduleId string does not match the id passed to defineModule, or ` +\n      `(b) the composable was called before the module's setup() ran ` +\n      `(do not call useModuleContext at module top-level — call it inside a component's setup() or onMounted()).`\n    )\n  }\n  return ctx\n}\n","/**\n * Convert a scoped module id to a vue-i18n-safe namespace key.\n *\n * vue-i18n uses `.` as path separator, so a raw id like `@openpen/freehand`\n * would be misinterpreted as a three-level path `['@openpen', 'freehand']`.\n * Stripping `@` and replacing `/` with `.` produces `openpen.freehand`,\n * which resolves correctly as a two-level namespace.\n *\n * @example\n * sanitizeIdForI18n('@openpen/freehand') // 'openpen.freehand'\n * sanitizeIdForI18n('@alice/todo')       // 'alice.todo'\n */\nexport function sanitizeIdForI18n(moduleId: string): string {\n  return moduleId.replace(/^@/, '').replace(/\\//g, '.')\n}\n\n/**\n * Maps a BCP-47 locale tag (e.g. `'en'`, `'zh-TW'`) to a localised string.\n *\n * Modules use this to declare i18n display names without coupling\n * themselves to the host app's i18n framework. The OpenPen registry\n * resolves the value at render time based on the active locale.\n */\nexport type LocaleMap = Record<string, string>\n\n/**\n * Resolve a `string | LocaleMap` to a single string for a given locale.\n *\n * Resolution order (first match wins):\n *   1. Plain string → returned as-is\n *   2. Exact tag match (e.g. `'zh-TW'`)\n *   3. Language prefix match (e.g. `'zh'` for `'zh-Hans-CN'`)\n *   4. English fallback (`'en'`)\n *   5. First declared value in the map\n *   6. Empty string (only when the map is `{}`)\n */\nexport function resolveLabel(\n  input: string | LocaleMap,\n  locale: string\n): string {\n  if (typeof input === 'string') return input\n\n  if (input[locale] !== undefined) return input[locale]\n\n  const lang = locale.split('-')[0]\n  if (lang !== locale && input[lang] !== undefined) return input[lang]\n\n  if (input.en !== undefined) return input.en\n\n  const first = Object.values(input)[0]\n  return first ?? ''\n}\n","/**\n * Public Tool / Stroke / Point primitives shared by host code and\n * every module / plugin. Declared inside @openpen/module-api so\n * third parties don't need to import host internals to type their\n * `canvas.tools` contributions.\n */\n\nexport interface Point {\n  x: number\n  y: number\n}\n\n/** Solid color or linear gradient between two stops. */\nexport type StrokeColor =\n  | string\n  | { type: 'linear'; from: string; to: string }\n\n/**\n * Reduce a `StrokeColor` to a single CSS colour string.\n *\n * `CanvasRenderingContext2D.strokeStyle` accepts a single colour string but\n * not a structured gradient descriptor; custom `renderStroke` implementations\n * that don't draw the gradient natively need a representative fallback.\n * Returns the string as-is for solid colours, and the `from` stop for linear\n * gradients. Future gradient kinds can pick their own representative without\n * touching callers.\n */\nexport function resolveStrokeColor(color: StrokeColor): string {\n  return typeof color === 'string' ? color : color.from\n}\n\nexport interface StrokeStyle {\n  color: StrokeColor\n  lineWidth: number\n  lineCap: CanvasLineCap\n  lineJoin: CanvasLineJoin\n}\n\nexport interface Stroke {\n  id: string\n  /** Id of the tool that produced this stroke (matches a ToolContribution.id). */\n  tool: string\n  points: Point[]\n  style: StrokeStyle\n  /**\n   * Tool-specific extra state. Tools MAY store arbitrary keys here during\n   * `onPointerDown` / `onPointerMove` / `onPointerUp`; those keys survive\n   * into `renderStroke(stroke, canvasCtx)` calls so the renderer can read\n   * them back.\n   *\n   * The host treats extra keys as `unknown` — type-cast at the read site is\n   * the plugin author's responsibility (TypeScript cannot infer the shape).\n   *\n   * @example\n   * // Store during onPointerUp:\n   * const stroke: Stroke = { id, tool: 'my-tool', points, style, opacity: 0.5 }\n   *\n   * // Read back in renderStroke:\n   * const opacity = (stroke.opacity as number) ?? 1\n   * canvasCtx.globalAlpha = opacity\n   */\n  [key: string]: unknown\n}\n\nexport interface PointerModifiers {\n  shiftKey?: boolean\n}\n\nexport interface Tool {\n  onPointerDown(\n    canvasCtx: CanvasRenderingContext2D,\n    point: Point,\n    style: StrokeStyle\n  ): void\n  /**\n   * Returns `true` when the engine should perform a full redraw\n   * (e.g. stroke-eraser removed an existing stroke). Otherwise `void`.\n   */\n  onPointerMove(\n    canvasCtx: CanvasRenderingContext2D,\n    point: Point,\n    modifiers?: PointerModifiers\n  ): void | boolean\n  /**\n   * Returns the finished `Stroke` to push into the store, or `null`\n   * to discard (e.g. an eraser that doesn't accumulate state).\n   */\n  onPointerUp(\n    canvasCtx: CanvasRenderingContext2D,\n    point: Point,\n    modifiers?: PointerModifiers\n  ): Stroke | null\n  /** When true, canvas-engine clears + redraws all strokes before each move. */\n  needsPreviewRedraw?: boolean\n  renderPreview?(canvasCtx: CanvasRenderingContext2D): void\n}\n","/**\n * Cursor compilation + sanitisation helpers shared by host runtime and\n * plugin SDK.\n *\n * Three closure layers gate every cursor entry before it reaches\n * `v-html`: R1–R12 shape validation here, DOMPurify content sanitisation\n * inside compileCursor, and a deep-clone + freeze in the contribution\n * store. Removing any one of them re-opens an attack surface the others\n * cannot close.\n */\n\nimport DOMPurify from 'dompurify'\nimport type {\n  CursorContribution,\n  CursorSpec,\n  Hotspot,\n  PngCursorSpec,\n  SvgCursorSpec,\n} from './types/contributions'\n\nexport interface CompiledCursor {\n  /** Sanitised SVG / HTML fragment to mount as `innerHTML` on the cursor element. */\n  svgMarkup: string\n  /** Hotspot offset, in CSS pixels relative to the markup's top-left. */\n  hotspot: Hotspot\n  /** CSS keyword fallback retained for legacy callers. */\n  fallbackCssKeyword: string\n}\n\nexport interface CursorResolutionContext {\n  /**\n   * Hostname-encoded plugin id (`@acme/x` → `acme.x`) used to assemble\n   * `openpen-plugin://<hostname>/<path>` URLs for relative-path specs.\n   * Undefined for built-in modules — path-form specs without a hostname\n   * resolve to `null` (host falls back to its default cursor).\n   */\n  pluginHostname?: string\n  /** Injection point for tests; defaults to global `fetch`. */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * W3C CSS UI Level 3 cursor keywords. The legacy `cursor: string` form\n * MUST match one of these (case-insensitive after trim); everything else\n * is rejected by R2 / R12.\n */\nexport const SAFE_CURSOR_KEYWORDS: ReadonlySet<string> = new Set([\n  'auto', 'default', 'none',\n  'context-menu', 'help', 'pointer', 'progress', 'wait',\n  'cell', 'crosshair', 'text', 'vertical-text',\n  'alias', 'copy', 'move', 'no-drop', 'not-allowed', 'grab', 'grabbing',\n  'e-resize', 'n-resize', 'ne-resize', 'nw-resize',\n  's-resize', 'se-resize', 'sw-resize', 'w-resize',\n  'ew-resize', 'ns-resize', 'nesw-resize', 'nwse-resize',\n  'col-resize', 'row-resize', 'all-scroll',\n  'zoom-in', 'zoom-out',\n])\n\nconst FORBIDDEN_CSS_LOAD_PATTERN = /url\\s*\\(|image-set\\s*\\(|-webkit-image-set\\s*\\(/i\n\nconst DEFAULT_FALLBACK_KEYWORD = 'crosshair'\n\nexport function isSafeRelativePath(p: unknown): p is string {\n  if (typeof p !== 'string' || p.length === 0) return false\n  // Bare `:` catches scheme prefixes without `://` (e.g. `data:`).\n  if (p.includes(':')) return false\n  if (p.startsWith('/')) return false\n  for (const seg of p.split('/')) {\n    if (seg === '' || seg === '..') return false\n  }\n  return true\n}\n\nexport function pluginHostname(moduleId: string): string {\n  return moduleId.replace(/^@/, '').replace(/\\//g, '.')\n}\n\nexport function pluginAssetUrl(moduleId: string, relativePath: string): string {\n  if (!isSafeRelativePath(relativePath)) {\n    throw new Error(`Unsafe asset path: ${relativePath}`)\n  }\n  return `openpen-plugin://${pluginHostname(moduleId)}/${relativePath}`\n}\n\n/**\n * Sanitise SVG markup before it reaches `v-html`. Rationale for each\n * flag: `USE_PROFILES: { svg: true }` covers script tags, on* handlers,\n * and javascript: hrefs; `FORBID_TAGS: ['foreignObject']` closes the\n * mXSS escape hatch the SVG profile alone does not; turning off\n * `ALLOW_UNKNOWN_PROTOCOLS` blocks `<use href=\"data:...\">` and friends.\n */\nexport function sanitizeSvgMarkup(raw: string): string {\n  return DOMPurify.sanitize(raw, {\n    USE_PROFILES: { svg: true },\n    FORBID_TAGS: ['foreignObject'],\n    // Cursor SVGs use presentation attributes (fill/stroke/etc.), never\n    // inline `style`. Forbidding it strips legacy `expression()` CSS\n    // smuggling vectors (S7) without touching anything we draw.\n    FORBID_ATTR: ['style'],\n    ALLOW_UNKNOWN_PROTOCOLS: false,\n  })\n}\n\nfunction resolveHotspot(spec: SvgCursorSpec | PngCursorSpec): Hotspot {\n  const h = spec.hotspot\n  if (!h || typeof h !== 'object') return { x: 0, y: 0 }\n  const x = typeof h.x === 'number' && Number.isFinite(h.x) ? h.x : 0\n  const y = typeof h.y === 'number' && Number.isFinite(h.y) ? h.y : 0\n  return { x, y }\n}\n\nfunction resolveFallback(spec: SvgCursorSpec | PngCursorSpec): string {\n  return typeof spec.fallback === 'string' && spec.fallback.length > 0\n    ? spec.fallback\n    : DEFAULT_FALLBACK_KEYWORD\n}\n\nfunction escapeHtmlAttr(s: string): string {\n  return s\n    .replace(/&/g, '&amp;')\n    .replace(/\"/g, '&quot;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n}\n\n/**\n * Convert a frozen, shape-validated CursorContribution.cursor into render\n * data ready for `v-html`. Returns `null` for legacy keyword strings\n * (caller falls back to the host default cursor) and for any spec the\n * sanitiser empties out completely.\n *\n * Async because path-form SVG specs are fetched through `openpen-plugin://`\n * at compile time; inline + PNG branches resolve synchronously inside the\n * returned Promise.\n */\nexport async function compileCursor(\n  spec: CursorSpec,\n  context: CursorResolutionContext = {},\n): Promise<CompiledCursor | null> {\n  if (typeof spec === 'string') return null\n  if (!spec || typeof spec !== 'object') return null\n\n  if ('svg' in spec && typeof spec.svg === 'string') {\n    const hotspot = resolveHotspot(spec)\n    const fallbackCssKeyword = resolveFallback(spec)\n    const trimmed = spec.svg.trim()\n\n    if (trimmed.startsWith('<')) {\n      const sanitised = sanitizeSvgMarkup(trimmed)\n      if (!sanitised) return null\n      return { svgMarkup: sanitised, hotspot, fallbackCssKeyword }\n    }\n\n    if (!context.pluginHostname || !isSafeRelativePath(trimmed)) return null\n    const url = `openpen-plugin://${context.pluginHostname}/${trimmed}`\n    const fetchImpl = context.fetchImpl\n      ?? (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : undefined)\n    if (!fetchImpl) return null\n\n    try {\n      const resp = await fetchImpl(url)\n      if (!resp.ok) return null\n      const raw = await resp.text()\n      const sanitised = sanitizeSvgMarkup(raw)\n      if (!sanitised) return null\n      return { svgMarkup: sanitised, hotspot, fallbackCssKeyword }\n    } catch {\n      return null\n    }\n  }\n\n  if ('png' in spec && typeof spec.png === 'string') {\n    const hotspot = resolveHotspot(spec)\n    const fallbackCssKeyword = resolveFallback(spec)\n    const trimmed = spec.png.trim()\n    if (!context.pluginHostname || !isSafeRelativePath(trimmed)) return null\n    const url = escapeHtmlAttr(`openpen-plugin://${context.pluginHostname}/${trimmed}`)\n    const svgMarkup =\n      `<img src=\"${url}\" alt=\"\" style=\"display:block;max-width:64px;max-height:64px;\" />`\n    return { svgMarkup, hotspot, fallbackCssKeyword }\n  }\n\n  return null\n}\n\nexport type CursorSanitizeRule =\n  | 'R1' | 'R2' | 'R3' | 'R4' | 'R5' | 'R6'\n  | 'R7' | 'R8' | 'R9' | 'R10' | 'R11' | 'R12'\n\nexport interface CursorSanitizeDiagnostic {\n  /** Contribution id, or `'<unknown>'` if `id` was missing / invalid. */\n  id: string\n  rule: CursorSanitizeRule\n  reason: string\n}\n\nexport interface CursorSanitizeOptions {\n  /**\n   * Built-in modules (host bundle) cannot use path forms because they\n   * have no `openpen-plugin://<hostname>` namespace. R7 / R10 reject\n   * such contributions for built-ins.\n   */\n  isBuiltin?: boolean\n}\n\nexport interface CursorSanitizeResult {\n  cleaned: CursorContribution[]\n  diagnostics: CursorSanitizeDiagnostic[]\n}\n\n/**\n * Shape-validate raw cursor contributions before they reach the\n * contribution-store. This is the R1–R12 gate; SVG markup content is\n * sanitised later inside {@link compileCursor} via DOMPurify.\n */\nexport function sanitizeCursorContributions(\n  cursors: unknown,\n  options: CursorSanitizeOptions = {},\n): CursorSanitizeResult {\n  const cleaned: CursorContribution[] = []\n  const diagnostics: CursorSanitizeDiagnostic[] = []\n\n  if (!Array.isArray(cursors)) return { cleaned, diagnostics }\n\n  for (const raw of cursors) {\n    if (raw === null || typeof raw !== 'object') {\n      diagnostics.push({ id: '<unknown>', rule: 'R1', reason: 'contribution is not an object' })\n      continue\n    }\n\n    const entry = raw as { id?: unknown; cursor?: unknown }\n    const id = typeof entry.id === 'string' && entry.id.length > 0 ? entry.id : '<unknown>'\n\n    if (id === '<unknown>') {\n      diagnostics.push({ id, rule: 'R1', reason: 'missing or empty `id`' })\n      continue\n    }\n\n    const { cursor } = entry\n\n    if (typeof cursor === 'string') {\n      const trimmedLower = cursor.trim().toLowerCase()\n      if (FORBIDDEN_CSS_LOAD_PATTERN.test(trimmedLower)) {\n        diagnostics.push({\n          id,\n          rule: 'R12',\n          reason: 'string contains url() / image-set() / -webkit-image-set(); loads external resource',\n        })\n        continue\n      }\n      if (!SAFE_CURSOR_KEYWORDS.has(trimmedLower)) {\n        diagnostics.push({\n          id,\n          rule: 'R2',\n          reason: `string '${trimmedLower}' is not in the safe CSS cursor keyword whitelist`,\n        })\n        continue\n      }\n      cleaned.push({ id, cursor: trimmedLower })\n      continue\n    }\n\n    if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor)) {\n      diagnostics.push({ id, rule: 'R1', reason: 'cursor field is neither string nor plain object' })\n      continue\n    }\n\n    const cursorObj = cursor as Record<string, unknown>\n    const hasSvg = Object.prototype.hasOwnProperty.call(cursorObj, 'svg')\n    const hasPng = Object.prototype.hasOwnProperty.call(cursorObj, 'png')\n\n    if (!hasSvg && !hasPng) {\n      diagnostics.push({ id, rule: 'R3', reason: 'cursor object has neither `svg` nor `png` key' })\n      continue\n    }\n    if (hasSvg && hasPng) {\n      diagnostics.push({ id, rule: 'R4', reason: 'cursor object has both `svg` and `png` keys (ambiguous)' })\n      continue\n    }\n\n    if (hasSvg) {\n      const svg = cursorObj.svg\n      if (typeof svg !== 'string') {\n        diagnostics.push({ id, rule: 'R5', reason: '`svg` value is not a string' })\n        continue\n      }\n      const trimmed = svg.trim()\n      const isInline = trimmed.startsWith('<')\n      if (!isInline) {\n        if (!isSafeRelativePath(trimmed)) {\n          diagnostics.push({\n            id,\n            rule: 'R6',\n            reason: '`svg` value is non-inline and not a safe relative path',\n          })\n          continue\n        }\n        if (options.isBuiltin) {\n          diagnostics.push({\n            id,\n            rule: 'R7',\n            reason: 'built-in modules cannot use path-form `svg` (no openpen-plugin hostname)',\n          })\n          continue\n        }\n      }\n    }\n\n    if (hasPng) {\n      const png = cursorObj.png\n      if (typeof png !== 'string') {\n        diagnostics.push({ id, rule: 'R8', reason: '`png` value is not a string' })\n        continue\n      }\n      if (!isSafeRelativePath(png.trim())) {\n        diagnostics.push({\n          id,\n          rule: 'R9',\n          reason: '`png` value is not a safe relative path',\n        })\n        continue\n      }\n      if (options.isBuiltin) {\n        diagnostics.push({\n          id,\n          rule: 'R10',\n          reason: 'built-in modules cannot use `png` (no openpen-plugin hostname)',\n        })\n        continue\n      }\n    }\n\n    if (cursorObj.hotspot !== undefined) {\n      const h = cursorObj.hotspot as Record<string, unknown> | null\n      const valid =\n        h !== null &&\n        typeof h === 'object' &&\n        typeof h.x === 'number' && Number.isFinite(h.x) && h.x >= 0 &&\n        typeof h.y === 'number' && Number.isFinite(h.y) && h.y >= 0\n      if (!valid) {\n        diagnostics.push({\n          id,\n          rule: 'R11',\n          reason: '`hotspot` must be `{ x: number ≥ 0, y: number ≥ 0 }`',\n        })\n        continue\n      }\n    }\n\n    // Output a strictly-allowlisted clone — only known primitive fields\n    // pass through. Anything else (function / symbol / getter / circular\n    // reference attached as an extra key) is dropped here so the\n    // downstream `structuredClone` in the contribution-store cannot\n    // throw and trigger a module-wide rollback.\n    const cleanedCursor: SvgCursorSpec | PngCursorSpec = hasSvg\n      ? { svg: (cursorObj.svg as string).trim() }\n      : { png: (cursorObj.png as string).trim() }\n    if (cursorObj.hotspot !== undefined) {\n      const h = cursorObj.hotspot as { x: number; y: number }\n      cleanedCursor.hotspot = { x: h.x, y: h.y }\n    }\n    if (typeof cursorObj.fallback === 'string') {\n      cleanedCursor.fallback = cursorObj.fallback\n    }\n    cleaned.push({ id, cursor: cleanedCursor })\n  }\n\n  return { cleaned, diagnostics }\n}\n"],"names":["h","s"],"mappings":"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"}

package/{src/inject-keys.ts → dist/inject-keys.d.ts}

@@ -5,11 +5,8 @@
  * 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 ─────────────────────────────────────────────────────────────
-
+import type { InjectionKey, Ref } from 'vue';
+import type { StrokeColor } from './types/tool';
 /**
  * Provides read + write access to the global stroke style state.
  * Provided by App.vue (root); available in all renderer windows.
@@ -17,17 +14,12 @@ import type { StrokeColor } from './types/tool'
  * 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
+    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 ────────────────────────────────────────────────────────────────
-
+export declare const STROKE_STYLE_CONTEXT_KEY: InjectionKey<StrokeStyleContext>;
 /**
  * Which side of the screen workArea the floating ball is anchored to.
  *
@@ -45,22 +37,13 @@ export const STROKE_STYLE_CONTEXT_KEY: InjectionKey<StrokeStyleContext> =
  * 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 ──────────────────────────────────────────────────────────
-
+export type SnapEdge = 'left' | 'right' | 'top' | 'bottom' | null;
+export declare const SNAP_EDGE_KEY: InjectionKey<Readonly<Ref<SnapEdge>>>;
 /**
  * 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 ─────────────────────────────────────────────────────────────
-
+export declare const IS_VERTICAL_KEY: InjectionKey<Readonly<Ref<boolean>>>;
 /**
  * Programmatic open / close for modals registered via `ui.modals` slot.
  * Provided by ModalStack.vue.
@@ -69,35 +52,24 @@ export const IS_VERTICAL_KEY: InjectionKey<Readonly<Ref<boolean>>> =
  * 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
+    /** 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 ───────────────────────────────────────────────
-
+export declare const MODAL_MANAGER_KEY: InjectionKey<ModalManager>;
 /**
  * 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')
-
+export declare const WRAPPER_EL_KEY: InjectionKey<Readonly<Ref<HTMLElement | null>>>;
 /**
  * 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 ──────────────────────────────────────────────────────
-
+export declare const ANCHOR_EL_KEY: InjectionKey<Readonly<Ref<HTMLElement | null>>>;
 /**
  * Reactive flag that is `true` while the ControlBar is running a scaleY
  * animation (expand 350ms / collapse 250ms / snap 250ms).
@@ -106,21 +78,26 @@ export const ANCHOR_EL_KEY: InjectionKey<Readonly<Ref<HTMLElement | null>>> =
  * 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 ─────────────────────────────────────────────────────
-
+export declare const CONTROL_BAR_ANIMATING_KEY: InjectionKey<Readonly<Ref<boolean>>>;
+/**
+ * `true` when the control bar's ball is sitting close to the workArea top
+ * edge, in horizontal mode. Buttons that render a tooltip above themselves
+ * (`bottom: calc(100% + 8px)`) would extend off-screen in that state, so they
+ * flip below the button instead.
+ *
+ * Provided by ControlBar.vue. Consumed by AppButton (and any other UIKit
+ * wrapper that renders an `::after` tooltip).
+ *
+ * `false` in vertical mode regardless of position — vertical bars use a
+ * sideways tooltip direction (see `SNAP_EDGE_KEY`).
+ */
+export declare const TOOLTIP_FLIP_DOWN_KEY: InjectionKey<Readonly<Ref<boolean>>>;
 /**
  * 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 ────────────────────────────────────────────────────
-
+export declare const HOST_DIALOG_OPEN_COUNT_KEY: InjectionKey<Ref<number>>;
 /**
  * Deliberate UX rule for initial popover placement direction.
  *
@@ -137,18 +114,12 @@ export const HOST_DIALOG_OPEN_COUNT_KEY: InjectionKey<Ref<number>> =
  * 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')
-
-// ── Active Tool ───────────────────────────────────────────────────────────────
-
+export type PopoverPlacementHint = 'top' | 'bottom' | 'left' | 'right';
+export declare const POPOVER_PLACEMENT_HINT_KEY: InjectionKey<Readonly<Ref<PopoverPlacementHint>>>;
 /**
  * The currently active tool id. Provided by ControlBar.vue as `readonly(activeToolId)`.
  * Module tool-button components inject this for reactive active-state without
  * depending on the event-bus timing (event bus is fire-and-forget; this ref is
  * always current regardless of when the component mounts).
  */
-export const ACTIVE_TOOL_KEY: InjectionKey<Readonly<Ref<string>>> =
-  Symbol('openpen:activeTool')
+export declare const ACTIVE_TOOL_KEY: InjectionKey<Readonly<Ref<string>>>;

package/{src/locale.ts → dist/locale.d.ts}

@@ -10,10 +10,7 @@
  * sanitizeIdForI18n('@openpen/freehand') // 'openpen.freehand'
  * sanitizeIdForI18n('@alice/todo')       // 'alice.todo'
  */
-export function sanitizeIdForI18n(moduleId: string): string {
-  return moduleId.replace(/^@/, '').replace(/\//g, '.')
-}
-
+export declare function sanitizeIdForI18n(moduleId: string): string;
 /**
  * Maps a BCP-47 locale tag (e.g. `'en'`, `'zh-TW'`) to a localised string.
  *
@@ -21,8 +18,7 @@ export function sanitizeIdForI18n(moduleId: string): string {
  * 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>
-
+export type LocaleMap = Record<string, string>;
 /**
  * Resolve a `string | LocaleMap` to a single string for a given locale.
  *
@@ -34,19 +30,4 @@ export type LocaleMap = Record<string, string>
  *   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 ?? ''
-}
+export declare function resolveLabel(input: string | LocaleMap, locale: string): string;