docs(plugins): add a rich-editor recipe and list frame theme variables in the skill (#37306)

recipes.md gains "A rich editor with a library" beside the hooks and status
bar recipes: an isolated-frame custom editor that vendors its library behind
an import map, syncs through orca.document.session with a merge by id, and
tests that sync with mockEditorHost. host-api.md lists every --orca-* frame
variable and what it paints, generated from the frame token allowlist.
This commit is contained in:
Neil
2026-11-01 21:30:37 -08:00
committed by GitHub
parent fa7c3f95fe
commit 591f2acbc8
6 changed files with 184 additions and 25 deletions
@@ -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 `<html>`. 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',
+10 -10
View File
@@ -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/<file>.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` |
@@ -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<T>)`: 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 `<html>`. 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.
@@ -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 '<json>'` 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 <dir> --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,
`<script type="importmap">{ "imports": { "lib": "./vendor/lib.js" } }</script>` (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<Scene>({
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 <dir> --json`
then reads every file the entry loads without running it, and
`ORCA plugin open <plugin-key> --editor <file>` shows it on a real file.
+76 -11
View File
@@ -2686,16 +2686,16 @@ const ORCA_PLUGIN_AUTHORING_MARKDOWN = [
"Run `ORCA skills get orca-plugin-authoring --reference references/<file>.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<T>)`: 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 `<html>`. 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 '<json>'` 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 <dir> --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,",
"`<script type=\"importmap\">{ \"imports\": { \"lib\": \"./vendor/lib.js\" } }</script>` (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<Scene>({",
" 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 <dir> --json`",
"then reads every file the entry loads without running it, and",
"`ORCA plugin open <plugin-key> --editor <file>` shows it on a real file.",
"",
].join('\n')
// oxfmt-ignore
@@ -122,6 +122,22 @@ function omittedValue(token: PluginAppThemeToken): string {
return light === dark ? light : `light: ${light}; dark: ${dark}`
}
const APP_THEME_TOKENS: ReadonlySet<string> = 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<string, string> = {
'--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`