shard-wiki/research/260614-tiddlywiki-deep-dive/findings.md

TiddlyWiki — deep dive (findings)

Date: 2026-06-14 · Source: SHARD-WP-0003 T3 · Subject: TiddlyWiki / TiddlyWiki5 (TW5), Jeremy Ruston's self-contained personal wiki.

Why this dive

The synthesis matrix names whole-file write granularity as one extreme of the write-granularity spectrum, anchored by TiddlyWiki. This dive confirms the anchor and the portability extreme it implies — a wiki that is a single HTML file you can email — and finds the twist: TiddlyWiki also has a Node.js file-per-tiddler substrate, so it spans the granularity spectrum the way Logseq spans file/DB (UC-62). The question: how does shard-wiki attach a backend whose entire content is one file?

1. The single-file model

Classic TiddlyWiki ships as one .html file that contains both:

1. the TiddlyWiki core (the JavaScript engine, parser, renderer, UI), and
2. every tiddler (all content), serialized into the file.

Open it in a browser and the file is the running application. There is no server and no build step — the app reconstitutes itself from the file it was loaded from. This is the portability extreme: a complete, self-hosting wiki in a single, emailable, USB-stick-able artifact that runs offline anywhere.

Saving is the catch: a browser page cannot normally overwrite the file it came from, so TiddlyWiki uses "savers" — TiddlyFox/browser extension, the File System Access API, a Node.js server, TiddlySpot/put-savers, or "download a new copy." Crucially, a save rewrites the entire HTML file (core + all tiddlers re-serialized). Hence whole-file write granularity: there is no concept of writing one page in isolation in the single-file mode — every save touches the whole artifact.

2. The tiddler data model

The atomic unit is the tiddler — a named record with fields:

