mosaic-headless 1.32.0 → 1.32.2

package/SKILL.md

@@ -5,7 +5,7 @@ description: |
 license: "MIT"
 metadata:
   author: "moksa (https://moksaweb.com)"
-  version: "1.32.0"
+  version: "1.32.2"
   homepage: "https://github.com/Moksa1123/mosaic-headless"
 ---
 
@@ -490,10 +490,12 @@ so the pattern is in the data, not just in this paragraph.
   properties whose descriptor exists, and those are created during sync on a
   `DataMeta` that starts empty. Animate with the CSS state path, which is fully
   verified: 36 of 37 probed states compile to exactly the promised selector.
-- Committing a **condition** has not been driven end to end. The grammar in
-  `references/templates-and-conditions.md` is read from source and from the live
-  metas; an element carrying one rendered as hidden, which is consistent with the
-  condition evaluating false but is not proof the shape was understood.
+- An element **condition** puts its comparator INSIDE the subject's options
+  (`subject.<type>Options.comparator`). One level up is a PHP fatal that blanks the
+  whole page; so is `{"v": …}` as a `variable` subject's `dynamicCode` (a plain
+  string there). A server-condition `regexp` needs delimiters (`/./`) - `.` never
+  matches and the element silently disappears. Driven end to end on a client build;
+  references/templates-and-conditions.md
 
 ## Orient yourself in this order
 
@@ -821,6 +823,19 @@ post — `build_all.py` resets first for that reason.
   default - it is a `<span>`, a label rather than a control. Measured all three.
   `menu-link` and `wysiwyg-link` still render `<span>` without a `url`.
 - **`text` renders as `<div>` by default** — set `tagName` for `<h1>`, `<p>` and so on.
+- **`menu-link` is `width: fit-content` by default** (`.m-menu-link{display:flex;gap:4px;
+  padding:4px 8px;width:fit-content;…}`). Used as a cell of a button row or a grid -
+  a phone contact bar on `2fr 1fr 1fr` - its background hugs the text and the cell
+  stays empty around it, whatever `display` or `justify-content` you give it. Set
+  `width: 100%` on it (reported from a client build; the rule read from 1.0.10's
+  `style.css`). The same rule's `align-items:center` matters when a `menu-link`
+  wraps a whole card: set `alignItems: stretch` and `textAlign: left` on it.
+- **`customDeclarations` is all or nothing, and its unit list is short.** The
+  validator parses every declaration and drops the WHOLE block if one value fails.
+  `!important` fails, and so does any unit outside `ValidatorCustomDeclarations`'s
+  list - `dvh`, `svh`, `lvh`, `dvw`, container units: `height: 100dvh` takes every
+  other line in the block with it, silently. The structured `height` / `maxHeight`
+  fields do accept `dvh`.
 - **`youtube` renders `<mosaic-youtube><iframe>` with no `title`** - the iframe gets
   only `loading`, `src`, `allow` and an id, so an accessible name has to be added
   some other way. `youtubeUrl` is `{"v": "https://www.youtube.com/watch?v=…"}`;

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.32.0"
+    "version": "1.32.2"
   },
   "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.32.0"
+    "version": "1.32.2"
   },
   "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.32.0"
+    "version": "1.32.2"
   },
   "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.32.0"
+    "version": "1.32.2"
   },
   "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.32.0"
+    "version": "1.32.2"
   },
   "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.32.0",
+  "version": "1.32.2",
   "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/design-system.md

@@ -60,7 +60,40 @@ Three things learned the hard way:
   goes away.
 - Look up the ID in `data/variants.csv` by `name`. Several rows share a
   name (`Button` appears four times) because sub-components have their own metas — the
