mosaic-headless 1.21.1 → 1.22.0

package/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface with `mo.py`, which joins every source table to the live sweeps so a lookup leads with the measured verdict rather than the declaration (126 node types, 191 properties, 98 style properties with 20 structured value shapes pinned down, 53 style states, 156 variants, 74 dynamic variables, 15 interaction triggers, 115 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, the design-token and element-class layers verified against compiled CSS, the @VAR() dynamic language verified against rendered output, nine designed pages built through the tables themselves, and the delivered pages re-read in Chromium at three viewports so a rule that is present, correct and still wrong cannot pass. Drives Mosaic's own theme export/import and its plugin data upgrade from outside the editor and holds the copy against the source tree for tree. Measured on Mosaic Pro 1.0.9: the modal (`<dialog>`), OpenStreetMap, the exit-intent and scroll-depth triggers, run rules and the memory actions all built on a live page and read back, and the 1.0.7 -> 1.0.8 -> 1.0.9 migrations driven from outside wp-admin.
 license: "MIT"
 author: "moksa (https://moksaweb.com)"
-version: "1.21.1"
+version: "1.22.0"
 ---
 
 # Headless Mosaic
@@ -700,6 +700,12 @@ post — `build_all.py` resets first for that reason.
   rows and `theme_zip_compare.php` reports a tree that does not match - delete
   nodes with a missing parent REPEATEDLY until none are left, because each pass
   orphans the next level down.
+- **`width` / `height` and their min/max take the keyword `stretch` since 1.0.9**,
+  and Mosaic emits `-webkit-fill-available` before it so an older engine still gets
+  something. They are still token-referencable - `CSSSizePropertyFactory` extends
+  the collection-variable one, which is why `data/style-properties.csv` resolves a
+  factory's ancestry rather than testing its name. 39 properties take a token, not
+  the 34 counted before that fix.
 - **A width copied out of Elementor needs `maxWidth: "100%"` beside it.**
   Elementor caps every widget with `max-width:100%`, so a px width there is a
   desktop intent its own CSS already constrains; carried across bare it keeps the
@@ -806,6 +812,7 @@ post — `build_all.py` resets first for that reason.
 | `copy_styles.py` | push one node's style onto others, by attrID or prefix |
 | `bootstrap_probe_theme.php` | a licence-free scratch theme |
 | `mint_session.php` | a matching cookie + `wp_rest` nonce from WP-CLI |
+| `check_tables.py` | re-extract all eleven source-derived tables and diff them against the shipped ones - the check for a table that is not wrong but STALE, which nothing else can see |
 
 ## Regenerating everything
 
@@ -817,6 +824,12 @@ python tools/extract_default_children.py <plugin-root> data/
 python tools/extract_style_properties.py <plugin-root> data/
 python tools/extract_interactions.py     <plugin-root> data/
 python tools/extract_dynamic_variables.py <plugin-root> data/
+
+# and then, always: a table extracted BEFORE its extractor was repaired keeps
+# describing the old source and ships silently. Row counts cannot see it and the
+# release gate never sees the plugin. Run this after ANY change to an extractor,
+# not only after a plugin upgrade.
+python tools/check_tables.py              <plugin-root>
 python tools/capture_live.py             data/          # from data/raw/*.json + db-columns.txt
                                                         # (raw dumps are gitignored;
                                                         #  re-capture from a live site)

package/assets/templates/platforms/claude-ai.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.21.1"
+    "version": "1.22.0"
   },
   "loaderBehaviour": "Upload via Settings -> Skills -> Upload. Claude.ai parses SKILL.md frontmatter and surfaces the skill in your library. The extraction tool (extract-block-schema.php) needs a live WP-CLI connection and won't run in the sandbox; use it from a local terminal against your own site instead.",
   "uploadSteps": [

package/assets/templates/platforms/claude-code.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.21.1"
+    "version": "1.22.0"
   },
   "loaderBehaviour": "Auto-loads on session start when SKILL.md frontmatter parses successfully.",
   "verified": true,

