Please note, the below instructions are loosely organized by priority, with most important being at the top.
CRITICAL RULE FOR ALL AGENTS: If you need source context that is NOT available locally within this repository (such as vanilla TiddlyWiki core files or external third-party plugins), DO NOT attempt to find or download it yourself. Instead, you MUST explicitly ASK THE USER (THE DEVELOPER) to provide the relevant context manually.
PHILOSOPHY: Lithic is one portable file. A wiki must open and work with no network at all, on a USB stick, over file://, or on a machine that has never been online.
REQUIREMENT:
- No runtime loads from another host. No plugin, widget, theme or library may fetch a script, stylesheet, font, model, or data file from a CDN or any other URL when the wiki runs. This includes
<script src>,<link>,@import,import(),fetch()of a remote URL, and web fonts. - Vendor every dependency into the repository. Third-party code is either a pinned entry in
external.yml(fetched at build time and bundled into the artifact) or a copy tracked underwiki/local-plugins/. Never leave a live external URL in a tiddler, and never rely on a host being reachable. - Bundled means embedded. The shipped artifact must carry every file it needs. Check this in the built output, not just the source, because a CDN URL can hide inside a minified bundle.
- A new plugin is judged by this first. Before adding or keeping a plugin, confirm its assets are bundled and that it opens with the network disconnected. A plugin that cannot is not accepted until it is vendored.
- Approved exception: the ESP32 flash offer. The launcher's Web Serial flash offer may fetch its firmware images (about 5 MB) from the project's GitHub at runtime, from the
esp32-firmwarebranch (raw.githubusercontent.com) thatesp32-firmware.ymlreplaces on every firmware build. Not from the release assets the same workflow publishes: GitHub answers a release download with a redirect to a storage host and neither hop sends anAccess-Control-Allow-Originheader, so a page cannot read one however healthy the release is. This is the one permitted runtime load from another host, and it applies only to that offer. Nothing else in the launcher or the wiki may follow it, and the rest of the offline rules still hold.
CONTEXT:
Every push to main starts a release, and the developer monitors that pipeline personally. An agent that polls run status, conclusions, logs or artifacts after a push only reports what the developer is already reading, and it spends the session doing it.
STANDARD OPERATING PROCEDURE:
- Push when asked, report the pushed commit, and stop there.
- Do NOT query the GitHub Actions API, do NOT watch or summarize run status or conclusions, and do NOT re-fetch to check whether a release commit has landed.
- Leave the pipeline entirely to the developer, who will pull the rebuilt artifacts when the release lands.
CONTEXT: The wiki is assembled in CI from tracked sources. Knowing what is a tracked SOURCE vs. ephemeral BUILD STAGING is critical: editing staging is always wrong, and placing "live" content under staging/archive paths silently corrupts builds.
| Path | Role |
|---|---|
wiki/local-plugins/<name>/ |
TRACKED SOURCE OF TRUTH for all Lithic-authored plugins/patches. Edit here. |
wiki/local-plugins/archive/ |
TRACKED reference copies of RETIRED plugins. Never edit; excluded from builds by both scripts/mirror.js and scripts/flatten-plugins.js. |
vendored.yml + vendored-lock.json |
TRACKED manifest for libraries baked INTO a Lithic plugin (pele in lithic-patch-mermaid, pdfjs-dist in lithic-import-handler, jspython-interpreter in tw-jspython). scripts/vendor-libraries.mjs fetches each upstream at build time, twiki-izes it into the plugin's own .tid (front matter kept verbatim, body replaced, CRLF, no trailing newline) and records the version and hashes in the lock, so the repo's plugin is complete without a network. Unpinned entries follow upstream's latest release; pin: freezes one. The refresh runs BEFORE mirror.js, and the bytes it writes are committed on the release branch the same run opens, so they ride the existing review pull request. See Vendored Libraries. |
external.yml + external-lock.json |
TRACKED dependency manifest for third-party plugins (fetched fresh at build time). The lockfile caches REMOTE revisions (ETag/Last-Modified) only — the fetched artifacts in wiki/external/ are gitignored, so mirror.js re-fetches any source whose local artifact is missing even when the lockfile matches. Includes the flibbles/uglify build-time compression tool (pinned via the same ETag mechanism). |
wiki/external/ |
Gitignored MERGE CACHE: external.yml downloads with wiki/local-plugins/* copied over them. Regenerated by npm run mirror on every build. |
wiki/plugins/, wiki/themes/, wiki/tiddlers/ |
GITIGNORED BUILD STAGING derived from the above by scripts/flatten-plugins.js (which wipes wiki/plugins/ + wiki/themes/ first, every run). Fully regenerable — NEVER edit or commit. |
wiki/tiddlywiki.info, wiki/output/, wiki/*.log |
Generated build config, artifacts, and logs. Not tracked. |
variants/ |
TRACKED committed build variants NOT needed by the Tauri app (which bundles only src/): prod.html (plain-named copy of the uglified flagship, committed by release runs) and pre.html (legacy stale build — do not use for validation). Non-prod CI runs commit variants/<env>.html. |
src/launcher.html |
TRACKED GENERATED artifact — the shipped launcher, built from launcher-ui/ by scripts/build-launcher.mjs. Never hand-edit, and never publish a local build: npm run build:launcher is a TEST, not the delivery path — it exists so you can run a launcher change and so npm run check:push has something to compare against. The committed bytes are produced by the release pipeline (build-wiki.yml runs npm run build:launcher and commits the result alongside the PWA bump), so a newer artifact arrives by PULL and never by hand. See GENERATED ARTIFACTS ARE CI-ONLY under GitHub Actions Build Process. It is the ONLY launcher artifact: the Tauri bundle (tauri.conf.json), the smoke/Puppeteer tests, the preview workflow, the server image and autoupdate.sh all reference this one name. src/lithic.html sits beside it as the engine it fetches. Never gitignore it or git rm --cached it: committing it IS publishing it — deploy/autoupdate.sh pulls this path from raw.githubusercontent.com on a timer to update running self-host instances, and deploy/Dockerfile COPYs it (a missing file fails the image build). Self-host has no build step at update time, so the committed file is its only delivery channel. |
assets/legacy-launcher.html |
TRACKED ARCHIVE of the retired hand-written launcher (the behavioral reference for the Svelte port). Read-only: launcher-fragments/ is extracted from it and scripts/inject-launcher-plugins.js maintains its defaultPlugins. Not shipped anywhere. |
STANDARD OPERATING PROCEDURE:
- To modify a Lithic plugin/patch, edit files under
wiki/local-plugins/<plugin>/ONLY. Never editwiki/plugins/**orwiki/external/**— both are regenerated from scratch at build time and any changes there are silently discarded. - If you ever find a Lithic-authored patch under
wiki/plugins/(e.g. a "live"lithic-patch-*), STOP — that is either a stale artifact of a previous build or an archive leak. Fix the source underwiki/local-plugins/and delete the staging copy. Nevergit addanything underwiki/plugins/. - To RETIRE a plugin, MOVE it from
wiki/local-plugins/intowiki/local-plugins/archive/and remove it from the<env>-tiddlywiki.infoplugin lists. To revive it, move it back OUT ofarchive/and re-add to config — do not edit archived copies in place. - Third-party plugin updates happen via
external.yml(+npm run mirror), never by editing mirrored copies. - After adding/moving plugins, verify parity: run
node scripts/mirror.js && node scripts/flatten-plugins.jsand confirm the flatten manifest contains no[SKIP]/[ERROR]entries for your plugin.
CONTEXT: There are two shapes of third-party code in the wiki, and they are updated by two different mechanisms.
- Third-party plugins (
external.yml) are fetched at build time intowiki/external/, a gitignored cache, and never live in the repo. - Libraries baked into a Lithic plugin (
vendored.yml) are twiki-ized into a.tidunderwiki/local-plugins/, committed, and shipped inside the artifact, so the plugin is complete in the repo and the built wiki needs no network at all (see Every Plugin Works Offline).
Those baked-in files used to be pasted in by hand, which lost three facts: which upstream file they came from, which version they are, and whether the copy on disk still matches either. vendored.yml is that record and scripts/vendor-libraries.mjs is what keeps it true. It replaces only the BODY of the target tiddler: the front matter (title, type, module-type) is Lithic's description of the module and is never derived from upstream.
STANDARD OPERATING PROCEDURE:
- Commands.
npm run vendorrefreshes every entry from upstream and rewrites its.tid;npm run vendor:checkis the offline gate (does the body on disk hash to whatvendored-lock.jsonsays). Add--dry-runto fetch and transform without writing,--only <name>for one entry,--pin <name=version>to reproduce a specific version,--summary <path>for the markdown the workflow publishes, and--best-effort(CI only) so an unreachable registry keeps the repo's bytes instead of blocking a release. Wrong bytes always fail: a 404 for a pinned version, a missing file in the tarball, a tarball that does not match the registry'sintegrity, a body underminBytes, or a body missing anexpectstring. - Adding a library is four lines in
vendored.yml(name,package+fileor aurl,target) plus the body's needs:transform.replace(eachfrommust match, so an upstream rename fails the sync rather than silently doing nothing) andtransform.append(how pele's browser-global build becomes a TW library module). Thennode scripts/vendor-libraries.mjs --adoptrecords the bytes already in the repo, and the next refresh fills in the real version. - Pinning is opt-in. An entry with no
pin:follows the registry'sdist-tags.lateston every build, which is the point of the mechanism. An entry withpin:is frozen, and the pin is a deliberate decision:pdfjs-distis pinned at 3.11.174 as a CEILING, not a bookmark. Version 4 moved to.mjsbuilds and droppedbuild/pdf.min.js;lithic-import-handlerloads a UMD global (pdfjsLib) as a TW library module and hands the worker tiddler its own copy of the worker script. Moving past 3.x is a migration of that plugin, not a version bump, and the two pdfjs entries must always carry the same version or the worker's message protocol drifts from the API it talks to.- Never add
wiki/local-plugins/tw-react/tovendored.yml.lithic-patch-whiteboardis the consumer: that whiteboard is a decoupled TiddlyWiki port of an older, much smaller TLDraw, and React 19 is the runtime it was ported onto, so an automatic bump would move the runtime out from under the port. It stays hand-managed, on purpose: a React upgrade there is a whiteboard migration, never a version bump, and no weekly run may decide it. tw-jspython's engine is the npm packagejspython-interpreter, notjspython. The package namedjspythonis an unrelated 0.0.3 by another author and ships no interpreter; the real project (github.com/jspython-dev/jspython) does not commitdist/either, so the npm tarball is the only place its browser build exists. That build is already UMD and takes theexports/modulebranch TiddlyWiki provides, so the entry needs no transform.
- Where it runs, and why there is no second pipeline. The refresh is a step in
build-wiki.yml(prod only, beforemirror.js), and the same run already stages everything on arelease/<stamp>branch and opens a review pull request, so the updated library and the artifact built from it arrive together in THAT review.schedule:adds a Monday tick (05:17 UTC) for the same workflow, which is the only reason the tick exists. It is prod only because a variant build ships the bytes committed on its branch, which is what makes a variant reproducible. - After a pdfjs change, run the behavioural half by hand:
npm run test:pdf-artifact [artifact]. The text comparison incheck-pdf-plugin-unminified.mjsproves the artifact carries the bundle; only the pixel test proves the import still renders pages.scripts/vendor-libraries.mjs --checkruns innpm run check:push, so a vendored.tidedited by hand fails before it is pushed.
WHAT THE MECHANISM ALREADY FOUND (2026-10-21): the pdfjs bundles in the repo were mojibake-damaged (UTF-8 bytes read as Latin-1 and re-encoded, so if (t[0] >= "ï") had become t[0] >= "ï") and had lost pdfjs's @licstart licence banner somewhere in the paste. The refresh restores both: the body becomes upstream's UTF-8, banner included, at the same pinned version. Pele's vendored bytes, by contrast, reproduce EXACTLY from pele@1.7.0 dist/pele.global.js plus the appended export line, which is what proves the fetch → tar → CRLF → transform path is faithful rather than merely close.
WHY (incident history): an archive-leak bug (mirror.js copied local-plugins/archive/ into wiki/external/, and flatten-plugins.js re-materialized it into wiki/plugins/) produced "live" shadow patches in the staging area, and stale mirror output (wiki/plugins/D&DTools/ from a retired source) was nearly mistaken for tracked source. Fixed 2026-09; the archive guards + gitignore entries exist so this cannot recur.
CONTEXT:
TiddlyWiki parses .tid files and relies on specific formatting for headers and body content.
PROBLEM:
Including a trailing newline at the end of a plugin *.tid file can sometimes cause formatting or parsing issues within the wiki.
STANDARD OPERATING PROCEDURE:
When creating or editing plugin *.tid tiddlers, make sure that they DO NOT have a trailing newline after the last character of the body content.
To guarantee this, after creating or editing a tiddler you should always execute the provided trim.ps1 script, passing in the paths of the files you modified:
powershell -ExecutionPolicy Bypass -File c:\Users\temp\Lithic_Dev\Lithic\assets\trim.ps1 -Files <path_to_file>
Additional conventions: repo .tid files are CRLF-encoded — if your editing tool wrote LF, convert to CRLF first (see Environment & Workflow Notes). Pass one path per -Files invocation; the comma-joined multi-path form had $_ quoting issues and silently did nothing.
Bad Example (Trailing newline):
title: $:/config/lithic/sidebar-visibility/$:/core/ui/SideBar/More
type: text/vnd.tiddlywiki
hide\nGood Example (No trailing newline):
title: $:/config/lithic/sidebar-visibility/$:/core/ui/SideBar/More
type: text/vnd.tiddlywiki
hideCONTEXT: Lithic is a highly opinionated, single-user PKMS. The following design decisions are intentional and should be respected when suggesting or implementing features. Do NOT suggest features that contradict these principles.
Lithic's primary authoring experience is built on the Streams plugin (outliner nodes), not the vanilla TiddlyWiki editor. Key implications:
- Keyboard navigation (Tab/Shift+Tab indent, Alt+Up/Down reorder, Ctrl+Enter new sibling) is already part of the Streams experience. The vanilla Streams plugin is NOT in the local repo — it is fetched at build time via
external.ymland extended bylithic-patch-streams. - Full-text search surfaces parent context via Streams' built-in breadcrumb navigation. This is not a gap.
- Per-tiddler version history does not integrate well with Streams because Streams subverts the vanilla TW edit/draft workflow. Wiki-level versioning via git/GitHub and browser-storage backups in
launcher.htmlis the chosen approach.
These features have been deliberately rejected. Do NOT suggest or implement them:
- Global graph view / force-directed backlink visualization: Considered smoke and mirrors that conflates knowledgebase importance with size/complexity. The Pyramid sidebar (hierarchical mermaid tree) and backlink pills are sufficient for discovering connections.
- Quick capture / inbox pattern / web clipper: The developer believes that if an idea can be lost, it wasn't worth remembering. The interstitial journal (today's journal entry) is the only intended capture point — jot a quick note there and do a "full capture" later. Adding an inbox workflow adds friction under a false fear of losing ideas.
$:/layoutin the document ($:/layoutis intentionally NOT saved, and is NOT an edit): which layout a Lith was last looked at in is view state, and an earlier round's request to persist it across a save has been withdrawn by the developer. Four writers set it on a press (the fullscreen whiteboard button, the whiteboard layout's own "Open In StoryView" button and rotate-gate exit, the streams row template's whiteboard action, andpdf-open-request.js), so a save that kept the tiddler rewrote the file on every view change, and a mount then opened in whichever layout the file happened to be saved with rather than the layout its engine ships. Both halves are therefore excluded, and they must stay in step: the dirty half iswiki/local-plugins/lithic-core/$__config_SaverFilter.tid(the wiki's own dirty-tracking filter —SaverHandler.prototype.titleSyncFilterin core — so a layout flip stops pulsing the save indicator, stops arming the beforeunload warning, and stops being recorded by$:/lithic/startup/standalone-transient-recovery.js, which compiles the same filter), and the save half iswiki/local-plugins/lithic-save/save-all.tid($:/core/save/all: Save Wiki and the published monolith),$:/lithic/exporter/lith+$:/lithic/exporters/export-to-new-wiki(both export paths), andLITHIC_BASE_FILTERinlauncher-ui/src/legacy-saver.ts(every.liththe launcher writes). A.liththat already carries a$:/layoutstill honours it on open — the value is read from the file, not ignored — it simply ages out, because no save writes it again. Do NOT re-add it to any of these filters, and do not treat its absence from a saved file as a bug. Do not editlauncher-fragments/runtime.jsto match: that file is extracted verbatim fromassets/legacy-launcher.htmlbyscripts/extract-launcher-fragments.mjsand is a read-only archive, not shipped code.
When adding new features to Lithic, follow these principles:
- FilterOps as the dashboard layer: New "views" or "dashboards" (e.g., weekly review, orphan detection, overdue todos) should be delivered as saved filters accessible via FilterOps, not as standalone tiddlers or sidebar tabs. Users can use the existing "transcludify" / eyeball button to create permanent views from filters they find useful.
- External reference wiki for templates: Anchor templates and example FilterOps presets should be delivered via an external "Lithic Reference Wiki" that users can drag-and-drop from, rather than bloating the core distribution.
- Markdown export via embed-stream: Rather than building a dedicated markdown exporter, the strategy is to improve the
<<embed-stream>>macro (removing extra whitespace) so it can produce markdown-friendly flattened output from nodestreams. This leverages existing workflows. - Lightweight plugin integrations only: When integrating third-party functionality (e.g., spaced repetition), prefer lightweight plugins that can slot into the Streams experience. Reject full "editions" or heavyweight solutions (e.g., TidMe) that would require architectural changes.
- Lithic Patina (simple UI mode) will eventually hide advanced TiddlyWiki UI elements. Features gated behind Patina (like hiding alternate storyviews) should be designed as toggleable via config tiddlers, not hard-coded removals.
- Palette-derived contrast variables for dynamic theming: Any feature needing palette-aware derived colors (Mermaid defaults, callout styling, charts) must consume the shared
--lithic-c-*CSS variables instead of raw<<colour>>values or hardcoded hexes. They are computed with WCAG contrast math from the live palette by$:/plugins/xyvir/lithic-core/contrast-publisher.js(math primitives in$:/plugins/xyvir/lithic-core/contrast.js), re-publish automatically on palette switch, and carry a static<<colour>>fallback in$:/plugins/xyvir/lithic-core/lithic-contrast.css. Roles:surface, page, foreground, foreground-muted, node-bg, node-fg, node-border, line, cluster-bg, cluster-border, cluster-fg, note-bg, note-fg, note-border, accent, accent-fg, scale-1..8, dark, code-bg, code-border, code-fg, code-ref, code-accent, code-warn, code-select-bg, code-select-fg, caret, menu-bg, menu-fg, menu-muted, menu-hover-bg, menu-hover-fg, menu-border, menu-selected-fg, notify-bg, notify-fg(each also as-rgbtriple and-alpha-12/-alpha-25tints).code-*covers editor/code surfaces (keywords/strings/numbers map tocode-accent/code-ref/code-warn, accents are hue-locked viahueShiftfromdirty-indicator/primaryso the brand hue survives);menu-*covers popup/context menus (hover band may be slid toward the surface when mid-luminance primaries make 4.5:1 ink unreachable);notify-*is the palette's OWNnotification-background/message-foregroundpair with a contrast-locked ink, shared with the streams patch's highlight band so the context-menu target band cannot drift from it -- bind such bands tonotify-*, never to a hardcoded hex or tomenu-hover-*. To add a new derived role, extend thederive()role map in the library — consumers pick it up automatically. Note that palette tiddlers are dictionary-type: read them viagetTiddlerData, and they may contain intra-palette<<colour x>>references that must resolve recursively (palette's own entry always wins over Vanilla, whether value or reference).
CSS variables in stylesheets — always use type: text/css: stylesheets that consume var(--lithic-c-*) must be typed text/css and must NOT embed <<colour ...>> macros inside var() fallbacks. TW's text/vnd.tiddlywiki parser mangles CSS custom-property double-hyphens into en-dashes at render time (the dash rule), which silently kills every var(...) declaration, and it also parses << inside CSS comments as broken macros. Sheets that still need <<colour>> transclusion (e.g. palette-key fallbacks unrelated to vars) must stay text/vnd.tiddlywiki — but then keep -- out of CSS custom properties and <<>> out of comments. A wikitext sheet that needs BOTH macros and var() has a third option: disable just the dash rule (\rules except dash) so the double hyphens survive, which is what $:/lithic/streams/styles/ctx-preview does. Prefer the exclusion form over \rules only <list>: a list must name every pragma the sheet uses (macrodef, whitespace, ...), and the first unrecognised pragma ends the scan. That is the trap behind the dash exclusion too -- TW only recognises pragmas in the sheet's LEADING block (parsePragmas() bails at the first non-pragma content), so a CSS comment or any text placed above a \define leaves the definition unparsed and leaks a literal \end token into the emitted CSS, silently killing the next selector. Keep every pragma above all comments and text.
7. Author-declared diagram styling is authoritative: when a diagram or widget declares its own styling (Mermaid %%{init} directives, style/classDef statements, per-widget attributes), default theming must stand down rather than compete on CSS specificity. The mermaid wrapper tags self-styled containers mm-user and default rules are scoped to :not(.mm-user).
-
Hardcoded colour gate (
scripts/check-colors.js, runs in CI before anything is built): any colour literal inwiki/local-plugins/outside the script'sALLOWLISTfails the build. Use<<colour field>>in wikitext (inline styles and<style>blocks) andvar(--lithic-c-*)intext/csssheets. For alpha washes prefer the publisher's companions --rgba(var(--lithic-c-foreground-rgb), 0.22)or the pre-fadedvar(--lithic-c-notify-bg-alpha-12)-- over grey/black/white literals, and remember that muting often needs no colour at all (a completed row isopacity: 0.6, notcolor: gray). Comments that mention colours are reported as informational and never fail. Allowlist entries each carry a reason and are deliberately narrow: palette definitions, the print stylesheet and the mermaid media-print block (paper is white), vendored single-line bundles, and content defaults that must NOT follow the wiki palette (PDF.js rendering, the 3D model material, the text-file iframe, whiteboard paste). Runnode scripts/check-colors.js --verboseto see them. A new exception needs a reason that would survive review, and a line-level exception (abox-shadowneutral, say) beats a file-wide one. -
Offline gate (
scripts/check-launcher-offline.mjs, runs in the launcher build CI step and innpm run check:push): the launcher is one file that has to behave the same on an instance, on a USB stick and overfile://, so nothing in it may load from somebody else's host. The gate fails on any externalsrc/href/@import/url(...)-- no allowlist for loads, because no version of this app needs one -- and on any absolute http(s) URL whose host is not declared with a reason in the script'sEXTERNALlist, which is how a new endpoint becomes a decision rather than an accident.--browseradds a runtime pass: boot the artifact overfile://with every non-local request aborted, drive search and the new-Lith entry, and fail if anything was attempted. That is the only way to judge a host assembled at runtime ('https://' + host), so the two passes are not redundant.node scripts/check-launcher-offline.mjs --listprints every URL with its declaration for review. Declared today: w3.org namespaces, Svelte's own error links, the GitHub and lithic.uk anchors a person clicks, the two swarm endpoints (docs/swarm.jsonandintro.lithfor the ephemeral public coderunner widget, both of which fail quietly offline), and the bookmark field's placeholder. -
Launcher palette (
launcher-ui/src/color-palette.ts, guarded bylauncher-ui/src/color-palette.test.ts): every colour the launcher draws is declared once, in that module, and reaches the page as a custom property:paletteCss()renders the:rootblockstyles.csscarries between itslithic-palette:markers, so the sheet holds no colour of its own and there is exactly one copy of every value. Edit the palette, runnpm run paletteto rewrite the block, and commit the two together. Washes are derived rather than written:WASHESnames a colour and an alpha and the serializer computes thergb()from the two, so recolouringaccentmoves all three of its washes with it, where a hand-writtenrgba(138, 180, 248, 0.12)is correct only until somebody changes the blue. The alphas are a ladder, not a recording: a tint behind text is 12 or 20 percent, a banner 10 or 45, a shadow 30, 50 or 72, a wash over chrome 7. One ramp per job is the rule that keeps the palette small: a job gets one tone, a new tone has to be a job the palette does not already have, and where several tones did one job the winner is the one the sheet used most and it keeps the role name. The test fails on a stale block, on a colour literal anywhere underlauncher-ui/src(comments included, the way the dash sweep counts them), on a variable the sheet reads and the block does not define, on two tokens holding the same colour, and on two tones in one family closer than 8/255 apart, which is the distance at which they are one tone: the fix is to merge into the nearer, never to add a value. A 60 token ceiling (PALETTE_TOKEN_CEILING) is the ratchet that stops the recording growing back.launcher-ui/index.htmlis deliberately out of scope, since itstheme-coloris a decision about browser chrome rather than about the launcher's own drawing: no part of this reads or writes that file. The canvas that paints an instance icon does read the palette (paletteValue('surface.control')), because a canvas takes a colour string rather than a custom property. In prose the sheet names a colour by token (line.thumboversurface.panel), never by hex, because the hex is the thing that moves. The consolidation pass (2026-09-30): the first pass was a faithful naming of what the sheet held, 271 literals and 25 washes named as 113 tokens, and what it held was 93 hex tones picked by eye at different times: twelve secondary text greys between#a0a0a0and#bcbcbc, two ambers six units apart doing the same job, five pale ambers all meaning "amber ink on an amber banner". The second pass holds the same rule as the rest of this file and came out at 53 tokens (40 colours, 13 washes), with no redesign: every survivor is a tone the sheet already drew, the hues are untouched, and 116 of the sheet's colour values moved, in 64 shifts, the largest 57/255. Three are above 40 and the rest are below 31:ok.basetakes the tick's#4caf50so a green check is drawn in the launcher's own green (57, the one merge plainly visible on screen), whileok.rimtakes a badge border anddanger.softa salmon hover that had drifted from their own families. Evidence for a retune is produced rather than asserted, by resolving both sheets and listing every declaration whose colour moved with its distance, plus a headless comparison of the built artifact's computed colours; that is how the numbers above were measured, and how a future merge should be judged before it is committed. -
Every OS-specific behaviour is one capability with one implementation per platform (
src-tauri/src/platform/): the Svelte launcher is one artifact shipped to every desktop, so it cannot branch on the operating system without shipping every platform's vocabulary to every user; what it branches on instead is capability, which Rust answers.platform/mod.rsis the table:Os,current(),capabilities(), and one routed function per capability (install_dir,install_target,running_image,launched_from_install,program_dir,state_dir,open_in_browser,flash_browser,reveal,install_launch_entry,register_file_associations,make_launchable), each answered bywindows.rs,linux.rsormacos.rsunder the same name. Adding a platform is a file and a table row, never anifinlib.rs, and the commandplatform_capabilitiesis how the page asks rather than guesses.flash_browseris the one capability about another program rather than the platform: the flash offer flashes in its own dialog where the window's webview implements Web Serial, and hands the samesrc/launcher.htmlto a Chromium browser at?flash=1(written to a temporary file) where it does not. A current WebView2 does implement it, measured: it answersnavigator.serialand draws its own chooser, titled "tauri.localhost wants to connect to a serial port", so the handoff exists for WKWebView, WebKitGTK and an older WebView2 rather than as the desktop app's only route. The Linux and macOS modules are compiled on every platform, on purpose: the Windows implementations are the only ones that need a platform crate (COM, the registry, ShellExecuteW), and the local gate runs on the developer's Windows machine, so code inside#[cfg(not(windows))]is codecargo check,clippyandcargo testnever see. Keeping them unconditional is what makes the local gate type-check, lint and unit-test the Linux path (thefind_icon, desktop-entry,exec_pathand install-target rules all have tests that run on Windows); only the FFI bodies inwindows.rsare conditional, and the two modules carry#![cfg_attr(windows, allow(dead_code))]for the same reasoninstance_search.rscarries the mirror-image attribute. Whatcapabilities()means for the page: an Install offer exists only whereinstallis true, the offer's sentence is keyed on thelaunch_entrytoken (start-menu|application-menu| none) rather than on a noun, because the noun is a translation and the platform cannot know the language any more than the page can know the platform; and the three webview flags are the flag side of the#[cfg(windows)]hooks inwebview_auth,instance_search::read_cachesandinstance_copy::forget, with a unit test that fails when one is implemented and its flag is not moved with it. macOS reportsinstall: falsedeliberately: a Mac distribution is a.dmgholdingLithic.appbeside a link to/Applications, so the drag is the install, the file types are the bundle'sInfo.plist, andopen -Ris the reveal; an app that also copied its own bundle into~/Documentswould be a second copy in a folder the user did not choose. And the one rule macOS cannot keep is "beside the program", which is why that question is routed rather than a call tocurrent_exe: a Mac program is a bundle, so the executable's folder isLithic.app/Contents/MacOS, inside the app — state written there is state the next install replaces (a cask upgrade swaps the whole bundle, a hand-dragged newer copy does the same), it is not something a signed bundle will accept, and a quarantined run is translocated to a read-only path where the writes fail anyway. Soprogram_diranswers with the folder holding the bundle (found by walking up to the.apprather than by counting Tauri's layout, so acargo runfrom a checkout keeps the plain rule) andstate_dir— the folder the portable sidecar and the vault live in — answers beside that folder when the bundle is somewhere a copy is carried (a stick, a folder of one's own, Downloads) and~/Library/Application Support/Lithicwhen it is parked in anApplicationsfolder, or when the folder it sits in cannot be written at all (a read-only mounted image, a translocated copy). Both are asked once per process, because the sidecar's writers ask on every command and a probe file is not something to leave on somebody's Desktop repeatedly. The concession stops at the platform line: Windows and Linux keep the executable's own folder, unchanged and unconditional, because there it is a real folder that travels — the program, its state and the liths beside it are one portable neighbourhood, and no part of macOS' bundle arithmetic is allowed to reach them. Linux installs itself properly, which is the part Windows code could not do:install_launch_entrywrites one freedesktop entry to$XDG_DATA_HOME/applications(which is also the file-association registration, since a.desktopfile declares the MIME types it opens), copies the AppImage's own icon into the icon theme rather than pointing at a path inside a temporary mount, and marks the copied program executable. Three Linux-specific facts are load-bearing:$APPIMAGEoutrankscurrent_exe(platform::running_image), because the executable inside an AppImage's mount is gone at the next reboot and copying or byte-comparing it would be copying a ghost; the install target keeps the.AppImageextension, or the kernel stops treating the copy as one; and anExec=path containing a space has to be quoted the way the format specifies, which is the difference between a menu entry and a menu entry that does nothing. And the installed copy is not content of the folder it lands in: that folder is also where a first backup proposes to live, so both distributions write the installed file's own name into its.gitignorebefore the copy arrives (ignore_installed_copy, inshim/src/install.rsand ininstall_monolith), because the alternative is a 4 MB binary in somebody's wiki history and in every clone of it. The two implementations do not link each other, so each carries its own test and a harness runs them over the same inputs to hold them in step. And the offer is not a second installer:platform::package_managedanswers whether something other than this app placed the copy that is running, from a sandbox marker (flatpak, snap) or from a path under a root the system owns (Program Files,%LOCALAPPDATA%\Programs,/usr,/opt,/nix/store,/snap,/var/lib/flatpak,/Applications), andinstall_supportedmakes that lose to the platform's answer, so adeb,wingetorbrewcopy is offered no Install button and no hand-delivered update while the manager stays its updater. The install record outranks the path evidence, because%LOCALAPPDATA%\Programsis both winget's per-user default and this app's own fallback when there is no Documents folder, andlaunched_from_installis the only thing that tells those two apart. The update half needs no second check: it is gated on that same record, which no manager's copy can satisfy. The rule is unit-tested including its boundary cases (/usrfoois not under/usr,C:\ProgramFiles2is not underC:\Program Files) and both sandboxes, and the comparison folds case on Windows and macOS but not on Linux, because it has to judge a Windows path on a Linux runner. One table, three registrations: the file types this app opens are declared once, insrc-tauri/src/platform/associations.json(extension, description, MIME type, whether the type keeps Lithic's own mark, whether it is imported rather than edited), andassociations.rsis its only reader in Rust. Windows turns a row into a ProgID, Linux into the entry'sMimeType=line, and the APK into manifest intent filters thatscripts/patch-android.mjsgenerates at build time, which is the one consumer that cannot ask Rust because it runs before anything is compiled. Adding a type is one row, and nothing may reintroduce a second list. The Android filters claim types by MIME, the only vocabulary the platform offers, and extensions bypathPatternforcontentandfile, the only way a provider that knows nothing about.lithcan offer the app; and every row is claimed, theimportedones included. Those are the types this app converts rather than edits, and a phone has no folder to write their sibling Lith into, so opening one starts a new blank Lith named the way its sibling would have been (<stem>_<extension>.lith, the rulelith_sibling_ofstates inlib.rs), with the file's bytes handed to the engine's importer and no file behind the Lith until the first save asks the platform's own save picker where to put it. That is a deliberate asymmetry with a share, which queues notes in the pending panel for a destination: a share is content waiting for a home, while an opened file is a document somebody asked to read, so it opens. What arrives afterwards differs by platform and is a capability: a desktop is started with the file as its argument (get_startup_file), and a phone is handed an intent (take_open_document, kept byMainActivity.rememberDocument), which the launcher opens throughopenTauriPathonly while the launcher is the page, because a handed document must not mount over an open Lith. -
A new file type is one row, and a new importer is a chain of places that each fail quietly (the table, the kinds module, the importer plugin, the handoff, the two drop handlers, the launcher's staging, the naming rules, the tests):
associations.jsonis the registration, the thing that makes a shell offer this app for a file. Converting a file is a second job with its own handoff, and the two can disagree in a way that looks like nothing at all:.pdfand the pictures were registered on every platform, opened by double-click on the desktop and by intent on a phone, and still did nothing when dropped on the launcher, becausehandleDrophad no branch for either and the branches it had (.lith,.json,.html,.epub,.docx) covered only the kinds that are documents of their own. So an importer touches all of these, and every one of them fails quietly by itself:The rule the launcher follows: a drop stages, it never opens. Every file this app converts (a PDF, a picture, a book, a Word document) and every
.lith/.jsonpayload lands in the pending imports panel as a row, and every text file this app edits instead (.md,.txt,.tid,.ipynb) lands there as the nodes the scratch editor would make of it, named for the file they came from. The two ways out of that panel are the person's choice: New Blank Lith, whose name field opens pre-filled withimportLithNameof the first queued file, or a Lith that is already open, into which the queue is merged without disturbing the view being read. Two shapes cannot be staged, and are the only stated exceptions: an instance backup (.json) is this device's own store rather than content, so it is imported, and an HTML page carries its own store and save behaviour, so it opens where it is dropped and takes nothing with it. Never let one kind mount "because it has nothing to wait for": that is exactly the inconsistency this rule replaced, where a dropped PDF opened a Lith while a dropped.lithqueued its notes.- The row (
src-tauri/src/platform/associations.json): extension, label, MIME type,own_icon, andimported: truefor a type this app converts rather than edits. Windows, Linux and the APK are all generated from it, so this is the only place a type is declared. - The kind (
launcher-ui/src/import-kinds.ts):ImportKind,importKindOf,IMPORT_REQUEST(the window property its bytes travel on),IMPORT_FALLBACK_NAME, andimportContainerTitle. A type missing fromimportKindOfis registered and unopenable at once, because both the phone's handoff and the launcher's drop handler ask that one function which converter a file wants. - The converter (
wiki/local-plugins/lithic-import-handler/): the reading lives in the wiki and never in the launcher, and is published as$tw.lithic.convertXToTiddlersbeside the page-level readers a gesture is built from (readPdfPages,readPicturePage,mergedDocumentTiddlers). - The handoff (
pdf-open-request.js): a*_REQUESTwindow property, anopenRequestedX, and a branch instartupthat sets the property to null before anything else can read it. A type whose files are pages of one document also travels on__LITHIC_IMPORT_FILES__, and a one-entry list must be answered by the one-file reader, so a drop and a double-click cannot produce two layouts of the same import. - The drop (
pdf-drop-handler.js.tid): a bucket inhandleFiles, the same files excluded from the trailingotherFilesfall-through (a file a converter consumed must not reach the generic importer), and a decision about the gesture: a PDF's pages and a picture join one board throughmergedDocumentTiddlers, while a book, a Word document and a notebook each make a document of their own. - The launcher's staging (
App.svelte):queueFileputs a dropped file inpendingFiles(handles, not bytes, since a queue is usually cleared unused) and the panel draws a row named for the file, which is the one thing about it the launcher can know before the engine has read it.queuedFileHandoffencodes the queue at the mount and puts it on__LITHIC_IMPORT_FILES__as{ files, openBoard }, because the bytes are wanted once.openBoardis the launcher's answer to the question the rule above settles: a document that exists only because of the gesture opens the board it drew, and a Lith someone opened keeps its view while the engine's import list names what arrived. AskingimportKindOfrather than adding another suffix test is what keeps this one list, and the panel's file rows are a second list besidependingImportsbecause a file is not a tiddler until the engine has converted it. The Mount picker next door (file-bridge.ts,OPEN_TYPES) is narrower on purpose: it offers documents to open, never types that are converted. - The other half, for a type this app edits rather than converts (
notes.md,notes.txt,notes.tid,book.ipynb, a.json): its vocabulary isresolveScratchPlanandparseScratchSourceinscratch-editor.ts, notimportKindOf, and a drop for one belongs in the samehandleDropswitch, after the branch that asks for a converter. It is queued as its nodes rather than as a file row, because that content is tiddlers already, and the root keeps the file's own name with its extension, exactly as the scratch editor titles it, so a note merged into a Lith says which file it came from. That half used to arrive nowhere: a droppednotes.mdwas ignored on the launcher while opening the same file from Explorer reached the scratch editor. Opening a file in place is still what Mount is for, the one gesture that names the file it will write back to. A registration still comes first, andimported: falseis what says "edits", which on a phone changes only what opens rather than whether the type is claimed, since every row is. - The naming:
<stem>_<extension>.lithfor the Lith (importLithName, which islith_sibling_ofspelled in the page, and which the New Blank Lith field is pre-filled from once a gesture is queued) and a container named for the file without its extension (importContainerTitle), which the importer has to agree with, becauseboardOfreaches a board through its container. - The tests, one suite per half, so a change that outruns either fails.
scripts/test-pdf-import.mjsboots the drop module and the handoff in a VM over a fake wiki, a fake pdf.js and arequirestub, and that stub has to serve every module the drop handler requires at module scope. It is a real trap: the archive reader the Word importer added broke all eight tests, and nothing noticed, because this suite ran only inbuild-launcher.yml, which isworkflow_dispatch. It is innpm run check:pushand in the release workflow now, and it pins what a queued gesture becomes: pages merged into one board, each file read by the converter its own name asks for, and a merge into an open Lith that leaves its view alone.launcher-ui/src/import-kinds.test.tsreadsassociations.jsonitself, so a row that reaches no branch, animportedflag that disagrees withimportKindOf, or a type claimed by both a converter and the scratch parser fails a test rather than reaching somebody's hands, which is the drift that let.pdfand then.mdbe registered and ignored.
- The row (
-
Monkey inputs are a local instrument, never a gate (
scripts/monkey-launcher.mjs,npm run monkey:launcher): the launcher's entry boxes are fuzzed on demand, by a person, because a fuzz run is noisy by nature — it needs a browser, it is driven by a seed — and a red build on an unlucky seed teaches people to press retry rather than to fix the crash it found. What it finds is promoted intoscripts/test-puppeteer-launcher.mjs, which is the harness CI runs, andscripts/pre-push-check.mjsfails if any workflow names it. What it does: it discovers every entry box the page draws by walkinginput/textarea/contenteditableinside each dialog it can open, keyed on the class names a person's clicks reach (never on a copy string, so a translation cannot hide a box), collapses a six-box PIN into one field, opens the collapsed advanced section of the backup dialog, and reopens the surface for each value instead of clearing it, because a field that keeps state across a close is its own finding. What it can judge: that the document is still the launcher, that typed markup did not become markup (a mutation watcher plus a__monkeyPwnedbait flag), that the × still closed the dialog, that a key storm left no overlay Escape could not clear, and that nothing reached the network — every non-local request is aborted, so a mount cannot quietly fetch the published engine and replace the page mid-run. What it cannot: anything a Rust command does with a value, which is why the harness says so in its own report rather than implying coverage. The five checks it pins are the guardrails a person would state out loud — a name already in Recents marks the check invalid and typing past it clears the mark, a name the launcher has to change says which file it will create, ajavascript:address is refused and not stored, a PIN of symbols neither fills nor submits, an empty name still starts a document and the page survives the mount failing overfile://— and they run after the fuzz pass, because they are only worth keeping if they still hold once the same dialogs have been stirred.--strictalso fails on theGAPfindings. The one class its first run found — a control character (a line break, a tab, a NUL) survivingnormalizeLithNameinto the name — is now stripped rather than refused, innormalizeDocumentName(C0 and DEL removed, both ends trimmed, an empty result stilluntitled), because the character is an accident and a name is not the place to reject a request;document-format.test.tsnames the three andlegacy-saver.test.tspins the launcher's own path through it. Names are also held to Windows' filename rules, because Windows is the strictest of the three systems this launcher ships to and a name legal there is legal on macOS and Linux as well: a run of< > : " / \ | ? *becomes one hyphen (soMP3/FLAC noteskeeps its boundary and../../etc/passwdbecomes a name in the folder rather than a walk out of it), trailing spaces and dots go the way Windows would drop them, a reserved device name (CON,NUL,COM1,CONIN$, and their superscript spellings) is moved out of the way with a leading underscore becauseCON.lithis the console with a suffix rather than a file, and the stem is cut so the whole name fits the 255-character component limit without halving an emoji. The report's separator column is therefore an inverted assertion: a separator surviving means the rule was weakened, not that a value was unlucky. And the rewrite is never silent. Every rule that makes a name legal somewhere also merges two names into one (a/banda-bboth arrive asa-b.lith,CONand_CONlikewise), which is unavoidable once one system's rules are the baseline but must not be invisible: the New Blank Lith field drawscopy.newLith.renamedabove itself whenever the name that will be written differs from the name that was typed, and says nothing for an ordinary name so the notice stays worth reading.typedDocumentNameindocument-format.tsis the comparison it is drawn from (the typed name plus the extension, sanitized by nothing),document-format.test.tspins both halves (silent fornotes,My Notes,notes.lith; speaking fora/b,notes.,CON, a.htmlname and a 400-character one), the collision check the field already had reads the same normalized name, so the second document to arrive under a merged name reports itself as taken, andtest-puppeteer-launcher.mjsasserts the notice at phone width, where it wraps inside the field rather than sliding under the page edge.--listprints what would be fuzzed and stops, which is what to run after adding a field. Opening is the other half (--mounts,--no-drop,--no-payload-urls,--mount-timeout): a Lith is bytes, and bytes do not arrive through a box. The opening phases serve the artifact, the engine beside it and a dozen fixtures from one loopback origin for the length of the run, because afile://page cannot fetch a sibling engine and a refused fetch would make every mount read as broken, then open each fixture three ways: through the Mount button withshowOpenFilePickeranswered from that origin, by dispatching a realdropevent carrying aFile(the bytes the OS would hand over), and through the launcher's own?json=address. The fixtures are the shapes an opened document has: empty, delimiters only, no title, duplicate titles, a title that is markup, a title full of filter brackets, NUL, ESC and DEL in a body, random bytes read as text, a body holding<script>and an image handler, one 8 MB tiddler, two thousand small ones, and a seeded mutation of a valid Lith, which is what an interrupted write leaves. What it can judge: the page ends as the wiki or as the launcher and never blank; a well-formed Lith always boots, or the pass says out loud that the rest of it proves nothing; an engine that boots into a document that draws nothing is a failure rather than a pass, which is also why the boot check asks for$tw.wiki.getTiddlerTextinstead of for$tw.wiki(a broken store leaves a half-built$twbehind, and that object was being mistaken for a wiki); payload markup reaching script is a failure; and a press or a mount that moves the address is a note, because a bookmark row hands the window to its instance on purpose, where a launcher that vanishes at the same address is the wedge.--mounts=allopens every fixture, a number samples that many from the seed, andoffskips the phase. Two harness faults had to be cleared before those phases could say anything, and both were the harness lying rather than the launcher failing: a local helper namedURLshadowed the constructor the fixture server needed, so it answered 400 to every request and the phase reported that the launcher would not come back, and the Tauri stand-in (which answers every command withnull) made the served page take the desktop route into a mount that quietly did nothing, which is why the phases now install the instrumentation withbridge: falseand fuzz the browser launcher they are actually driving. A phase that cannot finish is a finding and a note, never an uncaught error: the report is the whole point, and a reload that will not land must not take it down. The class it found is the one a text box can never reach: a tiddler body containing</script>was spliced into the engine'sapplication/jsonstore raw, which closed the element early, truncated the store, and booted a wiki with no page around it (a note about HTML, or a plugin's own docs, is enough to hit it).storeJsoninlauncher-ui/src/legacy-launcher-runtime.tswrites<as a JSON unicode escape throughString.raw, so the six characters survive the source and the body parses back unchanged, andlegacy-launcher-runtime.test.tspins a store that carries</script>,<script>and<!--without gaining a second script element. Thescript-bodyfixture is what caught it, and it now renders in 913 ms where it used to reportbooted blankat 256 ms. The edges a person reaches by accident are their own phase (edgerows in the report): a picker answered by cancellation, and one that throws into the classic chooser (thebusyflag has to come back off in both, or the Mount control stays disabled for the rest of the session); an engine that answers 404 at every candidate, which has to say so and stay usable; an engine that takes 25 seconds, where the page has to still be the launcher while it waits and Escape has to work before the answer arrives; two presses of Mount in one tick; a dropped instance backup, which is the.jsonbranchhandleDroptakes before it reads a.jsonas tiddlers; a dropped.txt, a broken.jsonand an extensionless file, which are ignored and therefore reported as silent rather than failed on; a gesture carrying three documents, one of them twice, where the repeated titles are refused with a note rather than queued as duplicate rows and a row's own ✕ removes only that row; opening a Lith that already holds a queued title, which asks before the merge replaces the stored copy and, when accepted, has to land the queued copy in the wiki; a?url=payload fetched and carried into the wiki; a real clipboard paste and an IME composition, judged the way a field always is; a thousand rows and a hundred-kilobyte query, whose timing is reported rather than asserted because no budget for it has been decided; and a cache whose writes are refused, where the mount still has to boot.clickMountwaits for the control to be enabled before pressing, because a press into a disabled button is dropped and the phase then blames the launcher for a mount that never happened. And the mutation generator, not a new seed, is where new bytes come from: each run draws one to three edits and the report names them (truncated at half, then every delimiter doubled, then tabs where the blank lines were), because a hundred seeds of one shallow edit produced a hundred near-identical files. The slow engine makes a full run about half a minute longer, which is the price of the one thing that cannot be tested quickly.
CONTEXT:
The launcher explains itself through the UI, not through prose. Every string a user can read — modal text, tooltips, button labels, status lines, empty states, Rust-side detail strings — follows one rule:
One short sentence. 10-15 words. No em dashes. Nothing restated.
- Terse and curt. The icon, the row and the button label already carry the meaning; the sentence orients the user to what the UI is for, and stops. If a sentence needs "which means that", either it is too long or the UI is unclear.
- Non-technical. No git, cache, index, token or file-format vocabulary unless the user has to act on it. "Saves push to GitHub automatically." beats "Every save of a file in this folder commits and pushes to main." One entry in a Lith is a note, never the engine's own word for it: the queue's rows name their titles, and a sentence about a merge says "note" where a count or a class of thing has to be named, so the wiki vocabulary never reaches a person.
copy.test.tswalks every deck leaf, and the source of every sentence function, failing on a word that has been decided against (tiddler,TiddlyWiki,wiki,payload,serialization,engine, each read from a stem so a plural or a compound is caught, and in every language a deck is written in), which is what keeps a new dialog from reintroducing the word that was just removed.cacheis deliberately not on that list: a handful of strings say where a saved copy actually is, and a person can act on it. - No em dashes or en dashes. They read as editorializing, wrap badly in tooltips and modals, and are the single clearest sign a string was written by an agent rather than trimmed by hand. Use a period, or rewrite. The ban covers comments and test names as much as copy, which is what makes it checkable: the launcher's sources are swept clean of both dashes and
scripts/check-launcher-copy.mjsscans them absolutely, so nobody has to work out which dash in a built artifact was a shipped string. - No restatement. State the consequence once. A warning names what is happening and what the button will do — not why, and not twice.
- Mechanics live in
README.md. The launcher is meant to be understood without explanation; anyone who wants the machinery reads the README, never a modal. - Diagnostics are data, not prose. A raw error string appended after a short clause is fine:
Last save did not upload: not authorized. Do not editorialize around it. - Both sides of the bridge count. Rust
detailstrings render in the sync dialog, so they obey the same rule and stay word-for-word in step with the matching entry inlauncher-ui/src/git-sync-health.ts(healthFailure). The same fault must not read two different ways depending on where the user looks. - The language comes from the environment, and only a request or a pin overrides it. Which deck a page reads is decided once, at import, by
resolveLocaleinlauncher-ui/src/copy.ts, in this order:?lang=es(a request, and the escape hatch from everything below it), thenVITE_LAUNCHER_LOCALE(the artifact's own pin, compiled in), then the person's own languages (navigator.languages, which is the environment in all three shapes of the launcher at once: the published PWA reads the browser, an instance's launcher reads the same browser, and the desktop app reads the machine, since the webview it runs in is the machine's own), thenen. A request nobody can carry is refused rather than trusted, so a misspelled link reads as the shipped language. A pin is forced, not preferred, which is what lets one build be a language site, and?lang=is the way out of it. A self-hosted instance pins without rebuilding by settingLITHIC_LOCALE, which rewrites the two files that belong to a deployment rather than to the release (deploy/pin-launcher-locale.sh, checked byscripts/check-self-host-locale.mjs): the redirector that sends/on to the launcher, which then brings?lang=esfor a visit that brought no query of its own, and the install manifest's start URL. Language is the document's as well as its words:main.tspublishes the resolved locale asdocument.documentElement.lang, and every date the launcher draws formats with the same tag, or a screen reader, a spell-checker and a timestamp each disagree with the page.
Worked examples:
| Too long | Terse |
|---|---|
| "Rebuilding drops it and deletes its cached copy and history. Files on disk are untouched." | "3 liths have no file on disk, so rebuilding deletes their cached copies and history." |
| "Every download is a complete, working copy of the wiki as it was at that moment — your history is never modified." | "Downloads are complete copies. This wiki is never changed." |
| "Pick the icon this instance is known by. It becomes the browser tab, taskbar and phone-home-screen icon, so your instances stay distinguishable at a glance." | "This icon identifies the instance in your tab and taskbar." |
When a string has to carry a count, a filename or a timestamp, keep those as data and let the sentence stay short; do not grow the prose to accommodate them.
CONTEXT:
Every launcher modal that can be dismissed carries an × in its corner (.modal-close). A Cancel button beside it that runs the same handler is a second control for one function, and it takes the place of the decisions the dialog actually exists to make.
RULE:
- No Cancel where the × does the same thing. Delete it; do not relabel it. The dialog may then have no action row at all — the per-instance PIN prompt is deliberately in that shape, because the sixth character is the submit and the × is the way out — and that is the target, not a gap to fill.
- A "cancel" that is not the × is named for what it does. The GitHub device flow's button abandons the authorization being waited on and leaves the dialog open where the × closes it, so it reads
Stop waiting. The inline control in the sync progress line stops a transfer mid-flight, so it readsStop syncing, neverCancel. - A yes/no confirmation keeps its Cancel instead of a ×, because there both answers are decisions and neither is a dismissal: the rebuild confirmation (Cancel is the choice not to drop the rows it just listed) and the destructive confirm. Every other dialog gets the × — including the ones whose Cancel was its only dismissal beside real choices, like the session-collision prompt, whose two buttons are the ways to open and whose Cancel meant not opening at all.
- Nothing else beside the × dismisses, whatever it is called. A
Close/Donethat was a dialog's only action is the same function under a friendlier word, so it goes with the Cancels: the vault manager's empty and list shapes now carry no dismissal, and a shape with nothing to decide has no action row at all (the empty manager is title, one line, and the path). git-sync's connected view keeps onlyReconnectandDisconnect. One dialog has neither a × nor a Cancel and is left as it is: the three-way unsaved-edits prompt, whose three answers are policies about the edits rather than a way out of the dialog — the one place left to settle by hand.
ENFORCEMENT:
the rule is stated at .modal-close in launcher-ui/src/styles.css, and assertNoExtraDismiss in scripts/test-puppeteer-launcher.mjs fails when a dialog that owns a × carries a button whose whole label is Cancel. Call it for each new dialog the smoke test opens, and keep the sheet's action rows read from ui-gallery/copy-deck.md when trimming one.
CONTEXT:
The header's status line holds the last thing the launcher said, and a later sentence replaces an earlier one. That half is right: a control's own answer should stand until the next thing happens. What was missing is an end. status has 64 writers in launcher-ui/src/App.svelte, and exactly two of them ever retire their own sentence — the install confirmation, and reportAndRetire, whose comment already explains why that one had to: a pass that runs behind a dialog has no click to follow it, so its line and the animated dots beside it stood for the rest of the session, reading as indexing that never stopped. Every other writer sets something final and leaves, and the render site then always drew .activity-dots, which mean work in progress. So a finished action pulsed forever. Reported from the shipped app as "sometimes these status messages get stuck and linger", with a screenshot of Mounted <file>.lith still waving long after the mount.
RULE — a status is transient by definition:
- One deadline per line, measured from the moment it was written. At 15s the line is gone on its own. It first shipped with two moments, the dots stopping at 15s and the sentence staying until 45s, and against the real launcher that read as a line that had half finished going away, so the second stage was removed: a line is either saying something or it is gone. The threshold is the contract, so it is exported from
launcher-ui/src/status-lifetime.tsand asserted in the test beside it: a line may stand at least 10s and never more than 60s. A minute is the outside of "transient" and a blink is not a status, and those two assertions are what fail on the day somebody moves the number quietly. - It is a catch-all on purpose, not a fix per writer. Every writer that forgets to retire its line is a new bug and there are dozens of them, where one deadline is one place to be right. A writer that knows its sentence is worth reading twice keeps using
reportAndRetire: assignstatus, then retire it on your own timer, guarded by the text you wrote. The cost this accepts is named rather than hidden, and the second half of the rule is the answer to it: a clock cannot tell a success from a failure, so a line that names something to act on opts out of the clear (rule 5) instead of a reader having to hope it was still on screen. - Assigning
statusarming its own deadline is not optional. One reactive statement ($: syncStatusDeadlines(status, heldStatus)) arms the clear or the hold, a newer line cancels the older line's deadline, and the clear is guarded by the text, so an older line's deadline arriving late can never take away a newer sentence. Anything that writesstatusgets the deadline for its class, which is exactly the point: nothing has to remember. - What stopping looks like, and who it is for.
.activity-dots.settled i { animation: none; }inlauncher-ui/src/styles.css, the same static shape theprefers-reduced-motionrule already gives these dots. It draws only for a held line now, because an ordinary line's dots leave with the sentence; a held line's sentence, its colour and its place are untouched. - A line that names something to act on is held, and is never cleared on a clock.
reportHeld(message)inApp.svelteis how a writer says so: the line keeps the deadline's settle half alone, so the dots stop at 15s and the sentence then stands until the next thing replaces it. Five copy entries are held today, at eleven sites:openFailed(four: the disk picker, a recent row, a disk path, and an instance opened externally),blankLithFailed(two),noPath(three),noCachedCopy, and thecopyDropNotefailure. Held by the sentence rather than by a flag, so an ordinary writer that runs after a failure cannot inherit the exemption. The stopping is what makes the exemption safe rather than a hole in the rule: the bug this whole section exists for was an unending pulse reading "work in progress", and a standing sentence is not that.mountErrorandremoteErrorare the same class in their own element, where there are no dots to stop, and they have always stood this way; the failures that reach them (uploadFailed,listingFailed,openNameFailed,createFailed,deleteFailed,downloadFailed,reindexFailed,introFailed,payloadFailed,droppedInvalid) need no change for the same reason.
ENFORCEMENT:
launcher-ui/src/status-lifetime.ts holds the threshold and the arming, and status-lifetime.test.ts holds the 10s floor, the 60s ceiling, that an ordinary line arms one deadline and goes at it with nothing left armed, that cancelling a line gives its deadline back, and that a held line arms one deadline, settles once and wakes no second time. The behaviour belongs on the running component rather than in the timers alone, and the technique is worth keeping: with window.showOpenFilePicker replaced in the page by handles that answer getFile, a multi-file Mount a Lith reaches copy.status.added(n), which mounts nothing, so a status line can be produced and watched at leisure, where every other status reachable in a browser is followed by a mount that replaces the document and takes the line with it. Measured that way for the two-moment version (see the round log): written with animationName: status-wave, settled 15.2s later with the sentence still on screen, cleared 45.0s after the write, and a newer line arriving after the previous one had settled came back with the animation running again. The hold was measured the same way, with a pick whose second getFile rejects so the real Mount button reports copy.status.openFailed: 275 consecutive samples carried that sentence from t=0.2s to t=55s, still on screen and static at 45.4s and 50.0s, and the ordinary line that replaced it at 55s cleared 44,999ms after its own write, which is the half that proves the exemption does not leak to the line after it. The single-deadline version was measured the same way: the ordinary line was gone 15.0s after it was written with nothing stopping its dots first, and a held line was still on screen at 16s and 20s, settled with animationName: none by then (the mock has to reject the second getFile call, since the first is how browserPicks reads the pick's name, and a first-call failure falls back to a hidden file input that never answers). The same browser drive is what to run when this number changes again.
DECISION (2026-10-22): the standalone *.html build does NOT carry a generated list of built-in edition plugins, and nothing should add one. Treat it as closed unless the developer reopens it.
WHY:
- The launcher injects the list on the fly. The generator (
scripts/generate-default-plugins.mjs) feedsVITE_LITHIC_BASE_PLUGINS, andgetLithicUserFilterinlauncher-ui/src/legacy-saver.tssubtracts those plugins at save time. The generator writes no tiddler, so there is no generated copy to keep in step. - The HTML can already make a data-only
.lith. The "All Notes" export filter,[all[]] -[is[system]](wiki/local-plugins/lithic-tweaks/$__config_TiddlyTools_Filters_All Notes.tid), selects only non-system tiddlers. Plugin tiddlers are system tiddlers, so that export is data-only without any exclusion list.
CONSEQUENCE: the hand-written lists in save-all.tid, $__config_SaverFilter.tid and LITHIC_BASE_FILTER (for uglify and uglify-wizard) are not a generator gap. Do not add a generator step that writes plugin lists into tiddlers, and do not add a parity test for them as a substitute, unless the developer asks.
REVERSED (2026-10-29): a generated export-filter tiddler for a light copy ($:/config/TiddlyTools/Filters/Lithic Light) was tried on 2026-10-22 and removed. The light distribution is built from lithic-light-tw.info and ships with the ESP32 firmware, so a prod wiki does NOT export its own light copy, and no script, workflow step or saved filter should offer one.
QUICKVIEW: kookma/quickview is a json-plugin in external.yml. It reaches the artifact through wiki/tiddlers/, not tiddlywiki.info, so it is not missing and does not need a .info entry.
A .lith file is an extension of the vanilla TiddlyWiki *.tid file format, which is based on an HTTP RFC format for headers and body.
Key differences and requirements for .lith formats:
- It supports multiple tiddlers appended together within a single file.
- The triple-asterism (
⁂⁂⁂) is used as a strict delimiter to separate each individual tiddler inside the file. Do NOT use standard asterisks. - The
titlefield is explicitly required for each tiddler entry within the file. - The
created:andmodified:front matter items are not necessary and should be omitted to save space.
CONTEXT:
The Lithic PKMS wiki is compiled and published automatically via a GitHub Actions CI/CD pipeline (.github/workflows/build-wiki.yml).
PROCESS OVERVIEW:
-
Dependency Installation: The pipeline starts by setting up the Node.js environment and running
npm install. -
Refreshing Vendored Libraries: Before anything is mirrored,
node scripts/vendor-libraries.mjsrefreshes the libraries baked into Lithic plugins fromvendored.yml(prod only, so a variant build ships its branch's bytes). It runs before the mirror step because the mirror copieswiki/local-plugins/over the fetched tree: a library refreshed afterwards would be baked into nothing. The rewritten.tidfiles andvendored-lock.jsonare committed on the release branch, so the updated library and the artifact built from it are reviewed together. See Vendored Libraries. -
Mirroring External Plugins: It dynamically fetches all third-party dependencies defined in
external.ymlusingnpm run mirror. The mirror step then copies the tracked Lithic plugins fromwiki/local-plugins/(minusarchive/) over the fetched tree inwiki/external/. Never place "live" plugins directly inwiki/external/— it is a merge cache, not a source location.- Note on External Plugins: External plugins (such as
tiddlystudy,relink, etc.) are intentionally omitted from the repository itself to keep the source tree clean and ensure they are fetched fresh or from specified remote sources during build time.
- Note on External Plugins: External plugins (such as
-
Flattening:
scripts/flatten-plugins.jsreadsplugin.infotitles out ofwiki/external/and re-derives the clean staging treeswiki/plugins/+wiki/themes/(wiping both first, every run). Retired content underarchive/is explicitly skipped so it cannot leak into builds. It writeswiki/flatten-manifest.log— check it for[SKIP]/[ERROR]entries when adding plugins. -
Configuration Generation: It dynamically generates the TiddlyWiki build configuration (e.g.,
prod-tiddlywiki.info) representing the specific compilation target. -
Compilation: The core
tiddlywikiCLI is invoked to compile the output. For prod builds, the flibbles/uglify plugin is loaded and engaged vianpx tiddlywiki wiki --uglify --build index, minifying core/plugin JS/CSS and the plugin JSON stores (~26% size reduction, 10.7 MB -> ~7.93 MB). Non-prod builds run plain--build index(generate-config.js strips flibbles/uglify from the pre/dev merged configs).- Uglify purge: the tracked local plugin
wiki/local-plugins/lithic-save/overrides the$:/core/save/allshadow with a save filter that hard-excludes$:/plugins/flibbles/uglify(and the wizard plugin) from the published store — the CLI equivalent of the uglify wizard's 'purge uglify-related tiddlers' option, so the uglify engine (~1 MB with its bundled library) never ships inside the artifact. Render-timepublishFiltervariables do NOT reach the core shadow macro on core 5.4.1 (verified), which is why the override plugin exists. - The wikitext uglifier is DISABLED, deliberately (
wiki/local-plugins/lithic-default-configs/$__config_flibbles_uglify_text_vnd.tiddlywiki.tid, valueno). Only JS/CSS/JSON compression runs. Reason (field-tested 2026-09-21): the wikitext pass collapses load-bearing whitespace - it eats the space between SVG attributes and after macro parameters (\parameters (size:"22pt")->\parameters(size:"22pt"),width=<<size>> height=<<size>>->width=<<size>>height=<<size>>), so all ~115$:/core/images/*SVGs become one malformed attribute run. A malformed<svg ...>swallows the following content as SVG child nodes, which browsers never paint - that is why the ahanniga context menu rendered as an empty themed box. It also shifts every slashcommandcaret-pos(the$:/lithic/slashcommands/*bodies lost their spaces), which is the/wb-imagecaret regression. Measured damage: 894 tiddler texts differ vs a plain build (98-99 whitespace-only). Cost of disabling it: +140 KB (7.79 MB -> 7.93 MB, still ~26% below plain). Do NOT 'fix' the SVGs by hardening the tiddlers - the source tiddlers are already correct; only the build mangled them. - The PDF import plugin is EXCLUDED from the uglify pass (
wiki/local-plugins/lithic-default-configs/$__config_flibbles_uglify_blacklist.tiddlywiki.tid, a$:/config/flibbles/uglify/blacklistlist of the plugin's three tiddlers).lithic-import-handlercarries its own pdfjs-dist build, which terser had already minified, and re-minifying that with the bundled uglify-js is what turned every imported PDF page white frombuild-2026.09.16-1658onward: the import still reported success and wrote a whiteboard, and text extraction kept working, so only the pixels said anything was wrong. Bisected between the two 2026-09-16 releases by swapping single unminified tiddler texts back into the bad artifact and measuring the rendered pixels: restoringpdf.jsalone restored every page (0% ink at 255 mean without it, 3-20% ink with it), while the widget, the worker and the handler each changed nothing. Cost of the exclusion: +147 KB on the 8.11 MB artifact (1.8%), measured by building the same tree twice, with and without the config tiddler, and diffing the stored tiddler texts: the plugin's own bundle is the only text that changes between the two builds. The blacklist matches an exact title, and these titles are not the plugin'splugin.infotitle (the tiddlers are$:/plugins/lithic/lithic-import-handler/*inside the bundle$:/plugins/xyvir/lithic-import-handler), soscripts/check-pdf-plugin-unminified.mjsasserts the built artifact still carries each of them byte-for-byte (line endings normalized) and runs in the prod verify step ofbuild-wiki.yml: a renamed tiddler, a lost config tiddler or a changed uglify setting fails the build here rather than in somebody's whiteboard.scripts/test-pdf-import-artifact.mjsis the behavioural half (npm run test:pdf-artifact [artifact] [--pdf file]): it dropsscripts/fixtures/pdf-import-smoke.pdfon a real artifact in headless Chrome and requires ink on every rendered page, and the same tree built without the blacklist fails it at 0% ink on every page. Do NOT harden the plugin's sources against minification, and never 'fix' a re-minified bundle by editing the artifact.
- Uglify purge: the tracked local plugin
-
Post-Processing & Release: The built HTML file is renamed, branded ("Lithic PKMS"), and for production releases, the PWA manifest/offline service worker version is bumped. Prod builds commit BOTH
src/lithic.html(uglified flagship; consumed by the Tauri app, the launcher engine path, the PWA service worker, and build-server.yml) ANDvariants/prod.html(an identical plain-named copy for download). Non-prod builds commitvariants/<env>.html. The final artifacts are committed to arelease/<stamp>branch and opened as a review pull request, and are attached to a GitHub Release when that pull request is merged — in ONE reference archive holding the flagship aslithic.html(taken fromsrc/lithic.html, so the bytes are the ones the app embeds),launcher.html, and the builtwiki/folder with itsflatten-manifest.log. Why one archive rather than four assets (2026-10-30): none of them is a distribution. They are what a maintainer opens to see what a build actually produced, and attached separately they made a download page carry four files to choose between, beside a handful that really are choices. The stamp is the wrapper folder inside the archive, so unzipping drops one directory rather than four items into somebody's Downloads. There is no light build in the release: the light export is generated on the fly by the launcher, so nolithic-light.htmlis committed or attached. It used to attach the flagship twice, aslith.htmland as the identicalprod.html, which read as two artifacts that were the same file;variants/prod.htmlis still committed, it is just not a release asset any more. The FOUR DESKTOP distributions are attached by the chained job instead (.github/workflows/desktop-release.yaml, run bypublish-release.ymlasbuild-desktop, after the merge):Lithic_<MM.DD.YY-HHMM>.exefor Windows, two macOS downloads (below), and two Linux AppImages whose names state which engine each carries, because their sizes differ by a factor of forty and the name is the only thing a downloader sees before the download.Lithic-webgtk_<MM.DD.YY-HHMM>.AppImagebundles WebKitGTK plus JavaScriptCore, about 43.5 MB of its 82 MB, and a name that hid that would make the 82 MB look like a mistake.Lithic_<MM.DD.YY-HHMM>.AppImageis the shim (shim/, assembled byscripts/build-shim-appimage.sh), which links no toolkit at all and serves the launcher and the engine to the browser already on the machine: the name reserved for it on 2026-09-30, now taken. Both Linux AppImages are published, and the 82 MB one is not redundancy to be tidied away: the AppImage catalogue (appimage.github.io) lists an application by opening one AppImage from its newest release and requiring it to draw a window of its own, which a build that serves a page to a browser cannot do, and its picker refuses to guess when one release carries two AppImages it cannot tell apart. So the WebKitGTK build is what that catalogue can carry, the shim stays the Linux distribution, and the two names are what keep them apart. All of them are stamp-named so the downloads of one release are distinguishable at a glance, and the stamp rule is shared with the exe. The macOS job publishes two files rather than one, and Gatekeeper is the whole reason. The disk image (Lithic_<MM.DD.YY-HHMM>.dmg, built--target universal-apple-darwinwith both rustup targets named, because one download has to open on either Mac) is the shape a Mac installs from; the tarred bundle (Lithic_<MM.DD.YY-HHMM>_universal.app.tar.gz) is the same app as one file, and it is not redundancy, because nothing fetches it through a browser:curlwrites no quarantine attribute, so it is the one macOS download with no Gatekeeper step in front of it, and unpacking it anywhere is the whole install. Neither is signed or notarized — a Developer ID and the notarization it enables are a paid annual membership — so a browser-fetched image needs one trip through System Settings → Privacy & Security → Open Anyway. That same decision is why the Homebrew cask lives in the project's own tap (Xyvir/homebrew-tap,brew install --cask xyvir/tap/lithic) rather than in homebrew-cask, whose casks must be signed and notarized; the tap is in the tap's own repository on purpose, because a workflow's token cannot write to another repository, so the tap pulls: a scheduled job there reads the newest release that carries an image, writes the cask from that asset's stamp and checksum, and commits it. Themacos-15runner is pinned for the same reason the Linux jobs pin 22.04 — the label decides the toolchain that produces a release — and it does not raise the artifact's floor: Tauri sets the bundle's own deployment target (10.13 by default, untouched here). The jobs are separate on purpose, so a failure in one costs only its own platform. The AppImage is built onubuntu-22.04rather thanubuntu-latestbecause an AppImage links against the build machine's glibc: a 24.04 base raises the floor to glibc 2.39 and the artifact then refuses to open on Ubuntu 22.04 and Debian 12. That runner is deprecated (retirement 2027-04-17), so the migration is a 22.04 container onubuntu-latest, never a newer runner. -
The launcher UI gallery is the review material. A
deckjob inbuild-wiki.ymlshootsscripts/ui-gallery.mjsagainst the launcher the build just produced. It needs four things the build job does not have, and the workflow says so by name: Node 24 (the deck importslauncher-ui/src/color-palette.tsdirectly, which is type stripping), a Chrome for Puppeteer, ImageMagick 7 for the tiling, and a text font for the tiling to be legible. The middle two arescripts/install-imagemagick7.sh, which fetches the project's own AppImage rather than the distro's packages:ubuntu-24.04runners carry no ImageMagick at all, andapt install imagemagickstops at version 6, which has nomagickentry point for the deck to invoke. The font is the script's other job, for a reason worth knowing: montage asks freetype for its label's metrics before it lays anything out, so a machine with no font fails the tile outright rather than drawing an unlabelled sheet, and removing-labeldoes not avoid it. The image's own package list has one font, an emoji face, and the AppImage bundles neither a font nor a fontconfig of its own, soscripts/sheet-tile.mjsnames a font by path and tiles with+append/-appendwhen there is none to name. The contact sheets are force-pushed to theui-deckbranch as a single commit underdeck/<stamp>/, andscripts/gallery-pr-body.mjscomposes the pull request body out of the deck's ownui-gallery/sheets.jsonandui-gallery/modal-coverage.md, embedding every sheet by raw URL. They are referenced by URL and never committed becauseui-gallery/is gitignored on purpose: 18 MB of PNGs is not a thing to put in the history of the branch under review. The job iscontinue-on-errorby design rather than as a softener: the deck is review material and not a gate, so a pane that cannot reach its state (which failsui-gallery.mjson purpose, so a sheet cannot silently become a picture of the wrong thing) must not stop a release from being reviewable at all. The pull request opens either way, and its description says the pictures are missing. -
Every setup step that repeats across jobs is one definition under
$/.github/actions/, and a step with two copies is a step that drifts.setup(checkout, Node, the npm cache) was already that; this pass addedrust(the toolchain plusswatinem/rust-cache, with the cached workspace and the rustup targets as inputs) for the six jobs that compile Rust, andlinux-deps(the apt list as an input, with the downloads kept across runs) for the three that install system packages, andbrowserfor the two that drive one. The copies had drifted before they were merged:rust-check.ymlinstalled its toolchain before its cache while all four desktop jobs did it the other way round, which is two orders for one pair of steps and nothing in either file to say which is right. Two rules come with a composite: arun:step inside one MUST name itsshell(there is no default shell to inherit), and a new action is referenced the waysetupalready is here,$/.github/actions/<name>.- The icon set is committed, so regenerating it changes nothing.
src-tauri/icons/**is tracked and pixel-identical to whatnpm run tauri icon src/app-icon.jsonwrites (measured 2026-10-16: all sixteen files compared pixel by pixel, no differing pixel, only the encoder's bytes, the fresh set slightly smaller), so the four jobs that each regenerated the set per release were overwriting the committed art with itself and rewriting sixteen tracked files apiece. Onlyandroid-release.ymlstill generates, and not by oversight:scripts/patch-android.mjscopiessrc-tauri/icons/android/**, which no commit carries. Run that command by hand whensrc/app-icon.pngchanges, and commit what it writes. - A job that never drives a browser does not download one.
npm ciinstalls puppeteer, whose install step fetches Chrome unlessPUPPETEER_SKIP_DOWNLOADis set (the browser cache this checkout's own runs filled is 681 MB).desktop-release.yaml,android-release.yml,publish-release.ymlandbuild-wiki.ymlnow set it at the top, and the skip covers the whole file. The only two jobs in the pipeline that drive a browser arebuild-launcher.yml's smoke suite andbuild-wiki.yml'sdeck, and each gets one from$/.github/actions/browser, which caches it: the install line the two were sharing, called where it has to run (after the job'snpm ci, because the command is the repository's own puppeteer), so a repeat run restores the browser instead of fetching it. A browser-needing job added to one of those four files installs one through that action.
- The icon set is committed, so regenerating it changes nothing.
HOW THE WIKI ARTIFACT GETS REBUILT (IMPORTANT): build-wiki.yml builds on push and stages a review. A push to main that changes anything load-bearing runs the prod build and commits src/lithic.html, variants/prod.html, the rebuilt src/launcher.html and the PWA bump, but on a release/<stamp> branch rather than on main, and then opens a pull request carrying them. Merging that pull request is what publishes: .github/workflows/publish-release.yml fires on the src/lithic.html the merge lands, tags the build, creates the GitHub Release and chains the desktop and server jobs. Those chained jobs read the committed src/lithic.html rather than downloading anything: an artifact belongs to the run that uploaded it, and built-wiki is uploaded by this build run while the installers run in the publish-release one, so the two continue-on-error steps that used to sit in each job could never resolve and would only have replaced the committed file with a copy of itself (this build copies wiki/output/lith.html onto src/lithic.html before committing and uploads that same file). They were removed from all six jobs on 2026-10-16; do not restore a download in their place. Closing the pull request publishes nothing and leaves nothing to undo, because no tag and no release exist yet to clean up. That one path is the trigger because only a release writes it and build-wiki.yml deliberately ignores it as an output, which is what stops a merge from starting another build when the release carried nothing but artifacts. It does not cover a release that carried the vendored refresh: vendored-lock.json and the wiki/local-plugins/ body are live paths a hand edit must still rebuild, so the merge of PR #87 (which landed both) rebuilt an identical tree and opened PR #88, whose only diff was the PWA bump. That is the cycle the landing job in build-wiki.yml answers, from the push's own commit subjects rather than from a path list: Release build-<stamp> and Merge pull request #N from <owner>/release/<stamp> commits mean main just received the build this pipeline already reviewed, so nothing is rebuilt and no deck or pull request is opened, while a dispatch, the weekly tick and any unparsable payload still build. checkReleaseTrigger in scripts/pre-push-check.mjs fails if that wiring is dropped. Nobody dispatches a release. A session that pushes several times leaves ONE live review rather than several: each push that builds opens its own pull request, so a person working in legs would be asked to approve the newest release and dismiss a growing list of earlier builds. The open-pr job therefore closes every other open review whose head is a release/<stamp> branch, with a line naming the build that superseded it, after the new one exists and never before it. They are closed and not merged, so nothing is published and nothing needs undoing, and each superseded review's branch is deleted with it: the build that branch carries is one nobody will merge, so leaving it behind is how forty stale release/ branches accumulated on a repository whose reviewer kept missing the delete tick. The closed review still reads after its branch is gone, because GitHub keeps a pull request's head commits reachable at refs/pull/<number>/head. That step is gated too: checkReleaseTrigger fails if it stops listing the open reviews, stops recognising their release/ branches, stops excluding the branch under review, or stops deleting the branch it retires. The cost of the gate is one delay worth naming: deploy/autoupdate.sh pulls src/launcher.html from main on a timer, so a launcher fix now reaches a self-hosted instance when somebody merges its review pull request rather than when the build finishes, and a pull request left open leaves that timer serving the previous launcher. Its filter is a blacklist over **: out are docs, CI config, the local-only harness and the paths the release commits itself, so a wiki-source edit (any .tid under wiki/local-plugins/) or a launcher-ui/src/** edit reaches the review pull request with the push, not whenever a human remembers to dispatch. Dispatch is still how you get the other configs (pre/dev/all) and a dry run, and it is the only way to run an edit to the workflow itself, since .github/** is excluded. build-launcher.yml is still a manual preview run. (Until 2026-09-23 bump-pwa-version.yml fired on any push touching src/lithic.html or src/launcher.html and committed its own version bump; it is manual now, because a prod release bumps the PWA itself and an unattended writer to main is what rejected a release's final push — see the policy block below. Automatic releases came back deliberately on 2026-09-24, once the local gates that verify the tip being pushed — scripts/pre-push-check.mjs (launcher-ui tests, svelte-check, cargo check/clippy/test), the Puppeteer smoke, the offline gate — were in place: hand-dispatching was the answer to an unverified main, and that is no longer the situation.) Do not rebuild src/lithic.html locally and commit it: the JSON key order inside the plugin bundles follows the host filesystem's directory order, so a Windows build differs from the Ubuntu runner's in key order alone (same 48 tiddlers, every individual tiddler hashing identically, ~19 bundles affected). The artifact the launcher ships is separately checked by npm run check:push, which compares a fresh Vite build with the committed src/launcher.html and fails only when the change being pushed would carry a locally built copy of it.
GENERATED ARTIFACTS ARE CI-ONLY (IMPORTANT):
CONTEXT: src/lithic.html, src/launcher.html and variants/*.html are build OUTPUT, committed only because the repository itself is their delivery channel: deploy/autoupdate.sh pulls src/launcher.html from raw.githubusercontent.com on a timer, deploy/Dockerfile COPYs it, and the Tauri bundle embeds it. Nothing on the receiving end builds, so the committed bytes ARE the shipped bytes.
POLICY — a local build is a test, never a release:
npm run build:launcher(and a localtiddlywiki --build index) exist so you can run and inspect a change against the shipped shape. Treat whatever they write as scratch output.- Never commit or push a locally built artifact. If a local build is sitting in your tree when you go to commit something else,
git checkout -- src/launcher.html src/lithic.htmlfirst — a stray local build swept into an unrelated commit is how the artifact drifts from its sources. - To get a newer artifact, PULL it (
git pull, orgit checkout src/launcher.html) after the release lands. Do not manufacture one locally to catch up. - If you changed
launcher-ui/src/**or anything underwiki/local-plugins/, say so when handing the change over: the release starts itself when the push lands, so a stale committed artifact is the normal state only for the minutes between that push and the run it triggered —git pullwhen it lands, and never manufacture the artifact by hand.
WHY (incident history, 2026-09-23): the browser-storage fallback had to reach deployed instances, and with no release in flight the only route was a hand-built src/launcher.html plus a hand-pushed PWA bump — precisely the reflex this policy ends. Within the hour a prod release, dispatched to do that job properly, died at its FINAL push: main had moved while the build ran (an unrelated commit), git push was rejected, and because that commit exists only on the runner, the rebuilt artifacts, the tag, the GitHub Release and the build-tauri/build-server jobs went with it. Two separate lessons — nothing should be pushed while a release is building, and the artifact never needed to be built locally in the first place. Both are now mitigated mechanically: build-wiki.yml and bump-pwa-version.yml share a repo-wide concurrency: group: main-writers (two writers now serialize instead of racing), and every CI push to main goes through scripts/ci-push-main.sh, which retries onto the new tip rather than letting one rejected push discard a finished release. That retry no longer covers a prod release, which stages its commit on a branch and is therefore never rejected; it now covers the non-prod variant commits and bump-pwa-version.yml.
THE GATE NO LONGER ASKS FOR A COMMIT (2026-10-27): scripts/check-launcher-artifact.mjs used to FAIL on a stale artifact and print git add src/launcher.html && git commit, which is the one instruction this policy forbids and the loudest reason local builds still got published: a change under launcher-ui/src/** CANNOT satisfy that gate without one, because CI can only regenerate the artifact once the source is on main. It was followed on 2026-10-27: a launcher change was committed with a locally built artifact and pushed, and because src/launcher.html is one of the four paths publish-release.yml triggers on, that push was read as a hand-pushed release and cut a dated tag, its desktop installers and its APK from a commit nobody had reviewed. The gate now FAILS on the act itself (the artifact staged here, or in the commits this branch would push) and warns, passing, when the committed artifact merely differs from a fresh build, naming git pull and the release that regenerates it as the two ways out. It also builds into a scratch file: the old gate rebuilt the published path and left the result in the tree, which is the other half of the same trap, since a stray local build is one git add away from being shipped. No case is left that needs git push --no-verify for this gate.
IMPORTANT DIRECTORY RULES:
wiki/plugins/,wiki/themes/,wiki/tiddlers/,wiki/external/are ephemeral build staging (all gitignored) — regenerated from scratch on every build. NEVER edit or commit anything there; all edits belong in the tracked sources:wiki/local-plugins/<plugin>/(Lithic plugins),external.yml(third-party deps), and the<env>-tiddlywiki.infoconfigs. See the Plugin Directory Map section near the top of this file.- The items within the
assets/directory are merely for local reference and debugging. They should NOT be manually edited. The CI/CD pipeline dynamically handles fetching the definitive external dependencies based onexternal.ymlduring the build process. - The
TIDDLYWIKI_PLUGIN_PATH/TIDDLYWIKI_THEME_PATHenv vars in.github/workflows/build-wiki.ymlpoint at the staging dirswiki/+wiki/plugins— they exist only so the CLI can load the flattened plugins at compile time. Local builds MUST set them too (e.g.TIDDLYWIKI_PLUGIN_PATH="$PWD/wiki:$PWD/wiki/plugins" TIDDLYWIKI_THEME_PATH="$PWD/wiki/themes" npx tiddlywiki wiki --build index): without them the CLI silently builds from core plugins only, producing a tiny (~3.8 MB), plugin-lessindex.htmlthat looks like a successful build.
CONTEXT:
When creating or editing JavaScript plugins, macros, or startup modules in TiddlyWiki via .js.tid files, the boot parser requires a specific dual-header format to function correctly.
PROBLEM:
If a .js.tid file is missing the leading plain-text frontmatter, or missing the /*\ comment block, the TiddlyWiki boot sequence will crash with a Syntax error in boot module or Unexpected identifier error. The core $tw.boot system reads the /*\ block to extract module metadata before the main parser is loaded.
STANDARD OPERATING PROCEDURE:
Every .js.tid file MUST contain the module metadata twice:
- Once as plain-text tiddler fields at the very top of the file (e.g.
title: ...,type: ...,module-type: ...). - A second time inside a
/*\...\*/block comment immediately preceding the JavaScript code.
(Note: The created: and modified: fields are not necessary and should be omitted from both the plain-text headers and the comment block metadata).
Example Format:
title: $:/Lithic/Widgets/example.js
type: application/javascript
module-type: widget
/*\
title: $:/Lithic/Widgets/example.js
type: application/javascript
module-type: widget
Description of the module goes here.
\*/
(function(){
"use strict";
// Your JS code here
})();CONTEXT:
The user relies on a custom TiddlyTools filter dropdown UI (referred to as FilterOps) for quickly accessing saved filters.
PROBLEM:
If you create a custom saved filter and place it in a standard namespace (e.g., $:/lithic/Filters/...), it will show up in the default Advanced Search but will not appear in the FilterOps dropdown. The dropdown explicitly looks for a specific TiddlyTools prefix to build its menu.
STANDARD OPERATING PROCEDURE: When creating or modifying saved filter tiddlers that are meant to be quickly accessible by the user, you MUST place them within the TiddlyTools namespace so they integrate with the custom UI automatically.
- Title Prefix: Must start exactly with
$:/config/TiddlyTools/Filters/- Example:
title: $:/config/TiddlyTools/Filters/All Highlights
- Example:
- Tags: Must be tagged with
$:/tags/Filter - Description: Include a
descriptionfield which is what will be displayed in the dropdown menu.- Example:
description: All Highlights
- Example:
- Filter: The actual filter logic goes in the
filterfield.
Example Tiddler (*.tid):
title: $:/config/TiddlyTools/Filters/My Custom Filter
tags: $:/tags/Filter
description: My Custom Filter
filter: [tag[SomeTag]] -[is[system]]CONTEXT:
The .lith deserializer/importer (register-lith-extension.js) automatically injects type: text/markdown into any non-system tiddler that lacks an explicit type field during import.
QUIRK / EDGE CASE:
The .lith exporter does not have symmetric logic to strip this out or explicitly mark native vnd.tiddlywiki types. This was an intentional decision to keep the exporter lightweight.
As a result, if a standard TiddlyWiki tiddler (which implicitly defaults to vnd.tiddlywiki) is exported to a .lith file, it will be exported without a type field. If that same file is subsequently re-imported, the importer will catch it as a "no-type non-system tiddler" and erroneously convert its type to text/markdown.
STANDARD OPERATING PROCEDURE:
If you encounter weird formatting issues where standard tiddlers suddenly behave like markdown after being passed through a .lith export/import cycle, be aware of this asymmetrical behavior. Do not try to "fix" the exporter with heavy JS macros unless explicitly requested again.
CONTEXT: the in-wiki exporter is what the scratch editor's "output to .lith" workflow runs. Each rule below is the reverse of a bug that shipped, all re-verified headlessly against a real engine (5.4.1).
- Render the block in the exporter; never transclude
$:/core/templates/tid-tiddler. That template's text begins with a newline, so every block it renders — the first included — opens with a blank line. The parser then took that blank line as the field separator, swallowed the field section into the body, and produced a tiddler with no title, which the engine will not boot around: the file white-screened on mount and looked corrupted rather than off by one newline.parseLithToJSONnow skips leading blank lines too (defence in depth), but the emit side renders fields and text itself so its bytes matchserializeJsonToLithexactly (bar the.tidfile's own trailing newline). Two traps: the$name$: $value$separator inside thetemplateattribute must be a REAL newline (a literal\nescape is not decoded there, and shipstags: x\ntitle: yas one line), and the separator goes between blocks (<$reveal default=<<counter-last>>), never before the first, so nothing can lead the file. - Exclusions must name a source:
-[all[tiddlers+shadows]prefix[x]], never-[prefix[x]]. A-run whose content is a bare prefix operator is re-evaluated as a source, and source operators only see real tiddlers — so everything the engine contributes as a shadow (themes, core, plugin bundles) survived it. Measured on the shipped build:-[prefix[$:/themes]]removed 3 of 63 theme tiddlers,-[prefix[$:/core]]removed 0 of 871; the sourced form removed all of each. The exported file is mounted on top oflithic.html, so a stale baseline copy in a.lithoverwrites the current engine tiddler — this is a correctness bug, not just bloat. - The filename comes from the active query, never the word "tiddlers". The
filenamefield finds the saved query whosefiltermatchesexportFilterand uses itsdescription, sanitised withsplitregexp[\s+]join[_], falling back toexport. A saved query is a$:/config/TiddlyTools/Filters/<Name>tiddler holding the filter in a field (get[filter], not its text); match withfield:filter<exportFilter>(a literal operand cannot contain[/]and errors with "Missing [ in filter expression").replace[...]returned nothing in this build —splitregexp+joinworks.
SCOPE: the exclusions cover what the launcher injects (~-prefixed overrides, $:/plugins/lithic/ephemeral/*, $:/config/OfficialPluginLibrary) plus the engine and session classes the .lith save path already drops (boot, core, themes, temp, state, HistoryList, $:/StoryList). Plugin roots are deliberately kept, so a plugin the user installed into their wiki still round-trips.
CONTEXT:
TiddlyWiki's core HighlightPlugin uses the $:/config/HighlightPlugin/LanguageMappings dictionary to map Tiddler MIME types (e.g., text/x-python) to languages for rendering entire tiddlers.
However, this config dictionary DOES NOT map the identifiers used in Markdown-style codeblocks (e.g., ```jspython).
PROBLEM:
If you try to alias a custom codeblock language like jspython to python by adding it to $:/config/HighlightPlugin/LanguageMappings, the core widget will not recognize it and the codeblock will not be highlighted.
STANDARD OPERATING PROCEDURE:
To register new codeblock languages or aliases so that ```customlang is properly styled, you must do it programmatically by hooking into the highlight.js engine on startup.
Create or modify a TiddlyWiki JS startup module (like wikitext-highlighter.js.tid) and call hljs.registerLanguage or hljs.registerAliases directly on the hljs object:
var hljs = window.hljs || require("$:/plugins/tiddlywiki/highlight/highlight.js");
if (hljs && typeof hljs.registerAliases === "function") {
hljs.registerAliases('customlang', {languageName: 'existinglang'});
}CONTEXT:
TiddlyWiki parses files from top to bottom. Macro definitions (\define) and other pragmas (\rules, \whitespace) are interpreted differently from regular wikitext body elements.
PROBLEM:
If you place HTML elements (like a <style> block) or normal wikitext before or in between \define statements, the TiddlyWiki parser switches from "pragma mode" to "body mode". Any subsequent \define macros will not be parsed as macros, but instead will be rendered directly to the screen as raw text.
STANDARD OPERATING PROCEDURE:
All \define macros and pragmas MUST be placed at the absolute top of the .tid file, consecutively, before any HTML tags, styles, or standard wikitext. If you need to add a <style> block or HTML, place it after all \define blocks have concluded.
CONTEXT:
TiddlyWiki filter syntax and widget/action behavior are subtle and under-documented. The built monoliths (variants/pre.html, src/lithic.html) embed the entire wiki as a JSON tiddler store, and Chrome can boot them headlessly. Empirically validating filter chains and action wikitext this way caught multiple real bugs that reading minified core source alone did not (sortsub operand parsing, $let first-element resolution, $action-setfield list mangling).
STANDARD OPERATING PROCEDURE:
- Tools: Node.js is NOT reliably available. Use Python 3 + headless Chrome for execution — the concrete paths for THIS machine live in the gitignored
.freebuff/local/agents.local.md(relative to the repo root), so rootagents.mdstays environment-agnostic. - Pick a bootable build: use
src/lithic.htmlONLY —variants/pre.htmlis a STALE build and must NOT be used for validation (it has misled us before).assets/blank_no_server.htmlis NOT bootable (bare store, no boot machinery). - Boot readiness quirk: the Lithic build ships a custom
wiki.jswhosegetTiddlers()takes an OPTIONS object and EXCLUDES system tiddlers by default (returns ~0 on a plugin-heavy monolith) — sogetTiddlers().length > 0is NOT a valid readiness probe. Probe$tw.wiki.getTiddler('$:/plugins/sq/streams')instead (plus$tw.rootWidgetfor widget work). - Inject a harness: write a small Python builder that reads the build HTML, inserts a
<script>test block immediately before</body>, and writes a copy (e.g.scripts/_test.html). The harness pollswindow.$tw && $tw.wiki && $tw.rootWidgeton asetInterval(boot is asynchronous), then runs assertions into a<pre id="out">element. - Run it:
"/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --disable-gpu --no-sandbox --virtual-time-budget=30000 --dump-dom "file:///.../_test.html"then extract the<pre id="out">text (sed between the<pre>tags and strip tags). - Invoke context-menu action wikitext:
wiki.parseText("text/vnd.tiddlywiki", body).tree→$tw.rootWidget.makeChildWidget({type:"widget", children: tree})→w.render(container, null)→ recursively walk the tree callinginvokeAction(node, null)on every widget that exposes it. - Invoke a single action widget directly: build
{type: "action-listops", attributes: {name: {type:"string", value: ...}}}. CRITICAL: callwidget.render(host, null)BEFOREinvokeAction()— attributes (e.g.$subfilter) are only computed inrender()→computeAttributes()/execute(). Skipping render silently no-ops the action.
GOTCHA: fixtures must be realistic. Alpha-sort tests passed with space-less titles but failed on real data: use bracket-wrapped, space-containing list entries (e.g. [[6th August 2026@1:40:02.470]]) and multi-child streams.
HARNESS PHILOSOPHY — it's a sieve, not an oracle: the harness reliably filters out parse-level bugs (filter errors, wrong operator semantics, list mangling). Do NOT chase harness perfection — results that depend on widget-scoped variables (which don't resolve headlessly in this build) go straight into the user's meatspace checklist with specific instructions, and unexpected edge cases are passed down for meatspace verification rather than debugged in the harness. Also: the extraction regex MUST allow attributes on the pre tag — the injected finish() sets style, so match <pre id="out"[^>]*>(.*?)</pre> (a bare <pre id="out"> silently fails and falls back to a truncated tail dump).
KNOWN HEADLESS LIMITATION (this build): widget-scoped variables do NOT resolve in headless boots. $tw.rootWidget.setVariable("x","3") followed by filterTiddlers("[<x>]", r) yields [""], and <$let>/<$set>-scoped variables render blank through $list. Only VARIABLE-FREE filter chains are reliably verifiable headlessly — substitute literal titles instead (e.g. [[Title]get[field]]). Any behavior that depends on widget-scoped variables (like the context-menu label keys) must be verified by the user in meatspace.
CONTEXT: all verified empirically against TiddlyWiki 5.4.1 headlessly; several contradict the official docs or common usage.
sortsubis broken for field operands.sortsub[{!!text}trim[]lowercase[]](the documented idiom) evaluates to nothing in 5.4.1 — the operand is parsed as a literal title. Use thesortoperator directly:[enlist{!!stream-list}sort[text]]sorts the input by a field, case-insensitively by default.enlist[]reads its OPERAND, not the input. To parse the filter's input as a list useenlist-input[]— that is why streams writesenlist{!!stream-list}(operand form) everywhere, and why conditions must use[<currentTiddler>get[stream-list]enlist-input[]count[]!match[0]].- NEVER write a list field via
$action-setfieldfrom a filter result.$value={{{[enlist<var>]}}}writes bare titles; TW's list parser treats spaces as separators, so6th August 2026@1:40:02.470shreds to2026@1:40:02.470. Always use$action-listopswith$subfilter(or$filter) — core parses the field viagetTiddlerListand writes it back viastringifyListas[[bracketed]]entries that round-trip. $action-listops$subfiltersemantics: core prepends"[all[]] "to the subfilter, and[all[]]with an EMPTY operand is an IDENTITY (returns the input unchanged) — so the subfilter genuinely operates on the parsed list (e.g.$subfilter="[sort[text]]"sorts the list in place;reverse[]flips it).- A
-filter run whose content is a bare prefix/field operator is evaluated as a SOURCE, not against the accumulated list — it therefore sees real tiddlers only and silently leaves every shadow in place (see the.lithExporter Rules section for the measurement). Write the source explicitly:-[all[tiddlers+shadows]prefix[x]]. Two related traps::except[a b]pipelines its clauses as AND (one:exceptper clause, or none of them apply), and a prefix run given a literal operand cannot contain brackets. - Multi-value
$letvariables expose only their FIRST element as the stringvalue(the full array lives in a hiddenresultList). So[<children>match<ascending>]silently compares first elements only — effectively always "equal" for permutations sharing the first item. Compare JOINED strings instead:$let sorted={{{[enlist{!!stream-list}sort[text]join[|]]}}}then[enlist{!!stream-list}join[|]match<sorted>]. - Use
join[|]as a list-join delimiter, notjoin[,]— commas are legal in tiddler titles;|is not, andjoin[|]parses fine as an operand (verified). has[done]checks a FIELD;tag[done]checks the TAG. The streams interactive checkbox stores state as thedonetag — ahas[done]condition silently never matches.- Avoid literal bracket-prefix operands like
prefix[[x] ]]— in the current build they produce a hardFilter error: Missing [ in filter expression(verified:[addprefix[[x] ]]]and every strip/prefix chain using[[ ] ]]-style literals fails). Define prefixes as variables ($vars todo1="[ ] " done1="[x] " num1="<<num>> ") and useprefix<todo1>/removeprefix<todo1>— the established streams pattern. CRITICAL: after a~separator, a variable run MUST be bracketed —~<done1>is parsed as the LITERAL TITLE<done1>(returns["<done1>"]), while~[<done1>]resolves the variable (returns[""]when unset). Verified both forms. - Don't chain
+[op...]after~union alternatives — attach the chain inside each run:[<t>removeprefix<done1>addprefix<num1>] ~[<t>removeprefix<done2>addprefix<num1>]. matchcompares single strings. For list-equality, join both sides first (see #5).removeprefix/addprefix/prefix/then/else/count/reverse/first[]/is[tiddler]/tag[]are all verified working as expected.$action-listops$tagsexpects FILTER entries with bracket-wrapped tags.$tags="-[done]"parses as an invalid filter and SILENTLY writes the error stringFilter error: Missing [ in filter expressioninto the tiddler'stagsfield (corrupting it). Use$tags="-[[done]]"/$tags="+[[tag]]"(the+/-prefix with[[brackets]]). Verified:-[[done]]cleanly removes the tag; this bug shipped once in cycle-leadmark and was caught by the harness.- Expressing bracket characters in filter strings: use regexp unicode escapes, not literals. Literal
[ ]operands get mangled (see #8), but a regexp operand can carry the characters as escapes and parses cleanly:[all[]search:text:regexp[\x5B \x5D]](character class matching[, space,]) — verified headlessly; it even catches plugin bundles whose JSONtextcontains brackets. CAVEAT for harness probes: the JS string layer decodes\x5B→[before TiddlyWiki sees it, so in JS test strings write\\x5B(double-backslash) so the filter receives a literal\x5B; in wikitext the raw\x5Breaches the filter parser intact and only the regexp engine decodes it. ~between runs is IF/ELSE, not union.[[A]] ~[[B]]yields["A"]— the second run is ONLY evaluated when the accumulated results so far are empty ([<v>match[zzz]] ~[[LIT]]→["LIT"]). Great for fallback/else chains (e.g. the ctx-label keys), but you cannot accumulate values across~runs. Verified on the current build (core 5.4.1); a code review once flagged two false-positive bugs by assuming union semantics.
CONTEXT: the vanilla Streams plugin source is NOT in the repo (fetched at build time via external.yml); a reference copy lives at assets/streams_and_fusion.json (a JSON array of plugin blobs — each blob's text field is itself JSON containing that plugin's tiddlers). Streams-specific patches live in wiki/local-plugins/lithic-patch-streams/.
Adding an item to the nodestream right-click menu (the Streams context menu — distinct from the standalone generic context-menu plugin):
- Create a tiddler tagged
$:/tags/streams/contextmenuwith:sq-contextmenu-name: <menu label>(shown in the menu)text:= the action wikitext (invoked on click;currentTiddleris the right-clicked node)- OPTIONAL
sq-contextmenu-condition:= a filter; if it evaluates empty the item is hidden (e.g.[<currentTiddler>get[stream-list]enlist-input[]count[]!match[0]]hides on childless nodes). The template override in lithic-patch-streams ($:/plugins/sq/streams/contextmenu/contextmenu-template) wraps every item in a conditional<$list>with anelse[yes]fallback, so items without the field remain visible — backward compatible.
- Operate on children with
[enlist{!!stream-list}is[tiddler]]; operate on the node itself when childless by branching on[enlist{!!stream-list}is[tiddler]count[]!match[0]]with anemptyMessagethat re-runs the ops on<<currentTiddler>>. - For multi-target ops use
<$list filter="..." variable="target">with inner$let/$listconditionals and$action-setfield/$action-listops. Widget attributes are computed at RENDER time from pre-click state, so keep per-target transitions free of cross-target dependencies. 3b. NEVER iterate a multi-value$let/$varsvariable through$list filter="[<var>...]"— a multi-value variable exposes only its FIRST element to filters (the full array lives in a hiddenresultList; see gotcha #5). Real shipping bug: a sibling list computed astargetList={{{ [<currentTiddler>get[parent]get[stream-list]enlist-input[]is[tiddler]] ~[<currentTiddler>] }}}and iterated with[<targetList>is[tiddler]]silently processed only the FIRST sibling — meatspace found it ("only top item cycled"). Re-read the field instead:$set name="currentTiddler" filter="[<currentTiddler>get[parent]]" select="0"then[enlist{!!stream-list}is[tiddler]](the established pattern alpha-sort and the children branch use). Root fallback: gate on[<currentTiddler>get[parent]get[stream-list]enlist-input[]is[tiddler]count[]match[0]]and iterate[<currentTiddler>]. - Reference implementations:
$__lithic_streams_contextmenu_alpha-sort.tidand$__lithic_streams_contextmenu_cycle-leadmark.tid. - Dynamic labels (children vs siblings): the template computes a label key from the target node (
currentTiddlerin the template is the right-clicked node;contextmenu-stateis in scope). A~else-run chain pickssq-contextmenu-name-children(has children),sq-contextmenu-name-siblings(childless with peers), or the basesq-contextmenu-name(childless lone node); the title is[<listItem>get<ctxLabelKey>] ~[<listItem>get[sq-contextmenu-name]] +[first[]]. Items opt in by defining the extra fields; non-dynamic items fall through tosq-contextmenu-name. - Hover-gated preview highlight (no JS): the streams context menu is transcluded ONCE per stream at the top level of
.stream-root(innodes-list-template) and TW's popup$revealrenders inline, so.stream-root:has(.sq-contextmenu .sq-ctx-item:hover) [data-node-title="X"] { ... }scopes the hover state cleanly. A wikitext stylesheet (tagged$:/tags/Stylesheet, resolving the state via[prefix[$:/state/sq-context-popup]get[current]!is[blank]first[]]) emits per-title selectors for the affected rows (children rows, or the parent'sstream-listwhen childless) gated by that:has()— for both a palette-aware bullet (<<colour primary>>) and the node background (the contrast core's--lithic-c-notify-bg/-fgroles -- the palette's own notification/message pair with a contrast-locked ink. Those roles are derived from the exact fields this band used to hard-bind, so both bands stay identical while the ink is repaired on palettes whose raw pair is unreadable, e.g. Nord). Requires:has()(Chrome/Edge 105+, Firefox 121+, Safari 15.4+). Reference:$__lithic_streams_styles_ctx-preview.tid.
Streams internals worth knowing:
- The interactive checkbox is
<$checkbox tag="done"/>(in$:/plugins/sq/streams/templates/stream-row-body) — checked state = thedonetag on the child tiddler, not a field. - The autonumber leadmark is the literal
<<num>>prefix;$:/lithic/macros/numrenders the node's 1-based position within its parent via[<currentTiddler>get[parent]get[stream-list]enlist-input[]allbefore<currentTiddler>count[]add[1]]. - Leadmark prefix conventions (from
$:/plugins/sq/streams/action-macros):todo1="[ ] ",todo2="- [ ] ",done1="[x] ",done2="[X] ",done3="- [x] ",done4="- [X] ",num1="<<num>> ", plus bullets-/*. - Vanilla context-menu selection highlight (source:
$:/plugins/sq/streams/stylesin the built store): the node background IS palette-aware —background: <<color notification-background>>; color: <<color message-foreground>>applied to[data-node-title="{{!!current}}"]AND its+ divchildren container (that's the "parent + children glow"). The bullet border, however, is HARDCODED#5778d8(NOT palette-aware). The ctx-preview stylesheet patches the bullet to<<colour primary>>and extends both effects to the affected rows (children/peers) under hover.
CONTEXT: Lithic users frequently switch between light and dark themes (palettes). Hardcoding HEX or RGB colors in styles will break the UI contrast when the theme changes.
STANDARD OPERATING PROCEDURE:
When applying custom styling, always use TiddlyWiki's core <<colour>> macro to resolve colors dynamically from the active palette, rather than hardcoding static hex colors.
Common Lithic Palette Variables:
<<colour primary>>: The main accent color (great for borders, highlights, active states).<<colour background>>/<<colour foreground>>: The base wiki background and text color.<<colour tiddler-background>>: The background color of standard tiddler frames.<<colour code-background>>: Very subtle off-background color (great for subtle UI highlights).<<colour muted-foreground>>: Dimmer text for secondary or inactive information.<<colour selection-background>>: The highlight color used when selecting text.
Example Implementation:
If injecting styles via a <style> block in wikitext, you can evaluate the macro directly:
<style>
.my-custom-class {
background-color: <<colour code-background>>;
border-left: 2px solid <<colour primary>>;
color: <<colour muted-foreground>>;
}
</style>- Environment-agnostic policy: root
agents.mddeliberately carries no machine-specific paths. Concrete tool paths (Python, Chrome), the notification-chime convention, and machine-specific workflow details live in the GITIGNORED.freebuff/local/agents.local.md(relative to the repo root) — read it if present. src/lithic.htmlis still not byte-reproducible across machines, for a reason no lockfile can fix (measured 2026-09-21): building the wiki locally and diffing against CI's committed artifact gives the same 48 tiddlers in the same order, with 19 plugin bundles differing only in JSON key order — every tiddler inside them hashes identically. The inner order follows the order tiddlers were loaded from the plugin folders on disk, which differs between Windows and the Ubuntu runner (the ext4/htree order is stable for a given runner, so CI-vs-CI agrees while local-vs-CI does not). Practical consequences: a locally rebuiltlithic.htmlwill not match the committed one, so do not treat that artifact's diff as meaningful, and never "fix" a divergence by copying a local build over it. Closing it properly means sorting titles at whatever point folds plugin tiddlers into the bundle JSON (not yet located) rather than relying on enumeration order.- Builds:
src/lithic.htmlis the current monolith (Tauri rolls it up) — use it for headless validation.variants/pre.htmlis a STALE build — do NOT use it.assets/blank_no_server.htmlis NOT bootable. - Line endings: repo
.tidfiles (andagents.md) are CRLF. Editing tools write LF — convert to CRLF BEFORE runningtrim.ps1, and pass ONE file path pertrim.ps1 -Filesinvocation. - Reading core sources: every built HTML embeds all plugins as a JSON array inside
<script class="tiddlywiki-tiddler-store" type="application/json">. Locate the$:/coreplugin object (the preceding character must be{), thenjson.loads(core["text"])["tiddlers"]yields every core module (widgets, filter operators) — far more reliable than grepping minified blobs. A module lives at a key like$:/core/modules/widgets/action-listops.js. - Rollup JSON for meatspace testing: after each major iteration that changes plugin tiddlers, generate a standalone importable rollup so the user can verify in their live wiki:
python scripts/make-rollup.py rollups/<date>-<feature>.json <changed .tid files...>. It emits the TiddlyWiki import format (a JSON array of tiddlers with every frontmatter field +text, including shadow-override titles like$:/plugins/sq/streams/contextmenu/contextmenu-template). Sync the rollup to the primary checkout; the user imports it into their live wiki and hand-tests.- Always use this script - never hand-roll the JSON. The format is a flat top-level JSON array of flat tiddler field objects; any wrapper (
{"tiddlers": ...},{"tiddler": {...}, "body": ...}) makes the importer show an empty/blank tiddler list. This bit us twice. For ad-hoc tiddlers (e.g. a self-test page), write them as a real.tidfile first (scratch/ is fine) and pass them to the script like any other. - Before handing the rollup over, prove it imports: run the array through the real deserializer (
require('tiddlywiki/core/modules/deserializers.js')['application/json']- seescratch/rollup-check.js) and confirm every tiddler has a title and non-empty text. - Format alone is not enough - also parse- and render-gate changed widget/macros: importing cleanly says nothing about whether the wikitext still parses. Real shipping bug: replacing
fullChart={{{ [...] }}}>(filter transclusion + widget-tag close) withfullChart=<<pyramidData>>silently swallowed the tag's own>(the macro's>>ate it), the<$let>never closed, and the whole sidebar rendered as literal</$let>text. Never end a widget tag on a bare=<<macro>>attribute - wrap in{{{ [...] }}}>or add the explicit>. Gate changed tiddlers by rendering them in the real built wiki (parseTiddler + makeWidget from$tw.rootWidget, container attached todocument.body, poll for async mermaid SVG) and asserting no literal widget syntax (</$let>,<$mermaid,classDef) leaks into text nodes - seescratch/render-gate.js(also seeds a stream +$:/StoryListbecause the pyramid renders empty without one).
- Always use this script - never hand-roll the JSON. The format is a flat top-level JSON array of flat tiddler field objects; any wrapper (
- **Critical (field-tested 2026-09-16): in mermaid 11 html-label mode the label DOM is
foreignObject > div.labelBkg > p > span.edgeLabel, and mermaid's own internal stylesheet paints the lightedgeLabelBackground(rgba(232,232,232,0.8)) on the<p>/.labelBkg- theming only the span/div leaves a white-on-white box that computed-style checks on spans happily report as "themed". Any edge-label theming rule set MUST includeforeignObject pand.labelBkg, and gates must assert no opaque light background painters anywhere insideforeignObject(scan every element; skip bare-SVG elements for background-color since it computes but never paints there) - see the light-painters check inscratch/edge-contrast-gate.js.
The commands, in one place. They were restated (with their assertion counts) at the end of every round's entry until 2026-10-02, which said the same thing sixty times and made the log three quarters of this file. A round now says which of these it ran, not how many assertions they hold, and it does not claim one it could not run: a check the machine cannot perform is worth saying out loud ("the desktop crate is CI-verified only on this box, because it needs GLib and WebKitGTK"), and is never worth silently skipping.
- Everything at once:
npm run check:push. It is the push gate, and it chains the copy rule, the locale pin, the artifact freshness check, the offline launcher gate andscripts/pre-push-check.mjs(which itself runs the phone's compile face, the lockfile sync, the workflow YAML sanity, the shim build tag, the release trigger, andcargo check,clippyandtestfor both crates). A failure here is the answer to "is this pushable". - The launcher's own gates:
npm run check:copy(no em dashes or en dashes in any launcher or shim file),npm run check:locale(the language pin rewrites the redirector and the install manifest and nothing else), andnpm run check:offline(the launcher's offline mode, in a browser). One more,node scripts/check-launcher-artifact.mjs, FAILS whensrc/launcher.htmlis part of the change a push would carry (staged here, or in a commit this branch would take upstream), and otherwise compares the committed copy against a fresh build oflauncher-ui/, warning and passing when they differ: the server image and the PWA manifest both ship that file by name, and after a launcher-source change the committed copy IS behind until CI rebuilds it, which the push itself starts. Expect the warning after such a change, and pull the artifact when the release lands: building one and committing it is the thing the policy above forbids. The build the gate makes lands in a scratch file, so a check never writes the published path. - The launcher's tests:
npm --prefix launcher-ui run check(svelte-check; must be 0 errors and 0 warnings) andnpm --prefix launcher-ui run test(the unit suite, which isnode --experimental-strip-types --experimental-specifier-resolution=node --test src/*.test.ts).npm testis the same suite through a cleannpm ci. - The Rust:
cargo test --manifest-path shim/Cargo.tomlandcargo clippy --manifest-path shim/Cargo.toml --all-targets -- -D warnings. The desktop crate is the same three commands againstsrc-tauri, and it needs GLib, GDK and WebKitGTK development packages: run them where those exist (CI does) and say so when they do not exist here. - The phone's compile face (one command, no SDK, no NDK):
npm run check:android-face—scripts/check-android-face.mjs, which is also a step in the Rust Check workflow and inscripts/pre-push-check.mjs. Android is the only platform wherelib.rsresolvesgitcoretogitcore_unsupportedrather than the libgit2 module, so it is the only arrangement in which the sync contract's surface is checked against the stub, and no flag switches a host build into it. The script copiessrc-tauri,shared/andsrc/into a throwaway directory, rewrites the 23cfg(target_os = "android")predicates in that copy toall(), and checks the library there against the crate's own target directory, so only the crate itself is compiled. Three things it arranges are asserted in the copy rather than trusted (the libgit2 module pruned, the stub as the git face, the git half ofshared/sync_core.rspruned the way the phone prunes it), because a rewrite that stopped matching the crate's spelling would compile the desktop's arrangement and pass. Two limits are deliberate and stated at the script: the phone's document answers inplatform/android.rscall Tauri APIs that exist only in a Tauri-for-Android build, so those bodies keep the phone's pruning and the APK job stays their gate; and the verdict line carries cargo's own evidence, with a pass refused outright when nothing was compiled — the first version of this gate readsrc_pathoffmessage.targetwhen cargo puts it besidemessageon the JSON line, dropped every message as a stranger's, and reported a clean pass over a copy that failed with fiveE0425s. - The browsers:
npm run test:puppeteer(the launcher smoke suite, which drives the real built artifact in a real browser;PUPPETEER_EXECUTABLE_PATHpoints it at a system Chromium when it cannot download its own) andnpm run gallery(the UI gallery, which photographs every state the launcher can be in). The smoke suite is the one that catches what the unit suites cannot: layout, keyframes, and whether a control is reachable at all.npm run check:pdf-plugin -- <artifact>andnpm run test:pdf-artifact <artifact> [--pdf file]are the PDF import pair and they answer different questions: the first reads the artifact and fails when the import plugin's JavaScript is not byte-for-byte what its source says (the prod uglify pass re-minified it once and every imported PDF page came out white, so this is the gate), the second boots the artifact in headless Chrome, dropsscripts/fixtures/pdf-import-smoke.pdfon it, and measures the ink on every page the import renders. The first is wired into the prod build's verify step; the second needs an artifact and so is a local tool, and--pdfruns the same drive against your own document. - The Linux artifact:
bash scripts/build-shim-appimage.sh --name NAME --output-dir DIR [--work DIR].--workkeeps the downloadedappimagetoolbetween builds instead of fetching it again. Worth doing after any change to the launcher's HTML, the shim, or the engine payload, because it is the shape a user actually runs.
The per-round history is no longer in this file. It lives in docs/rounds/<YYYY-MM>.md, one file per month, oldest first, and the next round's entry goes there, into the file named for its month, and not here. What an entry is for, and why the counts are not in it, is at the top of those files: the decision that was not obvious, and the trap that would otherwise be walked into twice.
This split happened on 2026-10-02, when the log had reached 239 KB of a 309 KB file and 77 percent of it was round entries that no task reads and every task scrolls past. Nothing was deleted in the move except the verification tallies: every entry is verbatim, and every "Left open" or "Unverified" caveat was kept, because a known hole is the most useful thing a round writes down. Note that code comments which cite agents.md for a particular decision or measurement mean the round log in docs/rounds/, while ones that cite a rule (the copy rules, the colour gate, the staging map) still mean this file.
DECISION (2026-10-27): Lithic ships no browser extensions, for Firefox, Chrome, Edge or Firefox for Android, and no WXT packaging pipeline. The motive that started the idea (a just-works, account-synced prong whose data lives in the browser's own profile sync) does not survive the platform, and what is left is a third distribution shape with no capability of its own. Treat it as closed unless the developer reopens it, and read the reasons before proposing it again.
WHY:
- The sync half is not obtainable.
storage.syncis item-capped (around 8 KB per item and 100 KB per account) and does not replicate IndexedDB, andunlimitedStoragedoes not lift it. A Lith is megabytes, so profile sync can never be its source of truth or its backup. The premise the prong was founded on is gone. - The engine cannot run in an extension page. MV3 forbids inline script and
unsafe-eval, and TiddlyWiki boots by evaluating its module tiddlers, so the engine needs a sandbox frame. A sandbox frame has an opaque origin with no IndexedDB and no localStorage, so storage would have to cross a postMessage bridge pinned to the saver'sget/set/delcontract. - The mount path assumes the launcher owns the document. The launcher
document.writes the engine over itself. In an extension the privileged page has to stay alive behind that frame, so saves, downloads, dirty state and the payloads parked onwindow(PDF, whiteboard) all need a channel they do not have. That is a re-architecture of the boot plus a second engine host kept in step forever, with every launcher change then tested in two shapes. - No extension filesystem API exists, and the one that did is dead.
chrome.fileSystemwas a Chrome Apps API, deprecated in 2020 (reference), and Firefox 57 removed XPCOM andnsIFilewith no WebExtensions replacement. Native messaging is the only route with real file access, and it is a bridge to a separately installed helper program: that program is the desktop app, which this repo already ships. - Firefox will never have the File System Access API. Mozilla's standards position is negative (#154), the picker-only proposal is defer (#738), and Bugzilla 1246236 is still NEW after ten years. So on the one platform with a motive, an extension could never write a real file in place, and OPFS is another origin bucket that a site-data clear takes with it.
- The platform with the only motive is where extensions are weakest. On Firefox for Android there is no native messaging, no downloads API (Bugzilla 1538348) and no pickers, so an extension would hold a Lith's only copy in extension storage with no extension-level way out; installation there goes through addons.mozilla.org rather than a sideload, so the platform that justifies the build is also the one carrying a distribution gate.
- On Chrome and Edge it is redundant rather than a bonus. Extension pages there can reach the pickers, since those are a web API, so it would not downgrade those users as first assumed. But in
webappmode Chrome already writes real files in place through the PWA, so a Chrome or Edge extension buys nothing that does not already exist, at the price of two store listings. - It muddies the product for the person using it. A third prong with no distinct capability turns "which one do I use" into a real question at first contact, while the difference between site storage and extension storage is an explanation only: to the person, both are just "in the browser". The one genuine niche (Firefox Android storage surviving a site-data clear) is narrow, unmeasurable because nothing here reports, and already mitigated by add-to-home-screen,
navigator.storage.persist()(which guards eviction, never a manual clear) and downloading a copy.
WHAT WOULD REOPEN IT: a capability that only an extension origin provides and the PWA cannot, such as an integration against a running instance. That would justify the packaging on its own merits, with Android as a rider rather than the whole reason. Nothing in the feature set today qualifies.
ALSO SETTLED HERE: the install offer stays absent on Firefox Android, because Firefox does not install PWAs from a manifest (MDN), so pwa-install.ts grows no Firefox path. The Firefox desktop pass this discussion produced is npm run test:firefox (20 checks, wired into launcher-firefox.yml); Firefox desktop and Safari are the two desktop browsers that land in the index-db fallback in webapp mode, and that path is measured intact.