-  `selectors` and `parent` columns tell them apart.
+  `selectors` and `parent` columns tell them apart. `Item` is the trap: the accordion,
+  loop and list items are all `Item` and all have a parent, so "the parent-less one"
+  finds none. `build_page.py` takes a theme variant key as the catalog id, the
+  `class_name` (`m-loop-item`) or a name, and refuses a name that matches more than
+  one row.
+
+More from a client build on 1.0.10:
+
+- **`HTML` and `Body` emit `html{…}` and `body{…}`**, and `customDeclarations` works
+  on them - the place for page-wide settings that have no node.
+- **The loop pagination states work on the variants**:
+  `____loop_pagination_number--active` on `Number`,
+  `___loop_pagination_button--disabled` on `Pagination button`.
+- **Variant CSS is printed early in `<head>`.** At equal specificity, a plugin's
+  `<link>` stylesheet and a page's own `<style>` both come later and win. Moving a
+  rule from a plugin stylesheet into a variant can therefore bring back a page rule
+  the plugin had been overriding.
+- **The Gutenberg variants are scoped to block markup.** They match
+  `:is(.entry-content, .wp-block-post-content) X`, and `List` matches only
+  `ul.wp-block-list` - a list written by Rank Math's FAQ block or in raw HTML has no
+  such class and is not styled. A `wpContent` node renders
+  `.m-post-content > .wp-site-blocks > .entry-content`.
+
+## Universal classes
+
+A universal class is the theme-global class a user names (the editor's "classes"),
+committed on the master document under the key `universalClass` with
+`data: {name, label, states}` - `states` is the same structure as a variant's. A node
+takes it through `style.universalClasses`, a map `{<classID>: <classID>}` (a map to a
+universal SUB class ID applies that sub class instead; `ElementMResourceStyle.php`).
+The emitted class is the `name` (sanitized, any `m-` prefix dropped - the
+class-name grammar is in SKILL.md), and its CSS is printed only
+on a page where some node uses it. `status: "delete"` removes one - unlike a variant,
+a universal class is not catalog-backed.
 
 ## Collection variables: the design tokens
 
@@ -213,18 +246,34 @@ only the slots that differ:
                "cs-name": {"text": "…"}}}
 ```
 
-**An instance's ids are prefixed with the instance's own attrID.** The definition's
-`cs-card` becomes `cs-0-cs-card`, `cs-1-cs-card`, and so on, so the definition's
-attrID is a SUFFIX in the delivered page and `getElementById` on it finds nothing.
-Address instances with `[id$="-cs-card"]`.
+**Mosaic copies the definition's ids into every instance verbatim; `build_site.py`
+is what makes them unique.** Mosaic has no id-prefixing of its own - an element's
+id is its `attrID` (`ElementAttrID.php`), and every instance renders the
+definition's nodes with the definition's attrIDs, so two instances put every id
+into the document twice. `build_site.py`'s override pass writes an `attrID` of
+`<instance attrID>-<definition attrID>` into each instance's override node: the
+definition's `cs-card` becomes `cs-0-cs-card`, `cs-1-cs-card`, and so on, so the
+definition's attrID is a SUFFIX in the delivered page and `getElementById` on it
+finds nothing. Address instances with `[id$="-cs-card"]`.
+
+Until 1.32.1 that pass ran only for instances that HAD overrides, so an instance
+written with none - a contact block placed as-is in a footer and in a page body -
+kept the definition's ids, and a client build found every one of them twice. It runs
+for every instance now; measured on the demo, two override-less instances gave
+`ft-a-cs-card` and `ft-b-cs-card` and no duplicates. A tool other than
+`build_site.py` that writes instances has to do the same, or accept duplicate ids.
 
 Four more things a build that leans on components runs into:
 
-- **The instance element itself carries no id.** Its `attrID` exists only as that
-  prefix, so a selector aimed at the instance's own attrID finds nothing - aim at
-  `<instance>-<definition id>`. Two instances given the SAME attrID (or none) get
-  the same prefix and so duplicate every id inside; give each a distinct attrID. A
-  page with two `case-card` instances, `cs-0` and `cs-1`, measured zero duplicates.
+- **The instance element itself carries no id.** Its `attrID` exists only as the
+  prefix `build_site.py` writes, so a selector aimed at the instance's own attrID
+  finds nothing - aim at `<instance>-<definition id>`. Two instances given the SAME
+  attrID (or none) get the same prefix and so duplicate every id inside; give each a
+  distinct attrID.
+- **A loop repeats ids too, and that one is Mosaic's.** Every `loop-item` renders
+  the same attrIDs, so a list of six cards carries six of each id (reported from a
+  client build). `ElementAttrID.php` evaluates an attrID per loop item, which is the
+  hook for making them unique; that has not been measured here.
 - **A component's id is its name.** `build_site.py` derives it with
   `uuid5(COMPONENT_NAMESPACE, name)` so rebuilds update the same row; renaming the
   key in `site["components"]` therefore creates a new component and leaves the old

package/references/dialog-and-triggers.md

@@ -604,6 +604,11 @@ document. Lay the forms out by positioning the WINDOW instead, which leaves
 | corner notice | no padding | `top:90px; right:24px`, a small `max-width` |
 | full takeover | no padding | `top:0; right:0; bottom:0; left:0`, `max-width:none` |
 
+"No padding" has to be written: the host starts with the browser's own
+`dialog { padding: 1em }`, because Mosaic's `.m-modal` rule resets inset, margin and
+border but not padding. A client build measured a drawer's host at `padding:
+14.408px` - 1em of its fluid body size - with no modal variant on the page.
+
 `transform` is a structured value, so the centring pull-back is two entries
 (`translateX`, `translateY`), not a string — `references/styling.md` has the shape.
 

package/references/dynamic-content.md

@@ -191,7 +191,21 @@ value `{"v": "@LOOP('post/work_category', 1, 'term_id')"}`. A Meta Box checkbox
 `settings: {"key": "work_featured"}` and a `text` comparator
 `{"operator": "equals", "settings": {"value": "1"}}` - six posts back, in order.
 
-`orderByClauses` accepts `random`: `{"type": "random", "uuid": "<uuid>",
+`orderByClauses` is a flat list of clauses, each `{uuid, type, <type>Options:
+{settings}}` (`ValidatorOrderBy.php`), under `wpPostType<Type>Options`. Sorting by a
+post column:
+
+```json
+[{"type": "postVariable", "uuid": "<uuid>", "postVariableOptions": {"settings": {
+  "key": "post_date", "cast": "auto", "direction": "ASC"}}}]
+```
+
+**Every settings field is required, `cast` included.** The validator runs each of the
+type's fields and rejects the clause on the first missing one, and a rejected clause
+is stored as `[]` - no error, and the loop falls back to the default newest-first
+order. Reported from a client build on 1.0.10; the validator read from source.
+
+`orderByClauses` also accepts `random`: `{"type": "random", "uuid": "<uuid>",
 "randomOptions": {"settings": {}}}`, a different order on every uncached render. Under
 a page cache that is one order per cache lifetime, not per visitor.
 

package/references/styling.md

@@ -179,7 +179,9 @@ which are `SingleTransformTypeFactory` and do take `{"value": …}`.
 rewrites stored rows, and `build_page.py` still accepts the old spelling in a spec)
 accepts raw CSS text and emits it verbatim into the rule:
 `"customDeclarations": "outline: 2px dashed rgb(7,8,9);"` compiled through
