egatari 0.0.0-stage → 0.6.4

package/README.md

@@ -1,3 +1,340 @@
-# Temporary Holding Version
+<!-- i18n: pair=README.ja.md sha256=790df57bc3cb2764 -->
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo/egatari-dark.svg">
+    <img src="assets/logo/egatari-light.svg" width="128" height="128" alt="Egatari logo: the hiragana え (e, picture) in Japanese corner brackets, its first stroke drawn as a sun">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Egatari Studio
+
+[![test](https://github.com/egatari/egatari-studio/actions/workflows/test.yml/badge.svg)](https://github.com/egatari/egatari-studio/actions/workflows/test.yml)
+
+English | [日本語](README.ja.md)
+
+*Egatari Studio (formerly motion-academic-slides). The npm package, the skills and the commands keep their names.*
+
+Academic slides as one self-contained HTML file, with step-by-step reveals and parts that follow the order of your explanation. One set of slides and script (`deck.html` + `narration.md`) gives you a live talk (with later steps shown faintly if you like), a PDF, and, optionally, a narrated video made with TTS. It is designed to be driven by [Claude Code](https://claude.com/claude-code) through the skills in `skills/`, but every step is a plain Node command and works without it.
+
+![A slide from the TMLR 2026 example](docs/images/hero.png)
+
+## Features
+
+- **Steps**: `data-step="k"` shows content in the order you speak. The conclusion line (`.concl`) always comes last
+- **Math**: KaTeX, rendered at build time. `\hlE{…}` / `\hlT{…}` / `\hlM{…}` color a term using the theme
+- **Parts**: Web Components from [egatari/components](https://github.com/egatari/components) (vendored in `vendor/components/`: `m-sweep`, `m-curves`, `m-flow`, `m-collect`, `m-seq`, and for business and pitch lessons `m-bars`, `m-quad`, `m-market`, `m-kpi`, and for coding lectures `m-codetree` (decoding a bit string with a code tree); `m-flow` also draws money and service flows). The screen depends only on (slide, step, time), so the same lesson can be exported frame by frame to video
+- **Links to slides**: an ordinary `<a href="#<slide id>">` (or `#<slide id>:<step>`) jumps to that slide or step and offers **Back** (button, Backspace, Alt+←, browser back); `m-menu` lays such links out as a grid of cards for a contents or choice slide. Plain anchors, no script, so an Egatari file (`.ega.html`) stays Core. See [contract §9](docs/contract.md#9-links-to-slides)
+- **Japanese language arts (国語)**: vertical writing (`.tate`), ruby, a Mincho font (BIZ UDPMincho) and theme `kokugo`; `m-kanbun` (白文 → 返り点 and 送り仮名 → the reading order traced character by character → 書き下し文), `m-kobun` (品詞分解 sentence by sentence, auxiliary-verb conjugation cards, modern translation), `m-gendai` (side lines, demonstrative → referent arrows, paragraph roles). See [reference](docs/reference.md#japanese-language-arts-kokugo)
+- **Emphasis**: `{mark:ID|circle}` in the script draws a hand-drawn underline, circle, box, spotlight or laser pointer dot on the slide at that word
+- **Morph transitions**: `data-morph` slides an equation or element from its place on the previous slide to its new place (like Keynote's Magic Move)
+- **Two modes from one source**: slide show (`?mode=talk`) and video (`?mode=video`). Show later steps faintly is an option of the slide show (`l`; `?mode=lecture` opens it with the option on)
+- **Presenter tools**: presenter view with speaker notes and timer, slide overview, laser pointer, pen, fading pen, toolbar
+- **Themes**: one base color per theme (`themes/<name>/tokens.css`). Parts only use theme variables. Seven bundled themes: 藍 Indigo (`default`), 墨 Ink (`sumi`), 国語 Kokugo, 常盤 Evergreen, 江戸紫 Edo purple, 焦茶 Dark brown, 浅葱 Teal ([reference](docs/reference.md#themes))
+- **Quality control**: the standards (R-fit, R-steps, …) say what a lesson must meet; the quality checker `kit/check.mjs` (`npm run check`) reports overflow, text size, steps, script coverage, contrast, part determinism, emphasis and morphs
+- **Dev server**: edit text and the script in the browser, leave comments for your AI coding tool
+- **Egatari file (`.ega.html`)**: `--portable` writes one HTML file (at the top of the lesson folder, named from the lesson title; the path is printed) that plays offline and also carries its source and audio, so it can be unpacked back into a working folder (`npm run portable -- unpack|pack`); `--play-only` writes a copy without the editable slides and script. It follows **Egatari** (絵語り, “narrating with pictures”), an open [format for Egatari files](https://github.com/egatari/egatari-spec) (draft 1.0). See [reference](docs/reference.md#single-file---portable)
+- **Output**: one self-contained HTML file (fonts, math, and local images, videos and stylesheets referenced by the slides embedded; works offline). Print to PDF from the browser or with `tools/pdf.mjs`
+
+**Reference**: every option, syntax, key and environment variable on one page: [docs/reference.md](docs/reference.md)
+
+| Emphasis | Morph (before / during / after) |
+|---|---|
+| ![mark](docs/images/mark.png) | ![morph](docs/images/morph.png) |
+
+| Presenter view | Slide overview |
+|---|---|
+| ![presenter view](docs/images/presenter.png) | ![overview](docs/images/overview.png) |
+
+## Two ways to use it
+
+| | Tier 1: slides (core) | Tier 2: narrated video (optional) |
+|---|---|---|
+| You get | HTML slides, presenter view, the option to show later steps faintly, PDF | per-step MP4 clips, a full video, an Egatari file with audio |
+| Needs | Node ≥ 22; Google Chrome only for the quality checker, PDF and tests | everything in tier 1, plus ffmpeg, uv, a TTS server and reference voices |
+| Optional | uv (font subsetting) | |
+
+**Slides are fully usable without TTS.** No tier-1 command imports anything from `tts/` or `render/`, and `build`, `check` and the dev server work when `audio/` and `voice.json` are absent. Without audio, autoplay (`a`) uses the default timing for each step, and the script still shows in the presenter view as speaker notes.
+
+## Requirements
+
+**Tier 1 (slides)**
+
+- [Node.js](https://nodejs.org/) 22 or newer, a release with the latest security fixes (see [SECURITY.md](SECURITY.md))
+- Google Chrome or Microsoft Edge for `kit/check.mjs`, `tools/pdf.mjs`, screenshots and tests (through `playwright-core`: Chrome first, then Edge). Building and presenting only need a browser to open the file. Without either, run `npx playwright-core install chromium` (the tools then fall back to Playwright's Chromium) or set `CHROME_PATH=/path/to/chrome-or-chromium`
+- Optional: [uv](https://docs.astral.sh/uv/). After `node tools/get-fonts.mjs` downloads the BIZ UDPGothic (and BIZ UDPMincho) TTF files, the build uses uv to run `pyftsubset` and embeds only the glyphs you use. Without the TTF files (or without uv) it embeds the matching `@fontsource` WOFF2 subsets instead. Those files are larger but look the same
+
+**Windows**
+
+A fresh Windows has neither Node.js nor Git. In PowerShell:
+
+```powershell
+winget install OpenJS.NodeJS.LTS Git.Git     # then open a new terminal
+winget install astral-sh.uv Gyan.FFmpeg      # optional: uv (smaller fonts), ffmpeg (video)
+```
+
+Edge is already there, so the quality checker and PDF work without Chrome. Run the commands below in PowerShell or Git Bash; replace `open` with `start`. Without Git, download the ZIP from GitHub (Code → Download ZIP). Making the script audio (tier 2) needs a TTS server; mlx-audio, the one we test with, runs only on a Mac with Apple silicon. On Windows, use another OpenAI-compatible TTS server, or make or record each step's audio in the editor app ([docs/video.md](docs/video.md#tts-server-mac-windows-linux)).
+
+**Browsers**
+
+- Presenting the built HTML: Chrome/Edge 119+, Firefox 128+ or Safari 18+ (these support the CSS relative color syntax and `color-mix()` that themes use to derive tints from `--base`). Older browsers still show the slides, with fixed fallback colors taken from the default theme instead of colors derived from the theme's `--base`
+- PDF (`tools/pdf.mjs`), video (`render/`), `kit/check.mjs` and the tests are produced and tested with Google Chrome (or Playwright's Chromium) only; Edge uses the same engine
+
+**Tier 2 (video)**
+
+- ffmpeg and ffprobe on `PATH`
+- uv (runs the small Python project in `tts/`)
+- A TTS server with an OpenAI-compatible speech API, e.g. [mlx-audio](https://github.com/Blaizzy/mlx-audio) serving `mlx-community/Irodori-TTS-v4.1-Small-fp16` (Japanese) or `mlx-community/VoxCPM2-8bit` (English and others). Set `IRODORI_URL` (default `http://localhost:8882`). mlx-audio runs only on a Mac with Apple silicon; on Windows and Linux, see [other TTS servers](docs/video.md#tts-server-mac-windows-linux)
+- Reference voices: the default voices `bob` and `alice` (synthetic, Japanese and English) are included in `tts/voices/` ([details](tts/voices/README.md)). Add your own as `<name>.wav` there (gitignored) or in `IRODORI_REF_DIR`
+
+## Quick start (tier 1: slides)
+
+```bash
+git clone --depth 1 https://github.com/egatari/egatari-studio.git
+cd egatari-studio
+npm ci
+node tools/get-fonts.mjs                            # optional: smaller font embedding (uses uv at build time)
+
+node kit/build.mjs examples/minimal/deck.html       # -> examples/minimal/out/deck.html
+open examples/minimal/out/deck.html                 # macOS; elsewhere, open the file in a browser
+
+node kit/check.mjs examples/minimal/deck.html       # quality check; the last line should read "エラー 0" (0 errors)
+node tools/pdf.mjs examples/minimal/out/deck.html examples/minimal/out/deck.pdf   # PDF, one page per slide
+npm run sheet -- examples/minimal                        # one PNG with every slide at its final step (look at it: the check cannot see everything)
+node server/dev.mjs examples/minimal/deck.html      # dev server at http://127.0.0.1:8730/ (Ctrl+C to stop)
+```
+
+### Start your own lesson
+
+```bash
+npm run new -- talks/mytalk --lang en --theme default --title "My talk"
+npm run build -- talks/mytalk/deck.html    # -> talks/mytalk/out/deck.html
+npm run dev -- talks/mytalk/deck.html      # edit in the browser
+npm run check -- talks/mytalk/deck.html    # the last line should read "エラー 0" (0 errors)
+```
+
+`npm run new -- <folder>` creates `deck.html` and `narration.md` from a clean template: a cover and sample slides showing steps, math, emphasis and a part, with a script for every step. It also writes `egatari.json` with `"componentsCatalogue": "2"`: new lessons are built with parts library 2, the parts the chat AI's instructions describe (a folder without that setting, such as an older lesson, keeps parts library 1). Options: `--lang en|ja` (default `ja`), `--theme <name>` (default `default`), `--title "…"`. It refuses to write into a folder that is not empty. You can change the theme later with `<html data-theme="business">` or `--theme business`. With `<html lang="en">` body text is set in Source Sans 3 and the quality check uses the English standards. For a fuller example, see `examples/minimal/`.
+
+Every slide of a new lesson has a stable id (`<section class="slide" id="s-k3f9q2">`), and its script heading names it (`## Heading {#s-k3f9q2}`), so you can rename headings without breaking the script, audio or timing. For a lesson made before ids, run `npm run ids -- talks/mytalk` once: it adds ids and renames the keys in `narration.md`, `audio/manifest.json`, `timeline.json` and `comments.json` (keeping backups in `.cache/edits/`).
+
+### With npm (no clone)
+
+The npm package `egatari` has the same tools as one command, `egatari`:
+
+```bash
+npx egatari new mytalk --lang en      # creates mytalk/deck.html, mytalk/narration.md and mytalk/egatari.json
+npx egatari build mytalk/deck.html    # -> mytalk/out/deck.html (--portable, --play-only and the other build options work too)
+npx egatari dev mytalk/deck.html      # edit in the browser
+npx egatari check mytalk/deck.html    # the last line should read "エラー 0" (0 errors)
+npx egatari doctor                    # Node, uv, ffmpeg and a browser: what is there and how to install what is missing
+```
+
+`npx egatari --help` lists the other commands (`ids`, `sheet`, `comment-shots`, `portable`, `video`, `tts`). `npx egatari video <working folder | .ega.html>` builds and exports a lesson with its existing audio to video (needs ffmpeg). Relative paths are resolved from the current folder. The package carries the fonts the build embeds (no `get-fonts`). `egatari tts` runs `tts/synth.py` with uv and keeps its Python environment in your cache folder (set `UV_PROJECT_ENVIRONMENT` to put it elsewhere).
+
+## Editing in the browser (dev server)
+
+You rarely need to open `deck.html` by hand. Start the dev server and fix things on the slide itself:
+
+```bash
+node server/dev.mjs path/to/deck.html            # then open http://127.0.0.1:8730/  (Ctrl+C to stop)
+```
+
+The page shows the slides (arrow keys, `p`, `a`, … all work), with the editing tools around it: the slides run in a sandboxed frame and can only point at what to edit, and nothing is written until you press Save in the editing tools. It reloads by itself whenever a file of the slides changes, and stays on the same slide and step.
+
+1. **Fix text: `e`, then double-click.** Editable elements get a dotted outline. Double-click one to open its source (HTML, with math as `\( … \)`), edit, and press ⌘/Ctrl+Enter. Only that element is replaced in `deck.html`.
+2. **Fix the script: `n`.** A drawer shows the script of the current step. Edit the text (add or remove turns, change the speaker) and save. Only that step is replaced in `narration.md`.
+3. **Leave a comment: Alt+click (on a Mac, hold ⌥ Option and click).** Write what you want changed ("make this figure larger", "split this slide"). Comments go to `comments.json`; `c` lists them. Then ask your AI coding tool (Claude Code, Codex, Gemini CLI …) to "apply the comments in comments.json" and it edits the slides; the page updates as soon as it saves.
+4. **Undo:** the previous versions of `deck.html` and `narration.md` are kept in `.cache/edits/` (last 30).
+
+| `e` + double-click: edit the source | `n`: edit the script | Alt / ⌥ Option + click: comment |
+|---|---|---|
+| ![editor](docs/images/dev-editor.png) | ![narration](docs/images/dev-narration.png) | ![comment](docs/images/dev-comment.png) |
+
+Details: [docs/dev-server.md](docs/dev-server.md) ([日本語](docs/dev-server.ja.md)).
+
+## Editor app (no install)
+
+The same editing as the dev server, as a web page that opens an Egatari file (`.ega.html`) or a working folder directly. Nothing to install: no Node, no terminal. An Egatari file opens and edits in any current browser; working folders need **Google Chrome or Microsoft Edge on a computer** (the File System Access API, which Safari and Firefox do not have).
+
+| Form | What it is | Here |
+|---|---|---|
+| Working folder | A folder with `deck.html`, `narration.md`, `audio/` …; the commands, AI coding tools (Claude Code, Codex, Gemini CLI …) and other editors read and write it | Edit it with “Work in a folder…” (Chrome / Edge) |
+| Egatari file (`.ega.html`) | One HTML file that carries its source and audio (`--portable`); open it in a browser to play | Edit it with “Open…” (any browser) |
+| Play-only (`--play-only`) | An Egatari file without the editable slides and script | Cannot be edited (open the original Egatari file or the working folder) |
+| Built HTML (`out/deck.html`) | The presentation output of `node kit/build.mjs` | Cannot be edited (open the working folder) |
+
+- **Open the editor:** **<https://studio.egatari.org/>** in Chrome or Edge (nothing to install), or build it yourself with `npm run build:app` and open `dist/editor.html` (the Offline editor, about 10 MB) by double-clicking it.
+- **Open an Egatari file, no folder needed:** “Open a file (.ega.html)…” on the first screen (or dragging and dropping the file) opens an [Egatari file (`.ega.html`)](docs/reference.md#single-file---portable) and edits it in memory; the file is extracted in a worker without running it. “Save” writes the same file again (or downloads it), “Save as…” writes a copy, or (ticking “Save as a new file”) a lesson under a new id that records the original, “Export working folder…” writes the source and audio to an empty folder; the lesson id and the rights notices are kept, and the license is shown before the first edit (with a confirmation for no-derivatives licenses). A script, audio or timing edit is saved without rebuilding: only those parts of the file change. A slide edit rebuilds the file, after a warning that slides you did not edit may look different. For an open folder, “Save as…” writes an Egatari file. Works in any current browser (saving downloads where there is no file picker)
+- **Edit:** the same keys as the dev server: `e` + double-click for the source, `n` for the script, Alt / ⌥ Option + click for a comment (`comments.json`), `c` for the list. Backups go to `.cache/edits/` in the folder.
+- **Open a working folder:** drag and drop the working folder (the one with `deck.html`) onto the page, or press “Work in a folder…”, and let the browser edit that folder. **New…** has a chat AI write a new lesson (a new working folder: `npm run new`). Recent working folders are listed on the first screen.
+- **Draft with a chat AI, no coding tool needed:** “New…” asks four questions (where it is used, what it is about, how it looks, and whether your chat AI is on a free or paid plan), copies the [instructions for the AI](docs/authoring-with-llms.md) for claude.ai, Gemini or ChatGPT, and takes the AI’s output in two fields, slides and script (paste the whole output into either and it is split): the editor gives the slides ids, creates the lesson as a new Egatari file (scripts in the output ask before running, like any opened file) and runs the quality check. “Copy a fix request for your AI” in the quality check panel writes the findings, the standards they break and the current files for the same chat; “Revise…” replaces the slides from its output in the current lesson (keeping its id and audio); “Insert slide…” can have the AI add slides after the one you select
+- **Script audio, one step at a time:** “Audio” plays the step's audio and marks it stale when the script changed after it was made; record a take from the microphone (with a level meter), import a file, or regenerate the step with “Make AI voice on this computer” (Irodori-TTS for Japanese with the reading dictionary, Kokoro for English; needs WebGPU, the model is downloaded once), then “Use this take”. Takes are processed like `tts/core.py` (trimmed, −20 LUFS) and saved as MP3 with where they came from ([details](docs/editor.md#script-audio-audio-panel)). In an Egatari file this is saved without rebuilding
+- **Work with an AI coding tool:** when anything else changes the files (Claude Code, Codex, a text editor), the editor notices within about 2 seconds, rebuilds, and stays on the same slide and step. A build error is shown over the preview until it is fixed.
+- **Language:** the editor follows your browser language; the **English / 日本語** button at the top right (or `?lang=en` / `?lang=ja`) switches it.
+- **Toolbar:** File ▾ (New…, Open…, Save, Save as…, Export ▸ For participants (play-only)… / Print / PDF, File info…, Work in a folder…), Slide ▾ (Insert slide…, Duplicate, Delete, Revise…), Quality check (with a warning count), Preview ▾ (check as a slide show or as a video, show later steps faintly, or in presenter view with the script and the next step).
+
+Limits: TTS with your own reference voices (`tts/synth.py`), video, `npm run check` (the command quality checker) and `tools/pdf.mjs` stay on the command line, and the preview does not play the folder's audio (the Audio panel does). The browser quality checker covers a subset (overflow, font size, length, missing narration, contrast) and is only a hint; the full quality check is `npm run check`. Exported HTML embeds whole font files instead of a subset (no fonttools in the browser), so it is larger than a command-line build (about 2 MB instead of 0.7 MB for `examples/minimal`). Repository parts and themes are the ones bundled when the editor was built; parts and themes inside the working folder are read from the folder.
+
+![editor app](docs/images/editor-app.png)
+
+Details: [docs/editor.md](docs/editor.md) ([日本語](docs/editor.ja.md)).
+
+## Using it with Claude Code
+
+Making lessons with Claude Code or Cowork (the Claude desktop app): [docs/with-claude.md](docs/with-claude.md) ([日本語](docs/with-claude.ja.md)).
+
+First delete the old `~/.claude/skills/motion-*` entries (and any copies in a project's `.claude/skills/`). The light `egatari` entry contains only make for authoring and needs no Node. Add `egatari-studio` for local quality checks, builds, parts and video. To use studio, install both entries:
+
+```text
+/plugin marketplace add egatari/egatari-studio
+/plugin install egatari@egatari
+/plugin install egatari-studio@egatari
+```
+
+The studio skill runs its commands through the egatari npm package (`npx egatari@0.6.x …`, see "With npm (no clone)" above): no clone and no `npm ci`, only Node.js (it starts with `npx egatari@0.6.x doctor`, which shows what is missing and how to install it). Update with `/plugin update egatari@egatari` and `/plugin update egatari-studio@egatari`. With make alone, open the finished working folder at <https://studio.egatari.org/> in Chrome or Edge. On Mac, Safari uses the single file (.ega.html) path.
+
+For a chat AI, upload `egatari-make-skill.zip`. Developers can create it with `node tools/make-llm-guide.mjs --zip out/release`. Its `make/` contents match the generated, committed `plugins/egatari/skills/make/` directory.
+
+| Skill | Use it for |
+|---|---|
+| `egatari:make` | plan, write, step and narrate a lesson (no Node needed) |
+| `egatari-studio:studio` | local quality checks and builds, writing parts, and exporting video with existing audio |
+
+Example prompts:
+
+- "Use egatari:make to make HTML slides from `paper/main.tex` for a 10-minute talk, default theme, single speaker."
+- "Add a slide that shows how the loss changes with the learning rate, using m-sweep."
+- "Apply the comments." (after leaving Alt / ⌥ Option+click comments in the dev server; the skill reads `comments.json`)
+- "Turn `talks/intro` with existing audio into a video with egatari-studio:studio."
+
+The skill first shows you an outline and writes HTML only after you approve it.
+
+## Making a video (tier 2)
+
+```bash
+D=examples/minimal
+uv run --project tts python tts/synth.py $D --dry-run    # silent placeholder audio, to try the pipeline offline
+uv run --project tts python tts/synth.py $D              # real TTS (needs the server and the voices)
+node kit/build.mjs $D/deck.html                          # rebuild so the audio lengths enter the timeline
+node render/render.mjs $D/out/deck.html --out $D/video   # add --only "更新の式:2" for one step, --full for one file
+```
+
+- Voices: `--voices expert=bob,novice=alice`, or `<deck>/voice.json` (`{"expert": "me"}`, or a path to a wav file). The defaults are `bob` (single speaker) and `bob` / `alice` (dialogue), looked up as `tts/voices/<name>.wav`; in an English lesson `<name>_en.wav` is used when it exists
+- If the server is not running or a voice file is missing, `synth.py` stops and names the URL or file it could not reach
+- No Mac? `synth.py` works with any OpenAI-compatible TTS server that takes the same request ([docs/video.md](docs/video.md#tts-server-mac-windows-linux)); the editor app can also make or record each step's audio
+- **Self-playing HTML with audio**: `node kit/build.mjs $D/deck.html --embed-audio` puts the script audio inside the HTML, so the HTML file plays with `a` (autoplay) anywhere. The audio is compressed to AAC (64 kbps, mono; about 4.5 MB for a 5-minute talk, instead of ~30 MB as WAV), which every current browser plays. Without `--embed-audio` the HTML refers to the WAV files in `audio/` and nothing is converted. If ffmpeg is missing, the WAV files are embedded as they are and the build warns
+- Details (caching, timing overrides in `timeline.json`, the reading dictionary): [docs/video.md](docs/video.md) ([日本語](docs/video.ja.md))
+
+## Keys (presenting)
+
+| Key | Action |
+|---|---|
+| → / Space, ← | next / previous step |
+| Shift+→ / Shift+← | next / previous slide |
+| number + Enter | go to that page |
+| f | fullscreen |
+| p | presenter view (speaker notes, next step, timer) |
+| a | autoplay (plays the audio if the lesson has it) |
+| l | show later steps faintly (on/off) |
+| b | black screen |
+| s / Shift+s | captions (script, about two lines at a time) / caption size S, M, L |
+| o | slide overview (arrows + Enter) |
+| x / d / v | laser pointer / pen / fading pen; Shift+d (or the swatches in the toolbar) changes the pen color |
+| Backspace (Shift+Backspace) | while a pen is active: clear the drawings on this slide (on all slides) |
+| Esc | leave the current tool |
+| ? | list of keys |
+
+All keys (Home/End, PageUp/PageDown, presenter-view keys) and URL parameters: [docs/reference.md#presenting](docs/reference.md#presenting).
+
+A toolbar with the same actions is shown for about 5 s when the lesson opens (the first time on a device, with a line that says how to bring it back), then whenever the mouse moves or the screen is tapped; it hides after 2.5 s. While it is hidden, a faint **Show toolbar** button at the bottom left brings it back. Drawings are kept per slide and never appear in print or video.
+
+![toolbar](docs/images/controls.png)
+
+## Themes
+
+A theme is a folder `themes/<name>/` with:
+
+- `tokens.css`: CSS variables. Usually only `--base` (the base color) is needed. The other colors (`--term`, `--emph`, `--muted`, `--title`, tints, `--series-*`) are derived from it in `themes/default/tokens.css`, and you can override any of them
+- `theme.json` (optional): `{"name": "mylab", "extends": "default", "logos": ["logos/cover.png"]}`. Logos appear on the cover slide
+
+```bash
+mkdir -p themes/mylab
+printf ':root{ --base: #006d5b; }\n' > themes/mylab/tokens.css
+printf '{"name": "mylab", "extends": "default"}\n' > themes/mylab/theme.json
+node kit/build.mjs examples/minimal/deck.html --theme mylab
+```
+
+A theme can also sit next to a lesson (`<deck>/themes/<name>/`) or in a folder of your own themes: set `EGATARI_THEMES` to a list of folders (separated by `:`, or `;` on Windows), or use `~/.egatari/themes` (it may be a symbolic link). Themes are looked up in the working folder, its `themes/`, your theme folders, then the bundled `themes/` ([reference](docs/reference.md#themes)). In the editor app, choose your theme folder once (**Choose theme folder…**, read only; [editor](docs/editor.md)), or put the theme in the lesson's `themes/`; otherwise it builds with `default` and a warning naming the missing theme. An Egatari file carries such a theme with it. Included: `default` (neutral), `business` (neutral, for business and pitch lessons: navy with orange emphasis, no logo) and `kokugo` (Mincho, for Japanese language arts). No institutional themes or logos are bundled.
+
+## Examples
+
+| Example | What it shows |
+|---|---|
+| [`examples/minimal`](examples/minimal) | Japanese, 6 slides on gradient descent: steps, KaTeX with `\hlE`, `{mark}`, `data-morph`, `m-sweep`, a script for every step. A fuller example to learn from (`npm run new` makes a clean template) |
+| [`examples/tmlr2026-calibration`](examples/tmlr2026-calibration) | English, 14 slides introducing a TMLR 2026 paper: lesson-local parts (`components/`), data made by scripts (`scripts/`, `data/`), English TTS (`voice.json`), theme `default` |
+| [`examples/pitch-fictional`](examples/pitch-fictional) | Japanese, 10 slides: a pitch for a fictional company (株式会社レポミル, a SaaS that drafts reports). `m-kpi`, `m-flow` (money flows and `pulse`), `m-bars` (with an axis rescale), `m-quad`, `m-market`, theme `business`, data written by a script (`scripts/`, `data/`). The company, product and every number are made up |
+| [`examples/kokugo-kanbun`](examples/kokugo-kanbun) | Japanese, 11 slides for a 国語 lesson: a contents slide with `m-menu` (links to each part, Back to return), kanbun with `m-kanbun` (『史記』, 孟浩然「春暁」, 杜甫「春望」, 『論語』), 『枕草子』 with `m-kobun`, an original modern text with `m-gendai` (vertical), theme `kokugo` |
+
+The `voice.json` of `examples/tmlr2026-calibration` uses the engine's default voice. The published video of this example was narrated with the author's own reference voice, which is not included in the repository.
+
+`examples/minimal`:
+
+![minimal example](docs/images/minimal-sheet.png)
+
+`examples/tmlr2026-calibration`:
+
+![tmlr2026-calibration example](docs/images/tmlr-sheet.png)
+
+`examples/kokugo-kanbun` (「春暁」: the reading order, the eye jumping back from 鳥 to 聞 at the 一二点):
+
+![kokugo-kanbun example](docs/images/kokugo-kanbun.png)
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `docs/contract.md` | the contract: position and time, parts, script, timeline, emphasis, morphs. **Read this first** ([日本語](docs/contract.ja.md)) |
+| `docs/dev-server.md`, `docs/editor.md`, `docs/video.md`, `docs/distributing.md` | guides: the dev server, the editor app, making a video, and handing a lesson to learners ([日本語](docs/dev-server.ja.md), [日本語](docs/editor.ja.md), [日本語](docs/video.ja.md), [日本語](docs/distributing.ja.md)) |
+| `docs/authoring-with-llms.md` | instructions for chat AIs (claude.ai, Gemini, ChatGPT) to write a first draft; the common body (standard parts); the part set packs (stats, math, maps, kokugo, english, music, business, tools, science) are in `docs/llm-parts/`; generated by `tools/make-llm-guide.mjs`, assembled by `node kit/llm-pack.mjs` ([日本語](docs/authoring-with-llms.ja.md)) |
+| `docs/reference.md` | reference: slide syntax, script, timing, themes, keys, URL parameters, and all CLI options and environment variables ([日本語](docs/reference.ja.md)) |
+| `kit/` | runtime (`deck.js`, `presenter.js`, `tools.js`), styles, build, script parser, quality checker, browser launcher; `kit/core/` is the build shared by Node and the editor app, `kit/templates/` the new-lesson template |
+| `vendor/components/` | copies of the [egatari/components](https://github.com/egatari/components) releases (parts), every version brought in; default versions pinned in `components.lock.json`; catalog in `vendor/components/CATALOG.md`. Update with `npm run components:update -- vX.Y.Z` |
+| `themes/` | themes |
+| `server/` | dev server and in-browser editor |
+| `app/` | editor app (no install): sources; `npm run build:app` makes the hosted editor in `dist/` (`dist/index.html`) and the Offline editor `dist/editor.html` |
+| `tts/`, `render/` | tier 2: TTS (a uv project), video rendering |
+| `skills/studio/` | local Claude Code studio skill |
+| `plugins/egatari/` | generated light plugin with only make |
+| `tools/` | new-lesson template (`new.mjs`), tests and helpers (`smoke`, `test-*`, `shot`, `pdf`, `get-fonts.mjs`) |
+| `CHANGELOG.md` | changes in each release |
+
+Tests (need Chrome):
+
+```bash
+node kit/build.mjs examples/minimal/deck.html
+node tools/smoke.mjs examples/minimal/out/deck.html /tmp/smoke     # timeline + screenshots
+node tools/test-components.mjs
+node tools/test-tools.mjs examples/minimal/out/deck.html
+node tools/test-controls.mjs examples/minimal/out/deck.html
+node tools/test-links.mjs                                          # links to slides, Back, embedding, m-menu, quality checker
+node tools/test-dev-server.mjs
+node tools/test-app.mjs                                            # editor app (builds dist/ in a temp folder)
+```
+
+## Feedback & contributing
+
+- In a lesson, press `?` and click **Send feedback** (also in the presenter view). It opens a [feedback form](https://github.com/egatari/egatari-studio/issues/new?template=feedback.yml) with only the version, browser, OS, language and mode filled in; nothing from your slides is sent. Turn it off with `<html data-feedback="off">`
+- In Claude Code, say "send feedback": the skill drafts an issue from the session and creates it only after you confirm
+- Want a new figure? Write it in your lesson first (inline SVG, or a lesson-local part); to have it in the Parts library, [propose it in egatari/components](https://github.com/egatari/components/issues/new?template=proposal.yml)
+- Questions: [Discussions](https://github.com/egatari/egatari-studio/discussions). How to contribute: [CONTRIBUTING.md](CONTRIBUTING.md)
+- What changed in each release: [CHANGELOG.md](CHANGELOG.md)
+
+## Security
+
+A lesson is code: its scripts and parts run in your browser and in the headless Chrome used by the quality checker and renderer, and the build reads local files inside the working folder. Build and serve only lessons you trust. The trust model and how to report a vulnerability: [SECURITY.md](SECURITY.md).
+
+## License
+
+- Code: [MIT](LICENSE), Copyright (c) 2026 Gendo Kumoi. Fonts and KaTeX fonts: see [NOTICE](NOTICE)
+- Fonts: BIZ UDPGothic, BIZ UDPMincho and Source Sans 3 are licensed under the SIL Open Font License 1.1 ([fonts/OFL.txt](fonts/OFL.txt) for BIZ UDPGothic, [fonts/OFL-BIZUDPMincho.txt](fonts/OFL-BIZUDPMincho.txt) for BIZ UDPMincho; the `@fontsource` packages ship their own license files). Built lessons embed subsets of them. KaTeX and its fonts are MIT
+- Logo: the Egatari logo ([assets/logo/](assets/logo/), and the editor's favicon and app icons) is not covered by the MIT license. You may use it unmodified to refer to Egatari or to Egatari-compatible software (software that reads or writes Egatari files). See [NOTICE](NOTICE)
+- No university or other institutional logos are included (the institutional themes were removed after 0.4.0; see [CHANGELOG.md](CHANGELOG.md)). A theme you add yourself, with its logos, is under its own terms

package/SECURITY.md

@@ -0,0 +1,74 @@
+# Security
+
+See also the [threat model](docs/threat-model.md) (what is protected, from whom, and where each protection lives in the code).
+
+## Trust model: a deck is code
+
+Treat a working folder like a source-code repository, not like a document. Build, check, render or serve only decks you trust.
+
+- **Scripts run.** Inline `<script>` in `deck.html`, components (`components/<name>/index.js`, deck-local ones first) and component attribute expressions (registry components up to v1.0.1, which are yanked; from components v1.0.2, the default, `m-sweep` and `m-curves` evaluate formulas with an arithmetic parser and never run them as code) run in the browser that opens the built HTML, and in the headless Chrome used by `kit/check.mjs`, `tools/pdf.mjs`, `render/` and the tests (Playwright).
+- **Build reads local files, inside the working folder only.** `/*INCLUDE:…*/`, `{{JSON:…}}`, `{{FIG:…}}`, `narration.md`, `timeline.json`, `macros.tex`, `audio/manifest.json` and referenced assets (`<img src>`, `<link rel="stylesheet">`, CSS `url()`, …) are resolved relative to the working folder (`INCLUDE` also searches `kit/`). Paths that leave the folder, through `../`, an absolute path or a symbolic link, are refused with a warning and nothing is read. Components (`components/<name>/index.js`) and theme files (`theme.json`, `tokens.css`, logos, and every theme reached through `extends`, at any depth) are checked by real path against their authorized root before they are read: the working folder for deck-local ones, the repository's `components/` or `themes/` for registry ones, and the folder itself for each of your theme folders (`EGATARI_THEMES`, `~/.egatari/themes`; real path, computed once). A deck-local theme can extend only themes in the working folder, your theme folders or `themes/`, so `extends` cannot leave through `../`, an absolute path or a link. A refused file is not read and the build warns (`refused: …`); a refused theme falls back to `themes/default`, a refused deck-local component is not replaced by the registry one. Links that stay inside the folder are followed for reads. What you name on the command line or in the environment is trusted: the deck file itself, a `--theme`, an `-o` output path, the folders in `EGATARI_THEMES`.
+- **Build size is bounded.** Includes, embeds (`data:` URIs, stylesheets, scripts, `@import`) and formulas are counted while they are expanded, and the build stops with `build-too-large` as soon as a budget is exceeded (defaults: 10 000 includes and embeds, 64 Mi characters after preprocessing, 256 Mi after embedding, 500 000 tags before each parse, 20 000 formulas; `opts.limits` changes them). Every file the build reads — source, includes, embeds, theme files and logos through every `extends`, components, narration, audio, fonts, runtime — counts toward the same include count and one aggregate read budget (`readChars`, 256 Mi), charged from the file size before the file is read, so a 1 GiB logo, stylesheet, component or audio file is refused without being read; the logos and the whole output are size-checked before they are joined. The size is only an estimate: each read is also charged with the bytes actually read, and a file larger than its reported size is refused. Only regular files are read: on Node the build checks the path (`lstat`) and the opened descriptor (`fstat`), opens non-blocking and reads at most the allowed bytes from that descriptor, so a FIFO, device or socket in the working folder is refused (`build-not-a-file`) instead of blocking the build. Sizes are always counted in bytes, never in UTF-16 code units. Audio compression reads the source `.wav` once, up to the size charged for it, and gives ffmpeg a copy of those bytes in a private temporary folder instead of reopening the path. The portable export (`--portable`, `--play-only`, the editor's export) uses the same budget as its build for everything it reads itself (narration, copied sources, `voice.json`, `egatari.json`, audio before and after compression, segment metadata) and checks the whole file before it builds each part it inserts: archive chunks from their projected size, the index from a lower bound before serializing (also against the reader's `indexBytes`), and the readable layer counted in escaped characters while it is built; base64 is encoded last. In the editor app, the build and the classification of an opened deck run in a worker that is terminated after 60 s. The editor reads only the files a build actually references (never the rest of the folder), at most 8 at a time and within the same budget (reserved from the folder listing before reading, each read capped at its listed size — a file that grew is refused — and checked from `File.size` again right before reading and from the bytes read); messages are bound to the worker that sent them, so a reply from a stopped worker is dropped and never reaches its replacement, and reads still queued for a stopped worker are not started.
+- **Build output is self-contained.** Local assets are embedded as data URIs. `http(s)` references are left as they are, and the build warns that the deck is then not fully offline.
+- **The dev server is local-only.** `server/dev.mjs` listens on `127.0.0.1` only, accepts only `Host: 127.0.0.1:<port>` or `localhost:<port>` (against DNS rebinding), and writes (text edits, narration, comments) need JSON, a same-origin request (requests with `Origin: null` or a cross-site `Sec-Fetch-Site` are refused) and a per-run token. It writes only inside the working folder (`deck.html`, `narration.md`, `comments.json`, `.cache/edits/`), through one helper (`kit/safe-fs.mjs`) that refuses when the file or any folder between the working folder and it is a symbolic link (even one pointing inside, and dangling ones), checks that the real parent is inside the working folder, and writes an exclusive temporary file in the same folder that is synced and renamed over the target. Backup cleanup deletes only regular files named like backups (`<time>-<name>`, the same rule as the editor app's cleanup), in a backup folder that is itself checked; other files in `.cache/edits/` are never deleted. It reads `narration.md`, `comments.json` and `deck.html` only if their real path is inside the working folder, only regular files and within fixed limits (16 MiB, 4 MiB, 32 MiB; a larger file gets 413 unread, a save that would exceed a limit gets 413 unwritten), streams files under `/deck/` only up to their `stat` size, and watches the working folder, `audio/`, `data/`, `figs/` and `components/` only if they are real folders inside it (a symbolic link is not watched, with a warning). The same helper is used by `npm run ids`, `npm run portable -- unpack` / `pack` and the build's `out/` and `egatari.json` writes. Not covered: the TTS and video tools (`tts/`, `render/`, tier 2) and `npm run new` write without these checks, and a race in which another local process swaps a folder for a link between the check and the write is not prevented (the threat is a link placed in a working folder, not a concurrent process). Do not expose it to a network or put it behind a proxy.
+- **TTS output.** `tts/synth.py` stops before writing `audio/`, `.cache/voices/` or the files in them through a symbolic link (since 0.2.2). It does not limit what it reads: `narration.md`, `voice.json` and a reference voice named by path in `voice.json` may be anywhere, by design.
+- **While you edit, the deck cannot write.** In the dev server and in the editor app the deck (its inline scripts and components) runs in a sandboxed iframe with an opaque origin (`sandbox="allow-scripts allow-modals"`, no `allow-same-origin`) and a Content-Security-Policy with `connect-src 'none'` and every other resource limited to `data:` / `blob:` (the dev server also allows its own `/deck/audio/` for audio and frames only its exact preview endpoint `/preview`, which it serves only into its own frame page — with a capability issued with that page and `Sec-Fetch-Dest: iframe` — and never as a top-level document; every file it serves from the working folder carries a CSP `sandbox` and is served as an inert download unless it is audio, video, an image or a font). The editor app puts that policy in a trusted prefix of the preview document, before any byte of the deck. The editing UI (`server/editor-ui.js`) runs outside the deck: in the dev server's frame page, which alone holds the per-run token, and in the editor app's own page, which alone holds the folder handles. The deck can only send hints (`server/hints.js`: which element or step to open, a note position, the keys `e` / `n` / `c` / Esc, its position); a hint carries no text to write. The editing UI reads the source itself, checks the range and hash against the current build, shows the text in its own card, and writes only when you press Save (or ⌘/Ctrl+Enter) there. The rights prompt and read-only modes of the editor app apply to those writes. The point of a note (its pin, in slide coordinates) comes from a hint too, so it is checked and clamped to the slide on both sides (`kit/core/comment-core.mjs`); a forged point only moves the marker, which the editing UI draws over the preview from the iframe's own size, without taking clicks. Images of what a comment points at are never taken from the preview: `tools/comment-shots.mjs` renders the step again from the source. `tools/hostile-deck.mjs` is a deck that tries to write in every way we know of; the dev-server and editor-app tests check that it changes nothing.
+- **A deck's own code still runs in the preview.** It cannot write or reach the network, but it can show anything inside the preview. **Anything inside the slide area can be drawn by the deck; trust only controls in the editor's own panels.** All editing controls (edit-mode bar, source box, note box and list, narration drawer) are drawn outside the slide area, in a side panel under an orange marker bar (“Editing — app” / “Editing — dev server”); while you edit in a trusted field (source or note box open, typing in the narration drawer or unsaved narration), the preview is inert so it cannot catch your clicks, and hints from the deck do not switch the panels. A fake card drawn by the deck cannot save. Before the editor app runs a deck's own code, it says so and starts the preview (and the presenter view) only after you confirm. Whether a deck has code is decided from its content, never from the profile a single file (`.ega.html`) declares, and from the built document — the source after every include, including files of any extension, the same bytes that are then shown: scripts without a data type, `<meta http-equiv="refresh">`, event-handler attributes, `javascript:` URLs, `srcdoc`, embedded documents, included SVG or HTML with any of these, JavaScript files, and component formulas that are not plain arithmetic. A file declared “core” whose content has code is treated as having code, with a warning.
+- **Untrusted files are read through one bounded reader.** Every read of deck, workspace or portable-file data goes through `kit/bounded-read.mjs` (Node: regular files only, checked by `lstat` and on the opened descriptor, opened non-blocking, refused before reading if larger than the limit, at most the limit read) or `app/bounded-read.js` (browser: `File.size` checked before `arrayBuffer()`, the bytes read checked after; never `File.text()`). Callers pass explicit limits; the default is 32 MiB. `tools/test-raw-reads.mjs` (part of `npm test`) fails on any `readFileSync`, `fs.readFile`, `createReadStream`, `text()`, `arrayBuffer()` and similar outside these two modules unless it is in an allowlist of reads of trusted repository files, each with a reason. Not covered: the Python TTS tools (`tts/`) read with Python's own I/O (see TTS output below).
+- **Opening a single file allocates within limits.** Sizes are checked before allocation (`npm run portable -- unpack` refuses a file over the format's 100 MiB from the opened file's size, before reading or copying it), the HTML is parsed with budgets for elements, attributes and nesting counted while parsing, and the editor app stops a read that takes longer than 30 s.
+- **Registry names in single files are identifiers.** `components[].name` and `themes[].name` of registry entries must match `^[a-z][a-z0-9-]{0,63}$` (format spec); the reader refuses others (`invalid-index`), and `npm run portable -- unpack` looks a registry component up by name and SHA-256 in `components.lock.json` and compares it only through a contained regular-file read of `vendor/components/<name>/<version>/index.js` (a link out of `vendor/components/` counts as missing). Library components are copies of [egatari/components](https://github.com/egatari/components) releases; `npm run components:update` checks the release tarball and every file against the release's `manifest.json` (SHA-256) before writing, never replaces a version it already has, and the build never fetches components. A name such as `../../private` no longer reveals whether, or with which hash, a file outside the registry exists.
+- **Classification parses as a browser with scripting on.** `<noscript>` (also `<noembed>`, `<noframes>`, `<iframe>` text) is raw text and ends at the first closing tag, so markup that a scripting-disabled parser would read as an attribute value cannot hide a script that runs. The build's boundary search, the portable reader and tier-A edits use the same mode.
+- **Links in folders opened in the editor app.** The memory and OPFS workspaces cannot contain links. For a folder picked with the File System Access API, Chromium (tested with 155 on macOS) does not list links inside the folder, cannot open them by name and cannot write through them (`tools/test-security.mjs` checks this); the API offers no way for the app to detect links itself, so this relies on the browser.
+- **A pasted AI reply is an untrusted deck.** The chat AI choices of “New…”, “Insert slide…” and “Revise…” in the editor app only parse the pasted text in the page (`kit/core/llm-import.mjs`: finding the code blocks, or telling a block pasted on its own from its content; `kit/core/slide-ids.mjs`: adding ids with parse5, nothing executed). The source is made into a single file in the build worker (same limits and timeout) and opened through the same path as a file you open: the content decides whether it has code, so a `<script>` or any other code in a reply asks before the preview starts, and Cancel opens nothing. Replacing a folder deck writes `deck.html` and `narration.md` with backups and asks about code again. The fix request only reads the current source and copies text to the clipboard.
+- **Narration audio in the editor app.** The microphone (`getUserMedia`, `MediaRecorder`), file import, post-processing and MP3 encoding run only in the editor's own page (recording mode, `app/rec-mode.js`, and the Audio panel, `app/audio-panel.js`). The preview cannot start a recording or a regeneration, and no audio is ever taken from the preview (for playback the editor sends the preview the bytes of the audio files that `audio/manifest.json` lists for its steps, read with the same limits, and the preview's trusted shim turns them into `blob:` URLs of the preview document); while recording mode is open the preview is inert, and while the panel makes or writes audio, hints from the deck do not change its step. The panel reads the step's audio and `audio/manifest.json` through the workspace with limits (each audio file 64 MiB, the manifest 16 MiB, an imported file 64 MiB checked before reading, a take at most 600 s) loads the MP3 encoder only from the editor's own site, and only when it encodes MP3 (`app/mp3-loader.js` imports `vendor/lame-wasm/index.js` of the built site: an unmodified copy of `dist/index.js` from the npm package `lame-wasm`, pinned in `package.json`, that `tools/build-app.mjs` makes; the WebAssembly is embedded in that file and nothing else is fetched; the single-file editor opened from `file:` has no encoder and saves WAV), records no device or file names, and writes only `audio/<rec|tts|imp>_<hash>.mp3` (or `.wav`) and `audio/manifest.json` (backed up to `.cache/edits/` first, refused if the manifest changed since it was read) through the same write paths as other edits; the file name in a manifest entry is used only if it is a plain relative path under `audio/`. Writes of a single file go to its in-memory folder and reach the file only through Save (tier A). The editor page's policy still allows no network. Browser TTS runs in a separate window of the same site (`lab/tts-helper.html`), opened only after you confirm the download; it loads pinned libraries from jsDelivr and the model from Hugging Face, like the lab page, and is sent only the text to read and the voice name. The editor accepts audio only from that window (`e.source`, same origin, the request id), checks the sample rate and length, and processes it like a recording. That window is same-origin with the editor, so it is trusted as the lab page is: a compromised jsDelivr or Hugging Face file running there could reach the editor's storage.
+- **Attachments are download-only.** Files under `attachments/` (format §3.8) are packed into a single file but never built, parsed for code, opened or run: the code check skips them, the editor lists them in its own panel without opening them or passing them to the preview, and the player of a single file only offers a download after checking the index hash and the attachment's size and SHA-256, as an `application/octet-stream` Blob through a link with `download` (no navigation, no new tab; an `.html`, `.svg` or `.pdf` attachment is saved, not rendered). Inside a host's sandboxed frame without `allow-downloads` the download is simply blocked. Packing reads only regular files under `attachments/` (links are not followed) within the build's read budget and the attachment limits (10 MiB each, 20 MiB together, 100 files), and only the formats each role allows (format §3.8): the type comes from the extension and is checked against the content without running anything, within decompression limits (`kit/core/attach-content.mjs`). Executables (and, in any role, the extensions common operating systems run or open as scripts, such as `.js`, `.bat`, `.ps1` or `.command`), HTML, SVG, archives, macro-enabled or legacy Office, audio and video, PDFs with JavaScript, embedded files, automatic actions other than going to a place in the document, link actions other than `GoTo` and `URI` (no `Launch`, `SubmitForm`, `ImportData`, `GoToR`, `GoToE`, `Rendition`), or encryption that needs a password, Office files with macros, ActiveX, embedded objects, external links, DDE, data-fetching functions, executing field codes or remote templates, and files of two types are not packed; the editor refuses them with the reason, and the player offers only the formats the role allows (extension and media type must agree), saves under the path's file name, notes that code should be run only if its source is trusted, and checks the first bytes before saving. An attachment is still a file from the author: what it does once you open it on your computer is outside Egatari.
+- **Saves stay with their deck.** The editor app rechecks after every wait that the deck a save started on is still open, aborts the file write otherwise, and marks a deck saved only if no edit happened during the save.
+- **Links that leave the lesson.** A deck's link to another site is never followed by a click alone: the player (and a single file) shows the destination's host and full address first and opens it only on confirmation, in a new context with `noopener,noreferrer`, asks every time when the link text names another host, the destination is not `https:`, or it downloads, and refuses `javascript:`, `data:`, `file:` and every scheme but `http(s)`, `mailto` and `tel` (format spec §11; `kit/core/link-policy.mjs`, `tools/test-extlinks.mjs`). The editor's preview opens nothing outside.
+- **TTS and video** (tier 2) send narration text to the TTS server in `IRODORI_URL` (default `http://localhost:8882`). Point it only at a server you run or trust.
+
+`comments.json`, `.cache/`, `.env*` and `*.local.json` are gitignored so that review notes, edit history and local settings are not published by accident.
+
+## Components yanked by the registry
+
+[Components](https://github.com/egatari/components) v1.0.0 and v1.0.1 are **yanked** (replacement: v1.0.2): their `m-sweep` and `m-curves` ran formulas from a lesson with `new Function`. Their tags and assets stay (a tag is never moved); every release's `manifest.json` from v1.0.3 on lists them under `yanked` with the replacement, and `npm run components:update -- v1.0.3` records that in `components.lock.json`. Following [spec §6](https://github.com/egatari/egatari-spec/blob/main/egatari-1.0.md#6-components-and-profiles):
+
+- **Never silent.** A deck that pins (`components` in `egatari.json`) or a single file that records a yanked version is built with exactly that version and a warning (`kit/build.mjs`, `kit/check.mjs`; stats `yanked`). The editor app shows a notice and a **Rebuild with 1.0.2** button; only pressing it changes `egatari.json` (and the single file's record), and a note lists which identity hashes changed.
+- **The editor page forbids eval.** Its Content-Security-Policy (`app/index.html`, the hosted editor and the single-file `editor.html`) has no `'unsafe-eval'` (only `'wasm-unsafe-eval'`, which the MP3 encoder's WebAssembly needs and which allows no `eval` or `new Function`); `tools/test-yanked.mjs` listens for CSP violations on the page. The preview frame is a sandbox without `allow-same-origin` (opaque origin: no access to the editor page, its storage or the folder handles) and inherits the page's policy, so inside the editor a yanked `m-sweep` / `m-curves` shows its placeholder instead of running its formula. `PREVIEW_CSP` (`app/preview-doc.js`) and the dev server's deck document (`server/dev.mjs`, a top-level sandboxed document) keep `'unsafe-eval'` so that yanked versions still play there; `lab/tts-helper.html` is a separate page of its own with its own policy (`wasm-unsafe-eval` for the speech model).
+- **The code scan** (`kit/core/code-scan.mjs`) still treats formulas outside plain arithmetic as code in documents that record a yanked version.
+
+## Node versions
+
+Use a Node.js release that includes the latest security fixes. The floor is the security release of 2026-10-20/21 (among others, Brotli and TLS certificate checking issues): **22.23.4, 24.22.1 or 26.12.1**, or later on the same line. Node 20, 23 and 25 are end-of-life and not supported.
+
+- `package.json` `engines` is `^22.23.4 || ^24.22.1 || >=26.12.1` (npm warns on an older Node; it does not refuse).
+- CI asks `actions/setup-node` for a range, not a bare major (`'>=22.23.4 <23'`, and `'>=24.22.1 <25'` for the Node 24 job). With a bare `22` the action takes whatever 22.x the runner image has cached, which lags behind: the Linux jobs of 2026-10-24 ran 22.23.3 and 24.21.0. With the range an older cached copy does not match, and the action downloads a patched one.
+
+## Dependency updates (cooldown)
+
+Dependabot (`.github/dependabot.yml`) proposes a new npm release only after it has been public for 7 days (14 days for a major version), and a new action release after 7 days. This gives a hijacked release (like the npm worms and `preinstall` payloads of 2025-2026) time to be found and unpublished before it reaches a pull request here. Security updates are not delayed: Dependabot does not apply the cooldown to them. A human still reads every update.
+
+## Install scripts
+
+CI installs with `npm ci --ignore-scripts`: no `preinstall`, `install` or `postinstall` script of any dependency runs. You can install the same way locally.
+
+- Packages with an install script in `package-lock.json` (`npm query ':attr(scripts, [install]), :attr(scripts, [preinstall]), :attr(scripts, [postinstall])'`, or `"hasInstallScript": true`): only **esbuild** (dev dependency, `postinstall: node install.js`). It is not needed: the binary comes in the platform package (`@esbuild/<os>-<arch>`, an optional dependency) and esbuild finds it at run time; the script only checks that binary and, on some systems, copies it over the JavaScript launcher to start a little faster. If a future esbuild ever needs it, run `npm rebuild esbuild` after `npm ci --ignore-scripts` for that package alone.
+- Playwright's Chromium is not an install script: CI downloads it in its own step (`npx playwright-core install --with-deps chromium`).
+- `tools/site-versions.mjs asset` (the release asset) also installs with `--ignore-scripts`.
+- Exception: the Colab notebook (`colab/egatari-tts.ipynb`) installs `onnxruntime-node` with its `postinstall`, which downloads the CUDA execution provider from NuGet; the GPU path does not work without it. The versions there are pinned (`tools/make-colab-notebook.mjs`).
+
+When a dependency is added or bumped, check the list again (`npm query` as above); a new install script needs a reason here and a targeted `npm rebuild <package>` step in the workflows.
+
+## Residual risks (accepted)
+
+After seven independent review rounds of this version line, no high-severity issue is known. The following are known limits that we accept for now; they concern resource use and local trust, not reading or writing outside a deck. Reports that show one of them leading to disclosure or to writing outside the deck are still welcome.
+
+- **Shared temporary caches assume a trusted local computer.** Audio compression works in a private folder (mode 0700, inputs created exclusively with mode 0600, removed afterwards; ffmpeg is started without a shell), but the shared caches for compressed audio and subset fonts in the system temp folder are not checked for ownership or links, and cached entries are reused without re-checking their content. Another local user could plant entries there.
+- **The raw-read check is a maintenance guard, not enforcement.** `tools/test-raw-reads.mjs` looks for direct reads outside the bounded readers by text. It can miss unusual spellings (for example extra spaces, computed property access, `FileHandle.read()`), and it does not scan tests, `vendor/` or non-JS code (the Python TTS tools read without these limits).
+- **Network reads in the TTS test page and the editor's TTS window are not size-limited before buffering.** `lab/irodori.js` and `lab/tts-engine.mjs` check model sizes after download (Kokoro's files are fetched by kokoro-js without a size check), and cached responses and preset voices have no cap. (`tools/get-fonts.mjs` downloads from a fixed commit with a size limit and a SHA-256 check.)
+- **Budgets limit what a deck can make the tools read and produce, not total process memory or time.** Several copies of the same data can exist at once during a build or export, some escaping is allocated before the exact size check, and ffmpeg has no timeout or output limit.
+- **Refused writes are not always free of side effects.** A dev-server save can create and prune a backup before the save itself is refused for size; `npm run ids` writes its files one after another, not as one transaction.
+- **Another local process changing the working folder while a tool runs** (for example swapping a folder for a link between a check and its use) is out of scope.
+
+## Reporting a vulnerability
+
+Please report security issues privately through GitHub's **Report a vulnerability** button (Security → Advisories) on <https://github.com/egatari/egatari-studio>, rather than in a public issue. Include the affected file or command, a minimal deck that reproduces it, and the impact. You should get a reply within two weeks. There is no bug bounty.