Egatari 1.0 is an Editor’s Draft: main is the live draft and may change at any time. Dated snapshots are tagged wd-YYYY-MM-DD (Working Draft); a second snapshot on the same day adds a letter (wd-YYYY-MM-DDb). Implementations say which snapshot they follow (for example, “Egatari Studio 0.4.6 follows Egatari 1.0 WD 2026-10-24”). Nothing is stable before 1.0 is frozen; snapshots exist so that implementations and lessons can name the draft they were built against.
Changes on main after the snapshot; they will be in the next Working Draft.
<div class="caution"> and <div class="caution warn"> (owner, 2026-11-14, from the municipal and medical guides; Studio v0.6.13): the producer adds the label (注意・警告 / Caution・Warning by <html lang>) and role="note"; colour roles --caution and --warn.+++ {"kind": "preface|chapter|appendix|afterword"} before a level-2 section gives it and the following sections that kind, up to the next such line, numbered as files of that kind are. Books keep using files of a kind. §9C.2 admits this one block break; §9C.6 adds data-section-kind; §9C.8 adds the errors and no longer warns that such sections are linked to no slide; §9C.14 lets the AI write the line. New fixtures section-kind, section-kind-all and four invalid cases.tone="emph") is used instead of the ramp; ramps run one way, and a diverging scale keeps its roles./ to /spec/. No change to the text.--ramp-1 … --ramp-5 (owner, 2026-11-10, from the showcase experiment): five stops from low to high for magnitudes (heat maps, densities, speeds), monotone in lightness, interpolated with color-mix() in oklab; never for categories or meanings; the magnitude is also readable without colour; fallbacks from --bg and one role (a component keeps the role it used before ramps).<p class="kicker"> (owner, 2026-11-10, from a comparison with editorial slide designs): an optional short label directly before a slide’s heading; not part of the title, no step of its own, styled by the theme.translate="no" on rendered math, code and component drawings, and keep headings, body, conclusion lines, captions and the article translatable, so that a viewer can read a lesson with the browser’s translation. Taken out of open issue 9A.{lang:<tag>|text} (owner, 2026-11-10, from the sentence-structure sample): a passage in another language inside the narration, spoken with a voice for that language; plain text, not a boundary, lang: reserved; rendered with lang in HTML. §5.4: a turn with spans appends ttsSegments to the inputHash canonical form (turns without spans hash as before; new test vectors). deck-narration gains ttsSegments?, recipe gains voices? (schema), and the device voice (§5.6) SHOULD read a span with a voice for its language.position before seeked, t: null while playing or paused, controls = what controls=0 hides, preview errors in video, stepEnded only when a step plays to its end and ended after the final state, error codes (command name; unsupported for unknown commands).--obj-white … --obj-gray (the eleven basic colour terms) for colours that are the content (balls, litmus paper, signals). The hue family is fixed by the name; never the only carrier (name or initial shown, outline when close to the background); components give a fallback, which may be a literal colour of that name.
ready is sent once per document after parts mount and the opening position settles, before the first position; version is the player’s version, docId is null when absent, slideTitle follows the readable layer, dur is at rate 1 (from Studio’s implementation, 2026-11-09). snapshot becomes OPTIONAL; a player without it replies error with code unsupported.--lit (light and what it lights; a fill colour drawn with an outline; components give a fallback). A colour derived by changing a role’s hue (relative colour syntax) is reported as outside the vocabulary; color-mix() of roles stays allowed.cmi.core.session_time and cmi.core.exit, and the player commits at beforeunload; an informative note explains LMSs that drop commits sent while the page closes.video for a viewer shows one start control (P3) and then advances. SCORM 1.2 binding §2.2: the 4096-character suspend-data limit is reached at about 8,000 steps (exact computation by Studio), not about 3000.
learn mode is removed. Self-study is talk with playback (start/pause, previous/next and jump keeping the playing state, rates 0.75–2 keeping pitch), which every player MUST offer; presenter tools stay. offer.modes and ctx.mode are talk or video; players read a former learn as talk. The notes pane and the learner’s notes (P5) leave the player: P5 keeps per-viewer preferences, and annotations (highlights, comments, kept ink, recall masks, export) move to the informative draft annotations.md for applications that open files (Egatari Viewer, learning platforms).{v:1,t:"join",key,pid}), not in the address, so that they stay out of proxy and server logs; close codes 4400/4403 and a 10 s join deadline; servers MAY keep accepting the earlier query form for older files (from the privacy review, 2026-11-05).unicode-range SHOULD NOT over-claim; a font subset SHOULD depend only on the face and the set of displayable code points (same set, same bytes); informative note that every font stack ends in a generic family, so characters added by tier A edits fall back to a device font.
row-headers makes the first cell of each body row a row header (th scope="row"), styled like the header row; in vertical writing header cells are centred and other cells start at the top (from the rashomon sample’s label column).deck-meta and its schema: creators? (copied from metadata.creators, like license, copyright and attribution), so that a play-only derivative, which has no index, can still show the creators in the information panel (§7.3).:::{table} takes :class:, and the class horizontal keeps a table in horizontal writing. Figures, display math and code stay horizontal.stage and text bitsets beside seen (their union), so that played: true survives a resume, and the 4096-character limit counts all three.<h2> in the lesson language and its items are in a <ul>; per-chapter reference ids use the footnote chapter token (ref-A-key, ref-preface1-key); without metadata.title the book’s title is deck-meta.title; the target line excluded from a section’s hash is the line directly before the next heading.preface<i>/afterword<i>); upright numbers in vertical writing are runs of one or two digits alone, so “3.14” and “12:30” rotate whole; egatari.json MAY carry article (unpacking writes the chapter order, otherwise kind then file name); a narrative citation’s locator is recognised by listed words in the source; an undefined footnote is an error, an unreferenced one a warning; validators check the source or the tree before the transforms; a definition description may hold inline content directly; the “section linked to no slide” warning covers kind: chapter files only. Fixtures: proof-kind-unknown uses prf:hypothesis (algorithm is valid), heading-setext uses a base32 id, new invalid footnote-undefined; FINDINGS 16–19.style or script; the narration as written; passed data as parsed JSON names, strings and numbers; glyphs; pieces joined by a line feed), the same for char and name; block keys MUST be strings (no String() coercion); a bad declaration makes the producer carry the whole part and warn, while registry tools reject it; names is [] when a name entry keeps nothing; sources are read as written into the runtime layer, so data inlined from a file counts and included code does not; the slide source is parsed by the HTML parsing algorithm as a document with scripting enabled and walked in tree order (template contents included, the document type not).build and glyphs as members of the value its factory returns, in the same shape as an element class’s static members; meta never carries them, and its literal grammar is unchanged. This lets one icons part carry the icon data block with subset (match: "name") for every part that uses it.:class: with one or more free names ([a-z][a-z0-9-]*); themes style them, unknown kinds look like plain asides, and goals, inquiry, tryit, reflect, point, summary, advanced, note, warning, history are recommended. Exercises and solutions (:::{exercise}, :::{solution} <label>; mystmd’s exercise extension): exercises numbered per chapter (“問 1.1”), solutions after the exercise or gathered elsewhere, shown closed on screen. Figures with subfigures (nested {figure}, lettered (a), (b)). Narrative citations @key (“Shannon (1948)”; previously outside the subset). {sub} and {sup}. Definition lists (previously outside) and one {glossary} with {term} links. All fifteen proof kinds of mystmd. Label prefixes exr-, sol-, alg-, asm- recommended, term- reserved. §9C.8, §9C.13 JATS rows; Appendix A 7 updated (index, CSV tables, worksheets stay for Text 2). Fixtures: 6 new valid trees and 2 moved from invalid (cite-narrative, definition-list), 6 new invalid cases; the fixture tool adds myst-ext-exercise 1.0.10.:::{aside} <title> (title required, no nesting, no figures inside); theorem-like blocks :::{prf:<kind>} for theorem, lemma, proposition, corollary, definition, example, remark and proof (node proof from mystmd’s proof extension; {proof:<kind>} converts to prf:); footnotes [^name] (paragraphs only; previously outside the subset); table legends (paragraphs after the table in :::{table}); tables with merged cells as one HTML <table> inside :::{table}, with only table/thead/tbody/tr/th/td, colspan/rowspan/align, and text with em/strong/code/sub/sup/br in cells (no Markdown or math, since MyST reads them as HTML), parsed by an allow-list parser and rewritten from the tree. One more Egatari role: ruby {ruby}`下人|げにん` (node egatariRuby, group ruby). Front matter kind: preface, chapter, appendix, afterword; appendices are lettered (A.1, 図 A.1). §9C.1A numbering: asides per chapter like figures, theorem-like blocks per kind as mystmd, footnotes per chapter. §9C.3 label prefixes box-, thm- … recommended; fn- reserved. §9C.6: runtime form of each, ∎ at the end of a proof, footnotes listed at the end of the section (not the page foot), emphasis dots for Japanese emphasis, upright one- and two-digit numbers in vertical writing, repeated table header rows in print, a generated table of contents. §9C.8 item 8, §9C.13 JATS rows, informative TeX and Aozora Bunko conversions. Appendix A 7: what stays for Egatari Text 2. Fixtures: 8 new valid trees (and footnote moved from invalid to valid), 12 new invalid cases; the fixture tool adds myst-ext-proof 1.0.13 and the HTML-table transforms of myst-transforms (existing trees unchanged).index.components lists every required name@version, transitively, and each entry is hashed on its own; a producer that cannot carry a required part refuses to build, and checks report it; readers of such a file warn and play the rest. index.themes entries gain extends (schema), and the parent theme is its own entry. The minimum registry manifest is defined: parts keyed by name with {version, sha256, requires, tag?, license, withdrawn?} (withdrawn keyed by version), and themes with {name, version, sha256, extends?, license}.match: "name"; keys are names [a-z0-9-], kept when they equal a token of the lesson’s text split at every other character; keep lists names chosen at play time; index.components[].subset.names records the kept names (schema). The default "char" is unchanged.v a definition may only add optional members; a reader that finds a higher v than it implements ignores the extension unless the definition says it is compatible; extensions that connect or send data off the device are registered only after the editors review them; what cannot be ignored is a feature in requires, not an extension. extensions.md: statuses draft / candidate / stable / withdrawn (candidate: complete definition, schema, fixtures, one passing implementation; stable: 60 days released without breaking change), how to propose, and the definition template (purpose, data, authoring source, play-only derivatives, network, data leaving the device, when ignored, security, tests, changes). Appendix A 9: the citation-locator fixtures exist.fixtures/article-text/ (32 valid input/tree pairs, 20 invalid cases), made with myst-parser 1.7.5 and four structural myst-transforms steps; npm test re-parses and compares. The table now matches the tree: reference links are link, targets attach to the next node and leave none, math has no enumerated.index.article is {path} (one article.md) or {chapters} (article/<name>.md in reading order; a book); new §9C.1A: front matter chapter numbers a chapter, and numbers then run per chapter (sections 4.1, figures 4.1, equations (4.1), as TeX book/report); numbering: false turns off section numbers; metadata.series {id, title, part?}; one lesson per session carrying its chapter is the usual form of a course, and a book can be built from such lessons (informative merge rules); TeX import mapping (informative). §9C.4: locators are the suffix of cite (checked against myst-parser 1.7.5) and are not interpreted; metadata.citations {style, list} (CSL style id; at least one author–date and one numeric style; lists end / chapter / none); placement stays open (issue 7). §9C.6: headings are numbered and section cross-references show the number; chapter markup. §9C.8: chapter errors. Schemas: index.article.chapters, metadata.series, metadata.citations, metadata.completion.played.step carries via (stage played, text read); completion counts both unless metadata.completion.played is true.fixtures/documents/ regenerated in the 1.0 shape from Egatari Studio v0.6.0-rc.1 (f112bb4, player 1.0.0); every expect.json unchanged. legacy-heading-keys stays a v0.3.1 file as the pre-1.0 draft case; new idless-source (ids assigned at export).define meta is a static object literal (identifier or double-quoted keys, double-quoted string or nested object values); status().failed[] carries element and the reasons meta, factory (not a function, throws, or no element constructor), missing, dependency, duplicate, element (name taken or defining fails); one definition per element name, else the producer refuses to build instead of dropping a required version; subset data is only block:<name> in 1.0; players MAY call layout more often, and a call at an unchanged size MUST be harmless.recipe (owner, 2026-10-28; closes open issue 3): a lesson MUST NOT carry the reference recording a voice was cloned from; it carries only the synthesized narration audio.article-v1 feature, not of the core: a conforming player MAY leave it out (it then shows slides and narration, §9C.10) and, if it implements it, follows P2 and §9C. article-v1 is to be frozen together with 1.0.status() for players and tools (defined parts; failures factory, missing, dependency, duplicate, element); a second define of the same name@version is ignored; define’s meta is a JSON object literal readable without running the part, recorded in index.components also for embedded parts; element names are unique per file (the producer keeps one version and reports the conflict). Rendered fields are named <field>Html (katex), <field>Svg and <field>Map (abcjs); index.components[].renderers in the schema. Subset: the lesson’s text includes attribute values; several entries apply in order; subset.keys is the union of kept keys in code-point order. ctx.report does not itself switch a part to its fallback; only a part that cannot draw does. layout(ctx) is called on laid-out size changes (not transform scaling), font loading, each time the slide becomes current and when the document becomes visible, with instant true and entered false. ctx.slides[].title follows the slide-list title (§8).egatariParts.define({name, version, requires, element}, factory) in dependency order, no imports or player globals, notices directly before third-party data, license and requires in index.components. §6.2 rendering at build time: build.fields with the renderers katex and abcjs, build-assigned data-* attributes, build.subset and glyphs, rendered output read through an element whitelist, renderer recorded. §8.4: context lang, slides, go(), report(); optional layout(ctx). Appendix A 1A is specified.mount); ctx.slides entries carry steps (largest numbered step key) and concl (whether the slide has a conclusion step).entered stays false and viewer input survives. ctx.report codes: data, attr, range, size, layout, theme, error; messages start with [<part name>].schema/rendered-markup-1.json (elements per namespace, attributes, value grammars; style as listed length/keyword properties set one at a time, no colour; fill/stroke only none/currentColor; no URLs). katex options.output may be html for fields whose meaning the part also gives as text. Renderers are recorded once per part as renderers: {<name>: {version, options}} in the data and in index.components. Missing rendered output shows the source as text and reports data. The list admits color: transparent (phantoms), margin/padding/border shorthands without colours, MathML mathsize, width on mtd, separator, largeop and filtered style; xmlns is a namespace check; build.options: {katex: {output: "html"}} declares HTML-only output. SVG fill/stroke on g and svg, stroke on text/tspan. build.subset.data may name block:<name>, a JSON block in the part’s code between /*@egatari-block <name>*/ and /*@egatari-block-end*/, re-serialised canonically; build.subset may be an array.clipPath) MUST be unique across parts and part versions in one file and deterministic.line-break: strict, on slides, the text pane, captions and the presenter’s script; hanging punctuation allowed.§9C.2 article front matter writing-mode (horizontal-tb |
vertical-rl); vertical-rl pages progress right to left, as EPUB page-progression-direction="rtl". Player P2: text size in at least three steps, reflowing, per viewer, following EPUB reading-system user settings; vertical writing turns pages leftward (left arrow and left taps go forward). |
Snapshot for Egatari Studio 0.6.0 (the first release in the 1.0 file shape). It includes everything below, the article layer (§9C) among it, and the first draft of Egatari Player 1.0, now a separate document. Files written to earlier drafts are not compatible (§7.1); they keep playing with their own player.
The 1.0 file shape (owner, 2026-10-25: the format describes the lesson; players are separate and anyone may write one)
player {name, version} is REQUIRED in the index and deck-meta; generator names the producer only; the lesson MUST be playable without the bundled player; an editor that rebuilds tells the user when the player changes; information panels show format, player, producer in that order.<meta> first in <head> (baseline connect-src 'none', every resource data:/blob: only); only extensions that allow network access add their declared destinations (live to connect-src, embed to frame-src); validators, editors and hosts check it. extensions/live.md and extensions/embed.md refer to it.player are pre-1.0 drafts; they keep playing with their own player; 1.0 editors MAY refuse to edit them and point to an earlier editor or migration instructions.data-key and s<n> (every slide has an id; narration headings carry {#id}); ?mode=lecture; :name: in Egatari Text; camera camera-v1 (§8.3A) and zoom in deck-marks — zooming is a component effect (owner, 2026-10-25).entry is no longer required when article is present (schema anyOf); an article-only lesson has no steps, narration or audio in 1.0, its primary face is read. index.article is now in the schema.deck.html structure, kinds of slide, steps including automatic list steps and the conclusion as max + 1, data-at, drawn strokes, motion length with the timing constants, meaning classes, math syntax and the allowed \html… commands, references in the source), §8.2 blocks and turns, §8.6 emphasis marks, §8.7 morphs. docs/contract.md of Egatari Studio is no longer normative.data-from (default 1), the steps attribute, k = clamp(K − from + 1, 0, steps), (k, ∞) outside the range, piecewise-linear mapping of t onto narration cues when the counts match. Declarations a player needs (steps, props, variants, clock, preview) are on the component class in the file; the release manifest only repeats them. New context member entered (first render after entering the slide from elsewhere or by a jump).ctx.slide is the slide’s key (a string), not an element or index; exempt content (data-preview="none", preview: "none") stays hidden even inside a faint ancestor; player and generator may carry title, the name to show people.data-egatari-seed) and the component seed attribute are removed; a component shows variant="<name>" or its default (the first in its manifest); producers may write variant names when making a lesson (owner, 2026-10-26: the seed made the format heavier than the benefit).preview: "none" (answers); authors may mark elements data-preview="none"; Player P1: faint opacity from the theme’s --preview-opacity (default 0.45).note may sound past the end of its step on forward crossings (live and video) and stops on going back, jumping or seeking; tempo is the component’s own (music parts).mode, preview, slide, instant, reset, extend, live?.poll; ctx.deck is not part of the interface) and the theme colour vocabulary (--fg --bg --emph --term --accent2 --muted --line). §4.1 states the draft limitation: components still depend on the bundled player’s globals; Appendix A 1A (blocker) opens the component host interface.metadata.primary and metadata.offer (§1.2), the link syntax (§9.1A), the rule that learner data never enters the file (§9.1B) and completion (§9.2). Player conformance (P9): talk and the read face MUST, learn SHOULD, video MAY. The SCORM 1.2 binding is outside the format.contracts.runtime is removed (contracts is {source}): the data-block layout is the format version, behaviour is the bundled player’s. Tier B rebuilds with the editor’s player; tier C is now updating components or themes beyond their pins. Tier A edits keep player and generator; rebuilding writes the editor’s player, generator and deck-meta.tracking.Viewer input and stage directions
{note:…} — shown only in the presenter’s view; not spoken, not in captions, video or print; outside ttsParts and inputHash.ctx.live under the live rules.ctx.extend(seconds) — a component with viewer input (a timer) MAY extend or shorten the live running time of the current step; durations, the timeline, video and print keep the author’s values. It returns the step’s total extension (ctx.extend(0) reads it).prefers-reduced-motion, a component that declares elapsed time as content (clock, e.g. a countdown) still receives the real t; only decorative motion is dropped.events(k) → [{t, sound, …}]; the player synthesizes bell (count 1–3), chime and note (pitch, dur, vel; chords at the same t) with Web Audio only, forward crossings in live playback only, one mute setting, the same events in video export; never the only carrier of information.Article layer (article-v1, draft, §9C)
article.md at the archive root in Egatari Text 1, a subset of MyST Markdown written into this specification and versioned with it (CommonMark core, $…$/$$…$$ math with labels, :::{figure}/:::{table} with :label:, pipe tables, [](#id) cross-references, [@key] citations against CSL-JSON references.json, and one role {step}`<slideKey>:<stepKey>`); a table of constructs with their AST node types; everything else is rejected or converted.index.article = {path, references?}; the dependency closure includes the references file and article images.sec- + 6 base32 characters, assigned by tools, never by AI authors; each section is wrapped in <section data-section-id> inside <article id="egatari-article">, nested as the last child of the readable layer.data-egatari-step and href="#<slideKey>:<stepKey>"; slides name sections with data-article.index.articleLinks[slideKey][sectionId] = {article, slide}, hashed over source text, not rendered text; also carried in egatari.json.article-v1 is not listed in requires; players without it play the lesson; editors without it are limited to tier A edits on lessons with an article (§7.2).Snapshot for the Egatari Studio release after 0.4.8 (new-lesson flow). It adds one change to WD 2026-10-24b; the article layer (§9C) stays on main as a draft and is not part of this snapshot.
Components (§8.4)
data-egatari-seed on the source root (absent = 0), seed and variant on a component; the variant is a pure function of these; variants never change steps, durations, cues, final content or colors, and never move more than seed 0; editors write a seed once when creating a lesson and preserve it.Second snapshot of the day, for Egatari Studio 0.4.8. It adds four changes to WD 2026-10-24; the article layer (§9C) stays on main as a draft and is not part of this snapshot.
Archive and index
egatari.json: a producer may keep its own state under one producer-named member, which others preserve.egatari.json may pin themes with the same rules as components; index.themes[].version is the theme’s own version.Runtime
deck-narration: optional ttsParts per turn, so that device read-aloud says what the audio would say.First dated snapshot. It covers the draft from 2026-10-17 to 2026-10-24.
Principles
live). Extensions are optional layers; players, editors and hosts conform without implementing any. Reference implementation: Egatari Studio.Archive and index
exportedFrom: marks a copy exported from an authoring folder; dropped when saved as a new lesson.egatari.json; a registry may withdraw a release, and editors offer a rebuild and never substitute silently.Audio and timing
inputHash matches.deck-audio carries kind; players mark synthesized narration.Components and embedding
openLink event (with an optional download flag) for links a sandboxed lesson cannot open itself.camera-v1, draft): zoom and pan in time with the narration.Security (§11)
Extensions
live (draft v1): join a live session from the distributed lesson (questions anchored to a step and region, “I don’t follow”, polls with labels, host replies); one-tap join; window and endpoint limits; a join page; a host acting for a sandboxed lesson (with an endpoint allow-list); one-way setup from the editor with a setup secret no lesson carries; results readers ignore unknown members, and the service records only declared activities.embed (draft v1): click-to-load third-party video and maps with a required placeholder.Open issues added or extended
[@key], presentation chosen by the author); 9A multilingual lessons and right-to-left scripts; 12 extension governance; 13 encrypted lessons.Other