Skip to content

Speculative Notebook Export

enumeratio edited this page Nov 15, 2026 · 1 revision

Notebooks as .ipynb

Speculative. A proposal, not adopted.

A notebook's cells already save as a Jupyter .ipynb (an Export button), but the file is thin: Epsil source and one typeset answer per cell. It drops what a reader of the file cannot recompute (the answer as an expression, a plot as a picture, a message, a control) and cannot be read back. This page designs the next step: a richer, schema-checked export that keeps the live form in a vendor MIME entry, reads back its own exports, and leaves a Jupyter kernel for Epsil alone. The Ideas page lists "Notebooks exported as .ipynb" as having no design; the first version exists (packages/frontend/src/ipynb.ts), so this is a design for extending it.

"Measured" means read from the tree at origin/main (path:line) or counted there. "From memory, not checked" marks a statement about nbformat, Jupyter, GitHub or a viewer that I did not look up (no network, no installs, nothing run). "Assumed" is reasoning, not read or run. Nothing here was built, executed or run through a validator.

Recommendation

Extend toIpynb in place; do not add a second exporter.

  • Keep the file honest for a reader and complete for us. Each answer is a MIME bundle: text/plain (InputForm), text/latex (StandardForm TeX), and application/vnd.notatio.v1+json carrying the answer's MathJSON and the cell's source. Add image/svg+xml for a graphic only where a static SVG exists without a kernel.
  • A control is reduced, not exported. The static outputs come from reduce(expr, env) under a pin-reading preset; the live expression stays in the vendor entry (section 2).
  • Prose is a markdown cell, once a notebook has prose cells; today it has none (section 1).
  • A message is a stream output on stderr, not an error output (section 1).
  • Read back only our own exports, from metadata.notatio, into the seed a notebook opens from. A foreign notebook is out of scope (section 3).
  • Test by a golden .ipynb validated against the nbformat JSON schema, under an UPDATE_* flag (the plan).
  • No Jupyter kernel. The export does not wait for one (section 5).

The first slice is small: the vendor MIME entry, stderr messages, a schema-validated golden, and a reader for our own file. Graphics and controls are the second.

What exists

The export (built).

  • toIpynb(cells, { title }) in packages/frontend/src/ipynb.ts:59-74 returns the JSON object of an nbformat 4.5 file (:66-67). It is exported from @notatio/frontend/core (packages/frontend/src/core.ts:27).
  • Each non-blank cell becomes one code cell (:60): source is the text as typed (:53), metadata.notatio holds only { format }, epsil or latex (:52), and id is cell-<position> (:50).
  • An answer is one execute_result with text/latex (the TeX wrapped as $\displaystyle …$, :42) and text/plain (inputform, else asciimath, else the TeX, :31). A cell with no answer has outputs: [] and execution_count: null (:35, :51). execution_count is the cell's position (:41, :50).
  • Notebook metadata names a kernelspec epsil ("Epsil (notatio)") and a language_info epsil with extension .epsil (:69-70). The file says in its header that "there's no Jupyter kernel for Epsil, so the file is for reading" (:1-4).
  • An optional title becomes the one markdown cell (:61-64). No other markdown cell is produced.
  • The button: #export in packages/components/src/notatio-notebook.ts:227-242 builds the cells from the live answers (an answer is used only if its source still equals the cell's value, :229-232), writes a Blob of JSON.stringify(…, null, 1) and downloads <title>.ipynb (:233-239); the button is at :331. The only test is packages/frontend/tests/ipynb.test.ts:11-32: one hand-written object comparison, no schema validation, no golden file.
  • No CLI command writes .ipynb: packages/cli/src/command.ts:1-5 lists eval, convert, forms, formats, completion, serve. The format registry has no ipynb entry (packages/formats/src/formats.ts registers InputForm, TeX, MathML, OutputForm, AsciiMath, MathJSON, WL, FullForm, Epsil, Python, GLSL, JavaScript, SVG; PNG is added by packages/formats/src/node.ts:25-37).

