mosaic-headless 1.2.0

package/references/responsive.md

@@ -0,0 +1,174 @@
+# Responsive (RWD)
+
+Responsive in Mosaic is the **second axis of the style object**, not a separate data
+structure and not a naming convention:
+
+```jsonc
+"style": {
+  "&": {                                  // state
+    "_":  {"paddingLeft": "48px"},        // base breakpoint
+    "_t": {"paddingLeft": "32px"},        // <=1079px
+    "_m": {"paddingLeft": "20px"}         // <=767px
+  }
+}
+```
+
+`state → breakpoint → property`. Get the two middle levels the wrong way round and
+the validator sees `'n'/'o'/'n'/'e'` as property names, because it is iterating the
+characters of a value it expected to be a dict.
+
+## The breakpoints are rows, not constants
+
+They live in `wp_mosaic_breakpoints`, scoped to the theme, and a fresh theme heals
+into exactly two. Read off the live table:
+
+| ID | name | width | direction | ordering |
+|---|---|---|---|---|
+| `_t` | Tablet | 1079 | down | `a0` |
+| `_m` | Mobile | 767 | down | `a1` |
+
+Both are `direction: down`, so both match on a phone, and **`_m` is ordered after
+`_t`** — which is the only reason a mobile value overrides a tablet one rather than
+losing to it. Custom breakpoints get UUIDs instead of `_t`/`_m`; do not hardcode the
+pair, read the table.
+
+## What it compiles to
+
+One inline stylesheet per breakpoint, in the head, each wrapped in its own query:
+
+```html
+<style id="mosaic-theme-block-editor-styles_-inline-css">    <!-- base, no query -->
+<style id="mosaic-theme-block-editor-styles_t-inline-css">   <!-- @media (max-width:1079px) -->
+<style id="mosaic-theme-block-editor-styles_m-inline-css">   <!-- @media (max-width:767px) -->
+```
+
+Rules inside them hang off the generated `.M_EL<n>` class, **never off your
+`attrID`**. The id is in the HTML and the rule is in the CSS, and the only bridge
+between them is `id="<attrID>" class="M_EL<n>"` in the delivered markup. Any tool
+that wants to check a breakpoint value has to read that mapping first.
+
+## The trap that has cost the most: an override cannot REMOVE
+
+**A breakpoint override can only CHANGE a property. It can never remove one the base
+breakpoint declared.** This is ordinary cascade behaviour and it is still the single
+most repeated bug in this codebase, because the shape of the data invites it:
+
+```python
+# WRONG - and it looks right
+"_":  {"customStyles": "border-left:1px solid #ddd;"},   # 4-up: rule between cells
+"_m": {"customStyles": ""},                              # 1-up: no rule wanted
+```
+
+The mobile value declares nothing, so nothing overrides, so the desktop
+`border-left` survives into the collapsed layout and draws a vertical rule down the
+middle of a single column. Same for the asymmetric padding that went with it.
+
+```python
+# RIGHT - say zero out loud
+"_m": {"customStyles": "border-left:0;"},
+```
+
+Measured twice on the same page: a 3×2 hairline list that kept a column rule and a
+48px indent on alternate rows at one column, and a 4-up statistics band whose third
+cell opened a row while still carrying the four-up rule. `tools/verify_rwd.py`
+reports every one of these as `RESET-RISK`.
+
+## `gridColumnStart` is in the surface and emits nothing
+
+`gridColumnStart`, `gridColumnEnd`, `gridRowStart` and `gridRowEnd` are all in
+`data/style-properties.csv` — they are real entries in the plugin's own property
+list, under the `gridChildPosition` group. They compile to nothing.
+
+Measured: 16 `gridColumnStart` declarations in a committed spec, **zero** occurrences
+of `grid-column` anywhere in the delivered CSS. No exception, no console warning, no
+change to the commit response. If you need a child in a particular column, change the
+template — do not try to place the child.
+
+## A row with more children than columns fills the gutter, not the width
+
+This is the trap the CSS checker structurally cannot catch, and it is worth stating
+on its own because every value involved verifies.
+
+A three-child row at `84px 1fr 1.35fr` narrowed to `48px 1fr` does not put its third
+child on the full width. Grid puts it in **column 1** — the 48px number gutter — and
+the body text comes out at one or two characters per line. Every declaration in that
+spec is present in the right media query with the right value; `verify_rwd.py`
+reports 251 verified and 0 missing. The stylesheet is right and the page is wrong.
+
+Measured twice on the same build: a services row whose body text ran 48px wide, and a
+four-child products row whose status chip landed alone in a 72px gutter on row two at
+tablet, 60px tall for one line of 10px type.
+
+The rule that follows: **when a template narrows, count the children.** Either the
+narrow template keeps as many columns as the row has children, or the row collapses
+to a single column, or a child that is really a property of another child moves
+inside it. The products chip took the third option — it describes the product, it was
+never a column of the table.
+
+## Three layout traps that only appear at a narrow width
+
+**A transform makes an element the containing block for its absolutely positioned
+descendants.** Any element in a scroll-reveal list carries one, so an
+`position:absolute; top:0; bottom:0` child resolves against *it* rather than against
+the section. Measured: a rule meant to span a 483px band came out 299px — the band
+minus its 92px padding, exactly. The fix is to move the absolute child out to the
+positioned ancestor you actually meant.
+
+**A flex row with no `nowrap` does not overflow — it shrinks its children until the
+text breaks.** A header row that looked like it was wrapping was actually being
+squeezed, splitting a three-character wordmark across two lines. `white-space:nowrap`
+makes the row hold its size so you can see the real overflow and design for it.
+
+**Inherited `line-height` sets element heights, not your padding.** A header measured
+66px with nothing wrapping in it, because every nav link inherited the `2.05`
+line-height set for running text. The design was not choosing that height; the
+cascade was.
+
+## Section is `display:flex`
+
+A `section` node is a flex container, so a max-width block child shrink-to-fits
+instead of filling: a 1120px wrap came out 415px. Every wrapper needs `width:100%`.
+
+## Verify it, do not look at it
+
+Resizing the browser checks the part of the page that happens to be on screen. The
+mechanical check reads what the spec declared and what the site actually served, and
+compares them key by key:
+
+```bash
+python tools/verify_rwd.py --config sweep.json --site sites/moksa.json --csv rwd.csv
+```
+
+It maps each `attrID` to its generated class, parses the `_t` and `_m` stylesheets,
+and asserts every declared property is present in that breakpoint's rule for that
+element. It exits non-zero on any `MISSING` or `RESET-RISK`.
+
+`data/rwd-verification.csv` is the current run: **569 responsive declarations across
+two sites and three pages, all `verified`, no `MISSING`, no `unmapped`, no
+`RESET-RISK`.**
+
+A verifier that has never failed is not evidence of anything, so it is checked
+against a poisoned copy of the spec — one undeclared property and one un-reset
+border injected — and it must report exactly those two and exit non-zero:
+
+```
+mk-svc-0,_m,letter-spacing,9px,,MISSING
+mk-svc-0,_m,border-left,set at base,not reset,RESET-RISK
+```
+
+Rows it cannot judge are labelled `unmapped`, never counted as passes: a tool that
+scores its own blind spots as successes is worse than no tool.
+
+**What it does not cover, and this matters:**
+
+- **Anything that needs layout rather than CSS.** Grid placement, horizontal
+  overflow, clipped text. The two worst bugs on this page both had a completely
+  clean verifier run — see the gutter trap above. Every width still needs a real
+  browser at 1440 / 1024 / 390.
+- **Nodes with no `attrID`.** The bridge from a spec declaration to a compiled rule
+  is `id="<attrID>" class="M_EL<n>"`, so a node that was never given an id is
+  invisible to the tool. The services body text was exactly that: it carried a
+  responsive declaration the tool never saw. Give an `attrID` to anything whose
+  responsive behaviour you want checked.
+
+The tool tells you the values arrived. Only the browser tells you they add up.

