Repository navigation
Speculative Notebook Export
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.
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), andapplication/vnd.notatio.v1+jsoncarrying the answer's MathJSON and the cell's source. Addimage/svg+xmlfor 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
markdowncell, once a notebook has prose cells; today it has none (section 1). -
A message is a
streamoutput onstderr, not anerroroutput (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
.ipynbvalidated against the nbformat JSON schema, under anUPDATE_*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.
The export (built).
-
toIpynb(cells, { title })inpackages/frontend/src/ipynb.ts:59-74returns 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
codecell (:60):sourceis the text as typed (:53),metadata.notatioholds only{ format },epsilorlatex(:52), andidiscell-<position>(:50). - An answer is one
execute_resultwithtext/latex(the TeX wrapped as$\displaystyle …$,:42) andtext/plain(inputform, elseasciimath, else the TeX,:31). A cell with no answer hasoutputs: []andexecution_count: null(:35,:51).execution_countis the cell's position (:41,:50). - Notebook metadata names a kernelspec
epsil("Epsil (notatio)") and alanguage_infoepsilwith 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
markdowncell (:61-64). No other markdown cell is produced. - The button:
#exportinpackages/components/src/notatio-notebook.ts:227-242builds the cells from the live answers (an answer is used only if itssourcestill equals the cell's value,:229-232), writes aBlobofJSON.stringify(…, null, 1)and downloads<title>.ipynb(:233-239); the button is at:331. The only test ispackages/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-5listseval,convert,forms,formats,completion,serve. The format registry has noipynbentry (packages/formats/src/formats.tsregisters InputForm, TeX, MathML, OutputForm, AsciiMath, MathJSON, WL, FullForm, Epsil, Python, GLSL, JavaScript, SVG; PNG is added bypackages/formats/src/node.ts:25-37).
The record (what is persisted).
-
NotebookRecordis{ key, cells, seed }(packages/components/src/notebook-record.ts:25-31);keyis the page path plus the notebook'sidor position (:45-47). A cell is{ id: number, value: string, answer? }(:19-23). -
CellAnsweris{ source, latex, markup?, inputform?, asciimath? }(:8-16).markupis 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
idis stable but the export does not use it (cell-<position>instead). - The notebook is reactive: cells share a
TrackedSymbols -> Allmodule, are scheduled by dependency, and have noOut[n](packages/components/src/notatio-notebook.ts:32-47;packages/components/docs/notebook.md:15-20). So anexecution_countthat 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)._messagesis held on the Out and sent in a different event (:403,:697,:795).jsonis 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
displayreturns{ boxes, text, draws };boxesis StandardForm, TraditionalForm and (for a list) MatrixForm (packages/frontend/src/display.ts:15-16,:47-58);texthasasciimath,inputformand 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); TeXapplication/x-texandtext/x-tex, encoded as the TeX of TraditionalForm (:71-80); MathMLapplication/mathml-presentation+xml(:83-91); MathJSONapplication/mathjson+json(:113-131, the constant isMATHJSON_MIME,packages/boxes/src/render/mathml.ts:45); SVGimage/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 isapplication/mathjson+json; the two disagree. Nothing I found builds that bundle:Prerenderedhasdisplay,latex,html,visual(packages/frontend/src/prerender.ts:19-35). - Two TeX spellings exist: the answer's StandardForm TeX (what
latexholds 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:
renderPlotreturns an SVG string for a plot box (packages/frontend/src/plot-box.ts:748-760);svgOfBoxdraws aGraphicsBoxas 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:Rasterizeaccepts 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). -
ComplexPlotandComplexPlot3Dare 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 aGraphicsBoxholding aRasterBox(packages/frontend/src/complex-plot-box.ts:1-8).reducerewrites a GPU head toRasterize(…)when the environment cannot drawgpubut can drawraster(packages/frontend/src/reduce.ts:455-461). - PNG:
@notatio/rasterrasterizes SVG withresvgin Node, no DOM (packages/raster/README.md:1-30); the PNG format is registered only by@notatio/formats/node(formats.ts:214comment;node.ts:25-37). A browser installs no rasterizer (packages/formats/src/graphics.ts:21-28). - The
Graphics3D,Plot3D,ListPlot3D,BarChart3Dheads (packages/frontend/src/graphics-3d-lowering.ts:21) draw throughGraphics3DBox; I did not read whether any has a static drawing. Assumed: none does.
Environments.
-
PRINT: no engine,linksonly,statictime, surfacesvectorandraster, formTraditionalForm,static: { controls: "sample", samples: 6, columns: 3 }(packages/frontend/src/environment.ts:48,:64-75).PIPEisTTYwith no engine andcontrols: "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
NotebookandCellheads 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.
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 iscell-<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.
toMathMLexists (formats.ts:83-91) but I do not know which viewers render aapplication/mathml+xmlor inline<math>output; from memory, not checked: browsers and JupyterLab can render inline MathML insidetext/html, GitHub's treatment is unknown.text/latexis 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+jsontypes as objects, from memory, not checked). It carries the answer's MathJSON, so nothing the viewer cannot show is lost. Thev1is the version of that payload. The type name is a proposal; whether to reuseapplication/mathjson+json(mathml.ts:45) for the bare expression is an open question. -
text/plaincomes 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"] }.
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
PRINTwithstatic.controls: "pin", a new preset beside the five inENVIRONMENTS(environment.ts:110); it has the shapePIPEalready uses for pinning (:92-100: spread a preset, overridestatic). Name it for what it is (for exampleNOTEBOOK); "ipynb" names a format, not an environment. Why pin and notPRINT's sample:PRINTlays 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 ask = 2 (0 ≤ k ≤ 5), and the body's static form. ADynamicreadout is kept for the renderer or folded withevaluateReadoutsby 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.
PRINTand a pin-reading variant havesurface: ["vector","raster"], soreducerewritesComplexPlottoRasterize(ComplexPlot(…))(reduce.ts:455-461). That reaches an image only where something evaluatesRasterizeover aComplexPlot;Rasterizeas 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>(renderPlotwrites 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 omitsimage/svg+xmland keepstext/plain,text/latexand 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
Graphics3Dfamily. The export writestext/plainand the vendor entry only. -
Prefer SVG to PNG. SVG needs no renderer, works in the browser export, and is exact; PNG needs
@notatio/rasterand so Node (node.ts:25-37). The SVG's themeablevar(--x, fallback)andcurrentColor(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.
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.
-
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.tshas 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 | bytesfor one value (packages/formats/src/registry.ts:16-33); a notebook is many values with sources and metadata. A format entry namedipynbwould be a different kind of thing under the same list. Assumed: keep it a function, and list it where:formatsis not (an.ipynbis a document, not a form of an expression). -
The button already calls
toIpynbwith live answers (notatio-notebook.ts:227-242). Slice 1 extends what it passes (the answer'sjson, its messages), reading both from thenotatio-resultandnotatio-assertevents the cell dispatches (notatio-out.ts:795,:807); the notebook already listens fornotatio-result(:322). KeepingjsoninCellAnsweris 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.
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).
Slice 1, in packages/frontend/src/ipynb.ts, its test, and notatio-notebook.ts:
- Output
display_data(notexecute_result) withexecution_count: null, record id as the cellid, andmetadata.notatioon the notebook (version,key,seed). This changes the existing golden; say so in the commit. - Add
application/vnd.notatio.v1+jsonwithmathjsonandsource, takingjsonfrom thenotatio-resultevent (notatio-out.ts:808). - Write messages as
stderrstreamoutputs, from the cell'smessages(notatio-out.ts:795). -
fromIpynb(file): returns{ key, seed, cells: [{ id, value }] }for a file withmetadata.notatio.version === 1, else throws. - Tests: (a) a golden
.ipynbfor a small notebook (a binding, a value, a message, a cell with no answer, a blank cell), asserted withexpect(actual).toEqual(golden)and regenerated behind anUPDATE_IPYNB=1flag, nevertoMatchSnapshot(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 thenbformatproject (from memory, not checked:nbformat/v4/nbformat.v4.5.schema.jsonin thejupyter/nbformatrepository). No dependency is added by assumption: vendor the schema file next to the golden under test data, or pullajv(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.
-
Pin or sample for a control? Recommend pin: one picture and a caption per cell, where
PRINTlays six values into a grid (environment.ts:48). Sample is one field to change if readers want the range. -
execution_count: null or the position? Recommend null. The notebook has no execution order and noOut[n](notebook.md:15-20); a position shows as a count that means nothing and breaks when a reader reorders. -
Vendor MIME: a new
application/vnd.notatio.v1+json, or reuseapplication/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'sapplication/x-mathjsonagainst the code's constant; one name should win. -
text/htmland 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. -
Messages:
stderrstream orerror? Recommendstderrfor a value with a message,erroronly for a cell with no answer. -
Does the record grow
jsonandmessages, 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. - 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).
-
Kernelspec for a file with no kernel: keep
epsil, or omitkernelspec? Recommend keep, then test in JupyterLab and VS Code (from memory, not checked: a missing kernel is tolerated). If a viewer refuses it, omitkernelspecand keeplanguage_info. - 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.
-
A registry entry named
ipynb? Recommend no (section 4): a notebook is not a value of one expression.
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.