• Core fields: title (the identity), text (the body), tags, created, modified, type (content type, e.g. text/vnd.tiddlywiki, text/markdown), plus arbitrary custom fields (any key→value). A tiddler is effectively a flexible flat record — closer to a typed-field record (UC-34) than to prose-with-frontmatter.
• Everything is a tiddler: not just pages, but tags, macros, templates, themes, plugins, and the wiki's own configuration are all tiddlers. A plugin is a bundle of tiddlers.
• Content markup is WikiText (TW5's own), though type can mark a tiddler as Markdown, JSON, image, etc. Transclusion is native: {{SomeTiddler}} embeds another tiddler; {{SomeTiddler!!field}} embeds a field.

3. The dual substrate — single-file vs file-per-tiddler

TiddlyWiki on Node.js stores each tiddler as a separate .tid file on disk: a small text file with a header of field: value lines, a blank line, then the body. The Node server assembles these into the same wiki at serve time. This substrate is:

• git-diffable and fine-grained — one file per tiddler, line-level diffs, per-tiddler history — the opposite end of the granularity spectrum from the single HTML file.
• the natural attach surface for a versioned, multi-author TiddlyWiki.

So TiddlyWiki spans the write-granularity spectrum by substrate (single-file = whole-file write; Node = file-per-tiddler write), exactly as Logseq spans file/DB (UC-62) and as the backend-swap question (UC-43) anticipates.

4. Native query — filter expressions

TiddlyWiki's query language is filter expressions over tiddler fields, e.g. [tag[todo]!tag[done]sort[modified]] — a compact DSL that selects/orders tiddlers by field and tag. Lists, tables, and dynamic views are built from filters. This is a native-query capability (UC-52 tier) — less expressive than SPARQL/datalog but real, and computed over the tiddler store.

5. Capability profile

Dimension (synthesis spectrum)	TiddlyWiki (single-file)	TiddlyWiki (Node .tid)
Attachment mode	file-store: one HTML file	file-store: dir of .tid files
Addressing granularity	tiddler (title) within the file	tiddler = one file
Content identity	title (placement-bound)	title ↔ filename
Structure	flat record store w/ arbitrary fields + tags	same
History	none in-file (whole-file save)	per-file git history
Merge model	whole-file replace (no merge)	git 3-way per tiddler
Native query	filter expressions	filter expressions
Translation	WikiText (or per-tiddler type: markdown/json/…)	same
Write granularity	whole file (the anchor)	file per tiddler
Operational envelope	trivial — a browser; no server	a Node server
Access grant	file access = full access	server/file perms
Content opacity	transparent (parse the HTML store)	transparent text
Provenance	created/modified fields	git + fields

6. INTENT mapping

Reinforcements

• Graceful degradation: a single-file TiddlyWiki is a trivial read-only / projection / backup shard — parse the tiddlers out of the HTML, project pages; no server needed. The limited-backend-still-usable principle at its simplest.
• Markdown-first but backend-neutral: tiddlers carry a type, so Markdown tiddlers coexist with WikiText — the page model's content-type field maps directly.
• Typed fields (UC-34): arbitrary tiddler fields are a flexible record model the page model already accommodates.
• Backend-swap under stable identity (UC-43): single-file ↔ Node .tid is the same logical wiki on two substrates — the migration UC-43 anticipates, within one engine.

Divergences (boundaries / notes)

• Whole-file write granularity is a real constraint: in single-file mode shard-wiki cannot write one page atomically — an overlay applied "to one page" still rewrites the whole file (T11). This is the coarsest write tier; model it explicitly so overlays/locks account for it (a write to any page conflicts with any concurrent write).
• Identity = title, file-local; cross-shard identity (T16) layered above.
• The app is in the file: when parsing a single-file TiddlyWiki, shard-wiki must extract the tiddler store and ignore the embedded engine — i.e. treat the HTML as a container format, not as page content (don't mistake the app for content).

What to keep

1. Single-file self-contained wiki as a first-class file-store shard — container-format parse, whole-file write granularity (UC-78); the portability/granularity extreme.
2. Whole-file write granularity as a named tier (T11) with overlay/lock implications.
3. Dual-substrate binding (single-file vs .tid dir) as another instance of substrate-choice under one identity (UC-43/UC-62).

7. UC seed

#	Seed	Disposition
UC-78	Attach a single-file self-contained wiki (TiddlyWiki HTML) as one shard — parse tiddlers out of the container, project pages; write = rewrite the whole file (whole-file write granularity, the coarsest tier)	new
—	whole-file write granularity anchor + overlay/lock implications	enrich UC-35
—	single HTML file as a file-store shard (container format)	enrich UC-40
—	tiddler arbitrary fields = flexible record	enrich UC-34
—	filter expressions as a native-query tier	enrich UC-52
—	single-file ↔ Node .tid substrate swap	enrich UC-43

8. Architecture notes for SHARD-WP-0002

• T11 (capability / write granularity): confirm whole-file as the coarsest named write tier (anchored by single-file TiddlyWiki), with the implication that an overlay to any page conflicts with concurrent writes (no per-page atomicity). File-per-tiddler is the fine tier on the same engine.
• T14 (attach binding): a single-file wiki binds as a container-format file-store (parse tiddler store, ignore embedded engine); a Node TiddlyWiki binds as a dir of .tid files (git-diffable). One engine, two bindings — parameterize like UC-43.
• Native query: filter expressions are a low-mid native-query tier between "none" and datalog/SPARQL — delegate where present (UC-52).

9. Open questions

1. In single-file mode, how does shard-wiki represent per-page overlays when writes are whole-file — buffer overlays and re-serialize, or require the Node .tid substrate for write-through and treat single-file as read/projection/backup only?
2. Is a single-file TiddlyWiki's embedded plugins/config ever relevant to the union, or strictly ignored as app-internals (parse only content tiddlers)?
3. Does shard-wiki expose tiddler filter expressions as a delegated query, or only its own union query over projected tiddlers?

10. Sources

• TiddlyWiki.com — Tiddlers, TiddlerFields, Filters, Saving, Node.js docs
• TiddlyWiki5 GitHub (Jermolene/TiddlyWiki5) — .tid file format, store structure
• prior: research/260614-logseq-deep-dive/ (file/DB dual substrate, UC-62)

11. Traceability

New UC UC-78 carries the marker ⊡ in the wikiengines column of spec/UseCaseCatalog.md. Enriched: UC-35, UC-40, UC-34, UC-52, UC-43. Architecture cross-refs: SHARD-WP-0002 T11 (whole-file tier), T14 (dual binding).