-unchanged. It is the fallback for anything whose structured shape you have not pinned
+unchanged. Every value is still validated, and one bad value - `!important`, a `dvh`
+or other unit outside the validator's list - drops the whole block silently. 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`,

package/references/templates-and-conditions.md

@@ -88,11 +88,12 @@ interaction gating and form actions — four contexts, one grammar.
         "uuid": "<uuid>",
         "type": "serverCondition",
         "serverConditionOptions": {
-          "subject":    {"type": "httpGet",
-                         "httpGetOptions": {"settings": {"name": "show"}}},
-          "comparator": {"type": "text",
-                         "textOptions": {"operator": "equals",
-                                         "settings": {"value": "yes"}}}
+          "subject": {"type": "httpGet",
+                      "httpGetOptions": {
+                        "settings":   {"name": "show"},
+                        "comparator": {"type": "text",          // INSIDE <type>Options
+                                       "textOptions": {"operator": "equals",
+                                                       "settings": {"value": "yes"}}}}}
         }
       }
     ]
@@ -103,6 +104,41 @@ interaction gating and form actions — four contexts, one grammar.
 The `<id>Options` suffix is the same convention as everywhere else in Mosaic
 (`RuleTypeAbstract::getOptionsDataName()` returns `getID() . 'Options'`).
 
