mosaic-headless 1.2.0

package/references/dynamic-content.md

@@ -0,0 +1,113 @@
+# Dynamic content: the `@` expression language
+
+Mosaic's answer to Elementor's dynamic tags. Verified end to end — every example on
+this page was committed to a live site and read back out of the delivered HTML.
+
+## The syntax you would not guess
+
+A bare identifier does **nothing**. `Evaluator::exec()` handles the `Identifier` node
+by returning the literal string `"Identifiers are not used currently"`. So this:
+
+```
+@post.title
+```
+
+is stored happily, renders as the text `@post.title`, and looks like a typo in your
+content rather than a broken feature.
+
+The real form is a **function call named `VAR`, taking a `namespace/name` string**:
+
+```
+@VAR('post/title')          ->  Probe lab
+@VAR('post/id')             ->  20
+@VAR('post/permalink')      ->  https://example.com/probe-lab/
+@VAR('site/name')           ->  example.com
+```
+
+Expressions compose, and the 19 evaluator functions take `@VAR(...)` results as
+arguments:
+
+```
+@concat('[', @VAR('post/title'), '] #', @VAR('post/id'))   ->  [Probe lab] #20
+@substr(@VAR('post/title'), 0, 5)                          ->  Probe
+@fallback(@VAR('post/nope'), 'DEFAULTED')                  ->  DEFAULTED
+```
+
+A literal `@` in ordinary text needs escaping as `\@`.
+
+`@VAR_RAW('…')` is the same lookup **without HTML-escaping**. The evaluator escapes
+untrusted (request-derived) values at the point of interpolation and carries a
+`{value, trusted}` envelope to do it; `VAR_RAW` opts out of that. Use `VAR` unless you
+are deliberately publishing markup from a trusted field.
+
+## Where an expression goes
+
+**Inline in text** — a `wysiwyg-variable` node inside a `text` node, with the
+expression as a plain string in `dynamicCode`:
+
+```json
+{"type": "text", "data": {"tagName": "p"},
+ "children": [{"type": "wysiwyg-variable", "data": {"dynamicCode": "@VAR('post/title')"}}]}
+```
+
+`wysiwyg-variable` is one of the seven types that **kill the page** when placed under
+a plain container — it needs a wysiwyg parent, and the sweep recorded it as
+`NodeMResourceFilterFunctionInterface parent is missing`.
+
+**On a property** whose validator chain includes `ValidatorDynamicCodeObject` — a
+button's `url`, an image's `src`, and so on. There the value is an object, because a
+literal is also legal in that slot and the object is what disambiguates:
+
+```json
+"url": {"v": "@VAR('post/permalink')"}
+```
+
+Two different shapes for the same language, and which one applies is decided by the
+property's validator chain in `data/node-properties.csv`: **`ValidatorDynamicCode`
+means a bare string, `ValidatorDynamicCodeObject` means `{"v": "…"}`**.
+
+## The variable namespace
+
+`data/dynamic-variables.csv` — 74 variables across 11 namespaces, each row carrying
+the exact `@VAR('…')` expression to paste:
+
+| namespace | n | what it needs to resolve |
+|---|---|---|
+| `post` | 22 | a post/page context — `title`, `id`, `permalink`, `content`, `featuredImage`, `publish_date`, `author_name`, `modified_timestamp`, … |
+| `user` | 13 | the current visitor — `displayName`, `email`, `loggedin`, `user_registered_date`, … |
+| `site` | 7 | always — `name`, `url`, `description`, `admin_email`, `wpurl` |
+| `author` | 7 | a post context |
+| `menu` | 7 | inside a menu loop — `href`, `title`, `hasChildren` |
+| `request` | 4 | always — `ip`, `page_url`, `referrer`, `user_agent` |
+| `slider` | 4 | inside a slider |
+| `wordpress_search` | 4 | a search results page — `searchQuery`, `resultCount` |
+| `wordpress_archive` | 3 | an archive page |
+| `form` | 2 | inside a form action |
+| `__current_theme` | 1 | always |
+| `row` | — | inside a loop; its schema is declared per loop source, not statically |
+
+**An unresolvable name is an empty string, never an error.** `@VAR('nope/nothing')`
+renders as nothing at all, and so does a real name in the wrong context — a
+`post/title` on a page with no post context is indistinguishable from a typo. That is
+what `@fallback()` is for, and why a blank spot on a page is the symptom to look for
+rather than a message in a log.
+
+The name separator is `/` (`TemplatingContextVariable::VARIABLE_SEPARATOR`), and the
+namespace is everything before the first one.
+
+## The functions
+
+`data/evaluator-functions.csv` — 19 of them with their arity:
+
+```
+abs(1)  round(1)  round_up(2)  calc(1)  sum(…)  avg(…)          numeric
+concat(…)  substr(3)  excerpt(4)  remove_html(1)                text
+esc_attr(1)  esc_html(1)  json_encode(1)                        escaping
+date(3)                                                         dates
+fallback(…)                                                     defaulting
+attachment(2)  find_image(2)  find_link(2)  find_video(2)       media
+```
+
+`sum`, `avg`, `concat` and `fallback` are variadic. `date()`'s timestamp argument is a
+true GMT Unix timestamp — pair it with `post/publish_timestamp_gmt`, not
+`publish_timestamp`, unless you want the local-time value re-interpreted as UTC.

