mosaic-headless 1.31.0 → 1.31.2

package/SKILL.md

@@ -5,7 +5,7 @@ description: |
 license: "MIT"
 metadata:
   author: "moksa (https://moksaweb.com)"
-  version: "1.31.0"
+  version: "1.31.2"
   homepage: "https://github.com/Moksa1123/mosaic-headless"
 ---
 
@@ -788,6 +788,10 @@ post — `build_all.py` resets first for that reason.
   references/dialog-and-triggers.md
 - **`scrollDepth`'s action slot is `reached` since 1.0.10** (plus `returned`). An
   action stored under the old slot name `scrollDepth` is kept and never runs.
+- **A local-context loop's `loopSource` is `@VAR('post/<loop>')`, never `@LOOP()`.**
+  Both render on the front end; `@LOOP` there throws in the editor
+  (`_loopEvaluatorFunction is not a function`) and the canvas never finishes.
+  `build_page.py` refuses it. `@LOOP(…)` inside text is fine.
 - **A custom field is `@VAR('post/meta_<key>')`, and a multi-value one is a LOOP.**
   ACF and Meta Box both, plus bare post meta. Derived properties hang off the
   name with two underscores (`meta_k__label`, `__url`, `__id`); an ACF group is
@@ -813,6 +817,12 @@ 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.
+- **`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=…"}`;
+  `lazyLoad` adds `loading="lazy"` and there is no click-to-load facade. Sized by
+  `width`/`height: 100%` inside an `aspect-ratio: 16/9` box. `privacy` alone still
+  emits nothing (NO_OUTPUT).
 - **Eight types emit custom elements**: `<mosaic-dropdown>`, `<mosaic-navbar>`,
   `<mosaic-tabs>`, `<mosaic-accordion>`, `<mosaic-vimeo>`, `<mosaic-youtube>` and
   friends. A selector written against `div`/`nav` misses all of them.

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.31.0"
+    "version": "1.31.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.31.0"
+    "version": "1.31.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.31.0"
+    "version": "1.31.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.31.0"
+    "version": "1.31.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.31.0"
+    "version": "1.31.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.31.0",
+  "version": "1.31.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/custom-fields.md

@@ -81,13 +81,36 @@ the source on the loop node:
 ```json
 {"type": "loop",
  "data": {"loopType": "localContext",
-          "localContextOptions": {"loopSource": {"v": "@LOOP('post/loopacf_rel')"}}},
+          "localContextOptions": {"loopSource": {"v": "@VAR('post/loopacf_rel')"}}},
  "children": [{"type": "loop-items", "children": [{"type": "loop-item", "children": [
    {"type": "text", "data": {"tagName": "p"},
     "children": [{"type": "wysiwyg-variable", "data": {"dynamicCode": "@VAR('item/value__label')"}}]}
  ]}]}]}
 ```
 