+**The comparator lives inside the subject's options**, beside `settings`, not beside
+`subject`. The validator reads it as `subject.<type>Options.comparator`
+(`ValidatorEvaluator.php`) and so does the evaluator (`RuleTypeAbstract.php`:
+`$subjectData->{$subjectType . 'Options'}->comparator`). Put it one level up and the
+evaluator finds no comparator and calls
+`SubjectMeta::getLocalOrGlobalComparatorMetaByID(null)`, which is a PHP fatal
+(`Undefined property $comparator`) that takes the WHOLE page down, not just the
+element. Reported from a client build on 1.0.10 and confirmed in the source; the post
+loop filters in `references/dynamic-content.md` use the same nesting.
+
+"Show only when a field has a value", as it ran on a client site on 1.0.10:
+
+```json
+{"uuid": "<uuid>", "type": "serverCondition", "serverConditionOptions": {"subject": {
+  "type": "variable", "variableOptions": {
+    "settings": {"dynamicCode": "@VAR('post/meta_x')"},
+    "comparator": {"type": "text", "textOptions": {
+      "operator": "regexp", "settings": {"value": "/./"}}}}}}}
+```
+
+- **`dynamicCode` is a plain string.** The `variable` subject hands its setting
+  straight to the evaluator; `{"v": "@VAR(…)"}` there reaches
+  `LocalContext::evaluateDynamicCodeToStringOrArray()` as a `stdClass` and is a
+  page-wide fatal. (A post loop FILTER value is the opposite: it is `{"v": …}`.)
+- **`regexp` needs its delimiters here.** `ServerConditionComparatorText` passes the
+  value to `preg_match()` as the whole pattern, so it is `/./`, not `.`. A pattern
+  without delimiters makes `preg_match` return false, which is read as "no match":
+  the element disappears on every page and nothing is reported. A post loop filter's
+  `regexp` is the opposite again - it becomes SQL `REGEXP` and takes NO delimiters
+  (`FilterSubjectPostTypes.php`).
+- Units in one group AND: `regexp /./` plus `not-contains` on the same variable is
+  "has a value and is not X".
+- Inside a `wpPostType` loop, `@VAR('<loopNamespace>/meta_x')` evaluates per item, so
+  each row shows or hides on its own field.
+
 **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.
@@ -134,9 +170,9 @@ can be an `@` expression rather than a literal — see `references/dynamic-conte
 ## 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).
+live metas endpoints. Element conditions (`node.data.conditions`) have been driven end
+to end on a client build on 1.0.10 with the shape above - the `variable` subject, the
+`text` comparator's `regexp` and `not-contains`, inside and outside a post loop. Other
+subjects are read from source only; build one, then read the row back and diff it
+against what you sent. A wrong shape is either silently dropped or a fatal on render,
+so load the page after every condition you commit.

package/tools/build_page.py

@@ -492,17 +492,25 @@ def theme_records(spec, doc, surface):
 
     classes = theme.get("variants") or theme.get("elementClasses") or {}
     if classes:
-        by_name = {}
-        for row in load_csv("variants.csv"):
-            by_name.setdefault(row["name"], []).append(row)
+        catalog = load_csv("variants.csv")
         recs = []
         for name, states in classes.items():
-            matches = by_name.get(name) or []
+            # a catalog id, a class_name (m-loop-item) or a name. Names repeat -
+            # `Item` is the accordion, loop AND list item, all three with a parent -
+            # so a name only resolves when it is the sole row, or the sole
+            # parent-less one, carrying it
+            matches = ([m for m in catalog if m["id"] == name]
+                       or [m for m in catalog if m["class_name"] == name]
+                       or [m for m in catalog if m["name"] == name])
             if not matches:
-                sys.exit("no variant named %r; see data/variants.csv" % name)
+                sys.exit("no variant %r; see data/variants.csv" % name)
+            roots = [m for m in matches if not m["parent"]]
+            if len(matches) > 1 and len(roots) != 1:
+                sys.exit("variant name %r is ambiguous; use one of: %s" % (
+                    name, ", ".join(m["class_name"] for m in matches)))
             # a fresh UUID here is accepted and then silently dropped, so the meta ID
-            # is the only thing that works - take the top-level (parent-less) one
-            top = next((m for m in matches if not m["parent"]), matches[0])
+            # is the only thing that works
+            top = roots[0] if len(matches) > 1 else matches[0]
             recs.append({"newRevisionRecord": {
                 "ID": top["id"], "parentType": "", "parentID": "", "ordering": "a0",
                 "status": "publish", "revision": "", "version": "",

package/tools/build_site.py

@@ -262,7 +262,11 @@ def apply_overrides(client, instance, key, uses, comps, envelope="templateDocume
     `strpos($type, 'component-instance')`, and strpos returns 0 for a needle at
     offset 0, so the condition is false for every instance there will ever be.
     """
-    wanted = [u for u in uses if u.get("overrides")]
+    # EVERY instance, not only the ones with overrides: this pass is also what gives
+    # each instance's inner nodes their own ids (below). Filtering on overrides left
+    # an instance without any as a verbatim copy of the definition's ids - a client
+    # build put the same component in a footer and a page body and got every id twice.
+    wanted = list(uses)
     if not wanted:
         return 0
     doc = unwrap(client.get(instance), envelope)