package/references/styling.md

@@ -0,0 +1,172 @@
+# Styling: how a value becomes CSS
+
+## Grouped properties are inert on their own
+
+`data/style-properties.csv` has a `group` column. Twenty of the 98 properties have a
+value in it, and **not one of them compiles when set individually** — swept live,
+zero exceptions:
+
+| group | members | result |
+|---|---|---|
+| `borderStyle` | `border{Top,Right,Bottom,Left}{Width,Style,Color}` | 12 / 12 inert |
+| `outlineStyle` | `outlineWidth`, `outlineStyle`, `outlineColor`, `outlineOffset` | 4 / 4 inert |
+| `gridChildPosition` | `gridColumnStart`, `gridColumnEnd`, `gridRowStart`, `gridRowEnd` | 4 / 4 inert |
+
+The commit is accepted, the row is stored, and the stylesheet simply has no such
+declaration. Meanwhile every one of the 58 testable ungrouped properties compiled.
+
+Use the grouped shape — `border` takes `{"width": "3px", "style": "dashed", "color":
+"rgb(...)"}` and does compile — or drop to `customStyles`. If you need a child in a
+particular grid column, change the template rather than trying to place the child.
+
+`data/style-verification.csv` is per-property, with the group beside the result.
+
+Measured on a live install by committing a styled `div` and reading what came back
+down the wire.
+
+## The shape
+
+A node's `data.style` is addressed by three axes — **state, breakpoint, property**:
+
+```json
+{
+  "style": {
+    "states": {
+      "&":     { "_":  { "backgroundColor": "rgb(11, 22, 33)", "paddingTop": "37px" },
+                 "_m": { "paddingTop": "9px" } },
+      "hover": { "_":  { "backgroundColor": "rgb(77, 88, 99)" } }
+    }
+  }
+}
+```
+
+- `states` keys come from `data/style-states.csv` — `&` is the base state, then
+  `hover`, `focus`, `focus-visible`, and 45 node-type-specific ones.
+- The next level is the **breakpoint ID**. `_` is the base breakpoint
+  (`DocumentBreakpoints::baseBreakpointID`); the others are rows in
+  `mosaic_breakpoints` — a fresh theme heals into `_t` (Tablet, ≤1079px) and
+  `_m` (Mobile, ≤767px). Custom breakpoints get UUIDs.
+- The leaf keys are the camelCase properties in `data/style-properties.csv`.
+
+`style` also carries `elementClass`, `utilityClasses`, `defaultClass` and
+`localStates` alongside `states` — those are the class/token layer, not per-node values.
+
+## What comes out
+
+That exact payload produced, in the delivered page:
+
+```html
+<div id="styleprobe" class="M_EL4 M_EL_Div">
+
+<style id="mosaic-theme-block-editor-styles_-inline-css">
+html{overflow-x:clip}body{opacity:0}html,body{margin:0}
+.M_EL4{padding-top:37px;background-color:rgb(11, 22, 33)}.M_EL4:HOVER{background-color:rgb(77, 88, 99)}
+</style>
+
+<style id="mosaic-theme-block-editor-styles_m-inline-css">
+@media only screen and (max-width: 767px){.M_EL4{padding-top:9px}}
+</style>
+```
+
+Four things to take from that:
+
+**Mosaic ships no stylesheet file.** Every compiled rule is an inline `<style>` block
+in the head, id `mosaic-theme-block-editor-styles_<breakpointID>-inline-css`, one
+block per breakpoint. Tooling that looks for a `<link rel="stylesheet">` to diff finds
+nothing — and would wrongly conclude the style had no effect. (That bug was in this
+skill's own property sweep until the probe above caught it.)
+
+**The selector is the element's generated class**, `.M_EL4`, not the `id` you set.
+`attrID` gives you an `id` attribute for your own use; it is not what styling hangs on.
+The `M_EL<n>` number is assigned per element per document and is **not stable** — do
+not write selectors against it. The companion `M_EL_Div` / `M_EL_Text` / `M_EL_Button`
+class *is* stable and is the type's marker.
+
+**States compile through their selector template.** `hover` used
+`&:HOVER` from `style-states.csv` and produced `.M_EL4:HOVER` — uppercase, exactly as
+the template is written. Everything in that CSV compiles the same way, so the template
+column tells you in advance what rule you will get.
+
+**Breakpoints compile to `@media`**, derived from the breakpoint row: `_m` has
+`width: 767, direction: down` and produced `@media only screen and (max-width: 767px)`.
+Breakpoints are theme data, so the same key means different things in different themes.
+
+Also note `body{opacity:0}` in the base block — the theme reveals itself from
+JavaScript. A page fetched without running scripts is fully styled but invisible;
+screenshot tooling must let the JS run before capturing.
+
+## Setting values
+
+The `factory` column in `data/style-properties.csv` tells you the value shape:
+
+| factory | write |
+|---|---|
+| `CSSPropertyFactory` (29) | a plain CSS value string — `"flex"`, `"center"`, `"700"` |
+| `CSSCollectionVariablePropertyFactory` (26) | a length string, or a reference to a collection variable |
+| `CSSColorPropertyFactory` (2) | `color`, `backgroundColor` — a colour string or variable reference |
+| `CSSGrouppedPropertyFactory` (20) | one leg of `borderStyle`, `outlineStyle` or `gridChildPosition`; the data is keyed under the group |
+| the other 21 | purpose-built shapes — shadow, transform, gradient, filter, mask. Read the factory named in the CSV. |
+
+Plain strings were accepted verbatim for the properties probed above. The 34
+token-referencable properties are the interface to the collection/variable layer,
+which is how a design system is meant to be expressed rather than hard-coding values
+on every node.
+
+## Where styling should actually live
+
+Setting `style` directly on a node works — everything above proves it — but it is the
+lowest layer and it opts that node out of both reuse mechanisms:
+
+1. **Element classes** (`data/element-classes.csv`, 151 built in) carry the shared
+   look; a node points at one through `style.elementClass`.
+2. **Collections → modes/skins → variables** are the token layer, the thing the
+   34 token-referencable properties reference.
+
+Per-node `style` is for the exception, not the rule. Build a design by putting values
+in the class and token layers and letting nodes inherit; reach for per-node style when
+one element genuinely differs.
+
+## The five structured values
+
+Five properties are silently useless if you write a CSS string to them. The string is
+accepted — no rejection, no exception — and the compiled rule comes out as
+`transform:none`, `box-shadow:none`, or simply never appears. Every shape below was
+found by probing and confirmed against the compiled CSS.
+
+```jsonc
+// border-radius:18px
+"borderRadius": {"type": "all", "allOptions": {"borderRadiusValue": "18px"}}
+
+// transform:translateY(-8px)   — one entry per transform, type names come from
+// TransformTypeFactoryManager: translateX/Y/Z, rotateX/Y/Z, skewX/Y, scaleX/Y/Z
+"transform": [{"type": "translateY", "translateYOptions": {"value": "-8px"}, "uuid": "<uuid>"}]
+
+// box-shadow:rgb(20, 20, 20) 8px 8px 0px 0px   — type is "outside" or "inside",
+// NOT "outset"/"inset"; a wrong type yields box-shadow:none
+"boxShadow": [{"x": "8px", "y": "8px", "blur": "0px", "spread": "0px",
+               "color": "rgb(20,20,20)", "type": "outside", "uuid": "<uuid>"}]
+
+// transition-property/duration/timing-function/delay
+"transition": [{"transitionProperty": "all", "transitionDuration": "350ms",
+                "transitionDelay": "0ms", "transitionTimingFunction": "ease", "uuid": "<uuid>"}]
+
+// all twelve border-*-* longhands; there is no shorthand form
+"borderStyle": {"borderTopWidth": "5px", "borderTopStyle": "solid", "borderTopColor": "rgb(...)",
+                "borderRightWidth": …, "borderBottomWidth": …, "borderLeftWidth": …}
+```
+
+The `<type>Options` suffix is the general pattern (`BorderRadiusTypeFactoryAbstract::
+getOptionsName()` returns `getType() . 'Options'`), so it applies to `flexSizing` and the
+other type-switched groups too.
+
+`scale` as a single transform entry did not compile with the `value` shape — it uses
+`ScaleTransformTypeFactory`, which takes separate axes. Use `scaleX`/`scaleY` instead,
+which are `SingleTransformTypeFactory` and do take `{"value": …}`.
+
+**The escape hatch.** `customStyles` accepts raw CSS text and emits it verbatim into
+the rule: `"customStyles": "outline: 2px dashed rgb(7,8,9);"` compiled through
+unchanged. It is the fallback for anything whose structured shape you have not pinned
+down — at the cost of bypassing the collection-variable layer entirely.
+
+`tools/build_page.py` wraps the five shapes above as `radius`, `shadow`,
+`transitionAll`, `move` and `border` shorthands so a design spec cannot get them wrong.

package/references/templates-and-conditions.md

@@ -0,0 +1,122 @@
+# Templates, routing and conditions
+
+## How Mosaic decides which template renders
+
+A Mosaic template row carries `assign`, `path` and `conditions`, and those three
+answer the whole routing question. From
+`LocatedTemplateRenderMResourceManager`:
+
+```php
+if ($templateRevisionRecord->getAssign() == 'auto'
+    && in_array($templateRevisionRecord->getPath(), $paths)
+    && $templateRevisionRecord->matchConditions()) { … }
+```
+
+So there are exactly two routing modes:
+
+| `assign` | how it is chosen |
+|---|---|
+| `auto` | `path` must be in the WordPress template hierarchy for the current request, **and** `conditions` must match |
+| `manual` | bound to one specific post through a row in `mosaic_template_assigns`; `conditions` are not consulted |
+
+`path` values come from `GET /template-path-dictionary` — `single-page.php`,
+`single-post.php`, `archive-post.php`, `taxonomy-category.php`, `author.php`,
+`single-product.php`, `archive-product.php` and so on. It is the WordPress template
+hierarchy, so a Mosaic template lands wherever the corresponding PHP template would.
+
+**`assign` + `path` is the other binding, and it is a real catch-all.** The
+template row carries `assign` (default `auto`) and `path` columns. Commit one with
+`assign:"auto"`, `path:"index.php"` and it binds to a template path rather than to a
+post; `X-Mosaic-Paths` on a 406 names the paths Mosaic looked for, and `index.php` is
+in all of them. Measured A/B: a URL with no template returned 406, was handled once
+the row existed, and returned to 406 when it was deleted.
+
+Two limits, both measured: `adminTemplateEditorInstance` does not list auto templates,
+and their document has no `template-internal` root - `heal()` builds that only for
+templates created through `createManualTemplate`, and committing one directly answers
+HTTP 500. So the row stops the 406 but there is no verified route to putting content
+in it.
+
+**`post/<id>` is the only resourceQuery `createManualTemplate` accepts.** The grammar in
+`ResourceQuery::create()` is just `explode('/', $s, 2)`, so anything parses - but the
+only resource type any template path registers is `post`
+(`setResourceType('post')` in PathPostTypePage, PathPostTypePost and PathPostTypes).
+`path/single-page.php` and `path/index.php` were both tried against the live
+endpoint and both returned HTTP 500. There is no catch-all: a URL with no template
+of its own gets `status_header(406)` and an empty body.
+
+**Manual assignment is a REST call, not a commit.** `POST /templateAssign/createManualTemplate`
+with `resourceQuery=post/<postID>` and `masterID=<masterID>` creates the template row
+*and* the assign row in one step, deriving the path and name from the post. The eight
+pages built by `tools/build_site.py` are all bound this way.
+
+One consequence worth knowing: **that endpoint creates a new template every time.**
+Calling it twice for the same post leaves two template rows and one assign row —
+`tools/build_all.py` resets the theme before rebuilding for exactly this reason.
+
+## The condition structure
+
+The same shape drives template routing, element visibility (`node.data.conditions`),
+interaction gating and form actions — four contexts, one grammar.
+
+```jsonc
+"conditions": [                              // groups are OR-ed
+  {
+    "uuid": "<uuid>",
+    "evaluationUnits": [                     // units within a group are AND-ed
+      {
+        "uuid": "<uuid>",
+        "type": "serverCondition",
+        "serverConditionOptions": {
+          "subject":    {"type": "httpGet",
+                         "httpGetOptions": {"settings": {"name": "show"}}},
+          "comparator": {"type": "text",
+                         "textOptions": {"operator": "equals",
+                                         "settings": {"value": "yes"}}}
+        }
+      }
+    ]
+  }
+]
+```
+
+The `<id>Options` suffix is the same convention as everywhere else in Mosaic
+(`RuleTypeAbstract::getOptionsDataName()` returns `getID() . 'Options'`).
+
+**An empty or absent `conditions` matches.** `matchConditions()` returns `true` when
+the evaluation yields null, so a template with no conditions always applies and an
+element with none always renders. Conditions subtract, they never add.
+
+## What you can test
+
+Two tables, both read off the running site rather than the source:
+
+- `data/condition-subjects.csv` — 59 subjects across four contexts (`element`,
+  `template`, `interaction`, `formAction`), each with its `settingsFields` and the
+  group it belongs to (`editor`, `http`, `currentUser`, `post`, `product`, `page`,
+  `attachment`).
+- `data/condition-comparators.csv` — 12 comparator rows with their operator sets:
+
+| comparator | operators |
+|---|---|
+| `text` | equals, not-equals, contains, not-contains, starts-with, regexp |
+| `number` | equals, not-equals, greater-than, greater-than-or-equal, less-than, less-than-or-equal |
+| `date` | after, before |
+
+`date` exists only in `serverCondition`. The `interaction` context additionally has a
+`browserCondition` rule type whose `text` comparator drops `regexp` — browser-side
+evaluation is a reduced subset, so a rule that works in a template will not
+necessarily work as an interaction gate.
+
+Most subject settings fields carry `supportDynamic: true`, meaning the value itself
+can be an `@` expression rather than a literal — see `references/dynamic-content.md`.
+
+## Verification status
+
+The routing rules and the condition grammar above are read from source and from the
+live metas endpoints. **Committing a condition has not been driven end to end** — the
+property sweep's naive string probe on `conditions` returns HTTP 500, which is
+consistent with the nested shape being required but is not proof the shape above is
+accepted. Build one, then read the row back and diff it against what you sent; on this
+data model that diff is the only error message you get
+(`references/interactions.md` explains why).

package/references/vs-elementor-gutenberg.md

@@ -0,0 +1,73 @@
+# Mosaic vs Elementor vs Gutenberg, as data models
+
+If you already know `elementor-headless` or `gutenberg-headless`, this is the page
+that tells you which of your habits transfer and which will actively mislead you.
+
+## The one-line difference
+
+| | Elementor | Gutenberg | Mosaic |
+|---|---|---|---|
+| Where the page lives | `wp_postmeta._elementor_data`, one nested JSON blob | `wp_posts.post_content`, serialized HTML comments | **23 own tables**, one row per element in `wp_mosaic_nodes` |
+| Unit of structure | widget in a nested array | block in a comment-delimited string | node row with a `parentID` |
+| Tree encoded by | JSON nesting | comment nesting in a string | a foreign key |
+| Ordering | array index | document order in the string | **fractional-index string** in `ordering` |
+| Scope | the post | the post | the **theme** (`themeID` on every row) |
+| Written by | overwrite the whole meta blob | overwrite `post_content` | checkout → commit, **per row, revision-checked** |
+| Silent-failure mode | unknown control stored and ignored | comment JSON and saved HTML disagree | validator rejection returned as HTTP 200 with an `exceptions` body |
+
+## What transfers
+
+**The core discipline transfers exactly.** All three builders will accept a payload
+they do not understand and give you a page that looks 90% right. In all three, the
+rule is the same: never write a property name, enum value, or Free/Pro claim from
+memory — look it up in `data/`.
+
+**The Free/Pro split is a real axis in both Elementor and Mosaic.** In Mosaic it is
+cleaner: 48 of 122 node types live under `NodeTypes/Pro/` and simply have no factory
+on a Free install (`edition` column in `data/node-types.csv`). There is no
+"partially available" state to reason about the way there is with Elementor Pro
+controls on Free widgets.
+
+**Dynamic values exist in all three**, under three names. Elementor calls them
+dynamic tags; Gutenberg has bindings; Mosaic has **evaluator functions** — 19 of
+them (`abs`, `attachment`, `avg`, `calc`, `concat`, `date`, `esc_attr`, `esc_html`,
+`excerpt`, `fallback`, `find_image`, `find_link`, `find_video`, `json_encode`,
+`remove_html`, `round`, `round_up`, `substr`, `sum`) plus 8 dynamic sources, in
+`data/pluggables.csv`. A property accepts one wherever its validator chain includes
+`ValidatorDynamicCodeObject`.
+
+## What will mislead you
+
+**"Edit the page's JSON."** There is no page JSON. The closest thing to
+`_elementor_data` is a *set of rows*, and the tree is a `parentID` column. Reading a
+Mosaic document means a query, not a `json_decode`.
+
+**"Reorder by array index."** `ordering` is a fractional-index *string*. Sorting it
+as a number scrambles the page; renumbering siblings the way you would an array is
+both unnecessary and destructive of other clients' inserts.
+
+**"The post is the unit."** In Elementor and Gutenberg, one post = one page's data.
+In Mosaic a post is a *target*: templates are assigned to types via
+`mosaic_template_assigns`, and the same template serves many posts. Editing "the
+page" usually means editing a template, and the blast radius is every post that
+template is assigned to. Check `mosaic_template_assigns` before you edit.
+
+**"Style the element."** Elementor puts controls on the widget. Mosaic puts styling
+in a **class system** (151 built-in element classes) layered over a **token system**
+(collections → modes/skins → variables). Writing styles onto individual nodes works
+and is almost always wrong; it opts that node out of both layers.
+
+**"Breakpoints are a site setting."** In Mosaic they are theme-scoped rows in
+`mosaic_breakpoints`. Two themes on one site can disagree about what "tablet" means.
+
+**"Overwrite and move on."** Elementor and Gutenberg tolerate blind overwrites.
+Mosaic checks the `revision` of every row you claim; a commit built on a stale
+revision is rejected, and the rejection arrives as HTTP 200. See
+`references/write-protocol.md`.
+
+## Which skill to reach for
+
+- Post content authored as blocks, on a normal WP theme → `gutenberg-headless`.
+- An Elementor site, page-level construction → `elementor-headless`.
+- A Mosaic site → here. The write path and all 74 free node types are measured; the
+  48 Pro-only types are extracted from source but not render-verified.

package/references/write-protocol.md

@@ -0,0 +1,79 @@
+# Writing to Mosaic: the checkout / check / commit protocol
+
+*Verified end to end against a live install: a master, a template and a text node were
+created through these routes and the result asserted in the delivered HTML. See
+`references/failure-modes.md` for what goes wrong and how it surfaces.*
+
+Mosaic has no "save the page" endpoint. Every document you can edit — theme,
+master, template, style guide, component, component node — is reached through an
+**editor instance**, and every editor instance exposes the same four routes:
+
+```
+GET  /mosaic/v<version>/theme/<themeID>/<instance>            open  (read state)
+POST /mosaic/v<version>/theme/<themeID>/<instance>/checkout   claim (take the lock)
+POST /mosaic/v<version>/theme/<themeID>/<instance>/check      poll  (still in sync?)
+POST /mosaic/v<version>/theme/<themeID>/<instance>/commit     write
+```
+
+All 114 routes are in `data/rest-routes.csv`; the namespace is
+`/wp-json/mosaic/v<plugin version>` — **the plugin version is in the namespace**, so
+the base URL changes on every Mosaic update. Read it from `mosaicOptions.rest_api_url`
+on any Mosaic admin page rather than composing it yourself.
+
+## The envelopes
+
+Both `checkout` and `check` take one required string parameter, `syncCheckEnvelopes`
+— a JSON string, not a JSON body — shaped as manager type → list of `[ID, revision]`
+pairs:
+
+```json
+{"node": [["<nodeID>", "<revision>"], ...], "elementClass": [[...]]}
+```
+
+The `revision` is the value from the row's `revision` column when you read it. The
+server compares them and returns `syncResponseEnvelopes` for anything that moved
+underneath you. This is **optimistic locking, per row** — not a page-level lock — so
+two callers editing different nodes of the same document do not conflict.
+
+`commit` takes `syncCheckEnvelopes` *and* `revisionEnvelopes` (also a JSON string).
+The server runs `doCommit(revisionEnvelopes)` → `pushToDB()` → and then immediately
+does a fresh `doCheckout` so the response hands you the new revisions to use for
+your next write. **Use them.** Reusing the pre-commit revision on the following
+commit is the single most likely way to get stuck in a sync-rejection loop.
+
+## Order of operations
+
+```
+1. GET  <instance>              read current state + revisions
+2. POST <instance>/checkout     with the revisions you just read
+3.      ...build your changes...
+4. POST <instance>/check        optional; cheap way to detect drift before committing
+5. POST <instance>/commit       with syncCheckEnvelopes + revisionEnvelopes
+6.      take the revisions from the response, go to 3
+```
+
+`isCheckoutAllowed()` / `isCheckAllowed()` / `isCommitAllowed()` gate each step and
+throw a bare `Not allowed!` when they fail — there is no useful error body, so if a
+commit throws, check the lock (`mosaic_locks`) and the capability of the user whose
+cookie you are sending before suspecting your payload.
+
+## Authentication
+
+These are `wp-json` routes behind a nonce, not application passwords:
+
+```
+Cookie:     the logged-in admin cookie
+X-WP-Nonce: mosaicOptions.common.nonces.wp_rest
+```
+
+Both are on the Mosaic admin page (`admin.php?page=mosaic`) in the `var mosaicOptions`
+blob. That blob is also where you find `mosaicEdition` (`pro` / free),
+`mosaicVersion`, `mosaicDataVersion`, `license.isLicenseActive`, `siteHash`, and the
+`availablePostTypes` map — read it once at the start of a session instead of probing.
+
+## What errors look like
+
+A failed validator does not return an HTTP error. The response is a
+`RESTJSONExceptionEnvelope`: HTTP 200 with an `exceptions` array in the body. Code
+that only checks the status code will report a clean save on a rejected write.
+Always read `exceptions` before believing a commit landed.