The record (what is persisted).

  • NotebookRecord is { key, cells, seed } (packages/components/src/notebook-record.ts:25-31); key is the page path plus the notebook's id or position (:45-47). A cell is { id: number, value: string, answer? } (:19-23).
  • CellAnswer is { source, latex, markup?, inputform?, asciimath? } (:8-16). markup is the TeX already typeset (:12-13). The record states that answers are kept "only to show at once" and are worked out again from the sources (:3-5).
  • Not in the record: the answer's MathJSON, messages, the library set, the scope, control state. A cell's id is stable but the export does not use it (cell-<position> instead).
  • The notebook is reactive: cells share a TrackedSymbols -> All module, are scheduled by dependency, and have no Out[n] (packages/components/src/notatio-notebook.ts:32-47; packages/components/docs/notebook.md:15-20). So an execution_count that is a position is an invented number, not a count.
  • The event a cell's answer comes from carries more than the record keeps: latex, json, inputform, asciimath, markup, n, name, plot (packages/components/src/notatio-out.ts:807-819). _messages is held on the Out and sent in a different event (:403, :697, :795). json is therefore available at export time but is dropped before the record.
  • A message is { head, code, args, text, hint? } (packages/engine/src/messages.ts:14-23).

Output forms.

  • A kernel's display returns { boxes, text, draws }; boxes is StandardForm, TraditionalForm and (for a list) MatrixForm (packages/frontend/src/display.ts:15-16, :47-58); text has asciimath, inputform and the code forms (packages/frontend/src/kernel-host.ts:27-32, :86-107).
  • Registered formats with a MIME type: InputForm text/plain (packages/formats/src/formats.ts:61-69); TeX application/x-tex and text/x-tex, encoded as the TeX of TraditionalForm (:71-80); MathML application/mathml-presentation+xml (:83-91); MathJSON application/mathjson+json (:113-131, the constant is MATHJSON_MIME, packages/boxes/src/render/mathml.ts:45); SVG image/svg+xml (:193-212).
  • The wiki's Kernels page lists the internal bundle as application/x-mathjson, text/x-epsil, text/latex, text/html, image/svg+xml, text/plain (Speculative-Kernels-and-Front-Ends §9, "Outputs and exports"). The code's MathJSON type is application/mathjson+json; the two disagree. Nothing I found builds that bundle: Prerendered has display, latex, html, visual (packages/frontend/src/prerender.ts:19-35).
  • Two TeX spellings exist: the answer's StandardForm TeX (what latex holds and what the export writes) and the TeX of TraditionalForm (formats.ts:77-78). The export uses the first.

Graphics.

  • Plots, charts and the field plots are heads that "draw" (GRAPHICS_HEADS, packages/formats/src/graphics.ts:93-). On the web a head lowers to a custom element (renderingOf, packages/frontend/src/symbols.ts; Vdom.md, "Realized").
  • Static SVG drawers exist per family: renderPlot returns an SVG string for a plot box (packages/frontend/src/plot-box.ts:748-760); svgOfBox draws a GraphicsBox as SVG with a lattice pinned (packages/frontend/src/show-box.ts:364-375). I found no single function from an arbitrary expression to an SVG string in Node: Rasterize accepts only a value that already carries <svg… text (packages/formats/src/graphics.ts:64-75, :247-264), and the plot lowering reads element attributes (packages/frontend/src/plot-lowering.ts:36-93).
  • ComplexPlot and ComplexPlot3D are GPU heads: on the web a WebGL2 shader draws them; "everywhere else -- Node, a build, a terminal" the same picture is evaluated on the CPU into a GraphicsBox holding a RasterBox (packages/frontend/src/complex-plot-box.ts:1-8). reduce rewrites a GPU head to Rasterize(…) when the environment cannot draw gpu but can draw raster (packages/frontend/src/reduce.ts:455-461).
  • PNG: @notatio/raster rasterizes SVG with resvg in Node, no DOM (packages/raster/README.md:1-30); the PNG format is registered only by @notatio/formats/node (formats.ts:214 comment; node.ts:25-37). A browser installs no rasterizer (packages/formats/src/graphics.ts:21-28).
  • The Graphics3D, Plot3D, ListPlot3D, BarChart3D heads (packages/frontend/src/graphics-3d-lowering.ts:21) draw through Graphics3DBox; I did not read whether any has a static drawing. Assumed: none does.

