diff --git a/config/scripts/generate-plugin-authoring-skill-references.mjs b/config/scripts/generate-plugin-authoring-skill-references.mjs index 73a31bfd89d..83da46bf089 100644 --- a/config/scripts/generate-plugin-authoring-skill-references.mjs +++ b/config/scripts/generate-plugin-authoring-skill-references.mjs @@ -43,7 +43,8 @@ function loadSources() { schema: 'src/shared/plugins/manifest/plugin-json-schema.ts', fieldDocs: 'src/shared/plugins/manifest/plugin-schema-field-docs.ts', cli: 'src/cli/specs/plugin.ts', - cliView: 'src/cli/specs/plugin-view.ts' + cliView: 'src/cli/specs/plugin-view.ts', + themeTokens: 'src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts' }) } @@ -248,6 +249,18 @@ function renderHostApi(sources, { frame, worker }) { .map((m) => bullet({ ...m, text: `document.${m.text}` })), '' ], + [ + '## Theme variables in frames', + '', + "HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on ``. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.", + '', + ...sources.themeTokens.pluginFrameThemeVariables().map(({ variable, paints }) => { + // Name the frame's own variables, not the app theme tokens behind them. + const role = paints.replace(/`--([\w-]+)`/g, '`--orca-$1`') + return `- ${code(variable)}${role ? `: ${role}` : ''}` + }), + '' + ], ['## Methods', '', ...methods, ''], [ '## Hooks', diff --git a/skill-guides/orca-plugin-authoring.md b/skill-guides/orca-plugin-authoring.md index 7ed3313cd8e..65a246aa89c 100644 --- a/skill-guides/orca-plugin-authoring.md +++ b/skill-guides/orca-plugin-authoring.md @@ -121,13 +121,13 @@ fingerprint Orca did not give you. New capabilities or changed commands print a Run `ORCA skills get orca-plugin-authoring --reference references/.md` and read only what you need (`--references` lists them; `--full` if `--reference` is rejected). -| Read when | Reference | -| -------------------------------------------------------------------- | -------------------------- | -| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` | -| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` | -| A worker panel, storage, settings; agent status; events; hooks | `references/recipes.md` | -| Writing a components panel: components, props, atoms, `host` | `references/components.md` | -| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` | -| Subscribing to worker, frame or panel events and their payloads | `references/events.md` | -| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` | -| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` | +| Read when | Reference | +| ------------------------------------------------------------------------------------ | -------------------------- | +| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` | +| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` | +| A worker panel, storage, settings; agent status; events; hooks; a rich custom editor | `references/recipes.md` | +| Writing a components panel: components, props, atoms, `host` | `references/components.md` | +| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` | +| Subscribing to worker, frame or panel events and their payloads | `references/events.md` | +| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` | +| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` | diff --git a/skill-guides/orca-plugin-authoring/references/host-api.md b/skill-guides/orca-plugin-authoring/references/host-api.md index 42a784ab023..102ae5aba18 100644 --- a/skill-guides/orca-plugin-authoring/references/host-api.md +++ b/skill-guides/orca-plugin-authoring/references/host-api.md @@ -42,6 +42,31 @@ Host API 1.2 (`"pluginApi": 1`). Call `host.call(method, params, { signal })`; a - `document.applyEdit(edit: EditorEdit)`: Rejects with `conflict`, `too_large` or `not_permitted` (read-only). - `document.session(options?: EditorSessionOptions)`: Document sync in one call; resolves once theme, locale and the first document are in. +## Theme variables in frames + +HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on ``. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours. + +- `--orca-background`: App canvas +- `--orca-foreground`: Body text +- `--orca-card`: Cards and panels +- `--orca-card-foreground`: Text on `--orca-card` +- `--orca-popover`: Menus, popovers and dialogs +- `--orca-popover-foreground`: Text on `--orca-popover` +- `--orca-primary`: Primary buttons +- `--orca-primary-foreground`: Text on `--orca-primary` +- `--orca-secondary`: Secondary buttons +- `--orca-secondary-foreground`: Text on `--orca-secondary` +- `--orca-muted`: Quiet fills +- `--orca-muted-foreground`: Secondary text +- `--orca-accent`: Hover and selected fills +- `--orca-accent-foreground`: Text on `--orca-accent` +- `--orca-destructive` +- `--orca-destructive-foreground` +- `--orca-border`: Borders and separators +- `--orca-input`: Input borders +- `--orca-ring`: Focus rings +- `--orca-radius`: Corner radius of cards and controls + ## Methods - `workspace.readContext` (capability `workspace:read`; worker, panel, editor; since 1.0): Branch, name and terminal ids of the focused workspace, or null when none is focused. diff --git a/skill-guides/orca-plugin-authoring/references/recipes.md b/skill-guides/orca-plugin-authoring/references/recipes.md index 2ff75c4b35b..d875bd6f664 100644 --- a/skill-guides/orca-plugin-authoring/references/recipes.md +++ b/skill-guides/orca-plugin-authoring/references/recipes.md @@ -1,4 +1,4 @@ -# Plugin recipes: panels, workers and data +# Plugin recipes: panels, workers, editors and data Hand-written companion to the `orca-plugin-authoring` guide. @@ -98,3 +98,43 @@ let the action through, so count blocks after deciding (`void orca.host.call(... `(await mountWorker(worker)).hooks.fire('terminal.send', event)`, which returns `{ kind: 'continue', event }` or `{ kind: 'deny', reason }`; against the loaded dev plugin, `ORCA plugin dev hook . terminal.send --data ''` prints the same decision. + +## A rich editor with a library + +A `sandboxed-ui` custom editor around a canvas or diagram library; start from +`ORCA plugin create --template editor`. Set `"frame": "isolated"` on the editor +(`engines.orca` `>=1.4.248`) so browser clients open the file in Source instead of a fallback. +There is no bundler or network: copy the library's ESM build into the plugin and map it, +`` (16 MiB a script, +1 MiB a `.ts` file; no `eval`). Style from the `--orca-*` variables in `references/host-api.md` +and redo it on `orca.on('theme', ...)`. Orca keeps no undo for editors: the library's own undo +gets Cmd/Ctrl+Z. + +```ts +// editor/sync.ts: the only code that talks to Orca; merge by id, never by array position. +export const start = () => + orca.document.session({ + decode: (content) => (content.kind === 'text' ? JSON.parse(content.text) : { elements: [] }), + encode: (scene) => ({ kind: 'text', text: JSON.stringify(scene) }), + merge: (base, outside, mine) => mergeById(base, outside, mine) + }) +// editor/main.ts: `const doc = await start()`, then library.load(doc.value), +// library.onChange((scene) => doc.change(scene)), doc.onReplace((scene) => library.load(scene)). + +// editor/sync.test.ts, run by `ORCA plugin test`: +import { assert, mockEditorHost, test } from 'orca/testing' +test('merges an agent write that lands while an edit waits', async () => { + const host = mockEditorHost({ text: '{"elements":[]}' }) + const doc = await (await import('./sync.ts')).start() + doc.change({ elements: [{ id: 'b' }] }) + host.replace('{"elements":[{"id":"a"}]}') // the agent writes first + await host.flush() // as a save: conflict, merge, resend + assert.deepEqual(JSON.parse(host.text ?? '').elements, [{ id: 'a' }, { id: 'b' }]) + doc.dispose() + host.dispose() +}) +``` + +Without `merge` an outside write wins and the draft is dropped. `ORCA plugin check --json` +then reads every file the entry loads without running it, and +`ORCA plugin open --editor ` shows it on a real file. diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index 7300f7b5848..13574f0d495 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -2686,16 +2686,16 @@ const ORCA_PLUGIN_AUTHORING_MARKDOWN = [ "Run `ORCA skills get orca-plugin-authoring --reference references/.md` and read only what you", "need (`--references` lists them; `--full` if `--reference` is rejected).", "", - "| Read when | Reference |", - "| -------------------------------------------------------------------- | -------------------------- |", - "| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |", - "| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |", - "| A worker panel, storage, settings; agent status; events; hooks | `references/recipes.md` |", - "| Writing a components panel: components, props, atoms, `host` | `references/components.md` |", - "| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |", - "| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |", - "| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |", - "| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |", + "| Read when | Reference |", + "| ------------------------------------------------------------------------------------ | -------------------------- |", + "| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |", + "| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |", + "| A worker panel, storage, settings; agent status; events; hooks; a rich custom editor | `references/recipes.md` |", + "| Writing a components panel: components, props, atoms, `host` | `references/components.md` |", + "| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |", + "| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |", + "| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |", + "| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |", "", ].join('\n') @@ -2921,6 +2921,31 @@ const ORCA_PLUGIN_AUTHORING_HOST_API_REFERENCE_MARKDOWN = [ "- `document.applyEdit(edit: EditorEdit)`: Rejects with `conflict`, `too_large` or `not_permitted` (read-only).", "- `document.session(options?: EditorSessionOptions)`: Document sync in one call; resolves once theme, locale and the first document are in.", "", + "## Theme variables in frames", + "", + "HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on ``. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.", + "", + "- `--orca-background`: App canvas", + "- `--orca-foreground`: Body text", + "- `--orca-card`: Cards and panels", + "- `--orca-card-foreground`: Text on `--orca-card`", + "- `--orca-popover`: Menus, popovers and dialogs", + "- `--orca-popover-foreground`: Text on `--orca-popover`", + "- `--orca-primary`: Primary buttons", + "- `--orca-primary-foreground`: Text on `--orca-primary`", + "- `--orca-secondary`: Secondary buttons", + "- `--orca-secondary-foreground`: Text on `--orca-secondary`", + "- `--orca-muted`: Quiet fills", + "- `--orca-muted-foreground`: Secondary text", + "- `--orca-accent`: Hover and selected fills", + "- `--orca-accent-foreground`: Text on `--orca-accent`", + "- `--orca-destructive`", + "- `--orca-destructive-foreground`", + "- `--orca-border`: Borders and separators", + "- `--orca-input`: Input borders", + "- `--orca-ring`: Focus rings", + "- `--orca-radius`: Corner radius of cards and controls", + "", "## Methods", "", "- `workspace.readContext` (capability `workspace:read`; worker, panel, editor; since 1.0): Branch, name and terminal ids of the focused workspace, or null when none is focused.", @@ -3211,7 +3236,7 @@ const ORCA_PLUGIN_AUTHORING_MANIFEST_REFERENCE_MARKDOWN = [ // oxfmt-ignore const ORCA_PLUGIN_AUTHORING_RECIPES_REFERENCE_MARKDOWN = [ - "# Plugin recipes: panels, workers and data", + "# Plugin recipes: panels, workers, editors and data", "", "Hand-written companion to the `orca-plugin-authoring` guide.", "", @@ -3312,6 +3337,46 @@ const ORCA_PLUGIN_AUTHORING_RECIPES_REFERENCE_MARKDOWN = [ "`{ kind: 'continue', event }` or `{ kind: 'deny', reason }`; against the loaded dev plugin,", "`ORCA plugin dev hook . terminal.send --data ''` prints the same decision.", "", + "## A rich editor with a library", + "", + "A `sandboxed-ui` custom editor around a canvas or diagram library; start from", + "`ORCA plugin create --template editor`. Set `\"frame\": \"isolated\"` on the editor", + "(`engines.orca` `>=1.4.248`) so browser clients open the file in Source instead of a fallback.", + "There is no bundler or network: copy the library's ESM build into the plugin and map it,", + "`` (16 MiB a script,", + "1 MiB a `.ts` file; no `eval`). Style from the `--orca-*` variables in `references/host-api.md`", + "and redo it on `orca.on('theme', ...)`. Orca keeps no undo for editors: the library's own undo", + "gets Cmd/Ctrl+Z.", + "", + "```ts", + "// editor/sync.ts: the only code that talks to Orca; merge by id, never by array position.", + "export const start = () =>", + " orca.document.session({", + " decode: (content) => (content.kind === 'text' ? JSON.parse(content.text) : { elements: [] }),", + " encode: (scene) => ({ kind: 'text', text: JSON.stringify(scene) }),", + " merge: (base, outside, mine) => mergeById(base, outside, mine)", + " })", + "// editor/main.ts: `const doc = await start()`, then library.load(doc.value),", + "// library.onChange((scene) => doc.change(scene)), doc.onReplace((scene) => library.load(scene)).", + "", + "// editor/sync.test.ts, run by `ORCA plugin test`:", + "import { assert, mockEditorHost, test } from 'orca/testing'", + "test('merges an agent write that lands while an edit waits', async () => {", + " const host = mockEditorHost({ text: '{\"elements\":[]}' })", + " const doc = await (await import('./sync.ts')).start()", + " doc.change({ elements: [{ id: 'b' }] })", + " host.replace('{\"elements\":[{\"id\":\"a\"}]}') // the agent writes first", + " await host.flush() // as a save: conflict, merge, resend", + " assert.deepEqual(JSON.parse(host.text ?? '').elements, [{ id: 'a' }, { id: 'b' }])", + " doc.dispose()", + " host.dispose()", + "})", + "```", + "", + "Without `merge` an outside write wins and the draft is dropped. `ORCA plugin check --json`", + "then reads every file the entry loads without running it, and", + "`ORCA plugin open --editor ` shows it on a real file.", + "", ].join('\n') // oxfmt-ignore diff --git a/src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts b/src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts index 89a182e1355..85fb724094b 100644 --- a/src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts +++ b/src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts @@ -122,6 +122,22 @@ function omittedValue(token: PluginAppThemeToken): string { return light === dark ? light : `light: ${light}; dark: ${dark}` } +const APP_THEME_TOKENS: ReadonlySet = new Set(PLUGIN_APP_THEME_TOKENS) +const isAppThemeToken = (token: string): token is PluginAppThemeToken => APP_THEME_TOKENS.has(token) +// Frame variables that are not colours of an app theme. +const FRAME_ONLY_ROLES: Record = { + '--radius': 'Corner radius of cards and controls' +} + +/** The `--orca-*` CSS variables panel and editor frames get, with what each paints. */ +export function pluginFrameThemeVariables(): { variable: string; token: string; paints: string }[] { + return PANEL_DESIGN_TOKEN_ALLOWLIST.map((token) => ({ + variable: `--orca-${token.slice(2)}`, + token, + paints: isAppThemeToken(token) ? TOKEN_ROLES[token] : (FRAME_ONLY_ROLES[token] ?? '') + })) +} + /** Colour token list for theme authors, rendered from the public token set. */ export function renderPluginThemeTokenReference(): string { const lines = [ @@ -144,8 +160,8 @@ export function renderPluginThemeTokenReference(): string { '', '| Variable | Orca token |', '| --- | --- |', - ...PANEL_DESIGN_TOKEN_ALLOWLIST.map( - (token) => `| \`--orca-${token.slice(2)}\` | \`${token}\` |` + ...pluginFrameThemeVariables().map( + ({ variable, token }) => `| \`${variable}\` | \`${token}\` |` ) ] return `${lines.join('\n')}\n`