konpeki 0.1.1 → 0.3.0

package/AGENTS.md

@@ -7,7 +7,7 @@ presents that same document.
 ## Choose the relevant guide
 
 - First-time setup: [SETUP.md](SETUP.md).
-- Creating or revising visuals: [authoring-visuals](.agents/skills/authoring-visuals/SKILL.md)
+- Opening the editor, creating or revising visuals: [Konpeki skill](skills/konpeki/SKILL.md)
   and [AUTHORING.md](AUTHORING.md), which owns design and factual-fidelity rules.
 - Changing the application: [development guidance](docs/development.md) and
   the [composition contract](composition/README.md).

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to Konpeki
+
+Thanks for helping improve Konpeki. Bug reports, focused fixes and additions that
+strengthen the shared human-agent canvas are welcome.
+
+## Before opening a change
+
+- Search existing issues before filing a new one.
+- Use an issue to discuss large features or changes to the composition contract
+  before investing in an implementation.
+- Do not include private compositions, credentials or proprietary source material
+  in issues, fixtures or screenshots.
+- Report security concerns through the process in [SECURITY.md](SECURITY.md), not
+  through a public issue.
+
+## Development
+
+Follow [docs/development.md](docs/development.md) to install the pinned Node.js and
+pnpm toolchain. Keep changes scoped and preserve existing composition compatibility
+unless a contract change has been agreed in advance.
+
+Before opening a pull request, run:
+
+```sh
+mise exec -- pnpm check
+mise exec -- pnpm test
+mise exec -- pnpm build
+mise exec -- pnpm check:package
+```
+
+UI changes also require visual inspection using the relevant browser checks in
+[docs/development.md](docs/development.md#verification). Include the affected
+states and verification performed in the pull request description.
+
+By submitting a contribution, you agree that it is licensed under the repository's
+[Apache-2.0 license](LICENSE).

package/README.md

@@ -1,53 +1,88 @@
-# Konpeki
+![Konpeki — Create clear visuals with your coding agent](slides/github-cover/cover.png)
 
-**An editable canvas for agent-made visuals. Create a single explanation or a
-whole presentation, then revise it together.**
+**Create clear visuals with your coding agent.** Konpeki is an opinionated design
+framework for covers, social graphics, visual explanations and presentations.
 
 Give your coding agent notes, source material and a brief. Konpeki provides the
-shared canvas, design guidance, typography and semantic components for social
-graphics, article headers, visual explanations and presentations.
+canvas, design guidance, typography and semantic components for the intended
+format and dimensions.
 
 People and agents edit the same composition. Export a page as PNG, download its
 editable JSON, or use **Present** for a chrome-free presentation.
 
-## Start in your coding agent
+## Use with your agent
 
 Requires **Node.js 24+**, npm, a coding agent that can edit files and run commands,
 and a browser.
 
-Give your coding agent the public setup URL and your brief. The guide covers
-installation; no repository clone or manual package installation is needed first:
+Install the [Konpeki skill](skills/konpeki/) with your agent's
+skill installer. Install the whole directory, including `scripts/` and `assets/`, not just
+`SKILL.md`. For example, ask a Codex skill installer:
 
 ```text
-Read https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md
-and set up Konpeki in this workspace.
-Turn these notes into a three-slide explanation for engineers. Make the request
-flow and failure handling easy to follow. Preserve facts and caveats. Save editable composition
-JSON, open the preview, then render, inspect and fix the result.
-
-[Paste notes or provide source files.]
+Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
 ```
 
+Then choose a mode, or just give it a brief:
+
+| Workflow | Codex CLI / IDE | Claude Code standalone skill |
+| --- | --- | --- |
+| Open a blank or existing editor; no generation | `$konpeki init` | `/konpeki init` |
+| Create, inspect and revise a visual | `$konpeki generate …` | `/konpeki generate …` |
+
+`init` accepts a composition JSON path and preserves existing work. `generate`
+uses the materials already in your conversation and prepares the runtime if
+needed; there is no required init step. Plugin installations may namespace the
+skill. Other hosts can select the skill or use natural language:
+
+> Use Konpeki to turn these launch notes into a product announcement.
+
+Or ask for an article cover, a social graphic, a chart, a diagram or a presentation.
+Natural-language creation requests select `generate` automatically.
+The skill reuses a compatible runtime or, with permission, installs the pinned
+npm release in a user cache. It creates editable JSON in your workspace, opens
+the preview and visually checks the result. You do not need to clone Konpeki,
+edit a package manifest, or repeat your prompt in a blank canvas.
+
+First-run installation, browser permissions and remote preview forwarding depend
+on your agent host. If skills are unavailable, give the agent the public
+[SETUP.md](https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md) URL and
+your brief together. The setup guide also covers the optional Codex plugin package.
+
 Ask for revisions in the same conversation. Add “Stop after the outline for
 approval” when you want a checkpoint. Supply a visual direction or leave it open;
 [authoring modes](AUTHORING.md#authoring-mode) provide defaults without requiring
 you to choose fonts, colors or layouts first.
 
-The package includes the authoring skill, design guidance and examples—no GitHub
-clone is required. Keep your documents outside `node_modules`.
+Canvas review notes use **Build it** and an active agent listener, or the
+button's copyable handoff to resume the agent. Opening the editor alone does not
+connect or wake an agent. The skill modes are not terminal CLI subcommands.
+
+## Try the editor in your browser
+
+[Open the editable Konpeki example](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
+
+The browser-only playground lets you edit an example or start blank, keep a local
+working copy, import/download editable JSON, export PNG and present. It requires
+no account or AI service. Browser-local data is not cloud backup; download JSON
+to keep or move your work. Continue with your coding agent using that file.
+
+The [GitHub Pages playground](docs/development.md#github-pages) does not connect
+to an agent or expose **Build it**. The agent-led workflow above is the route
+from a prompt to a finished visual.
 
-## Try an editable example
+## Manual npm start
 
 For a manual start, install [Konpeki from npm](https://www.npmjs.com/package/konpeki)
 in your workspace (run `npm init -y` first in a new, empty directory):
 
 ```sh
-npm install --save-dev konpeki@0.1.1
-cp node_modules/konpeki/slides/introducing-konpeki/composition.json introduction.json
+npm install --save-dev konpeki@latest
+curl -fL https://raw.githubusercontent.com/vcfgdev/konpeki/main/slides/introducing-konpeki/composition.json -o introduction.json
 npm exec --no -- konpeki preview introduction.json
 ```
 
-Open the exact URL printed by `preview`. Browser edits save to your copied file;
+Open the exact URL printed by `preview`. Browser edits save to your downloaded file;
 valid agent edits appear on the same canvas. In a remote environment, use its
 authenticated preview mechanism rather than sharing a local address.
 
@@ -60,6 +95,7 @@ authenticated preview mechanism rather than sharing a local address.
 - [Canvas workflow](docs/workflow.md): page sizes, export and agent handoff.
 - [Development](docs/development.md): architecture, demo hosting, packaging and checks.
 - [Composition contract](composition/README.md) and [design resources](design/README.md).
+- [Contributing](CONTRIBUTING.md) and [security policy](SECURITY.md).
 
 Konpeki requires no account or hosted AI service. Your coding agent's pricing
 and data handling still apply. Supply facts and approved assets; examples and

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security policy
+
+## Supported versions
+
+Konpeki is early-stage software. Security fixes are made against the latest npm
+release and the `main` branch; older releases are not maintained separately.
+
+## Reporting a vulnerability
+
+Do not disclose a suspected vulnerability in a public issue. Use GitHub's
+**Security → Report a vulnerability** flow to send the maintainers a private
+report. Include the affected version, reproduction steps, impact and any suggested
+mitigation. Please avoid accessing data that is not yours while investigating.
+
+The maintainers will acknowledge the report, assess its impact and coordinate a
+fix and disclosure. If private vulnerability reporting is unavailable, open an
+issue containing no sensitive details and ask the maintainers for a private
+reporting channel.
+
+Konpeki's file-backed preview uses a session URL as a local authorization secret.
+Do not publish that URL or its token, and expose remote previews only through an
+authenticated tunnel or workspace portal.

package/SETUP.md

@@ -1,79 +1,133 @@
 # Set up Konpeki for your coding agent
 
-Give your agent this document and your brief in the same conversation:
+Install the `konpeki` skill once, then give your agent a creation brief:
 
 ```text
-Read Konpeki's SETUP.md and set it up in this workspace.
-Use it to explain [source] to [audience], with the takeaway [idea].
-Create [one visual / a short presentation]. Open the editable preview,
-then render, inspect and fix the result.
+Use Konpeki to turn these launch notes into a product announcement.
 ```
 
-Konpeki is a shared visual canvas, not an AI service. The coding agent creates
-and revises composition files; the browser lets the person edit, review, present
-and export them. Keep the initial brief and revision conversation in the coding
-agent. An in-app browser is convenient but not required.
+Opening and inspecting the editable preview is part of the skill, not an extra
+instruction the person has to remember. Covers, social graphics, charts,
+diagrams and presentations use the same workflow. Keep the brief and revisions
+in agent chat; the browser edits, reviews, presents and exports the document.
+Konpeki supplies no hosted AI service or additional model subscription.
 
-## 1. Prepare the environment
+## 1. Install the skill or plugin
 
-- Check for Node.js 24+ (`node --version`), npm (`npm --version`), and a browser
-  the agent can use for visual inspection. Report missing prerequisites rather
-  than claiming setup succeeded. Follow the host's rules for installing tools.
-- Reuse an existing workspace when requested, or create a new directory. Do not
-  overwrite the user's files or replace their agent guidance.
-- Install the pinned release locally so the agent can find its resources and
-  reuse the same CLI version. Do not edit files inside `node_modules`.
+Use the host's skill installer to install the complete
+[`skills/konpeki`](skills/konpeki/) directory from
+`vcfgdev/konpeki`. Keep its `scripts/` and `assets/` directories. In Codex, ask the skill installer:
+
+```text
+Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
+```
+
+Other agents may use another installer or skill location. Follow their documented
+mechanism; there is no universal slash command. If a host does not discover skills,
+read the installed `SKILL.md` directly. Do not overwrite existing agent guidance.
+
+If you previously installed `authoring-visuals`, replace that installed skill
+with `konpeki` rather than keeping both copies. The runtime package is unchanged.
+
+### Choose init or generate
+
+| Mode | Codex CLI / IDE | Claude Code standalone skill |
+| --- | --- | --- |
+| Open the editor without generating | `$konpeki init [composition.json]` | `/konpeki init [composition.json]` |
+| Create or revise from your materials | `$konpeki generate [brief]` | `/konpeki generate [brief]` |
+
+`generate` automatically prepares the runtime when needed. It uses materials
+already supplied in chat, referenced files and the current canvas; it does not
+require `init` first or a repeated brief. Natural-language “Use Konpeki to…”
+creation requests also select generate. Follow-up feedback continues the same
+document without another command. Other GUIs may use skill selection, and plugin
+installations may namespace the skill. These modes are not terminal subcommands.
+
+For `init`, choose the supplied path or the document already active in the
+conversation; otherwise use `slides/untitled/composition.json`. After resolving
+the runtime below, run:
+
+```sh
+node "<installed-skill>/scripts/prepare-document.mjs" "<cli>" "<composition.json>"
+node "<cli>" preview "<composition.json>"
+```
+
+The helper validates existing files without rewriting them. For a missing file,
+it validates and writes the bundled blank document without overwriting a file
+created concurrently. Invalid data is preserved, not replaced with a sample.
+Reuse an already running preview for the same file. Open and verify its exact
+session URL as described below, then stop: init does not generate or start a
+review listener. The starter works with the pinned published runtime; it does
+not import TypeScript from `node_modules` or require an unreleased `init` CLI.
+
+### Optional Codex plugin packaging
+
+The root `plugin.json` packages that same skill, without MCP servers, hooks or
+credentials. `.agents/plugins/marketplace.json` exposes it as a repo marketplace.
+On a compatible Codex client, add the repository marketplace with:
 
 ```sh
-npm install --save-dev konpeki@0.1.1
+codex plugin marketplace add vcfgdev/konpeki
 ```
 
-In a new empty directory, run `npm init -y` first. Run subsequent commands from
-the workspace where Konpeki was installed. Its resources are under
-`node_modules/konpeki/`: `AGENTS.md`, `AUTHORING.md`, `composition/`, `design/`,
-and `.agents/skills/authoring-visuals/SKILL.md`. If the package/version cannot be
-resolved, report the installation issue rather than substituting another package.
-Copying the skill alone does not install the runtime.
+Then install Konpeki from that source in the desktop plugin directory and test it
+in a new conversation. Install either the standalone skill or the plugin, not
+both. This is repository distribution, not a listing in OpenAI's public directory.
+It becomes available from the remote repository after these files are published.
+Native Codex GUI installation needs a separate client smoke test; package checks
+alone do not establish host compatibility.
 
-For repository development instead, clone `https://github.com/vcfgdev/konpeki.git`
-with the required access and follow the [mise setup](docs/development.md).
-Use `mise exec -- pnpm konpeki` in place of `npm exec --no -- konpeki` below.
-Mise is for contributors to this repository; npm package users do not need it.
+## 2. Let the skill prepare the runtime
+
+Check Node.js 24+, npm, command/file access and the host's browser capabilities.
+Follow host approval and toolchain rules if prerequisites are missing.
+
+From the user's document workspace, run:
+
+```sh
+node "<installed-skill>/scripts/ensure-runtime.mjs"
+```
 
-## 2. Read the authoring instructions
+The script reuses a compatible workspace installation, surrounding Konpeki
+checkout, or cached runtime. If none exists, obtain any required host approval
+and rerun with `--install`. It installs the pinned `konpeki@0.3.0` release in a
+user cache, without adding project dependencies or changing project guidance.
+Missing/incompatible runtimes are never reported ready. The script prints JSON
+with `root`, `cli` and `version`; installation diagnostics go to stderr.
 
-Read [AGENTS.md](AGENTS.md), then use the
-[authoring-visuals skill](.agents/skills/authoring-visuals/SKILL.md). If the agent
-does not discover project skills, read that file directly. It links to the design
-policy and composition contract; no special slash command is required.
+Use the returned absolute `root` for resources and `cli` for commands. Do not rely
+on repo-relative paths from a copied skill. Keep documents outside the runtime.
+For manual project-local npm installation, see [Manual npm start](README.md#manual-npm-start).
+Repository contributors instead use the [mise setup](docs/development.md); users
+of the published package do not need mise.
 
-Use the brief already supplied. Ask only for missing information that prevents
-a faithful result. Do not ask the person to re-enter their intent in the canvas.
-Create a new document without overwriting an example or existing work. By default,
-save it as `slides/<name>/composition.json` with its brief and source notes beside
-it. If the user specifies another destination, pass that file's absolute path to
-the CLI.
+## 3. Generate, validate and open the visual
 
-## 3. Validate and open the result
+Follow the installed skill and the runtime's `AUTHORING.md`, composition contract
+and design resources. Use the brief already supplied; ask only for information
+needed for faithful work. Do not ask the person to repeat their prompt in the
+canvas. Continue the current document when revising or following init. Save new
+work to an unused `slides/<name>/composition.json`, with brief/source notes,
+unless the person chooses another destination. Preserve existing documents.
 
-For an installation check, validate the bundled introduction:
+For an installation check, validate the bundled example:
 
 ```sh
-npm exec --no -- konpeki validate node_modules/konpeki/slides/introducing-konpeki/composition.json
+node "<cli>" validate "<root>/slides/introducing-konpeki/composition.json"
 ```
 
 After authoring the user's document:
 
 ```sh
-npm exec --no -- konpeki validate slides/<name>/composition.json
-npm exec --no -- konpeki preview slides/<name>/composition.json
+node "<cli>" validate "slides/<name>/composition.json"
+node "<cli>" preview "slides/<name>/composition.json"
 ```
 
-Keep the preview process running using the host's supported service mechanism.
-Open the exact printed session URL; do not drop its query string or expose its
-token in public logs. For remote workspaces, use the host's authenticated preview
-or port-forwarding mechanism, preserving the session query. Do not present a
-remote machine's loopback address as a user-accessible link.
+Reuse an existing preview for that file when available. Keep the process running
+using the host's supported service mechanism. Open the exact printed session URL
+in the in-app browser when supported, otherwise the regular browser. Preserve its
+query string and never publish its capability token. In remote workspaces, use
+authenticated preview/port forwarding, not a remote loopback address.
 
 Verify that the browser loads the intended document, then render, inspect and
 repair the result as directed by the skill. The file-backed canvas saves browser
@@ -82,5 +136,12 @@ validation succeeds and the intended composition opens—not merely when a serve
 process starts. If browser inspection is unavailable, report that limitation.
 
 Return the document path, usable preview link and verification outcome. Continue
-revisions in agent chat. The optional **Build it** / `wait` handoff is described in
-[Canvas workflow](docs/workflow.md); the button cannot wake an agent by itself.
+revisions in agent chat. For submitted canvas reviews, generate checks `request`,
+claims a `submitted` request with `wait`, applies the notes against the latest
+document, and acknowledges it with `finish` only after validation and inspection.
+Coordinate ownership before resuming an already `working` request.
+
+An ongoing listener runs only when explicitly requested and supported by the host.
+Otherwise, use **Copy prompt** after **Build it**, or resume generate in agent chat.
+The [canvas workflow](docs/workflow.md) describes this handoff; the button cannot
+wake an idle agent, and an open preview is not a live agent connection.

package/composition/README.md

@@ -1,6 +1,6 @@
 # Composition contract
 
-`konpeki-composition/v18` describes one or more bounded visual pages
+`konpeki-composition/v1` describes one or more bounded visual pages
 shared by a person and coding agent. It is a visual intent contract, while the
 Konpeki canvas is its editor and presentation preview. Component rectangles are
 preferences; factual fidelity and readable
@@ -9,67 +9,44 @@ default is `none`; rules/dividers are separate appearance parameters. Editor
 guides never enter the contract. The contract is tool-agnostic: no Konpeki
 package, repository checkout, or separate authoring kit is required.
 
-Schema identifiers are immutable compatibility boundaries. New fields or
-vocabularies that an older reader could reject require a new identifier. Konpeki
-migrates compatible v1–v4 single-slide documents to a one-slide deck on import
-or load. V1 and v2 obsolete
-authoring-kit targets are removed; v3 callouts and comparisons become configured
-Text blocks without changing component IDs, geometry, slots, relationships or
-orders. V5 Evidence becomes Visual; Process and System map become a typed
-Diagram; and the Page-number component becomes a slide setting. V7 makes the
-Headline optional while retaining its singleton and reading-order constraints
-when present. V8 adds standalone Image, Icon and Shape primitives, Pie visuals,
-Text-block logical order and empty slides; v7 Image visuals migrate to Image
-components. V9 adds a first-class Table primitive with content-derived dimensions,
-header placement, grid treatment, density and color scheme. V10 adds optional
-slide-coordinate preferred rectangles to explicit diagram nodes so circular,
-branched and asymmetric topology can preserve authored geometry. V11 merges
-Headline and Footnote into Text-block roles, renames Visual to Chart, moves Icon
-and Shape into Diagram nodes, and renames Diagram `template` to `layout`. Schema
-v12 replaces Diagram's coarse process/system and layout pair with 32 semantic
-grammars adapted from the MIT-licensed Diagram Design taxonomy. The previous six
-layouts become derived implementation engines; all v11 combinations migrate
-deterministically. Diagram owns structural grammars while Chart owns the six
-scale-based historical grammars (bar, line, radar, treemap, scatter and Sankey).
-Pie and Annotated detail are additional Konpeki Chart grammars. V13 lets any of
-the same five semantic components own an optional self-contained SVG interior.
-V14 adds a structured vector interior: lines, shapes, paths and text have stable
-IDs, editable attributes and parent relationships. Legacy SVG remains an opaque
-compatibility fallback. The composition is authoritative for both outer geometry
-and editable vector internals. V15 adds explicit theme bindings to vector styles;
-v14 documents migrate with their literal styles unchanged. Current exports are
-always v18. Consumers must reject unknown future versions rather than interpreting them as v18. The JSON
-Schema `$id` and deterministic compiler version are versioned with this contract.
+Schema identifiers are immutable compatibility boundaries. This is the first
+public contract, so current exports use v1 and unknown versions are rejected.
+The JSON Schema `$id` and deterministic compiler version are versioned with this
+contract.
 
-V18 adds Diagram and Chart `appearance.selection`: `auto` delegates form selection
-to the agent; `explicit` makes the diagram type or chart template binding. Omission
-means explicit, never permission to switch. New canvas diagrams and charts use auto.
-Older documents migrate to explicit because their selection provenance is unknown.
-Type/template, artwork and geometry remain
-unchanged. The agent must ask before changing an explicit form or component kind,
-and may not silently reset it to auto. This is a handoff requirement, not a runtime
-permission barrier against arbitrary external file edits.
-The form picker remains available for finished vectors and legacy SVG as well as
+The contract has five semantic component kinds: Text block, Diagram, Chart,
+Image and Table. Any component can own optional self-contained SVG or structured
+vector artwork. Structured lines, shapes, paths and text have stable IDs,
+editable attributes and parent relationships. Opaque SVG remains a supported
+fallback. The composition is authoritative for both outer geometry and editable
+vector internals.
+
+Diagram and Chart `appearance.selection` controls form choice: `auto` delegates
+selection to the agent; `explicit` makes the diagram type or chart template
+binding. Omission means explicit, never permission to switch. New canvas diagrams
+and charts use auto. The agent must ask before changing an explicit form or
+component kind, and may not silently reset it to auto. This is a handoff
+requirement, not a runtime permission barrier against arbitrary external file edits.
+The form picker remains available for finished vectors and opaque SVG as well as
 drafts. Changing the requirement preserves existing artwork; it does not redraw it.
 Sankey topology cannot be discarded by selecting another template, even in Auto.
 
-V17 makes each page's `canvas.width` and `canvas.height` integers from 256 to 4096.
+Each page's `canvas.width` and `canvas.height` are integers from 256 to 4096.
 `innerPadding` is nonnegative and must leave a content area. Component rectangles
 must fit their owning page. `intendedViewingSize` accepts `presentation`, `social`,
-`article` or `custom`. Existing v16 decks migrate without geometry or content changes.
+`article` or `custom`.
 The JSON key `slides` remains the ordered page collection for compatibility; it
 does not restrict the document to presentations. Resizing does not transform content.
 
-V16 gives ordinary Text blocks plain `content` and optional `textStyle`: size
+Ordinary Text blocks have plain `content` and optional `textStyle`: size
 (8–240 slide pixels), weight (400/500/600), lineHeight (1–3), color
 (ink/muted/accent), and font (heading/body). Newlines are preserved and lines wrap
 inside the component. Missing content is empty; new manually added blocks start
 with editable “Text”. `intent` is separate agent guidance and never supplies live
-displayed copy. Legacy non-vector blocks copy their formerly displayed intent to
-content once on import; legacy custom visuals remain untouched. Custom visuals,
-when present, still own rendering. Ordinary text should not use custom visuals.
-Layout/purpose metadata from older drafts remains agent guidance rather than fake
-placeholder lines. Use separate Text blocks when independently positioned copy is needed.
+displayed copy. Custom visuals, when present, still own rendering. Ordinary text
+should not use custom visuals. Layout and purpose metadata remains agent guidance
+rather than displayed copy. Use separate Text blocks when independently positioned
+copy is needed.
 
 ### Theme-linked vector styles
 
@@ -77,9 +54,22 @@ placeholder lines. Use separate Text blocks when independently positioned copy i
 `theme:background`, `theme:surface`, `theme:divider`, `theme:accent`,
 `theme:on-accent`, and `theme:wash`. `font-family` accepts `theme:heading-font`
 and `theme:body-font`. These resolve from the deck theme in every canvas view.
-Use on-accent for text over an accent fill. Heading fonts are IBM Plex Serif for
-Editorial, Noto Sans for Precision, and IBM Plex Sans otherwise; body fonts are
-Noto Sans for Precision and IBM Plex Sans otherwise.
+Use on-accent for text over an accent fill. `theme.typography` independently selects
+`plex-sans` (IBM Plex Sans throughout), `noto-sans` (Noto Sans throughout),
+`plex-serif` (IBM Plex Serif headings / IBM Plex Sans body), or `hanken-grotesk`
+(Hanken Grotesk throughout). `theme.id` still selects the color palette and
+`theme.mode` selects Paper or Night. For example:
+
+```json
+{ "id": "green", "mode": "paper", "typography": "noto-sans" }
+```
+
+Omitting typography preserves the legacy pairing: Precision uses Noto Sans;
+Editorial uses Plex Serif headings and Plex Sans body; other palettes use Plex
+Sans. When revising colors, retain the current typography explicitly so changing
+the palette does not change fonts. The editor does this automatically. Older
+runtimes that do not support `theme.typography` reject documents containing it;
+use a compatible runtime rather than removing the field and changing appearance.
 
 Literal values are fixed overrides. SVG conversion preserves literals; it never
 guesses roles from colors. Legacy raw SVG stays inert, fixed artwork. In the

package/composition/compile.ts

@@ -117,7 +117,7 @@ function compileSlidePlan(slide: CompositionSlide, index: number) {
     const custom = component.customVisual
       ? component.customVisual.format === "vector"
         ? ` Custom visual — ${component.customVisual.elements.length} editable vector elements in a ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; preserve element IDs and edit individual geometry or styling while this component ID and preferred rectangle own slide placement.`
-        : ` Custom visual — legacy self-contained SVG, ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; convert its source to editable vector elements when revising while this component ID and preferred rectangle own slide placement.`
+        : ` Custom visual — opaque self-contained SVG, ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; convert its source to editable vector elements when revising while this component ID and preferred rectangle own slide placement.`
       : "";
     return `- ${componentLabel(component)}, ${placement(component, slide)}: ${component.intent?.trim() || "Use its content-slot instructions."} Appearance — ${appearance(component)}.${grammar}${custom} Required slots — ${slotLabels}.`;
   });
@@ -213,7 +213,7 @@ Legacy Text-block purpose, treatment, layout and logical-order fields are guidan
 Text-block role controls typography and semantic placement: title, subtitle, body, caption or footnote. Use title for the main takeaway and footnote for sources, scope and caveats.
 Ordinary Text blocks store visible copy in content (plain text with newlines) and typography in textStyle (size in slide pixels, weight 400/500/600, lineHeight, ink/muted/accent color and heading/body font). Intent is separate agent guidance, never displayed copy. Revise content for manual and agent-authored text alike; do not replace ordinary text with customVisual. Custom vectors remain for genuinely custom artwork.
 When a Text block records a logical order other than none, express that relationship in its text and shape arrangement: parallel, progressive, cyclical, general-to-specific or hierarchical.
-Resolve authoring mode to ${document.authoringMode ?? "default"} and theme to ${document.theme?.id ?? "plex"} / ${document.theme?.mode ?? "paper"}. Theme and authoring mode are independent.
+Resolve authoring mode to ${document.authoringMode ?? "default"} and theme to ${document.theme?.id ?? "plex"} / ${document.theme?.mode ?? "paper"}. Theme and authoring mode are independent.${document.theme?.typography ? ` Use typography ${document.theme.typography} independently of the color palette. plex-sans uses IBM Plex Sans throughout; noto-sans uses Noto Sans throughout; plex-serif uses IBM Plex Serif headings with IBM Plex Sans body; hanken-grotesk uses Hanken Grotesk throughout. Preserve this choice when changing colors.` : ""}
 For editable vector interiors, bind fill/stroke/color to theme:ink, theme:muted, theme:background, theme:surface, theme:divider, theme:accent, theme:on-accent or theme:wash. Bind font-family to theme:heading-font or theme:body-font. Literal values remain fixed overrides; never infer theme roles from imported colors. Check text bounds after font changes; do not silently shrink or rearrange content.
 Preserve the supplied slide order and slide names. Do not hide overflow, shrink required content, merge slides, or silently add slides. Report an overfull brief and ask for a scope decision. When rendering is requested, inspect and repair every slide at presentation and review sizes. Deliver the updated composition JSON, any requested editable render source, verified output and limitations.