mosaic-headless 1.32.1 → 1.32.2

package/SKILL.md

@@ -5,7 +5,7 @@ description: |
 license: "MIT"
 metadata:
   author: "moksa (https://moksaweb.com)"
-  version: "1.32.1"
+  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.1"
+    "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.1"
+    "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.1"
+    "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.1"
+    "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.1"
+    "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.1",
+  "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
 

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": "",