Architecture

Invariants

37 min read

These are the rules the code refuses to break. None of them is a style preference. Each exists because a specific class of bug happened, or because working around it would break something non-obvious.

They were referenced by number in code comments — invariant 1/2/3/5/8 — without being collected anywhere. ADR 001 wrote them down; this page explains them.

There are five series:

I1 to I9, the original invariants, reconstructed from the code, and the privacy of a screen's notes.
M1 to M8, introduced by Muse.
Q1 to Q5, introduced by the quality pass.
U1 to U5, introduced by Motion Ultra.
D1 to D5, introduced by the admin dashboard.

Plus two unnumbered rules that carry just as much weight: the SSRF guard, and the "no database, no native dependencies" posture.

Series I — the core#

I1. Never parse generated source with a regular expression#

The rule. Never analyse generated or vendored source with a regular expression to discover names or decide what it contains. Use a real Babel scope walk.

What it protects. A regular expression does not know what a string is. motion. appears inside a string literal, inside a comment, and in the middle of the word promotion. Removing an import by line pattern breaks as soon as the specifier list spans several lines.

How it is done. stripForbiddenMotion() in src/lib/stripMotion.ts runs a Babel plugin: ImportDeclaration for imports, JSXMemberExpression for .

export/rewrite.ts first transforms JSX into React.createElement, so every component reference becomes an ordinary identifier, then queries the scope.

Babel already compiles this code. Asking it what the code is costs one parse and cannot be fooled.

The explicit exemption. Parsing Markdown prose is allowed. export/theme.ts and extractDesignColors() scan a DESIGN.md, not code, and say so in a comment.

The edge case. tryDirectTextReplace() replaces a text literal by string match, but only when it appears exactly once, and only for text the user is literally looking at in the preview. That is not name discovery.

I2. The preview iframe has an opaque origin#

The rule. The preview is sandboxed with allow-scripts and never allow-same-origin. Never add a crossorigin attribute.

What it protects. Without allow-same-origin the document's origin is opaque: no localStorage, so no API key; no cookies; no access to the parent DOM. The preview runs model-written code continuously.

Why no crossorigin. Since the origin is null, that attribute would turn every