@openpen/module-api 1.0.0 → 1.1.0

package/README.md

@@ -21,8 +21,11 @@ npm install @openpen/module-api zod
 import { defineModule, z } from '@openpen/module-api'
 
 export default defineModule({
-  id: 'my-module',
-  name: { en: 'My Module', 'zh-TW': '我的模組' },
+  id: '@scope/my-module',
+  version: '0.1.0',
+  metadata: {
+    name: { en: 'My Module', 'zh-Hant': '我的模組' },
+  },
   settingsSchema: z.object({
     enabled: z.boolean().default(true),
   }),
@@ -44,9 +47,13 @@ export default defineModule({
 | Method | Description |
 |--------|-------------|
 | `ctx.getSettings<T>()` | Read this module's parsed settings (requires `settingsSchema` to be declared) |
+| `ctx.updateSettings(patch)` | Persist a partial update to this module's settings |
+| `ctx.onSettingsChange<T>(cb)` | Subscribe to settings changes; returns an unsubscribe function |
 | `ctx.callMain(action, payload?)` | Call this module's main-side handler |
 | `ctx.onDispose(fn)` | Register a cleanup callback (called in reverse order when the module is unloaded) |
 | `ctx.notify(payload)` | Show a short-lived toast in the overlay window; returns `NotifyHandle` for early `dismiss()` |
+| `ctx.t(key, params?)` | Resolve an i18n key against this module's `contributes.locales` for the current host locale |
+| `ctx.locale` | The host's current locale (e.g. `'en'`, `'zh-Hant'`) |
 
 ```typescript
 import { defineModule } from '@openpen/module-api'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpen/module-api",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "OpenPen Module API — public contract for built-in modules and third-party plugins",
   "author": "navishachiku <navishachiku@gmail.com>",
   "homepage": "https://github.com/openpen-platform/openpen#readme",
@@ -42,9 +42,15 @@
     "node": ">=20",
     "npm": ">=9"
   },
-  "keywords": ["openpen", "plugin", "module", "sdk"],
+  "keywords": [
+    "openpen",
+    "plugin",
+    "module",
+    "sdk"
+  ],
   "dependencies": {
-    "reka-ui": "~2.9.6"
+    "dompurify": "^3.4.5",
+    "reka-ui": "~2.9.7"
   },
   "peerDependencies": {
     "vue": "^3.5.0",

package/packages/module-api/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [1.1.0](https://github.com/openpen-platform/openpen/compare/v1.0.0...v1.1.0) (2026-05-19)
+
+
+### Features
+
+* **cursors:** DOM overlay cursor system + plugin SDK doc gaps ([2f77192](https://github.com/openpen-platform/openpen/commit/2f771927fb94586b0ceef58e07fcb5220ed40c02))
+
+
+### Bug Fixes
+
+* **control-bar:** pause auto-collapse timer while any dialog is open ([#1](https://github.com/openpen-platform/openpen/issues/1)) ([add84ff](https://github.com/openpen-platform/openpen/commit/add84ff89f1ad5135c7371fd7d4bfd64b1ef2395))
+
+## 1.0.0 (2026-05-14)
+
+
+### Features
+
+* initial open source release ([f58abd7](https://github.com/openpen-platform/openpen/commit/f58abd7c4f3e12be9c88cdad23c61c82f9db7a7f))
+
+
+### Bug Fixes
+
+* **settings:** persist single Color Mode change to disk ([db9e6dd](https://github.com/openpen-platform/openpen/commit/db9e6dda0b9e584f349fb31da4349bdfaec0a84a))
+
+## Changelog

package/src/cursors.ts

@@ -0,0 +1,369 @@
+/**
+ * Cursor compilation + sanitisation helpers shared by host runtime and
+ * plugin SDK.
+ *
+ * Three closure layers gate every cursor entry before it reaches
+ * `v-html`: R1–R12 shape validation here, DOMPurify content sanitisation
+ * inside compileCursor, and a deep-clone + freeze in the contribution
+ * store. Removing any one of them re-opens an attack surface the others
+ * cannot close.
+ */
+
+import DOMPurify from 'dompurify'
+import type {
+  CursorContribution,
+  CursorSpec,
+  Hotspot,
+  PngCursorSpec,
+  SvgCursorSpec,
+} from './types/contributions'
+
+export interface CompiledCursor {
+  /** Sanitised SVG / HTML fragment to mount as `innerHTML` on the cursor element. */
+  svgMarkup: string
+  /** Hotspot offset, in CSS pixels relative to the markup's top-left. */
+  hotspot: Hotspot
+  /** CSS keyword fallback retained for legacy callers. */
+  fallbackCssKeyword: string
+}
+
+export interface CursorResolutionContext {
+  /**
+   * Hostname-encoded plugin id (`@acme/x` → `acme.x`) used to assemble
+   * `openpen-plugin://<hostname>/<path>` URLs for relative-path specs.
+   * Undefined for built-in modules — path-form specs without a hostname
+   * resolve to `null` (host falls back to its default cursor).
+   */
+  pluginHostname?: string
+  /** Injection point for tests; defaults to global `fetch`. */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * W3C CSS UI Level 3 cursor keywords. The legacy `cursor: string` form
+ * MUST match one of these (case-insensitive after trim); everything else
+ * is rejected by R2 / R12.
+ */
+export const SAFE_CURSOR_KEYWORDS: ReadonlySet<string> = 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'
+
+export function isSafeRelativePath(p: unknown): p is string {
+  if (typeof p !== 'string' || p.length === 0) return false
+  // Bare `:` catches scheme prefixes without `://` (e.g. `data:`).
+  if (p.includes(':')) return false
+  if (p.startsWith('/')) return false
+  for (const seg of p.split('/')) {
+    if (seg === '' || seg === '..') return false
+  }
+  return true
+}
+
+export function pluginHostname(moduleId: string): string {
+  return moduleId.replace(/^@/, '').replace(/\//g, '.')
+}
+
+export function pluginAssetUrl(moduleId: string, relativePath: string): string {
+  if (!isSafeRelativePath(relativePath)) {
+    throw new Error(`Unsafe asset path: ${relativePath}`)
+  }
+  return `openpen-plugin://${pluginHostname(moduleId)}/${relativePath}`
+}
+
+/**
+ * Sanitise SVG markup before it reaches `v-html`. Rationale for each
+ * flag: `USE_PROFILES: { svg: true }` covers script tags, on* handlers,
+ * and javascript: hrefs; `FORBID_TAGS: ['foreignObject']` closes the
+ * mXSS escape hatch the SVG profile alone does not; turning off
+ * `ALLOW_UNKNOWN_PROTOCOLS` blocks `<use href="data:...">` and friends.
+ */
+export function sanitizeSvgMarkup(raw: string): string {
+  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: SvgCursorSpec | PngCursorSpec): Hotspot {
+  const h = spec.hotspot
+  if (!h || typeof h !== 'object') return { x: 0, y: 0 }
+  const x = typeof h.x === 'number' && Number.isFinite(h.x) ? h.x : 0
+  const y = typeof h.y === 'number' && Number.isFinite(h.y) ? h.y : 0
+  return { x, y }
+}
+
+function resolveFallback(spec: SvgCursorSpec | PngCursorSpec): string {
+  return typeof spec.fallback === 'string' && spec.fallback.length > 0
+    ? spec.fallback
+    : DEFAULT_FALLBACK_KEYWORD
+}
+
+function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/**
+ * Convert a frozen, shape-validated CursorContribution.cursor into render
+ * data ready for `v-html`. Returns `null` for legacy keyword strings
+ * (caller falls back to the host default cursor) and for any spec the
+ * sanitiser empties out completely.
+ *
+ * Async because path-form SVG specs are fetched through `openpen-plugin://`
+ * at compile time; inline + PNG branches resolve synchronously inside the
+ * returned Promise.
+ */
+export async function compileCursor(
+  spec: CursorSpec,
+  context: CursorResolutionContext = {},
+): Promise<CompiledCursor | null> {
+  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) : undefined)
+    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
+}
+
+export type CursorSanitizeRule =
+  | 'R1' | 'R2' | 'R3' | 'R4' | 'R5' | 'R6'
+  | 'R7' | 'R8' | 'R9' | 'R10' | 'R11' | 'R12'
+
+export interface CursorSanitizeDiagnostic {
+  /** Contribution id, or `'<unknown>'` if `id` was missing / invalid. */
+  id: string
+  rule: CursorSanitizeRule
+  reason: string
+}
+
+export interface CursorSanitizeOptions {
+  /**
+   * Built-in modules (host bundle) cannot use path forms because they
+   * have no `openpen-plugin://<hostname>` namespace. R7 / R10 reject
+   * such contributions for built-ins.
+   */
+  isBuiltin?: boolean
+}
+
+export interface CursorSanitizeResult {
+  cleaned: CursorContribution[]
+  diagnostics: CursorSanitizeDiagnostic[]
+}
+
+/**
+ * Shape-validate raw cursor contributions before they reach the
+ * contribution-store. This is the R1–R12 gate; SVG markup content is
+ * sanitised later inside {@link compileCursor} via DOMPurify.
+ */
+export function sanitizeCursorContributions(
+  cursors: unknown,
+  options: CursorSanitizeOptions = {},
+): CursorSanitizeResult {
+  const cleaned: CursorContribution[] = []
+  const diagnostics: CursorSanitizeDiagnostic[] = []
+
+  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 as { id?: unknown; cursor?: unknown }
+    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 as Record<string, unknown>
+    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 !== undefined) {
+      const h = cursorObj.hotspot as Record<string, unknown> | null
+      const valid =
+        h !== null &&
+        typeof h === 'object' &&
+        typeof h.x === 'number' && Number.isFinite(h.x) && h.x >= 0 &&
+        typeof h.y === 'number' && Number.isFinite(h.y) && h.y >= 0
+      if (!valid) {
+        diagnostics.push({
+          id,
+          rule: 'R11',
+          reason: '`hotspot` must be `{ x: number ≥ 0, y: number ≥ 0 }`',
+        })
+        continue
+      }
+    }
+
+    // Output a strictly-allowlisted clone — only known primitive fields
+    // pass through. Anything else (function / symbol / getter / circular
+    // reference attached as an extra key) is dropped here so the
+    // downstream `structuredClone` in the contribution-store cannot
+    // throw and trigger a module-wide rollback.
+    const cleanedCursor: SvgCursorSpec | PngCursorSpec = hasSvg
+      ? { svg: (cursorObj.svg as string).trim() }
+      : { png: (cursorObj.png as string).trim() }
+    if (cursorObj.hotspot !== undefined) {
+      const h = cursorObj.hotspot as { x: number; y: number }
+      cleanedCursor.hotspot = { x: h.x, y: h.y }
+    }
+    if (typeof cursorObj.fallback === 'string') {
+      cleanedCursor.fallback = cursorObj.fallback
+    }
+    cleaned.push({ id, cursor: cleanedCursor })
+  }
+
+  return { cleaned, diagnostics }
+}

package/src/index.ts

@@ -63,6 +63,10 @@ export type {
   SettingsTabContribution,
   SettingsPanelContribution,
   CursorContribution,
+  CursorSpec,
+  SvgCursorSpec,
+  PngCursorSpec,
+  Hotspot,
   StatusContribution,
   ModalContribution,
   TrayMenuContribution,
@@ -89,9 +93,30 @@ export {
   CONTROL_BAR_ANIMATING_KEY,
   HOST_DIALOG_OPEN_COUNT_KEY,
   POPOVER_PLACEMENT_HINT_KEY,
+  ACTIVE_TOOL_KEY,
 } from './inject-keys'
 export type { StrokeStyleContext, SnapEdge, ModalManager, PopoverPlacementHint } from './inject-keys'
 
+// Cursor compilation + sanitisation (used by host runtime; helpers
+// re-exported so plugins can validate cursor specs in their own tests).
+export {
+  compileCursor,
+  sanitizeSvgMarkup,
+  sanitizeCursorContributions,
+  isSafeRelativePath,
+  pluginHostname,
+  pluginAssetUrl,
+  SAFE_CURSOR_KEYWORDS,
+} from './cursors'
+export type {
+  CompiledCursor,
+  CursorResolutionContext,
+  CursorSanitizeRule,
+  CursorSanitizeDiagnostic,
+  CursorSanitizeOptions,
+  CursorSanitizeResult,
+} from './cursors'
+
 // Re-export zod so modules don't need a separate import path.
 export { z } from 'zod'
 

package/src/inject-keys.ts

@@ -141,3 +141,14 @@ export type PopoverPlacementHint = 'top' | 'bottom' | 'left' | 'right'
 
 export const POPOVER_PLACEMENT_HINT_KEY: InjectionKey<Readonly<Ref<PopoverPlacementHint>>> =
   Symbol('openpen:popoverPlacementHint')
+
+// ── Active Tool ───────────────────────────────────────────────────────────────
+
+/**
+ * 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')

package/src/types/contributions.ts

@@ -161,10 +161,45 @@ export interface SettingsPanelContribution {
   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
-  /** CSS cursor value or a data URL. */
-  cursor: string
+  cursor: CursorSpec
 }
 
 export interface StatusContribution {

package/src/uikit/components/AppSegmented.vue

@@ -21,6 +21,7 @@ interface Option {
   value: string
   label: string
   icon?: string
+  testid?: string
 }
 
 defineProps<{
@@ -60,6 +61,7 @@ function onValueChange(val: unknown) {
       <button
         class="app-seg-btn"
         :class="{ active: modelValue === opt.value }"
+        :data-testid="opt.testid"
       >
         <span
           v-if="opt.icon"

package/src/uikit/components/DialogHost.vue

@@ -18,7 +18,7 @@
  * falls back gracefully (no mutual exclusion, no animating-guard) — it still
  * renders and resolves correctly, just without those host integrations.
  */
-import { computed, nextTick, provide, ref, watch } from 'vue'
+import { computed, inject, nextTick, provide, ref, watch } from 'vue'
 import AppDialog from './AppDialog.vue'
 // _activeRequest MUST come from the package barrel — see AppPopover.vue header
 // comment. The runtime build externalises '@openpen/module-api/uikit' so host
@@ -27,11 +27,17 @@ import AppDialog from './AppDialog.vue'
 // callers to write to a different ref than DialogHost watches (dialog never
 // opens in production).
 import { _activeRequest, _resolveActive } from '@openpen/module-api/uikit'
+import { HOST_DIALOG_OPEN_COUNT_KEY } from '@openpen/module-api'
 import { DIALOG_PLUGIN_HANDLE_KEY } from '../composables/dialog-internal-keys'
 import type { DialogPluginComponentHandle } from '../composables/useDialogPluginComponent'
 
 const MODAL_ID = '__openpen_imperative_dialog__'
 
+// Increment/decrement the host-level dialog-open counter so ControlBar can
+// pause the auto-collapse timer while any imperative dialog is visible.
+// Falls back to a local ref when not provided (settings window has no host bar).
+const dialogOpenCount = inject(HOST_DIALOG_OPEN_COUNT_KEY, ref(0))
+
 // Whether the dialog is open: true when there is an active request.
 const isOpen = ref(false)
 
@@ -47,6 +53,9 @@ watch(_activeRequest, (req) => {
     if (req.kind === 'prompt') {
       promptValue.value = req.opts.defaultValue ?? ''
     }
+    if (!isOpen.value) {
+      dialogOpenCount.value++
+    }
     isOpen.value = true
     if (req.kind === 'prompt') {
       nextTick(() => {
@@ -54,6 +63,9 @@ watch(_activeRequest, (req) => {
       })
     }
   } else {
+    if (isOpen.value) {
+      dialogOpenCount.value = Math.max(0, dialogOpenCount.value - 1)
+    }
     isOpen.value = false
   }
 })