package/assets/templates/platforms/codex-cli.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.21.1"
+    "version": "1.22.0"
   },
   "loaderBehaviour": "Confirmed (2026-07-11): Codex CLI natively supports the SKILL.md spec. Place SKILL.md under .codex/skills/<name>/ (project) or ~/.codex/skills/<name>/ (personal) and Codex loads the name+description at session start, then the full body on demand. A parallel, broader convention .agents/skills/ (searched from cwd up to repo root, then ~/.agents/skills/) also exists across multiple tools - if your Codex CLI version prioritizes that path instead, mirror the same SKILL.md there.",
   "verified": true,

package/assets/templates/platforms/copilot.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.21.1"
+    "version": "1.22.0"
   },
   "loaderBehaviour": "CHANGED as of 2026-07-11: GitHub Copilot added a proper '.github/skills/' Agent Skills directory (December 2025), alongside the older single-file .github/copilot-instructions.md convention. This config targets the new skills-directory form. If your Copilot version predates this (pre Dec 2025), use the instructions-append fallback instead (see fallback below).",
   "fallback": {

package/assets/templates/platforms/gemini-cli.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.21.1"
+    "version": "1.22.0"
   },
   "loaderBehaviour": "CHANGED as of 2026-07-11: Gemini CLI now natively supports the same SKILL.md standard as Claude Code and Codex CLI - the same directory-based skill works unmodified. Gemini CLI discovers skills in this precedence order: built-in, extension skills, ~/.gemini/skills/ (personal), .gemini/skills/ (project, shared via version control). At session start Gemini injects each discovered skill's name+description into the system prompt and calls activate_skill when a task matches.",
   "verified": true,

package/data/interaction-rules-verification.csv

@@ -0,0 +1,14 @@
+subject,case,result,detail
+pickOne,"12 fresh loads, remember=page",PASS,exactly one of the three modals opened every time; 4/6/2 across the group
+pickOne,"8 reloads of one tab, remember=page",PASS,re-drawn on every load: 6/1/1
+pickOne,"8 reloads of one tab, remember=forever",PASS,the same contender all 8 times
+pickOne,"6 fresh browser contexts, remember=forever",PASS,draws again in a new context: 1/3/2 - the record is per browser profile
+pickOne,storage record,PASS,"mos:v1:r:<name> gains lastID, naming the contender the draw chose"
+targetModifiers,plain element,PASS,"[{""type"":""all"",""selector"":""._e""}]"
+targetModifiers,plain variant,PASS,"[{""type"":""all"",""selector"":""h2,.m-heading-2""}] - a variant resolves to its own selectors"
+targetModifiers,children(variant),PASS,"appends {""type"":""children"",""selector"":""h2,.m-heading-2""}"
+targetModifiers,sibling(variant),PASS,"appends {""type"":""sibling"",...}"
+targetModifiers,parent(variant),PASS,"appends {""type"":""parent"",...}"
+targetModifiers,include(element),PASS,"appends {""type"":""include"",...}"
+targetModifiers,exclude(element),PASS,"appends {""type"":""exclude"",...}"
+targetModifiers,children then exclude,PASS,"three entries, in the order written - the list is a pipeline, not a filter set"

package/data/style-properties.csv

@@ -38,12 +38,12 @@ wordSpacing,,CSSCollectionVariablePropertyFactory,,,yes
 whiteSpace,,CSSPropertyFactory,,normal|pre-wrap|nowrap|pre,
 textTransform,,CSSPropertyFactory,,none|lowercase|uppercase|capitalize,
 textShadow,,CSSTextShadowStylePropertyFactory,,,
-width,,CSSSizePropertyFactory,,,
-minWidth,,CSSSizePropertyFactory,,,
-maxWidth,,CSSSizePropertyFactory,,,
-height,,CSSSizePropertyFactory,,,
-minHeight,,CSSSizePropertyFactory,,,
-maxHeight,,CSSSizePropertyFactory,,,
+width,,CSSSizePropertyFactory,,,yes
+minWidth,,CSSSizePropertyFactory,,,yes
+maxWidth,,CSSSizePropertyFactory,,,yes
+height,,CSSSizePropertyFactory,,,yes
+minHeight,,CSSSizePropertyFactory,,,yes
+maxHeight,,CSSSizePropertyFactory,,,yes
 position,,CSSPropertyFactory,,static|relative|absolute|fixed|sticky,
 zIndex,,CSSPropertyFactory,,,
 top,,CSSCollectionVariablePropertyFactory,,,yes