+**The `loopSource` is `@VAR('<namespace>/<loop>')`, never `@LOOP(…)`.** This page
+used to show `@LOOP('post/loopacf_rel')` here, and that form breaks the editor while
+the front end renders it fine - the worst kind of split, because the page looks done:
+
+- the front end (`LoopEvaluator.php`) takes the first string argument of whatever
+  function call it is given and ignores the function's name, so `@LOOP('post/x')`
+  and `@VAR('post/x')` resolve to the same loop;
+- the editor (`evaluateLoop` in `AppMosaicEditor-bundle.js`, 1.0.10) builds its
+  expression evaluator with the loop lookup as the VARIABLE evaluator and `null` as
+  the loop evaluator, so `@VAR` resolves the loop and `@LOOP` calls `null`:
+  `TypeError: this._loopEvaluatorFunction is not a function`, the canvas renders
+  for a long time and never finishes. Mosaic's own callers write
+  `evaluateLoop("@VAR('<menu>/loop')")`.
+
+Reported from a client build (a Meta Box `image_advanced` gallery as the source):
+changing the source to `@VAR('post/loopwork_gallery')` cleared the editor error and
+the front end still rendered all 35 images. `@LOOP(…)` *inside text* goes through a
+different evaluator that is given both functions, and is fine in the editor too -
+measured on the same build: a loop item's image `alt` of
+`@concat(@VAR('post/title'), '｜', @LOOP('post/work_category', 1, 'term_name'), '作品照片 ', @VAR('item/index'))`
+opens with zero console errors and delivers `墨竹｜住宅設計作品照片 1`. The table
+above stays valid there.
+
 `loopType:"localContext"` is the built-in source that evaluates an expression in the
 page's context; the sweep's `loop` COMMIT_500 is what happens without it. The loop
 rendered exactly the rows the field holds for every family above (2, 2, 1, 1, 2, 2,

package/references/dynamic-content.md

@@ -66,6 +66,14 @@ Two different shapes for the same language, and which one applies is decided by
 property's validator chain in `data/node-properties.csv`: **`ValidatorDynamicCode`
 means a bare string, `ValidatorDynamicCodeObject` means `{"v": "…"}`**.
 
+Getting it wrong on a URL is silent and looks like a broken link rather than a broken
+expression. `menu-link`'s `url` chain is `ValidatorDynamicCodeObject → ValidatorURL →
+ValidatorUrlObject`; given a bare `"@concat('/contact/?ref=', @VAR('post/title'), '#consult')"`
+it commits without complaint and delivers
+`href="http://concat('/contact/?ref=%27…"` - the leading `@` dropped and the rest taken
+as a URL (measured on a client build on 1.0.10). As `{"v": "@concat(…)"}` it delivers the evaluated link.
+
+
 ## The variable namespace
 
 `data/dynamic-variables.csv` — 74 variables across 11 namespaces, each row carrying
@@ -140,6 +148,42 @@ one. `build_page.py` resolves it by treating a loop container as standing in for
 its parent's children: what `slider-loop-slides` accepts is what `slider-slides`
 accepts.
 
+## Filtering and ordering a post loop
+
+A `wpPostType<Type>` loop takes `filters` (the condition structure of
+`references/templates-and-conditions.md`: units in one `evaluationUnits` group are
+AND-ed, groups are OR-ed) and `orderByClauses`. The filters are evaluated in the
+context the loop sits in, so inside a single-post template `@VAR('post/…')` is the
+post being viewed. Subject IDs are built from WordPress names, camel-cased after
+every `-`, `_` or space (source: `FilterSubjectPostTypes.php`):
+
+| subject | id | operators | value |
+|---|---|---|---|
+| the posts themselves | `postType<Type>` (`postTypeWork`) | `includes` / `excludes` | a list of post ids; dynamic |
+| a taxonomy | `taxonomy<Taxonomy>` (`taxonomyWorkCategory`) | `includes` / `excludes` | term ids; dynamic |
+| a meta key | `postType<Type>PostMeta`, `settings.key` | the comparator you pick: `text`, `number`, `date` | per comparator |
+
+A dynamic filter value is `{"v": …}` - the field declares `SupportDynamic`, which the
+reader validates with `ValidatorDynamicCodeObject`. "More work in the same category,
+not this one", measured on a client build on 1.0.10:
+
+```json
+{"uuid": "<uuid>", "type": "filter", "filterOptions": {"subject": {
+  "type": "postTypeWork", "postTypeWorkOptions": {"settings": {}, "comparator": {
+    "type": "postTypeWork", "postTypeWorkOptions": {
+      "operator": "excludes", "settings": {"value": {"v": "@VAR('post/id')"}}}}}}}}
+```
+
+with a second unit in the same group on `taxonomyWorkCategory`, operator `includes`,
+value `{"v": "@LOOP('post/work_category', 1, 'term_id')"}`. A Meta Box checkbox
+(stored `"1"`) filters as subject `postTypeWorkPostMeta` with
+`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>",
+"randomOptions": {"settings": {}}}`, a different order on every uncached render. Under
+a page cache that is one order per cache lifetime, not per visitor.
+
 ## `loop-pagination`, and the key you must not use
 
 ```

package/references/failure-modes.md

@@ -476,3 +476,14 @@ rendered - server-side output was fine - but with no front-end runtime every dro
 sat open and no modal could open. `find mosaic -type d -exec chmod 775 {} +` (files
 664), matching the other plugin folders, and purge the page cache. A REST-level check
 cannot see this; only fetching an asset can.
+
+## A loop source written as `@LOOP()` renders on the front end and kills the editor
+
+`loopType: "localContext"` with `loopSource: {"v": "@LOOP('post/<loop>')"}` renders
+every row on the delivered page, and opening the page in the Mosaic editor throws
+`TypeError: this._loopEvaluatorFunction is not a function` from
+`evaluateLoop` / `createLoopContextFactory`, leaving the canvas loading. The front
+end reads the loop name out of any function call; the editor only out of `@VAR`.
+Write `@VAR('post/<loop>')`. No server-side check can see this - the page is 200 and
+complete - so it is only caught by opening the editor. Details in
+`references/custom-fields.md`.

package/tools/build_page.py

@@ -131,6 +131,19 @@ class Surface:
                 problems.append("code content contains `%s` - Mosaic's template parser reads "
                                 "it as a function call and the page renders as HTTP 500; "
                                 "write `%s (`" % (hit.group(0), hit.group(0)[:-1]))
+        # A local-context loop's source written as `@LOOP('post/x')` renders on the
+        # front end - LoopEvaluator.php reads the loop name out of any function call -
+        # and throws in the editor, whose evaluateLoop only resolves `@VAR`
+        # ("this._loopEvaluatorFunction is not a function", canvas never finishes).
+        # The page is 200 and complete, so nothing downstream of this can see it.
+        if not force:
+            opts = (node.get("data") or {}).get("localContextOptions") or {}
+            src = opts.get("loopSource")
+            code = src.get("v") if isinstance(src, dict) else src
+            if isinstance(code, str) and code.lstrip().upper().startswith("@LOOP("):
+                problems.append("loopSource %r breaks the Mosaic editor (front end renders, "
+                                "editor throws _loopEvaluatorFunction is not a function); "
+                                "write it as %r" % (code, "@VAR(" + code.lstrip()[6:]))
         # node-verification.csv measured every type UNDER A PLAIN DIV. A type that broke
         # there is not broken in general - most of them are family members that simply
         # need their own parent. So the measured verdict only applies when the parent is