mosaic-headless 1.31.2 → 1.32.0

package/SKILL.md

@@ -5,7 +5,7 @@ description: |
 license: "MIT"
 metadata:
   author: "moksa (https://moksaweb.com)"
-  version: "1.31.2"
+  version: "1.32.0"
   homepage: "https://github.com/Moksa1123/mosaic-headless"
 ---
 
@@ -529,6 +529,10 @@ so the pattern is in the data, not just in this paragraph.
 15. `references/upgrading.md` — what a plugin update does to the data and to the
    delivered page, measured on 1.0.7 -> 1.0.8; how to drive the migration and what
    to re-verify afterwards.
+16. `references/server-thumbnails.md` — Mosaic's headless-Chrome thumbnails on a host
+   without root: where Mosaic looks for the binary, a no-root install, and the two
+   things (PHP-FPM's disabled functions, a setting decided once) that make a working
+   install look broken.
 
 ## The data files
 

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.2"
+    "version": "1.32.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.31.2"
+    "version": "1.32.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.31.2"
+    "version": "1.32.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.31.2"
+    "version": "1.32.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.31.2"
+    "version": "1.32.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/package.json

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

@@ -218,6 +218,33 @@ only the slots that differ:
 attrID is a SUFFIX in the delivered page and `getElementById` on it finds nothing.
 Address instances with `[id$="-cs-card"]`.
 
+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.
+- **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
+  one behind.
+- **An expression inside a definition is evaluated where the instance is.** A link
+  `{"v": "@concat('/contact/?ref=', @VAR('post/title'), '#consult')"}` inside a
+  component, placed in a single-post template, carries THAT post's title (reported
+  from a client build on 1.0.10).
+- **The header and footer can hold instances.** `build_site.py` commits the theme's
+  design tokens first, builds the components, and only then writes the shell's
+  header and footer - with components resolved and overrides applied in the master,
+  as on a page. Measured: a footer instance with one override rendered with its
+  prefixed ids and the overridden text. (Before this order, a component in the shell
+  was impossible: its styles name tokens the shell commit had not made yet.)
+
+What this is good for on a client site: anything repeated in several places that
+the client should be able to change themselves - an office address block, a contact
+bar, opening hours. Make it a component and it is edited once, in Mosaic's
+Components panel, and every page follows, with no "site settings" plugin page.
+
 The claim worth verifying is not that three cards rendered. It is that they are the
 same definition, and the evidence is in the class: all three carry the identical
 generated token (`_fm` here) while their text differs. Three copy-pasted sections

package/references/dynamic-content.md

@@ -116,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.
 
@@ -228,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/server-thumbnails.md

