mosaic-headless 1.21.2 → 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.2"
+version: "1.22.0"
 ---
 
 # Headless Mosaic
@@ -812,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
 
@@ -823,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.2"
+    "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.2"
+    "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.2"
+    "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.2"
+    "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.2"
+    "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/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.2",
+  "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

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/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()