@@ -61,19 +61,19 @@ paddingLeft,,CSSCollectionVariablePropertyFactory,,,yes
 borderRadius,,CSSBorderRadiusPropertyFactory,,,
 borderTopWidth,borderStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 borderTopStyle,borderStyle,CSSGrouppedPropertyFactory,,,
-borderTopColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,
+borderTopColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,yes
 borderRightWidth,borderStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 borderRightStyle,borderStyle,CSSGrouppedPropertyFactory,,,
-borderRightColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,
+borderRightColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,yes
 borderBottomWidth,borderStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 borderBottomStyle,borderStyle,CSSGrouppedPropertyFactory,,,
-borderBottomColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,
+borderBottomColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,yes
 borderLeftWidth,borderStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 borderLeftStyle,borderStyle,CSSGrouppedPropertyFactory,,,
-borderLeftColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,
+borderLeftColor,borderStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,yes
 outlineWidth,outlineStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 outlineStyle,outlineStyle,CSSGrouppedPropertyFactory,,,
-outlineColor,outlineStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,
+outlineColor,outlineStyle,CSSGrouppedPropertyFactory,CSSColorProperty,,yes
 outlineOffset,outlineStyle,CSSGrouppedPropertyFactory,CSSCollectionVariableProperty,,yes
 boxShadow,,CSSBoxShadowStylePropertyFactory,,,
 opacity,,CSSPropertyFactory,,,

package/data/value-coercion-verification.csv

@@ -0,0 +1,13 @@
+validator,probed_on,sent,result,note
+ValidatorInteger,maxlength on textarea-input,"""12""",12,accepted
+ValidatorInteger,maxlength on textarea-input,"""12abc""",12,"trailing garbage ignored - parseInt semantics, new in 1.0.9"
+ValidatorInteger,maxlength on textarea-input,"""abc""",(absent),"no leading digits, rejected"
+ValidatorInteger,maxlength on textarea-input,"""-5x""",(absent),"parses to -5, then refused by the property's own min:0 - the parser accepted it"
+ValidatorInteger,maxlength on textarea-input,""" 7 """,7,leading and trailing whitespace tolerated
+ValidatorInteger,maxlength on textarea-input,"""0012""",12,"leading zeros are decimal, not octal"
+ValidatorInteger,maxlength on textarea-input,"""1e3""",1,NOT 1000 - the exponent is trailing garbage
+ValidatorInteger,maxlength on textarea-input,"""12.9""",12,"truncated toward zero, not rounded"
+stretch,width,"""stretch""",width:-webkit-fill-available then width:stretch,"both emitted, prefix first"
+stretch,height,"""stretch""",height:-webkit-fill-available then height:stretch,both emitted
+stretch,maxWidth,"""stretch""",max-width:-webkit-fill-available then max-width:stretch,both emitted
+stretch,width,"""STRETCH""",width:STRETCH,"kept as typed - the match is case-sensitive, and CSS keywords are not, so it still applies"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "AI-agent skill: build Mosaic Pro (Nextend) WordPress sites by writing the underlying data model directly - 23 custom tables, no visual editor, no DOM. Every node type, style property and node property swept against a live install and asserted on the delivered HTML and compiled CSS. Installs into Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot, Continue, Windsurf and Claude.ai.",
   "keywords": [
     "wordpress",

package/references/dialog-and-triggers.md

@@ -119,6 +119,33 @@ What that writes, measured: `localStorage` **and** `sessionStorage`, both under
 that opens a second tab to prove a cap is testing nothing — reload the same tab.
 That mistake made the cap look broken here until the tab was reused.
 
+### `pickOne`, measured
+
+`pickOne` is the one rule that is about a GROUP rather than one interaction, and the
+group is the `name`: give three modals the same `name` and exactly one of them opens.
+Three `pageLoad` modals sharing `probe-pick` were loaded repeatedly:
+
+| what | result |
+|---|---|
+| 12 fresh browser contexts, `remember: "page"` | one modal every time, 4 / 6 / 2 across the three |
+| 8 reloads of the SAME tab, `remember: "page"` | re-drawn each load — 6 / 1 / 1 |
+| 8 reloads of the same tab, `remember: "forever"` | the same contender all 8 times |
+| 6 fresh contexts, `remember: "forever"` | draws again — 1 / 3 / 2 |
+
+No load ever opened more than one. So `remember` on `pickOne` does not mean "how long
+until it may run again", it means **how long the draw is kept**: `page` re-rolls on
+every navigation, `session` and `forever` hand one visitor the same variant each time
+— which is the whole point, since a popup that changes on reload reads as a bug. The
+last row is the limit worth knowing: `forever` is localStorage, so it is per browser
+profile, and a fresh context is a fresh visitor who draws again.
+
+The record gains one field for this: alongside `counter` / `firstAt` / `lastAt`,
+`mos:v1:r:<name>` carries **`lastID`**, the uuid of the interaction that won the draw.
+That is what makes the choice stick, and it is also how you read the drawn variant
+back in a test without inspecting which modal is open.
+
+`data/interaction-rules-verification.csv` has the runs.
+
 ## Memory: remember / forget
 
 Two actions that write and clear the same records a run rule reads, so one
@@ -198,6 +225,33 @@ anywhere. That is the skill's existing rule (`ValidatorDynamicCode` = bare strin
 `ValidatorDynamicCodeObject` = `{"v": …}`) applying to a new element, and it is also
 why those three can hold `@VAR('post/meta_lat')` and a custom field can drive the map.
 
