konpeki 0.2.0 → 0.3.1

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,42 +1,94 @@
-![Konpeki — A shared canvas for you and your agents](slides/github-cover/cover.png)
+![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 once, choosing your agent when prompted:
 
-```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.]
+```sh
+npx skills add vcfgdev/konpeki -g
 ```
 
-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`.
-
-## Try an editable example
+Start a new conversation or reload your agent's skills. **Send this to your agent:**
+
+> Use Konpeki to create a one-page explainer of how a browser, API and database work together.
+
+Replace the example with your own brief and materials. Your agent prepares the
+runtime, creates editable JSON in your workspace, opens the canvas and checks the
+result. No clone or separate `init` step. First use may require installation and
+browser permissions; remote workspaces need authenticated preview forwarding.
+
+Keep revisions in the same conversation. Canvas notes use **Build it** and its
+copyable handoff unless an agent listener is active; the button cannot wake an
+idle agent. See [setup details and optional commands](SETUP.md) for other install
+methods, or give that guide's [raw URL](https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md)
+to your agent with your brief.
+
+## 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.
+
+## Showcase
+
+Illustrative examples with editable text and vector artwork. Click a preview to
+view it full-size, or download its JSON and choose **Demo Mode → Import** in the
+[playground](https://vcfgdev.github.io/konpeki/).
+
+<table>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <a href="slides/gallery/architecture.png"><img src="slides/gallery/architecture.png" width="420" alt="Harbor Market order-platform architecture"></a><br>
+      <strong>Explain a system</strong><br>
+      Order handling, events and fulfillment<br>
+      <a href="slides/gallery/architecture.json">Editable JSON</a>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <a href="slides/gallery/sankey.png"><img src="slides/gallery/sankey.png" width="420" alt="Proportional Sankey showing a fictional 1,000-user trial cohort"></a><br>
+      <strong>Communicate data</strong><br>
+      Trial users, activation and outcomes<br>
+      <a href="slides/gallery/sankey.json">Editable JSON</a>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <a href="slides/gallery/release.png"><img src="slides/gallery/release.png" width="420" alt="Clearpath 0.4 portrait release announcement in orange"></a><br>
+      <strong>Announce a release</strong><br>
+      A portrait social graphic for Clearpath<br>
+      <a href="slides/gallery/release.json">Editable JSON</a>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <a href="slides/gallery/explainer.png"><img src="slides/gallery/explainer.png" width="420" alt="Folio one-page explainer showing accepted and rejected document saves"></a><br>
+      <strong>Teach a concept</strong><br>
+      One-page guide to preventing stale saves<br>
+      <a href="slides/gallery/explainer.json">Editable JSON</a>
+    </td>
+  </tr>
+</table>
+
+[Browse the gallery](slides/README.md) for briefs, sources and more examples.
+
+## 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):
@@ -53,13 +105,14 @@ authenticated preview mechanism rather than sharing a local address.
 
 ## Examples and guides
 
-- [Example gallery](slides/README.md): 18 fictional examples and an editable
-  Konpeki introduction. Retained React/SVG examples are drawing references;
-  new editable documents use composition JSON.
+- [Native example gallery](slides/README.md): editable diagrams, data graphics,
+  a social announcement and a one-page explainer, plus the product introduction
+  and repository cover. Older React/SVG drawing references remain separate.
 - [Agent-led setup](SETUP.md) and [authoring guidance](AUTHORING.md).
 - [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,149 @@
 # Set up Konpeki for your coding agent
 
-Give your agent this document and your brief in the same conversation:
+Requires **Node.js 24+**, npm, a coding agent with file and command access, and a browser.
+
+Install once, choosing your agent when prompted:
+
+```sh
+npx skills add vcfgdev/konpeki -g
+```
+
+Start a new conversation or reload your agent's skills. **Send this to your agent:**
+
+> Use Konpeki to create a one-page explainer of how a browser, API and database work together.
+
+Or use your own brief and materials. The agent prepares the runtime, creates the
+document, opens the canvas and checks the result; no separate `init` step is
+needed. Allow any required installation/browser permissions. Remote workspaces
+need authenticated preview forwarding. Keep revisions in the same conversation.
+
+## Other installers
+
+For an unattended install, select a single agent (Amp example):
+
+```sh
+npx skills add vcfgdev/konpeki -g -a amp -y
+```
+
+This avoids auto-selecting unrelated agent targets when no terminal prompt is available.
+
+You can also use your agent's native skill installer:
 
 ```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.
+Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
+```
+
+Install the complete [`skills/konpeki`](skills/konpeki/) directory, including
+`scripts/` and `assets/`. Follow the host's documented skill location; if it 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.
+
+## Optional commands
+
+| 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>"
 ```
 
-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.
+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.
 
-## 1. Prepare the environment
+### Optional Codex plugin packaging
 
-- 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`.
+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.
+## Agent setup reference
+
+The installed skill handles these steps; the person does not need to run them manually.
+
+### 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.1` 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.
+### 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 +152,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

@@ -54,9 +54,22 @@ copy is needed.
 `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

@@ -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.
 

package/composition/schema.json

@@ -2968,6 +2968,15 @@
             "night"
           ],
           "type": "string"
+        },
+        "typography": {
+          "enum": [
+            "plex-sans",
+            "noto-sans",
+            "plex-serif",
+            "hanken-grotesk"
+          ],
+          "type": "string"
         }
       },
       "required": [

package/composition/schema.ts

@@ -4,6 +4,7 @@ import {
   compositionSchema,
   themeIds,
   themeModes,
+  typographyIds,
   vectorElementKinds,
 } from "./types.ts";
 import { chartTemplates, diagramTypes } from "./visualizations.ts";
@@ -319,7 +320,8 @@ export const schema = {
       theme: object({
         id: enumeration(themeIds),
         mode: enumeration(themeModes),
-      }),
+        typography: enumeration(typographyIds),
+      }, ["id", "mode"]),
       slides: array(
         object(
           {

package/composition/types.ts

@@ -25,6 +25,8 @@ export const themeIds = [
 export type ThemeId = (typeof themeIds)[number];
 export const themeModes = ["paper", "night"] as const;
 export type ThemeMode = (typeof themeModes)[number];
+export const typographyIds = ["plex-sans", "noto-sans", "plex-serif", "hanken-grotesk"] as const;
+export type TypographyId = (typeof typographyIds)[number];
 export type Rect = { x: number; y: number; width: number; height: number };
 export type Alignment = "start" | "center" | "end";
 export type TitleStyle = "plain" | "prominent";
@@ -262,6 +264,6 @@ export type CompositionDocument = {
   schema: typeof compositionSchema;
   title: string;
   authoringMode?: AuthoringMode;
-  theme?: { id: ThemeId; mode: ThemeMode };
+  theme?: { id: ThemeId; mode: ThemeMode; typography?: TypographyId };
   slides: CompositionSlide[];
 };

package/design/themes/README.md

@@ -1,21 +1,39 @@
 # Themes
 
-Themes combine font roles and a referenced color palette, not a slide layout.
+Document appearance has independent **Typography**, **Color palette**, and
+**Background** controls. These do not choose a layout or change font sizes.
 
 Use [authoring guidance](../../AUTHORING.md#taste-and-creative-freedom) for theme
 selection, font defaults and deck-wide consistency.
 
 ```ts
 import { getTheme } from './design/themes/index.ts';
-const theme = getTheme('Plex', 'paper');
+const theme = getTheme('Green', 'paper', 'noto-sans');
 // theme.body, theme.headline, theme.typography, theme.palette
 ```
 
-Eight light/dark themes: Plex, Precision, Editorial, Blue–cyan, Orange–coral,
-Yellow, Green and Graphite. Precision uses Noto Sans; Editorial uses Plex Serif
-headlines with Plex Sans body; the others use Plex Sans. Font loading remains
-the author's responsibility; load the required Fontsource Latin weights before
-measuring or rendering text.
+Eight palettes retain their existing names: Plex, Precision, Editorial,
+Blue–cyan, Orange–coral, Yellow, Green and Graphite. Each supports Paper and Night.
+Choose any palette with any of these typography presets:
+
+| Typography ID | Headings | Body |
+| --- | --- | --- |
+| `plex-sans` | IBM Plex Sans | IBM Plex Sans |
+| `noto-sans` | Noto Sans | Noto Sans |
+| `plex-serif` | IBM Plex Serif | IBM Plex Sans |
+| `hanken-grotesk` | Hanken Grotesk | Hanken Grotesk |
+
+Composition JSON stores the optional choice in `theme.typography`, independently
+of `theme.id` (palette) and `theme.mode` (background). Omitted typography preserves
+legacy appearance: Precision uses Noto Sans, Editorial uses Plex Serif headings
+with Plex Sans body, and all other palettes use Plex Sans. Changing the palette
+in the editor records the current typography so colors no longer change fonts.
+Two-argument `getTheme` callers retain those legacy pairings too.
+
+Font loading remains the author's responsibility; load the required Fontsource
+Latin weights before measuring or rendering text. Theme-linked native text and
+vectors follow the selection; literal font/color overrides remain fixed.
+Different fonts can change wrapping or overflow, so inspect the result.
 
 Mineral and Botanical are light-only palette candidates in
 [palettes/candidates.ts](../palettes/candidates.ts).

package/design/themes/index.ts

@@ -1,13 +1,24 @@
 import { typography } from '../../lib/taste.ts';
 import { paletteNames, resolvePalette, type PaletteName, type PaletteMode } from '../palettes/index.ts';
+import type { TypographyId } from '../../composition/types.ts';
 
 export const themeNames = paletteNames;
 export type ThemeName = PaletteName;
 export type ThemeMode = PaletteMode;
+export const typographyLabels: Record<TypographyId, string> = {
+  'plex-sans': 'IBM Plex Sans',
+  'noto-sans': 'Noto Sans',
+  'plex-serif': 'Plex Serif + Plex Sans',
+  'hanken-grotesk': 'Hanken Grotesk',
+};
 
 // Themes combine typography with a palette; they do not choose a composition.
-export function getTheme(name: ThemeName, mode: ThemeMode) {
-  const body = name === 'Precision' ? '"Noto Sans", sans-serif' : typography.family;
-  const headline = name === 'Editorial' ? '"IBM Plex Serif", serif' : body;
-  return { name, body, headline, typography: { ...typography, family: body }, palette: resolvePalette(name, mode) };
+// Omitted typography retains the original pairing for older documents/callers.
+export function getTheme(name: ThemeName, mode: ThemeMode,
+  typographyId: TypographyId = name === 'Precision' ? 'noto-sans' : name === 'Editorial' ? 'plex-serif' : 'plex-sans',
+) {
+  const body = typographyId === 'noto-sans' ? '"Noto Sans", sans-serif'
+    : typographyId === 'hanken-grotesk' ? '"Hanken Grotesk", sans-serif' : typography.family;
+  const headline = typographyId === 'plex-serif' ? '"IBM Plex Serif", serif' : body;
+  return { name, typographyId, body, headline, typography: { ...typography, family: body }, palette: resolvePalette(name, mode) };
 }