mosaic-headless 1.31.1 → 1.31.3

package/SKILL.md

@@ -5,7 +5,7 @@ description: |
 license: "MIT"
 metadata:
   author: "moksa (https://moksaweb.com)"
-  version: "1.31.1"
+  version: "1.31.3"
   homepage: "https://github.com/Moksa1123/mosaic-headless"
 ---
 
@@ -817,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.1"
+    "version": "1.31.3"
   },
   "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.1"
+    "version": "1.31.3"
   },
   "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.1"
+    "version": "1.31.3"
   },
   "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.1"
+    "version": "1.31.3"
   },
   "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.1"
+    "version": "1.31.3"
   },
   "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.1",
+  "version": "1.31.3",
   "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/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
@@ -108,7 +116,18 @@ fallback(…)                                                     defaulting
 attachment(2)  find_image(2)  find_link(2)  find_video(2)       media
 ```
 
-`sum`, `avg`, `concat` and `fallback` are variadic. `date()`'s timestamp argument is a
+`sum`, `avg`, `concat` and `fallback` are variadic.
+
+**`@concat` drops any argument that evaluates to `'0'`** (and `''`). Each argument is
+`strval()`-ed and appended only `if ($item)` (`EvaluatorFunctionConcat.php`), and
+`'0'` is the one non-empty string PHP calls false. So a number that can be zero must
+not be built into a sentence with `@concat`:
+`@concat('SEARCH · ', @VAR('wordpress_search/resultCount'), ' 件作品')` delivers
+`SEARCH ·  件作品` on an empty search - the count vanishes, the spaces stay. Put the
+number in its own `wysiwyg-variable` between two text runs instead; a bare
+`@VAR(…)` prints `0`. The same goes for a price, a stock count or a loop index that
+can be 0. `@fallback` has the mirror-image rule: it treats `'0'` as empty, and returns
+its fallback only if that is truthy, so `'0'` can never be the fallback. `date()`'s timestamp argument is a
 true GMT Unix timestamp — pair it with `post/publish_timestamp_gmt`, not
 `publish_timestamp`, unless you want the local-time value re-interpreted as UTC.
 
@@ -140,6 +159,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
 
 ```
@@ -184,3 +239,40 @@ The less precise side sets the precision: a date against a date-time compares th
 two days. Whatever cannot be read as a date matches **no** operator, so a typo is a
 condition that is never true rather than an error. Loop filters compare in SQL
 (`post_date_gmt` / `post_modified_gmt` as UTC, the others as the site's wall clock).
+
+## The search results page
+
+A `search.php` auto template (`references/templates-and-conditions.md`) has a
+`wordpress_search` namespace. Measured on 1.0.10, searching a term with four matches
+and one with none:
+
+| expression | 4 results | none |
+|---|---|---|
+| `@VAR('wordpress_search/resultCount')` | `4` | `0` |
+| `@VAR('wordpress_search/searchQuery')` | the term | the term |
+| `@fallback(@VAR('wordpress_search/resultCount'), 'none')` | `4` | `none` |
+| `@fallback(@VAR('wordpress_search/resultCount'), '0')` | `4` | `0` |
+
+`resultCount` is `number_format_i18n(found_posts)` - a formatted string, so `1,234`
+past a thousand, and `0` (not empty) when nothing matched. Do not wrap it in
+`@concat`: a `0` there is dropped (above), which is exactly how "the count is empty
+on a search with no results" was first reported from a client build. `@fallback` treats `''`,
+`'0'` and `'NaN'` as empty, and returns its second argument only if THAT is truthy in
+PHP, so a fallback of `'0'` can never be chosen; any other text can.
+
+The results are a loop: `loopType: "localContext"`, `loopSource:
+{"v": "@VAR('wordpress_search/results')"}` (a `@VAR`, as every loop source must be).
+**Inside it each result is `item`, unless you rename it**:
+
+| per-result expression | result |
+|---|---|
+| `@VAR('item/title')`, default namespace | the title |
+| `@VAR('post/title')`, default namespace | empty - `post` is the page's own context, and a search page has none |
+| `@VAR('post/title')` with `loopNamespace: "post"` on the loop | the title |
+
+With `loopNamespace: "post"` every per-post expression works per result - meta,
+`@LOOP('post/<taxonomy>', 1, 'term_name')`, the permalink. WordPress's own query
+arguments narrow the search (`/?s=…&post_type=work&work_category=<slug>`), so a
+filter bar is a set of `menu-link`s whose `url` is
+`{"v": "@concat('/?post_type=work&work_category=<slug>&s=', @VAR('wordpress_search/searchQuery'))"}`
+- the term survives the switch.

package/references/templates-and-conditions.md

@@ -31,11 +31,31 @@ post; `X-Mosaic-Paths` on a 406 names the paths Mosaic looked for, and `index.ph
 in all of them. Measured A/B: a URL with no template returned 406, was handled once
 the row existed, and returned to 406 when it was deleted.
 
-Two limits, both measured: `adminTemplateEditorInstance` does not list auto templates,
-and their document has no `template-internal` root - `heal()` builds that only for
-templates created through `createManualTemplate`, and committing one directly answers
-HTTP 500. So the row stops the 406 but there is no verified route to putting content
-in it.
+**On 1.0.10 an auto template is an ordinary, writable template.** Earlier releases
+measured two limits here - `adminTemplateEditorInstance` did not list auto templates,
+and their document had no `template-internal` root, so there was no route to putting
+content in one. Re-measured on 1.0.10, both are gone:
+
+```
+POST theme/<themeID>/adminTemplateEditorInstance/commit
+revisionEnvelopes.template = [{"newRevisionRecord": {
+    "ID": "<uuid you mint>", "parentType": "", "parentID": "", "ordering": "a0",
+    "status": "publish", "revision": "", "version": "", "name": "Search",
+    "masterID": "<master>", "assign": "auto", "path": "search.php",
+    "conditions": []}, "originalRevisionRecord": null}]
+```
+
+answers 200; the template's document already holds one node, the
+`template-internal` root the server created; `build_site.build_page_document()`
+writes a tree under it like any page's; and `/?s=…` renders it. The template is
+listed by `adminTemplateEditorInstance` and is deleted the same way, with
+`status: "delete"`. This is the commit the editor's own "add template" dialog sends -
+`createAutoTemplate` is the post-type case only. Any path from the hierarchy works the
+same way: `search.php`, `404.php`, `archive-<type>.php`, `taxonomy-<tax>.php`.
+
+An auto template is not in `template_assigns` - it binds by path - so a clean-up that
+deletes "templates nothing is assigned to" deletes it. Recreate it after any such
+prune.
 
 **`post/<id>` is the only resourceQuery `createManualTemplate` accepts.** The grammar in
 `ResourceQuery::create()` is just `explode('/', $s, 2)`, so anything parses - but the