@@ -0,0 +1,84 @@
+# Server-side thumbnails without root
+
+Mosaic can capture page and component thumbnails on the server with headless
+Chrome. Its documentation installs Chrome with `apt` as root, which a managed host
+(Cloudways and the like) does not allow. The procedure below needs no root. It was
+worked through end to end on a live client site (Debian 12, Mosaic 1.0.10) - Mosaic's
+"generate thumbnails" completed for every template - and each step is checked
+against the plugin source.
+
+## How Mosaic finds Chrome
+
+`Mosaic/Common/ScreenshotChrome.php`:
+
+- the binary is, in order: the constant **`MOSAIC_CHROME_BINARY`**, then whatever the
+  filter **`mosaic_chrome_binary_path`** returns, then chrome-php's `AutoDiscover`,
+  which also honours a `CHROME_PATH` server variable;
+- `isChromiumAvailable()` checks only that `shell_exec`, `proc_open` and
+  `is_executable` exist and that the binary is executable;
+- launch options pass through **`mosaic_screenshot_chrome_options`**, and Mosaic
+  already runs with `noSandbox`.
+
+So anything executable at a path you name will do, including a wrapper script.
+
+## The procedure
+
+**1. Check from a web request, never from WP-CLI.** PHP-FPM and the CLI have
+different `disable_functions`: on the client host FPM disabled `proc_open`,
+`proc_close`, `proc_terminate` and `shell_exec` while the CLI did not, so `wp eval`
+said Chrome was available and every web request said it was not. Put a temporary
+PHP file in the web root that loads `wp-load.php` and prints
+`function_exists('proc_open')`, `function_exists('shell_exec')` and
+`\Mosaic\Common\ScreenshotChrome::isChromiumAvailable()`; fetch it once; delete it
+straight away.
+
+**2. Install Chrome as the site's own user**, in a directory the app owns outside
+the web root (e.g. the app's `private_html/chrome`):
+
+- download `chrome-headless-shell` from Chrome for Testing - the version is in
+  `https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_STABLE`, the
+  archive at
+  `https://storage.googleapis.com/chrome-for-testing-public/<version>/linux64/chrome-headless-shell-linux64.zip`;
+- `ldd chrome-headless-shell | grep "not found"` - on the client host:
+  `libnspr4`, `libnss3`, `libnssutil3`, `libatk-1.0`, `libatk-bridge-2.0`,
+  `libXcomposite`, `libXdamage`, `libatspi`;
+- `apt-get download libnspr4 libnss3 libatk1.0-0 libatk-bridge2.0-0 libxcomposite1
+  libxdamage1 libatspi2.0-0` (no root needed), unpack each with `dpkg-deb -x`, and
+  copy the `*.so*` files into `chrome/lib`; repeat `ldd` until nothing is missing;
+- a wrapper `chrome/chrome`, mode 755, that sets `LD_LIBRARY_PATH` to `chrome/lib`
+  and `exec`s `chrome-headless-shell "$@"`.
+
+CJK text needs a CJK font the system already has (`fc-list :lang=zh`); that host's
+Droid Sans Fallback was enough.
+
+**3. Point Mosaic at the wrapper**:
+`wp config set MOSAIC_CHROME_BINARY /path/to/chrome/chrome --type=constant`.
+
+**4. Let PHP-FPM run it.** Remove exactly `proc_open`, `proc_close`, `proc_terminate`
+and `shell_exec` from the app's `php_admin_value[disable_functions]` and keep the rest.
+On Cloudways that is Application Settings → PHP-FPM Settings, or the API's
+`app_fpm_settings_update` (which takes the whole settings block, base64-encoded);
+either way it changes only that app. chrome-php and symfony/process use
+`proc_open` / `proc_close` / `proc_terminate` / `proc_get_status`; Mosaic's own
+detection uses `shell_exec`.
+
+**5. Repeat step 1.** `isChromiumAvailable()` from the web request must now be true.
+
+**6. Turn the setting on by hand.** `serverSideThumbnailRender` is stored the first
+time Mosaic reads its settings, as whatever `isChromiumAvailable()` said then, and is
+never re-evaluated (`MosaicSettingsMResource.php`). Reload Mosaic → Settings: the
+"Server-side thumbnail rendering" switch appears in the same group as "Load scripts
+inline" and "WordPress emoji support" - only once Chrome is available - so switch it
+on and save.
+
+**7. Let the capture past a full-screen entrance.** A page with an entrance veil or
+overlay is photographed as the veil: the client's homepage came out as a single flat
+colour, a 760-byte JPEG. Have the front end drop the veil when
+`/HeadlessChrome/.test(navigator.userAgent)` or `window.self !== window.top`. A
+Playwright check of that entrance then needs a context whose user agent does not
+contain `HeadlessChrome`, or it measures the veil-less page.
+
+**8. Generate the thumbnails** from Mosaic. A 600x338 capture took about 2.6s.
+
+Steps 2-4 belong to the app, not the site: a new server or a cloned app needs them
+again; moving the same app to another domain does not.

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

package/tools/build_site.py

@@ -109,19 +109,46 @@ def build_shell(client, cfg, site, surface):
 
     VAR_IDS.clear()
     payload = theme_records(site, doc, surface)
-
-    records = []
+    if payload:
+        commit(client, instance, doc, payload, "theme")
+    print("shell master=%s  theme=%s" % (master_id[:8], ", ".join(sorted(payload)) or "-"))
+    return master_id, header_div["ID"], footer_div["ID"]
+
+
+def fill_shell(client, cfg, site, surface, master_id, header_id, footer_id, comps):
+    """Write the header and footer into the master - AFTER the components exist.
+
+    The shell used to be one commit with the theme, which made a component in the
+    header or footer impossible: a component's styles name design tokens, the tokens
+    are committed by the shell, so components had to be built after it, and by then
+    the shell was already written. The theme now goes first (build_shell), the
+    components next, and the regions last, with components resolved and their
+    overrides written into the master exactly as a page's are into its template.
+    The workaround this replaces - commit an empty shell, then a second real one -
+    leaves an extra master behind on every build."""
+    instance = "masterDocumentInstance/%s" % master_id
+    key = "node/master/%s" % master_id
     shell = site.get("shell") or {}
-    if shell.get("header"):
-        records += flatten(shell["header"], header_div["ID"], master_id, surface, False, parent_type="div")
-    if shell.get("footer"):
-        records += flatten(shell["footer"], footer_div["ID"], master_id, surface, False, parent_type="div")
-    if records:
-        payload[key] = [{"newRevisionRecord": r, "originalRevisionRecord": None} for r in records]
-    commit(client, instance, doc, payload, "shell")
-    print("shell master=%s  header+footer nodes=%d  theme=%s" % (
-        master_id[:8], len(records), ", ".join(sorted(payload)) or "-"))
-    return master_id
+    COMPONENT_USES.clear()
+    records = []
+    for region, parent in (("header", header_id), ("footer", footer_id)):
+        tree = shell.get(region)
+        if not tree:
+            continue
+        if comps:
+            tree = resolve_components(tree, comps)
+        records += flatten(tree, parent, master_id, surface, False, parent_type="div")
+    if not records:
+        return 0
+    uses = list(COMPONENT_USES)
+    doc = unwrap(client.get(instance), "masterDocumentInstance")
+    commit(client, instance, doc, {key: [{"newRevisionRecord": r, "originalRevisionRecord": None}
+                                         for r in records]}, "shell regions")
+    done = apply_overrides(client, instance, key, uses, comps,
+                           envelope="masterDocumentInstance") if (comps and uses) else 0
+    print("shell header+footer nodes=%d  component instances=%d  overrides=%d"
+          % (len(records), len(uses), done))
+    return len(records)
 
 
 # A component's row id is derived from its NAME, for the same reason a design
@@ -224,7 +251,7 @@ def ensure_components(client, cfg, site, surface):
     return out
 
 
-def apply_overrides(client, instance, key, uses, comps):
+def apply_overrides(client, instance, key, uses, comps, envelope="templateDocumentInstance"):
     """Second pass: write each instance's own content into the override nodes.
 
     Mosaic materialises one override node per component node per instance - node,
@@ -238,7 +265,7 @@ def apply_overrides(client, instance, key, uses, comps):
     wanted = [u for u in uses if u.get("overrides")]
     if not wanted:
         return 0
-    doc = unwrap(client.get(instance), "templateDocumentInstance")
+    doc = unwrap(client.get(instance), envelope)
     by_attr = {(n.get("data") or {}).get("attrID"): n for n in doc[key]}
     revisions = []
     for use in wanted:
@@ -387,8 +414,9 @@ def main():
     # AFTER the shell, not before: build_shell is what commits the theme's design
     # tokens and fills VAR_IDS, and a component that uses one cannot be flattened
     # until the token it names exists.
-    master_id = build_shell(client, cfg, site, surface)
+    master_id, header_id, footer_id = build_shell(client, cfg, site, surface)
     comps = ensure_components(client, cfg, site, surface)
+    fill_shell(client, cfg, site, surface, master_id, header_id, footer_id, comps)
 
     for page in site["pages"]:
         template_id = bind_page(client, cfg, master_id, page["slug"], page["post_id"])