package/references/failure-modes.md

@@ -0,0 +1,182 @@
+# How Mosaic fails, measured
+
+## `$wpdb->insert()` casts any column named `ID` to an integer
+
+WordPress hardcodes `'ID' => '%d'` in `$wpdb->field_types`, because `wp_posts.ID` is
+an integer. Mosaic's `ID` columns are `varchar(36)` — UUIDs, and for breakpoints the
+literals `_t` and `_m`.
+
+So `$wpdb->insert($table, $row)` on a Mosaic table stores `_t` as `0`. It happened to
+fail loudly here, because `_m` also becomes `0` and collides on the composite primary
+key — on a table where only one row was affected it would have been silent.
+
+Pass an explicit format array on every insert:
+
+```php
+$wpdb->insert($table, $row, array_fill(0, count($row), '%s'));
+```
+
+## WP-CLI eats `--flags` before your script sees them
+
+`wp eval-file script.php --active` fails with *unknown --active parameter*: WP-CLI
+parses anything `--`-prefixed as its own option. Script arguments must be bare
+keywords — `wp eval-file script.php active`.
+
+## An invalid `ordering` orphans the node, silently
+
+`ordering` is a fractional-index STRING. Send something that is not one and the
+commit returns **no exception** — and the row is stored with **both `ordering` and
+`parentID` blanked**. The node has no parent, so it never renders, and anything you
+were measuring through it reads as a clean negative.
+
+Measured side by side in one commit, three sibling probes:
+
+```
+ordering "a6"    -> stored: ordering=a6  parentID=a2dd9602-...   renders
+ordering "z000"  -> stored: ordering=''  parentID=''            orphan
+ordering "z001"  -> stored: ordering=''  parentID=''            orphan
+```
+
+This cost a whole style-property sweep: 77 probes committed without error, none
+rendered, and all 77 properties came back ABSENT — including `color` and
+`paddingTop`, which the entire site is built on. The result looked like a finding.
+It was the tool being broken.
+
+Use `ordering_for()` in `tools/build_page.py`; never format your own. And when a
+sweep returns a suspiciously total failure, check that the probes rendered before
+believing the measurement — `sweep_style_properties.py` now exits rather than
+reporting a run in which nothing rendered.
+
+## Duplicate `ordering` among siblings drops nodes, silently
+
+`ordering_for()` in `build_page.py` wraps after 62 entries, so `ordering_for(i % 62)`
+hands two siblings the same index. Mosaic keeps one and discards the other without an
+exception. A sweep of 79 probes left 39 nodes in the database and still printed a
+result table.
+
+For more than 62 siblings, generate your own monotonic index - `"a" + ALPHA[i // 62]
++ ALPHA[i % 62]` gives 3844 lexicographically ordered slots.
+
+## A sweep must refuse a contaminated page
+
+Probe ids from separate runs share an id space, and two runs can give the same id to
+different node types - `np-101` was a `<select>` from one run and a `<div>` from the
+next, on the same page. Every number read off that page was meaningless.
+
+Worse, the cleanup query was `LIKE "%np-0%"`, which silently misses every id from
+`np-100` up, so "0 remaining" was itself wrong. Match the stored shape:
+`LIKE '%"attrID":"np-%'`.
+
+`sweep_node_properties.py` now exits unless the page carries exactly the probes this
+run planned, allowing for the ones whose own property relocates them out of the tree.
+
+## heal() owns the body's children
+
+Do not parent anything directly to a `body` node. `heal()` rebuilds the
+body > three-div skeleton whenever it decides one is missing, and probes hung
+straight off the body do not survive it. Attach to a div inside the body instead.
+
+Every failure below was produced on purpose, on a live install, by the sweep in
+`tools/sweep_node_types.py`. None of it is inferred from source.
+
+## Mosaic does not validate placement at commit time
+
+This is the fact that shapes everything else. Mosaic's commit endpoint will happily
+store a node whose parent makes no structural sense. The rejection happens later, at
+**render** — and it takes the entire page with it.
+
+Placing `accordion-item` directly under a `div`:
+
+```
+commit  -> HTTP 200, syncResponseEnvelopes with action "create". The row is in the DB.
+render  -> HTTP 200, 54 bytes, body: "AccordionElementMResource instance required"
+```
+
+Not a 500. Not a WordPress error page. A **200 with a plain string where the site used
+to be**. Three of the 74 free types do this from a plain `div` parent:
+
+| type | what the dead page says |
+|---|---|
+| `accordion-item` | `AccordionElementMResource instance required` |
+| `accordion-content` | `AccordionItemElementMResource instance required` |
+| `wysiwyg-variable` | `NodeMResourceFilterFunctionInterface parent is missing` |
+
+The consequence for anything automated: **a successful commit is not evidence of a
+working page.** Fetch the page and check its size after writing. A monitor that only
+watches status codes will report a healthy site that is serving 54 bytes.
+
+It also means a batch write is dangerous in a way it is not in Elementor or Gutenberg:
+one bad node does not degrade its own corner of the page, it deletes the page. Write
+one subtree, verify, then write the next.
+
+## Some types kill the commit request itself
+
+Five free types return **HTTP 500** from `/commit` when placed under a `div`:
+
+```
+component-instance   loop   loop-items   loop-pagination-numbers   loop-pagination-number
+```
+
+These are the types that require a resolved context — a component to instantiate, a
+query to iterate — and the constructor throws before Mosaic can turn the problem into
+a normal validation response. Nothing is written, so a 500 here is *safer* than the
+silent 200 above, but it is still a PHP fatal in the error log rather than an
+error message you can show a user.
+
+`document` produced a 502 on one run and a 500 on another: the same fatal, sometimes
+surfacing as a gateway timeout instead. Treat 5xx from `/commit` as one class.
+
+## Validator rejections arrive as HTTP 200
+
+Separate from both cases above: when Mosaic *does* reject a value cleanly, it answers
+`RESTJSONExceptionEnvelope` — HTTP **200** with an `exceptions` array in the body.
+
+```python
+resp = commit(...)          # 200
+resp["response"]["exceptions"]   # <- the actual verdict lives here
+```
+
+So there are three distinct outcomes and only one of them changes the status code:
+
+| what happened | status | how you detect it |
+|---|---|---|
+| clean validator rejection | 200 | `exceptions` in the body |
+| PHP fatal during commit | 500/502 | status code |
+| structurally invalid node accepted | 200 | **nothing, until you fetch the page** |
+
+## Commit has side effects beyond the rows you sent
+
+The first commit against a fresh theme came back having created things nobody asked
+for:
+
+```
+create breakpoint      _t
+create breakpoint      _m
+create collection      9083a14b-…
+create collectionMode  9a674a81-…
+create collectionSkin  e4beb80a-…
+```
+
+`heal()` runs as part of the commit path, so the response's `syncResponseEnvelopes`
+can contain resources from managers you never touched. Read the whole envelope list
+and take every revision in it — assuming the response only describes your own writes
+will leave you holding stale revisions for the rest of the session.
+
+Composite types heal aggressively too: a naive batch that placed all 74 types once
+produced **802 node rows**, because types like `accordion` and `navbar` build their
+required children on commit.
+
+## `modified_gmt` is server-assigned
+
+A record committed with `"modified_gmt": "2026-09-05 17:00:00"` came back stored as
+`16:59:16`. The server overwrites it. Do not use a value you sent as a local cache key.
+
+## Reproducing all of this
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php          # licence-free scratch theme
+python tools/sweep_node_types.py --config sweep.json --setup
+python tools/sweep_node_types.py --config sweep.json --sweep
+```
+
+The sweep is destructive by design and must only be pointed at a scratch site.

package/references/interactions.md

@@ -0,0 +1,126 @@
+# Interactions: Mosaic's JavaScript animation system
+
+There are two ways to animate in Mosaic and they are completely separate.
+
+**The CSS path** — a `transition` array plus a `hover` (or any other) state — is fully
+verified and is what `sites/_moksa.py` uses. It covers hover, focus and
+every node-type state in `data/style-states.csv`. Reach for it first;
+`references/styling.md` has the shapes.
+
+**The interaction path** is this document: scroll-driven and event-driven animation
+with keyframes, run by Mosaic's own JavaScript. It is **partially verified**, and this
+page is explicit about where the verified part ends.
+
+## What is confirmed
+
+The envelope, the trigger types and the action/timeline structure all reach the
+browser. A node carries:
+
+```json
+"interactions": [{
+  "type": "scrollIntoView",
+  "scrollIntoViewOptions": {
+    "name": "Reveal",
+    "ID": "<uuid>",
+    "actionSlots": {
+      "scrollIntoView": {
+        "actions": [{
+          "type": "animation",
+          "uuid": "<uuid>",
+          "animationOptions": {
+            "propertyMetas": [ … ],
+            "initial": { … },
+            "keyframes": [{"uuid": "<uuid>",
+                           "progressData": {"delay": 0, "duration": 100}}]
+          }
+        }]
+      }
+    }
+  }
+}]
+```
+
+and the page then emits, in a `<script>` before the frontend bundle:
+
+```js
+var mosaicInteractionTypes={"progress":[{"id":"scrollIntoView",
+  "defaultSettings":{"allowBackward":"1","smoothing":"60","startWhen":"middleOfTheScreen",
+                     "startOffset":"0px","endWhen":"middleOfTheScreen","endOffset":"0px"},
+  "supportsLivePreview":true,"timelineKeys":["_"]}]};
+var mosaicInteractions=[{"type":"scrollIntoView","triggerSelector":".M_EL3",
+  "action":{"scrollIntoView":{"actions":[{"type":"animation","data":{},
+    "animationOptions":{"timelines":{"_":{"keyframes":[
+      {"progressData":{"delay":0,"duration":100},"easing":"ease"}]}}}}]}}}];
+```
+
+That payload is the oracle for anything still unknown: commit a shape, fetch the page,
+read `var mosaicInteractions`. Whatever survives into it is what Mosaic accepted.
+
+Confirmed from it:
+
+- **The action-slot key is the interaction's own ID** when the type declares no
+  explicit slots (`TimedInteractionTypeFactory` falls back to `$this->reader->getId()`).
+- **The array inside a slot is `actions`**, not the slot name.
+- **The keyframe array is `keyframes`**, not the timeline key — the timeline key
+  (`_` for a single-timeline type) is applied by the server, which reshapes
+  `animationOptions` into `{"timelines": {"_": {"keyframes": [...]}}}`.
+- **`progressData` uses floats 0–100**, not durations, for progress-family triggers —
+  it is a percentage of the scroll range, not milliseconds.
+- **`easing` is defaulted to `ease`** by the server.
+
+## What is NOT solved
+
+**Property binding.** `propertyMetas` and per-keyframe `properties` did not survive
+into the payload in any shape tried: flat array of metas, metas nested one level
+deeper (which made the whole interaction vanish), properties as an object, properties
+as an array. The keyframes arrive with timing but with nothing to animate.
+
+Do not ship an interaction animation on the strength of this page. Use the CSS path,
+or drive the editor once by hand and read the stored row back out of `wp_mosaic_nodes`
+— that row is the authoritative example, and one look at it would settle the shape.
+
+## The failure mode that makes this hard
+
+**Invalid sub-structures are silently pruned.** Committing the full interaction above
+returned HTTP 200, no `exceptions`, and a normal `create` envelope — and the row
+stored was:
+
+```json
+[{"type":"scrollIntoView","scrollIntoViewOptions":{"name":"Reveal"},"uuid":"…"}]
+```
+
+`ID`, `actionSlots`, the action and the whole animation were dropped without a word.
+Mosaic also *added* a `uuid` of its own. So on this data model:
+
+- a successful commit says nothing about whether your structure was understood;
+- **read the row back** (`GET …/masterDocumentInstance/<masterID>`) and compare it to
+  what you sent — the diff is the error message Mosaic never gives you.
+
+That check is worth applying to any deeply-nested Mosaic write, not just interactions.
+
+## The surface, extracted
+
+`data/interaction-types.csv` — 12 trigger types in two families:
+
+| family | how it runs | types |
+|---|---|---|
+| `timed` | its own clock, fired by an event | `pageLoad`, `click`, `hover`, `formSubmit`, `tabChange`, `slideChange`, `dropdownChange`, `accordionItemChange`, `elementScrollIntoView`, `scrollDirectionChange` |
+| `progress` | driven by a scalar, scrubbable both ways | `scrollIntoView`, `pointerMove` |
+
+`data/animatable-properties.csv` — the 22 properties a keyframe can drive. **This is
+not the same set as the 98 style properties**, and ten of them animate through a CSS
+custom property rather than the property itself:
+
+```
+transform  translateX/Y/Z (--mosaic-translate-*)  scale, scaleX/Y/Z (--mosaic-scale*)
+rotateX/Y/Z (--mosaic-rotate-*)  opacity  color  backgroundColor  borderColor
+boxShadow  textShadow  width  height  filter  backdropFilter  transformOrigin
+```
+
+Animating through `--mosaic-translate-y` rather than `translate` is why a Mosaic
+interaction can move an element that already has a CSS `translate` set: the two
+compose instead of one clobbering the other.
+
+`data/pluggables.csv` lists the 11 non-animation action types an interaction can run —
+`link`, `script`, `setCookie`, `player*`, `interaction*` — for triggering behaviour
+rather than motion.

package/references/placement.md

@@ -0,0 +1,117 @@
+# Placement: the rule the API will not enforce for you
+
+Mosaic decides whether an element may sit inside another element in **two** places,
+and neither of them is the REST commit endpoint.
+
+```
+canBeParentFor($childFactory)      on the PARENT type - "will I take this child?"
+canBeNestedChildFor($target, $br)  on the CHILD  type - "am I allowed in this ancestry?"
+```
+
+The visual editor calls both before it lets you drop anything. `POST …/commit` calls
+neither. A node committed into a parent that would have refused it is stored, returns
+HTTP 200 with a normal `syncResponseEnvelopes`, and the **public page then dies**,
+serving a bare string like `AccordionElementMResource instance required` as a 200 with
+a ~54 byte body.
+
+That is the whole reason this table exists. Writing Mosaic headlessly means being the
+component that checks placement, because nothing downstream will.
+
+## The parent side: `data/placement-rules.csv`
+
+One row per node type, extracted from every `canBeParentFor` in the source (122 types):
+
+| rule | count | meaning |
+|---|---|---|
+| `none` | 59 | leaf. Refuses every child — the default on `NodeTypeFactoryAbstract`. |
+| `any` | 34 | takes anything. `div`, `body`, `section`, `button`, `menu`, `slider-slide`, `tabs-tab-pane`, … |
+| `allow` | 26 | takes only the types in `allowed_children`. |
+| `complex` | 3 | the body is not a plain `instanceof` chain — `fieldset`, `select-input`, `styleguide-entry-content-text-quote`. Read the file named in `declared_in`. |
+
+The `allow` rows are the component families, and they are strict. A few worth knowing
+by heart because they are the ones people get wrong:
+
+```
+accordion            -> accordion-item | accordion-loop-items
+accordion-item       -> accordion-item | accordion-loop-items
+list                 -> list-item | list-loop-items
+tabs                 -> tabs-content | tabs-menu
+tabs-menu            -> tabs-loop-tabs | tabs-tab
+tabs-content         -> tabs-loop-tab-panes | tabs-tab-pane
+slider-slides        -> slider-loop-slides | slider-slide
+slider-navigation    -> slider-navigation-bullet
+form-wrapper         -> form | success-screen
+submit-button        -> submit-label | submit-loading
+loop-items           -> loop-item
+wp-menu              -> list-item
+```
+
+Note `accordion-item -> accordion-item`: an accordion item's children are further
+items, not arbitrary content. The content goes in `accordion-title` and
+`accordion-content`, both of which are `rule = any`.
+
+## The child side: `nested_rule`
+
+**55 of the 122 types also implement `canBeNestedChildFor`** — a runtime condition on
+the *ancestry*, not just the immediate parent. A static table cannot resolve these,
+so the CSV flags them and names the file.
+
+`accordion-item` is the worked example:
+
+```php
+// legal only if the target is an accordion / accordion-loop-items,
+// or an accordion appears somewhere up the branch
+if (!$inAccordion && !$elementFactoryNode->hasFactoryOnBranch(AccordionElementTypeFactory::class)) {
+    return false;
+}
+```
+
+`div` says `any`, so the parent side waves `accordion-item` through. The child side
+would have refused — but only the editor asks it. Commit does not, and the page dies.
+This is exactly the measured `BROKE_PAGE` case.
+
+## The rule to write into your own code
+
+Before committing a node of type `C` under a parent of type `P`:
+
+1. Look up `P` in `placement-rules.csv`. If `rule` is `none`, stop. If `allow`, `C`
+   must be in `allowed_children`. If `complex`, read `declared_in`.
+2. Look up `C`. If `nested_rule` is `yes`, its required ancestry must genuinely be
+   present — the parent chain, not just the immediate parent.
+3. Commit, then **fetch the page and check its size**. Step 3 is not optional; steps
+   1 and 2 are a static approximation of two runtime methods.
+
+Types with `rule = any` are the safe scaffolding: `div`, `section`, `body`,
+`loop-item`, `tabs-tab-pane`, `slider-slide`, `styleguide-entry-content`. Build with
+those and place specialised children only inside the family that declares them.
+
+## What this table does NOT tell you
+
+It does not predict which types are unsafe to drop into a plain container. That was
+tested rather than assumed, and it failed:
+
+```
+predictor                        tp / fp / fn   precision  recall
+nested_rule == yes                9 / 46 / 13     0.16      0.41
+rule == allow                    11 / 15 / 11     0.42      0.50
+rule in (allow, complex)         11 / 18 / 11     0.38      0.50
+rule == allow AND nested_rule     5 / 12 / 17     0.29      0.23
+rule == allow OR nested_rule     15 / 49 /  7     0.23      0.68
+```
+
+22 of the 122 types break the page or fault the commit when placed under a bare `div`,
+and they are spread across every rule value - 11 are `allow`, 6 are `none`, 5 are
+`any`. No flag in this table separates them, and the best combination still misses a
+third of them while flagging 49 types that are perfectly fine.
+
+So the two questions are different, and only one of them is settled by source:
+
+| question | authority |
+|---|---|
+| which children does parent P accept? | `placement-rules.csv` - reliable, this is literally `canBeParentFor` |
+| is child C safe under a plain container? | `node-verification.csv` - **measured**, nothing else predicts it |
+
+Reach for the measured table when you are deciding what to build with, and this one
+when you are deciding what may go inside what. `tools/check_placement_predicts.py`
+re-scores the numbers above after any re-sweep, so the claim stays honest if the
+plugin changes.