muninn-artifact-formats

# Muninn Artifact Formats

The list below is the single source of truth for what an artifact can be stored as. Read the intent column, pick from the candidates, pass the matching mime to muninn_artifact_add.

The one rule that decides everything

Store the layer that carries the meaning. Let everything below it be regenerated. A description is a record. A rendering is an output. Muninn holds records.

• Mermaid, DOT, D2 are descriptions — claims about what connects to what.

Store the payload alone. If a renderer version shifts the arrangement and the connections are still right, nothing was lost.

• SVG is an arrangement — the placement is the argument. A cropped viewBox, a

footnote placed left of a line so it cannot be misread. It stores as itself.

• Three.js is a program. There is no declarative Three.js; a scene is

imperative code and the code is the content. That stays format: html.

• Charts sit on the seam. The data is a record, the chart is an output. Prefer

storing the data. If you store a config, it must be JSON-only with declarative options and no function callbacks — a tick or tooltip formatter turns data back into code.

Never store a payload and a rendered copy of it. That is the same thing twice, and one copy goes stale. Pick one, and which one is decided by whether the meaning lives in the relations or in the arrangement.

How to read the table

• Candidates are plural on purpose. The table says what is possible. You say

what you can actually write well. Format fluency varies by model and is a write-time judgement, not table data.

• Do not ask the user which format. They described the thing; the artifact

should appear. Decide silently.

• mime is a label. It sets the download extension and nothing else. Muninn

renders nothing from it and gates nothing on it.

• renderable is what the Muninn web app draws today. no still stores fine —

it means the reader gets source and a correct download, not a picture.

The list

intent,candidates,mime,extension,execution,renderable
"show how these connect; boxes and arrows; a flowchart","mermaid|dot|d2|svg","text/vnd.mermaid|text/vnd.graphviz|text/vnd.d2|image/svg+xml",".mmd|.dot|.d2|.svg",inert,yes
"show messages passing between systems; a sequence","mermaid|plantuml","text/vnd.mermaid|text/vnd.plantuml",".mmd|.puml",inert,partial
"show an org chart; a hierarchy; a tree","mermaid|dot|svg","text/vnd.mermaid|text/vnd.graphviz|image/svg+xml",".mmd|.dot|.svg",inert,yes
"show state transitions; a state machine","mermaid|dot","text/vnd.mermaid|text/vnd.graphviz",".mmd|.dot",inert,partial
"show a database schema; entities and relations","mermaid|dot|sql","text/vnd.mermaid|text/vnd.graphviz|text/plain",".mmd|.dot|.txt",inert,partial
"show a timeline; a roadmap; a gantt","mermaid|svg|html","text/vnd.mermaid|image/svg+xml|text/html",".mmd|.svg|.html",inert|executable,yes
"draw exactly this; placement carries the argument; an annotated figure","svg","image/svg+xml",".svg",executable,yes
"plot this data; a bar, line or pie chart","csv|json|chartjs","text/csv|application/json|application/vnd.chartjs+json",".csv|.json|.json",inert,partial
"a chart Chart.js cannot draw; sankey, treemap, calendar heatmap","echarts|html","application/vnd.echarts+json|text/html",".json|.html",inert|executable,partial
"something interactive; it moves; a simulation; a 3D scene","html","text/html",".html",executable,yes
"a 3D model that came out of a modeller or scanner","gltf|glb|obj|stl","model/gltf+json|model/gltf-binary|model/obj|model/stl",".gltf|.glb|.obj|.stl",inert,no
"points and shapes on a map","geojson|svg|html","application/geo+json|image/svg+xml|text/html",".geojson|.svg|.html",inert|executable,partial
"a written document; prose; notes; a report","markdown|html|text","text/markdown|text/html|text/plain",".md|.html|.txt",inert|executable,yes
"a table of records","csv|tsv|json|markdown","text/csv|text/tab-separated-values|application/json|text/markdown",".csv|.tsv|.json|.md",inert,yes
"structured data; a config; an API payload","json|yaml|xml","application/json|application/yaml|application/xml",".json|.yaml|.xml",inert,partial
"a styled page someone opens and reads","html","text/html",".html",executable,yes
"code; a script; a snippet","code","text/plain",".txt",inert,yes
"a document that must paginate, print or be filed","pdf|latex|html","application/pdf|text/x-tex|text/html",".pdf|.tex|.html",inert|executable,no
"a file someone else will edit in Office","docx|xlsx|pptx","application/vnd.openxmlformats-officedocument.wordprocessingml.document|application/vnd.openxmlformats-officedocument.spreadsheetml.sheet|application/vnd.openxmlformats-officedocument.presentationml.presentation",".docx|.xlsx|.pptx",inert,no
"a bundle of files; an export someone downloads","zip|tar|gzip","application/zip|application/x-tar|application/gzip",".zip|.tar|.gz",inert,no
"a picture; a screenshot; a raster image","png|jpeg|webp|gif","image/png|image/jpeg|image/webp|image/gif",".png|.jpg|.webp|.gif",inert,no
"events someone imports into a calendar; contact details","ics|vcard","text/calendar|text/vcard",".ics|.vcf",inert,no

Notes on the names

Registered IANA names are used wherever they exist — image/svg+xml, model/gltf+json, text/vnd.graphviz (DOT really does have a registered vnd. type), application/geo+json, application/yaml.

The rest carry a vnd. prefix, which is the correct convention for an unregistered type rather than a workaround: text/vnd.d2, text/vnd.plantuml, application/vnd.chartjs+json, application/vnd.echarts+json. text/vnd.mermaid is the Mermaid project's own recommended type, pending IANA recognition, not registered.

Registries do not agree with each other and never have. IANA is the registry but nothing ships from it; Windows uses its own Registry; macOS uses Uniform Type Identifiers and keeps MIME only as a web translation; Linux desktops use freedesktop.org shared-mime-info. Mermaid, DOT and D2 are absent from the current freedesktop database. The extension is what actually determines what opens. Do not assume the browser or the OS does anything sensible with the type.

code maps to text/plain and exports as .txt, because a code artifact carries no language tag and a guessed extension is worse than a plain one.

Chart library ranking

Chart.js first, and not close — stable since 2013, the v3/v4 config shape is simple enough to write correctly from memory. ECharts second, for what Chart.js cannot draw (sankey, treemap, calendar heatmap, dual axes, large datasets), and it can render SVG instead of canvas when crisp-at-any-size matters. D3 third: it is not a chart library, it hands you scales and you place things yourself.

Avoid Plotly (heavy, wide API surface), Highcharts (commercially licensed, wrong for anything published), Vega-Lite (good idea, low confidence in spec details). Chart.js draws to canvas, so it does not scale as vector for print or projector.

3D

glTF is the right thing to store — declarative JSON plus binary buffers, and every engine imports it. But it is an export format from a modeller or scanner, not something authorable from a verbal description; the buffers are base64 binary. So: if a 3D asset came out of a tool, glTF is the record. If it came out of your hands from a description, it is a program and stays format: html.

What runs, and what that costs

An html or svg artifact runs sandboxed at an opaque origin, never at its own published address. One document, one load, no human editing afterwards. External scripts from a CDN do load, so Three.js and friends work — but a fetch that can fail is a fetch that will fail in front of an audience. Pre-warm anything being presented live.

---

*A Muninn skill — part of the Muninn memory system.*