+## The rest of 1.0.9, briefly
+
+Not everything in the release is a node you place. Four things that change how the
+plugin behaves rather than what you can build:
+
+- **`stretch` on the size properties.** `width`, `height` and their min/max moved to
+  `CSSSizePropertyFactory`, which accepts the keyword and emits
+  `width:-webkit-fill-available` **then** `width:stretch` — the modern value last so
+  a current engine lands on it and an older one keeps the alias. Measured on all
+  three of width / height / max-width; the author's casing is preserved as typed.
+- **`ElementClassPruner`.** The generated `_<token>` class is now a placeholder while
+  the tree renders, and one pass over the finished HTML keeps it only where a
+  selector actually claimed it. The marker is random per render, so the pass can
+  never touch a class that arrived from post content or a shortcode. This is the
+  mechanism behind "an element whose styles compile to nothing has no generated
+  class" — it is a deliberate feature, not an accident.
+- **Author and term page instances.** `PageInstance/PageTypes/Author` and `Term` let
+  the editor put a specific author or taxonomy term in front of an archive template;
+  a term has no assign of its own, because a term archive is only ever rendered by
+  its path.
+- **`POST /template/createAutoTemplate`** (`resourceQuery`, `masterID`) creates the
+  automatic template a post type is missing — a template on the post type's PATH,
+  with nothing recorded against the resource that prompted it. Deliberately not the
+  assign endpoint: a post type whose resources cannot carry an assign still needs a
+  way to be designed, and conflating the two would make this look like an assign.
+  115 routes now, up from 114.
+
 ## What else moved in the delivered page
 
 **The three per-breakpoint stylesheets became one.** Through 1.0.8 a page carried

package/references/failure-modes.md

@@ -294,3 +294,27 @@ The other half of this finding is about the checkers: WordPress's "critical erro
 page is 2,697 bytes, above the 2,000-byte healthy floor, and `Client.page()` was
 returning an HTTPError's body as the page - so `build_site` announced `OK` over a
 500 and a whole batch believed it. A 5xx now returns an empty body.