Environments.

  • PRINT: no engine, links only, static time, surfaces vector and raster, form TraditionalForm, static: { controls: "sample", samples: 6, columns: 3 } (packages/frontend/src/environment.ts:48, :64-75). PIPE is TTY with no engine and controls: "pin" (:92-100). can.drive(env) is "has an engine and some way to move a control" (:172).
  • reduce(expr, env) leaves controls alone where something can drive them, else pins or samples them and writes a caption (packages/frontend/src/reduce.ts:405-446, :475-478); a pinned control takes its start, else the least it allows (:188-197). The order is fixed: reduce, scope, lower (Rendering Environments, "Controls, scope and held heads").
  • The Notebook and Cell heads exist as held heads (packages/formats/src/graphics.ts:220, :238; packages/frontend/src/symbols.ts:1190-1196), so a notebook also has an expression form, Notebook([Cell(…), …]). The record does not use it.

Wiki, as it stands. Notebooks.md §2 says Export "saves the notebook as a Jupyter notebook … which GitHub, Jupyter and VS Code show with its answers typeset." Speculative-Sessions-as-Data lists "A journal as .ipynb" as step 3 and says the journal "is what an .ipynb export serialises." That journal (a transcript the kernel appends to, replayed on open) is not built; the notebook has no Out[n] history.

1. The nbformat mapping

nbformat facts used below are from memory, not checked: the file is JSON with nbformat: 4, nbformat_minor, metadata, cells; cell types markdown, code, raw; from 4.5 each cell has an id matching ^[a-zA-Z0-9-_]+$, 1 to 64 characters; source is a string or a list of strings; a code cell has execution_count (integer or null), metadata and outputs; an output is execute_result (with execution_count), display_data (no count), stream (name stdout or stderr, text) or error (ename, evalue, traceback); data maps a MIME type to a string or a list of strings, JSON MIME types to an object; metadata.kernelspec is { name, display_name, language? } and language_info needs name. The nbformat JSON schema is published in the nbformat project; the repo has no copy (no match for nbformat outside ipynb.ts).

Notebook metadata. There is no Jupyter kernel for Epsil, so the file names a kernelspec that no installation has. Keep the existing kernelspec/language_info (ipynb.ts:69-70) and add metadata.notatio: { version: 1, key, seed, format, environment }. From memory, not checked: JupyterLab and VS Code open a notebook whose kernel is missing, show the cells and outputs, and ask the reader to pick a kernel only on run; an unknown language_info.name means no syntax highlighting. Whether a viewer rejects language: "epsil" is not known; the file as written today is the evidence to test with first.

A code cell.

  • source: the text as typed (RecordCell.value), as a list of lines (ipynb.ts:28-29).
  • id: the record's stable id as a string (c<id>), not the position, so a reordered notebook exports the same ids and a read-back keeps them. Today it is cell-<position> (:50).
  • execution_count: null. A reactive notebook has no execution order, and the position is not a count (above). Viewers show [ ] for null (from memory, not checked); the order of cells in the file is the order. This changes the existing golden (ipynb.test.ts:18, :24).
  • metadata.notatio: { format, locked? } and nothing derivable from the source.

An answer. One output per cell. execute_result carries an execution_count, which is null here; use display_data, which has none and is what a viewer shows without an Out[n] label. A display_data entry is shown by the viewer's richest supported MIME type (from memory, not checked: Jupyter picks by a fixed preference, roughly images and HTML and Markdown and LaTeX and plain, depending on the front end), so each type must be a complete answer on its own.

MIME type Holds Source in tree Who shows it
text/plain InputForm: Epsil you can retype CellAnswer.inputform (notebook-record.ts:14), toInputForm (kernel-host.ts:92-95) every viewer; the copyable value
text/latex $\displaystyle …$, StandardForm TeX CellAnswer.latex (ipynb.ts:42) JupyterLab and VS Code render it through MathJax (from memory, not checked); GitHub: ipynb.ts:2-4 claims typeset answers on GitHub (the repo's statement, not checked here)
image/svg+xml a graphic, where a static SVG exists section 2 Jupyter, VS Code, nbviewer; GitHub (from memory, not checked: it shows PNG for sure, SVG likely)
image/png the same graphic rasterized @notatio/raster (Node only) everywhere; omit in the browser export
text/html static markup CellAnswer.markup is KaTeX HTML do not emit: KaTeX HTML needs its stylesheet and fonts, and GitHub's sanitizer strips scripts and most styling (from memory, not checked)
application/vnd.notatio.v1+json { mathjson, source, environment } notatio-result json (notatio-out.ts:808) only us: our front end re-renders live; a future JupyterLab MIME renderer

Decisions behind the table:

  • MathML is not emitted. toMathML exists (formats.ts:83-91) but I do not know which viewers render a application/mathml+xml or inline <math> output; from memory, not checked: browsers and JupyterLab can render inline MathML inside text/html, GitHub's treatment is unknown. text/latex is the portable choice. Revisit if a viewer is found where LaTeX fails and MathML works.
  • The vendor type is application/vnd.notatio.v1+json, a JSON object (nbformat stores +json types as objects, from memory, not checked). It carries the answer's MathJSON, so nothing the viewer cannot show is lost. The v1 is the version of that payload. The type name is a proposal; whether to reuse application/mathjson+json (mathml.ts:45) for the bare expression is an open question.
  • text/plain comes first in intent (it is the fallback and the only thing every viewer shows) even though viewers, not file order, decide what is drawn.

Markdown cells. The notebook has no prose cell today (RecordCell is a source string, notebook-record.ts:19-23; the docs list "convert a cell into full-width block markup" as roadmap, packages/components/docs/notebook.md:35-37). When prose cells exist, they export as markdown cells; the $…$ islands are Epsil's LaTeX and are valid Markdown math for Jupyter's renderer (from memory, not checked), written unchanged. The repo records one viewer quirk: GitHub prints a Markdown cell's code-fence language as a line of code (ipynb.ts:3-4), so avoid fenced blocks with a language in prose cells and use indented or inline code. The Markdown dialect the notebook reads is readMarkdown/toMarkdown (packages/boxes/src/render/markdown.ts:1-8).

Messages. A message (Head::code text, messages.ts:14-23) is a diagnostic that sits beside a value, not a failure: the head declined and the expression stays unevaluated. An error output has ename, evalue, traceback and in Jupyter marks the cell as failed (from memory, not checked); that is wrong for a value that was answered. Write each as a stream output, name: "stderr", text Head::code: text (plus hint on a new line), after the display_data. A cell that fails to parse or evaluate (status: "error", notatio-out.ts:781-785) has no answer; its message is an error output with ename the code and evalue the text. The record does not keep messages (above), so an export from the record, rather than from live answers, omits them unless the record grows a field.

A worked cell. Cell Sqrt(a^2 + 1) after a := 5, one answer, one message:

{
  "cell_type": "code",
  "id": "c2",
  "execution_count": null,
  "metadata": { "notatio": { "format": "epsil" } },
  "source": ["Sqrt(a^2 + 1)"],
  "outputs": [
    {
      "output_type": "display_data",
      "metadata": {},
      "data": {
        "text/plain": ["Sqrt(26)"],
        "text/latex": ["$\\displaystyle \\sqrt{26}$"],
        "application/vnd.notatio.v1+json": {
          "mathjson": ["Sqrt", 26],
          "source": { "text": "Sqrt(a^2 + 1)", "format": "epsil" }
        }
      }
    }
  ]
}

The mathjson value is illustrative: I did not evaluate this cell. The id, display_data and execution_count: null differ from today's output (ipynb.test.ts:15-29). A message would add { "output_type": "stream", "name": "stderr", "text": ["Head::code: …\n"] }.

2. Controls and dynamic content

A cell with a Slider and a plot that follows it has no static meaning: the answer is a function of state the file does not hold. The rule already exists: an environment with nothing to drive a control pins or samples it, and the expression is rewritten before anything renders (Rendering Environments; reduce, packages/frontend/src/reduce.ts:475-478).

  • The export reduces under a pin-reading environment. Use PRINT with static.controls: "pin", a new preset beside the five in ENVIRONMENTS (environment.ts:110); it has the shape PIPE already uses for pinning (:92-100: spread a preset, override static). Name it for what it is (for example NOTEBOOK); "ipynb" names a format, not an environment. Why pin and not PRINT's sample: PRINT lays six values out in a grid (environment.ts:48), which is right for paper and large in a notebook cell; a pin is one picture with a caption (captions, reduce.ts:416, :446) that says which values it shows. That is a judgement; sampling is one field away.
  • What the reader of the file sees: each control replaced by its start value (pinValue, reduce.ts:188-197), a caption such as k = 2 (0 ≤ k ≤ 5), and the body's static form. A Dynamic readout is kept for the renderer or folded with evaluateReadouts by a host that evaluates (reduce.ts:340); the export has the engine at that point (the live notebook, or a kernel in Node), so it folds.
  • What the file keeps live: the vendor entry holds the unreduced MathJSON, so our front end opens the cell with its controls. The static MIME entries are derived from it and are never read back.
  • GPU plots. PRINT and a pin-reading variant have surface: ["vector","raster"], so reduce rewrites ComplexPlot to Rasterize(ComplexPlot(…)) (reduce.ts:455-461). That reaches an image only where something evaluates Rasterize over a ComplexPlot; Rasterize as declared needs an expression that already carries SVG text (graphics.ts:64-75, :247-264). The CPU path (complexPlotBox, complex-plot-box.ts:1-8) exists; whether it can be reached from an answer's MathJSON to an SVG string with an embedded raster is not shown by anything I read. Assumed: a builder wires it, as the terminal and the build already draw the same picture (complex-plot-box.ts:5-7).
  • Where the SVG comes from. In the browser the plot element has already drawn an <svg> (renderPlot writes one, plot-box.ts:748-760); the export button can take that node's markup. In Node there is no expression-to-SVG function (Graphics, above), so a Node export (section 4) can write static SVG only for the families that have a drawer there, and otherwise omits image/svg+xml and keeps text/plain, text/latex and the vendor entry. A picture that cannot be drawn statically is left out; it is not replaced with a placeholder image.
  • 3D. Assumed: no static form for the Graphics3D family. The export writes text/plain and the vendor entry only.
  • Prefer SVG to PNG. SVG needs no renderer, works in the browser export, and is exact; PNG needs @notatio/raster and so Node (node.ts:25-37). The SVG's themeable var(--x, fallback) and currentColor (packages/raster/README.md:15-19) must be flattened to concrete colours first or the SVG renders without them in a viewer with no page stylesheet; the same flattening exists for the rasterizer (flattenCss) but its use for plain SVG output is a builder's check.

3. Fidelity and the round trip

What an export loses, and where it is kept:

Lost from the live notebook Kept in
the cell's stable id cells[i].id (c<id>), read back
the author's seed, the page, the notebook's key metadata.notatio.{seed,key}
answers as expressions vendor MIME entry, mathjson
control state and the live expression vendor MIME entry; static entries are the reduction
the notebook's library set and scope not kept; a notebook's libraries come from the page and catalogue (assumed, not read in notebook-record.ts or notatio-notebook.ts); metadata.notatio may name the catalogue version
messages, unless live stream outputs, when exported from live answers
the reader's drag order the order of cells
Transient -> True not an export concern (notatio-notebook.ts:57-58)

Reading back our own export is in scope and exact where it matters: sources, order, ids and format, which are the record (RecordCell, notebook-record.ts:19-23) and the seed. Answers are not read back: the record states they are recomputed (notebook-record.ts:3-5), so the reader takes source and id, discards every output and lets the notebook evaluate. The guard is a file with metadata.notatio.version it knows; a file without it is refused, not guessed at. Tested by: export a notebook, read it back, and require the record's cells (id, value) to equal the original, plus a check that a notebook exported from a read-back equals the first export. That test is fast and deterministic and so is a standard-run test (AGENTS.md, Testing).

Reading a foreign notebook is out of scope: code cells in Python, R or Julia are not Epsil, and mapping a notebook's markdown cells into prose cells needs the prose cells above. A foreign file with no metadata.notatio is rejected with a message, not partly imported.

4. Where it lives and how it is invoked

  • The mapping stays in @notatio/frontend (ipynb.ts), pure: cells and answers in, a JSON object out, no DOM, no Node. It already imports nothing (ipynb.ts has no imports). The new inputs (MathJSON, messages, an SVG string) are arguments, which keeps it a browser-safe function that a Node caller can use.
  • Not a registry format. The registry's contract is encode(value) -> string | bytes for one value (packages/formats/src/registry.ts:16-33); a notebook is many values with sources and metadata. A format entry named ipynb would be a different kind of thing under the same list. Assumed: keep it a function, and list it where :formats is not (an .ipynb is a document, not a form of an expression).
  • The button already calls toIpynb with live answers (notatio-notebook.ts:227-242). Slice 1 extends what it passes (the answer's json, its messages), reading both from the notatio-result and notatio-assert events the cell dispatches (notatio-out.ts:795, :807); the notebook already listens for notatio-result (:322). Keeping json in CellAnswer is the other way, and costs a record-schema change for what is an export-only value; leave the record as is, and export from live answers.
  • A CLI command (notatio export notebook.json --to ipynb) would evaluate cells in Node: createKernel(ce, catalogue, NOTEBOOK_KERNEL) is already used there by the site build and a test (Kernels page §9; web/.vitepress/theme/engine-libraries.test.ts:56). It needs an input file to read, and the record is in IndexedDB, not a file; the only file form of a notebook today is a page's seed. Defer; it is the only place PNG (@notatio/raster) would be reachable (node.ts:25-37). A Node export also lets a guide's seed notebook be exported at build time; that is a different feature and not designed here.
  • Node-only pieces: rasterizing (PNG) and any CPU field-plot drawing that is not already browser-safe. The browser export ships SVG, TeX, text and JSON only.

5. The line to a Jupyter kernel

This design writes a file and reads our own back; it never runs Epsil inside Jupyter. A Jupyter kernel for Epsil would add execution there: run a cell in JupyterLab or VS Code and get the same answers. It needs the Jupyter messaging protocol (from memory, not checked: ZeroMQ sockets and a connection file, with a Node or Python process holding the engine) or an in-browser kernel (JupyterLite or a xeus-style kernel running in the page, from memory, not checked), plus the kernel's display as a MIME bundle, which is the bundle this page defines. The export does not wait for it: the file is useful as a reader's copy today (the existing header says so, ipynb.ts:1-4), and the bundle is a prerequisite for a kernel, not a rival to it. The kernel-and-front-end split is in Kernels and Front Ends; its KernelSession is the seam a Jupyter front end would plug into (not read in detail here).

Plan for a builder

Slice 1, in packages/frontend/src/ipynb.ts, its test, and notatio-notebook.ts:

  1. Output display_data (not execute_result) with execution_count: null, record id as the cell id, and metadata.notatio on the notebook (version, key, seed). This changes the existing golden; say so in the commit.
  2. Add application/vnd.notatio.v1+json with mathjson and source, taking json from the notatio-result event (notatio-out.ts:808).
  3. Write messages as stderr stream outputs, from the cell's messages (notatio-out.ts:795).
  4. fromIpynb(file): returns { key, seed, cells: [{ id, value }] } for a file with metadata.notatio.version === 1, else throws.
  5. Tests: (a) a golden .ipynb for a small notebook (a binding, a value, a message, a cell with no answer, a blank cell), asserted with expect(actual).toEqual(golden) and regenerated behind an UPDATE_IPYNB=1 flag, never toMatchSnapshot (AGENTS.md, Testing; a precedent: UPDATE_CARRIER_PICKER, packages/frontend/tests/carrier-picker.test.ts:2, :32); (b) the round trip above; (c) validate the golden against the nbformat v4.5 JSON schema. The schema comes from the nbformat project (from memory, not checked: nbformat/v4/nbformat.v4.5.schema.json in the jupyter/nbformat repository). No dependency is added by assumption: vendor the schema file next to the golden under test data, or pull ajv (not checked whether the repo has it) as a dev dependency; the owner decides which (Open questions).

Slice 2: 6. A pin-reading NOTEBOOK preset; reduce the answer's expression before writing the static entries; fold Dynamic readouts. 7. image/svg+xml from the plot element's drawn <svg> in the browser export, colours flattened; golden covers one plot and one cell with a control. 8. The golden for (7) pins the PRINT-like reduction's caption text.

Slice 3 (only if wanted): 9. A Node notatio export, PNG, and a prose-cell mapping once prose cells exist.

Open questions, with recommended answers

  1. Pin or sample for a control? Recommend pin: one picture and a caption per cell, where PRINT lays six values into a grid (environment.ts:48). Sample is one field to change if readers want the range.
  2. execution_count: null or the position? Recommend null. The notebook has no execution order and no Out[n] (notebook.md:15-20); a position shows as a count that means nothing and breaks when a reader reorders.
  3. Vendor MIME: a new application/vnd.notatio.v1+json, or reuse application/mathjson+json (mathml.ts:45)? Recommend the new type: it holds the source and environment as well as the expression, and carries its own version. Also settle the Kernels page's application/x-mathjson against the code's constant; one name should win.
  4. text/html and MathML in the bundle? Recommend neither: KaTeX HTML needs assets a viewer lacks, and nothing in the tree says which viewers read MathML. Add one only with a viewer in hand that shows it.
  5. Messages: stderr stream or error? Recommend stderr for a value with a message, error only for a cell with no answer.
  6. Does the record grow json and messages, or does export read live answers? Recommend live answers: the record is a display cache that the notebook recomputes (notebook-record.ts:3-5), and keeping export-only data in it makes it larger and a schema change. The cost: an export from a record with no live notebook, such as a future Node command, recomputes.
  7. Validate with the nbformat schema by vendoring the file or by a dev dependency? Recommend vendoring the one schema file (a few hundred lines, not read) beside the golden, with its source version in a comment: no dependency, no network in tests. The owner should confirm the licence of copying it (from memory: BSD-3, not checked).
  8. Kernelspec for a file with no kernel: keep epsil, or omit kernelspec? Recommend keep, then test in JupyterLab and VS Code (from memory, not checked: a missing kernel is tolerated). If a viewer refuses it, omit kernelspec and keep language_info.
  9. Round trip: reject or best-effort a foreign file? Recommend reject with a message. A guess that imports Python cells as Epsil sources is wrong silently.
  10. A registry entry named ipynb? Recommend no (section 4): a notebook is not a value of one expression.

Measured versus assumed

Measured (read at origin/main): the whole of ipynb.ts (74 lines) and its test (32 lines); notebook-record.ts; the export and reactive-notebook parts of notatio-notebook.ts; the notatio-result event's fields and the held _messages in notatio-out.ts; Message in messages.ts; Display/displayBoxes; the formats registry entries and MIME types in formats.ts and node.ts; the environment presets, can.drive, reduce and pinValue; svgOf/Rasterize, renderPlot, svgOfBox, the complex-plot-box.ts header, @notatio/raster's README; the Cell and Notebook declarations; the wiki pages named; that ipynb appears in no CLI file and in no registry entry; that no nbformat schema is in the tree.

From memory, not checked: every nbformat schema fact in section 1 (4.5 cell ids, output types, +json MIME objects, kernelspec and language_info fields, the schema's path in jupyter/nbformat, its licence); how JupyterLab, VS Code, nbviewer and GitHub treat a missing kernel, text/latex, SVG, HTML, MathML and an execution_count of null; GitHub's sanitizer; the Jupyter messaging protocol and JupyterLite/xeus.

Assumed: that the plot element's drawn <svg> can be taken at export time; that no Graphics3D head has a static form; that a Node path from a field plot's MathJSON to an SVG with an embedded raster can be wired; that a notebook's library set is not in the record; that pinning rather than sampling reads better in a viewer; that ajv is or is not already a dev dependency.

Not determined: whether any viewer rejects language: "epsil"; whether prose cells are about to land; the end-to-end route from an answer to SVG for each plot family; what KernelSession offers a Jupyter front end.

Home

Project

Working

Design: every design page, by subject

Clone this wiki locally