+
+## A shipped table can be stale rather than wrong
+
+The failure this skill nearly shipped three times in a row is not a bad value, it is
+an old one. `data/node-types.csv` carried an empty `default_element_class` for three
+releases: the column's regex was repaired AFTER the extraction run that produced the
+table, so the file went on describing the previous source and nothing compared the
+two again.
+
+Nothing in place could see it. Row counts were right the whole time — the table had
+the correct number of rows, with one column quietly blank. The release gate counts
+verification tables but never sees the plugin source, because that source is licensed
+third-party code and is not in the repository, so it cannot re-derive anything. And a
+reader of the skill has no way to tell a legitimately-empty column from a lost one.
+
+`tools/check_tables.py` closes it: it re-runs all seven extractors into a tempdir and
+diffs every output against the shipped file, naming the first differing line rather
+than just the filename. The moment to run it is **after any change to a
+`tools/extract_*.py`**, not only after a plugin upgrade — the upgrade is the case
+everyone remembers.
+
+The general shape, worth carrying beyond this repo: a derived artifact checked into
+the tree is only as fresh as the last time someone re-derived it, and if the deriving
+input is not in the tree, no amount of CI will notice.

package/references/interactions.md

@@ -143,6 +143,39 @@ Mosaic also *added* a `uuid` of its own. So on this data model:
 
 That check is worth applying to any deeply-nested Mosaic write, not just interactions.
 
+## Aiming an action somewhere else: `targetModifiers`
+
+Every pluggable action takes a `settings.target`, and a target is either
+`{"type": "element", "uuid": "<nodeID>"}` or `{"type": "variant", "uuid": "<variantID>"}`.
+`settings.targetModifiers` then narrows or widens it — a list of
+`{"uuid", "type", "data"}` where `data` is another target of the same two shapes and
+`type` is one of `children`, `sibling`, `parent`, `include`, `exclude`.
+
+The thing worth knowing is what that compiles to. The page hands the runtime a
+`targetSelectorData` **pipeline**: one entry for the base target, then one per
+modifier, applied in the order written.
+
+```
+plain element                 [{"type":"all","selector":"._e"}]
+plain variant                 [{"type":"all","selector":"h2,.m-heading-2"}]
+element + children(variant)   [{"type":"all","selector":"._e"},
+                               {"type":"children","selector":"h2,.m-heading-2"}]
+element + sibling(variant)    [... {"type":"sibling",   ...}]
+element + parent(variant)     [... {"type":"parent",    ...}]
+variant + include(element)    [... {"type":"include",   ...}]
+variant + exclude(element)    [... {"type":"exclude",   ...}]
+children then exclude         three entries, in that order
+```
+
+Two consequences. A **variant target resolves to the variant's own CSS selectors**,
+so "every H2" costs you nothing — you do not have to enumerate nodes. And because it
+is a pipeline rather than a filter set, **order matters**: `children` then `exclude`
+excludes from the children, while the reverse excludes from the base and then
+descends. Write the modifiers in the order you want them applied.
+
+All eight shapes above were committed and read back from the delivered page;
+`data/interaction-rules-verification.csv` has them.
+
 ## The surface, extracted
 
 `data/interaction-types.csv` — 12 trigger types in two families:

package/references/styling.md

@@ -109,12 +109,13 @@ 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 |
+| `CSSCollectionVariablePropertyFactory` (20) | a length string, or a reference to a collection variable |
+| `CSSSizePropertyFactory` (6) | `width`, `height` and their min/max. A collection-variable length like the row above - it is a subclass - plus the keyword **`stretch`**, which Mosaic emits as `-webkit-fill-available` FIRST and `stretch` second, so a current engine takes the standard value and an older one the alias. New in 1.0.9; measured. |
 | `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
+Plain strings were accepted verbatim for the properties probed above. The 39
 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.
@@ -127,7 +128,11 @@ lowest layer and it opts that node out of both reuse mechanisms:
 1. **Variants** (`data/variants.csv`, 152 built in - Mosaic's element classes) carry
    the shared look; a node points at one through `style.variant`.
 2. **Collections → modes/skins → variables** are the token layer, the thing the
-   34 token-referencable properties reference.
+   39 token-referencable properties reference. (34 until this was last counted:
+   `data/style-properties.csv` resolves a factory's ANCESTRY now rather than
+   testing its name, which 1.0.9 made necessary - `CSSSizePropertyFactory` extends
+   the collection-variable one - and which also recovered the five grouped colour
+   legs whose value class was always `CSSColorProperty`.)
 
 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

package/references/write-protocol.md

@@ -77,3 +77,34 @@ 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.
+
+## Validators coerce before they reject — a number need not arrive as a number
+
+Silent rejection is the documented hazard, but the quieter one is silent *acceptance*
+of something other than what you sent. As of 1.0.9 `ValidatorInteger` mirrors
+JavaScript's `parseInt()`: it takes the leading integer and discards the rest, where
+the previous release fell back to PHP's `intval()` and treated a zero result as a
+failure. Measured on `textarea-input`'s `maxlength`:
+
+| sent | stored | |
+|---|---|---|
+| `"12"` | 12 | |
+| `" 7 "` | 7 | whitespace tolerated |
+| `"0012"` | 12 | decimal, not octal |
+| `"12abc"` | **12** | trailing garbage ignored |
+| `"12.9"` | **12** | truncated toward zero, not rounded |
+| `"1e3"` | **1** | **not** 1000 — the exponent is trailing garbage |
+| `"abc"` | absent | no leading digits |
+| `"-5x"` | absent | parsed fine as −5; refused by the property's own `min: 0` |
+
+`"1e3"` is the row to remember: a value that looks numeric to a human, is numeric to
+`floatval()`, and lands as 1. A typo in a unit (`"16px"` where a bare integer was
+wanted) likewise stores 16 and never complains. Send integers as integers, and read
+the row back when you did not.
+
+The companion change is `ValidatorMimeType`, which now accepts any number of media
+type parameters including quoted values containing spaces — so
+`video/mp4; codecs="avc1.42E01E, mp4a.40.2"` is valid where 1.0.8 rejected it.
+
+`data/value-coercion-verification.csv` has these runs, along with the `stretch`
+keyword's emitted declarations.

package/scripts/check-release.mjs

@@ -102,6 +102,8 @@ const counts = {
   "data/slider-verification.csv": 19,
   "data/navigation-verification.csv": 46,
   "data/page-modal-verification.csv": 19,
+  "data/interaction-rules-verification.csv": 13,
+  "data/value-coercion-verification.csv": 12,
 };
 for (const [file, expected] of Object.entries(counts)) {
   if (!fs.existsSync(path.join(ROOT, file))) { fail(`${file} missing`); continue; }

package/tools/check_tables.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Re-extract every source-derived table and fail if a shipped one differs.
+
+    python tools/check_tables.py <plugin-root>
+
+The failure this exists for is not a wrong value, it is a STALE one, and it ships
+silently. Extracting the tables and then fixing the extractor leaves the shipped
+table describing the old source with no sign anywhere: `node-types.csv` carried an
+empty `default_element_class` for three releases because the column's regex was
+repaired after that run, and nothing compared the two again.
+
+Row counts cannot catch it - the count was right the whole time - and neither can
+the release gate, which never sees the plugin source: it is licensed third-party
+code and is not in the repository. So this is a local step, and the right moment
+for it is after ANY change to a tool under `tools/extract_*.py`, not only after a
+plugin upgrade.
+"""
+import filecmp
+import os
+import subprocess
+import sys
+import tempfile
+
+EXTRACTORS = [
+    "extract_node_types.py",
+    "extract_style_properties.py",
+    "extract_placement.py",
+    "extract_default_children.py",
+    "extract_dynamic_variables.py",
+    "extract_interactions.py",
+    "extract_pluggables.py",
+]
+
+
+def main():
+    if len(sys.argv) != 2:
+        sys.exit(__doc__)
+    plugin_root = sys.argv[1]
+    here = os.path.dirname(os.path.abspath(__file__))
+    data = os.path.join(here, "..", "data")
+    if not os.path.isdir(plugin_root):
+        sys.exit("no plugin source at %s" % plugin_root)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        for name in EXTRACTORS:
+            r = subprocess.run([sys.executable, os.path.join(here, name),
+                                plugin_root, tmp],
+                               capture_output=True, text=True, encoding="utf-8",
+                               errors="replace")
+            if r.returncode != 0:
+                sys.exit("%s failed:\n%s" % (name, (r.stdout + r.stderr)[-600:]))
+
+        stale, checked = [], 0
+        for fname in sorted(os.listdir(tmp)):
+            shipped = os.path.join(data, fname)
+            if not os.path.exists(shipped):
+                stale.append("%s: extracted but not shipped" % fname)
+                continue
+            checked += 1
+            if not filecmp.cmp(shipped, os.path.join(tmp, fname), shallow=False):
+                # name the columns that moved, not just the file
+                with open(shipped, encoding="utf-8") as a, \
+                        open(os.path.join(tmp, fname), encoding="utf-8") as b:
+                    al, bl = a.read().splitlines(), b.read().splitlines()
+                first = next((i for i, (x, y) in enumerate(zip(al, bl)) if x != y), None)
+                detail = ("%d lines -> %d" % (len(al), len(bl)) if len(al) != len(bl)
+                          else "first difference at line %d:\n    shipped: %s\n    fresh  : %s"
+                               % (first + 1, al[first][:110], bl[first][:110]))
+                stale.append("%s: %s" % (fname, detail))
+
+    print("checked %d source-derived tables against a fresh extraction" % checked)
+    if stale:
+        print("\nSTALE:")
+        for s in stale:
+            print("  - %s" % s)
+        sys.exit(1)
+    print("every one matches")
+
+
+if __name__ == "__main__":
+    main()

package/tools/extract_style_properties.py

@@ -110,6 +110,44 @@ def style_enums(plugin_root):
     return out
 
 
+def factory_parents(plugin_root):
+    """class -> its parent, for every property factory under Builder/Style.
+
+    Read because a factory's NAME stopped being enough in 1.0.9:
+    `CSSSizePropertyFactory extends CSSCollectionVariablePropertyFactory` and drives
+    width / height and their min and max, which still take a collection variable -
+    but a name test for "CollectionVariable" misses it and the table then says six
+    length properties cannot reference a design token, which is false.
+    """
+    parents = {}
+    base = os.path.join(plugin_root, "Mosaic", "Builder", "Style")
+    for root, _dirs, files in os.walk(base):
+        for name in files:
+            if not name.endswith(".php"):
+                continue
+            with open(os.path.join(root, name), encoding="utf-8", errors="replace") as fh:
+                src = fh.read()
+            # `extends Foo` and `extends \Name\Space\Foo` both; only the last
+            # segment is kept, which is what the factory column shows.
+            bs = chr(92)
+            for m in re.finditer("class" + r"\s+(\w+)\s+extends\s+([" + bs * 2
+                                 + r"\w]+)", src):
+                parents[m.group(1)] = m.group(2).split(bs)[-1]
+    return parents
+
+
+def is_tokenable(factory, value_class, parents):
+    """Does this factory, or anything it inherits from, accept a collection variable?"""
+    for name in (factory, value_class):
+        seen = set()
+        while name and name not in seen:
+            if "CollectionVariable" in name or "Color" in name:
+                return True
+            seen.add(name)
+            name = parents.get(name)
+    return False
+
+
 def extract(plugin_root, out_dir):
     enums = style_enums(plugin_root)
     path = os.path.join(plugin_root, "Mosaic", "Builder", "Style", "SupportedStyleProperties.php")
@@ -118,6 +156,7 @@ def extract(plugin_root, out_dir):
     with open(path, encoding="utf-8", errors="replace") as fh:
         src = fh.read()
 
+    parents = factory_parents(plugin_root)
     rows = []
     for factory, first, member, value_class in RE_ADD.findall(src):
         grouped = factory == "CSSGrouppedPropertyFactory"
@@ -128,10 +167,9 @@ def extract(plugin_root, out_dir):
                 "factory": factory,
                 "value_class": value_class.split("\\")[-1] if value_class else "",
                 "accepted_values": "|".join(enums.get(member if grouped else first, [])),
-                "tokenable": "yes" if (
-                    "CollectionVariable" in factory or "Color" in factory
-                    or "CollectionVariable" in (value_class or "")
-                ) else "",
+                "tokenable": "yes" if is_tokenable(
+                    factory, value_class.split("\\")[-1] if value_class else "",
+                    parents) else "",
             }
         )