mosaic-headless 1.29.1 → 1.30.0

package/README.md

@@ -67,17 +67,29 @@ below runs only when Claude follows `SKILL.md` and you approve the command:
 - **`tools/*.php`** run inside your own WordPress through `wp eval-file`. They read
   and write Mosaic's own tables and theme data on that site.
 - **`tools/mint_session.php`** creates a logged-in WordPress session and a matching
-  REST nonce for an account on *your* site. You put them in a local config file
-  (`--config sweep.json`); they are printed to your terminal and sent nowhere else.
+  REST nonce for an account on *your* site. They are printed to your terminal and
+  sent nowhere else. **Nothing here goes looking for a credential on your machine** -
+  you supply the session, one of two ways:
+  - installed as a plugin, Claude Code prompts for `Mosaic site URL`,
+    `WordPress logged-in cookie` and `wp_rest nonce`. The two credentials are
+    declared `sensitive`, so they are masked on entry and kept in your platform's
+    credential store, not in `settings.json`. Export them for a tool run as
+    `MOSAIC_SITE_URL`, `MOSAIC_REST_COOKIE` and `MOSAIC_REST_NONCE`
+  - or put them in a JSON file of your own and pass `--config <file>`, which is what
+    the examples in the skill show
+  The environment wins over the file, and with the environment set no credential
+  needs to be written to disk at all.
 - **`tools/build_site.py`, `data_upgrade.py`, `theme_zip.py`, `probe_accordion.py` and the `sweep_*.py`
   tools** call Mosaic's REST routes on the site in that config file, with that
   session, to read and write pages, components and themes. They contact only that
   site.
 - **`tools/verify_*.py`** open pages of that same site with Playwright (Chromium) or
   `urllib` and compare what was delivered with what was written.
-- **`sites/`** holds the worked example (the author's own site) as data. Its design
-  loads Google Fonts, so pages built from it make visitors' browsers fetch fonts from
-  Google, as any page using Google Fonts does.
+- **`sites/`** holds the worked example (the author's own site) as readable Python
+  modules. `python sites/_moksa.py` generates `sites/moksa.json` from them; the
+  generated file is not shipped. The design loads Google Fonts, so pages built from
+  it make visitors' browsers fetch fonts from Google, as any page using Google Fonts
+  does.
 
 The tools need Python 3 and Playwright. Nothing is downloaded at install time, and no
 data is sent to the author or any third party.

package/SKILL.md

@@ -3,8 +3,10 @@ name: "mosaic-headless"
 description: |
   Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface with `mo.py`, which joins every source table to the live sweeps so a lookup leads with the measured verdict rather than the declaration (128 node types, 191 properties, 98 style properties with 20 structured value shapes pinned down, 53 style states, 156 variants, 74 dynamic variables, 15 interaction triggers, 115 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, the design-token and element-class layers verified against compiled CSS, the @VAR() dynamic language verified against rendered output, nine designed pages built through the tables themselves, and the delivered pages re-read in Chromium at three viewports so a rule that is present, correct and still wrong cannot pass. Drives Mosaic's own theme export/import and its plugin data upgrade from outside the editor and holds the copy against the source tree for tree. Measured on Mosaic Pro 1.0.9: the modal (`<dialog>`), OpenStreetMap, the exit-intent and scroll-depth triggers, run rules and the memory actions all built on a live page and read back, and the 1.0.7 -> 1.0.8 -> 1.0.9 migrations driven from outside wp-admin.
 license: "MIT"
-author: "moksa (https://moksaweb.com)"
-version: "1.29.1"
+metadata:
+  author: "moksa (https://moksaweb.com)"
+  version: "1.30.0"
+  homepage: "https://github.com/Moksa1123/mosaic-headless"
 ---
 
 # Headless Mosaic
@@ -535,8 +537,8 @@ so the pattern is in the data, not just in this paragraph.
 | `data/dialog-verification.csv` | 19 | **driven live** - the 1.0.9 modal, its triggers, its run rules and the memory actions, each exercised in a real browser |
 | `data/dialog-form-verification.csv` | 49 | **driven live** - the same three nodes made into five FORMS (sheet, drawer, corner, takeover, gate), each re-opened at 390px and 768px; also where `pickOne` on a click turned out to be a latch rather than a lottery |
 | `data/token-verification.csv` | 15 | **driven live** - every `:root` custom property declared once, non-empty, and resolved by something on the page; a token nothing points at is a token that is not working |
-| `data/mobile-audit.csv` | 64 | **driven live** - what a sideways-scroll check cannot see: type under the legible floor, controls too small to hit, a grid that never collapsed, content escaping its box |
-| `data/component-wall-verification.csv` | 20 | **driven live** - tabs switched, an accordion opened, a form's fields and Mosaic's own honeypot, and an OpenStreetMap asserted on the coordinates it was GIVEN rather than the default it falls back to |
+| `data/mobile-audit.csv` | 65 | **driven live** - what a sideways-scroll check cannot see: type under the legible floor, controls too small to hit, a grid that never collapsed, content escaping its box |
+| `data/component-wall-verification.csv` | 26 | **driven live** - tabs switched, an accordion opened, a form's fields and Mosaic's own honeypot, and an OpenStreetMap asserted on the coordinates it was GIVEN rather than the default it falls back to |
 | `data/form-surface-verification.csv` | 15 | **driven live** - every field type Mosaic ships in one form: select with labelled options, radio and checkbox groups, file upload, and the browser's own validation refusing an empty submit |
 | `data/content-loop-verification.csv` | 12 | **driven live** - a slider, a tab bar, a list and a paginated archive whose children all come from one authored template repeated per post; the pagination is clicked and the rows asserted to CHANGE |
 | `data/custom-fields-verification.csv` | 62 | **rendered live** - ACF and Meta Box fields of every common type read back through `@VAR` / `@LOOP` off the delivered page, loops included |
@@ -822,8 +824,41 @@ post — `build_all.py` resets first for that reason.
 | `copy_styles.py` | push one node's style onto others, by attrID or prefix |
 | `bootstrap_probe_theme.php` | a licence-free scratch theme |
 | `mint_session.php` | a matching cookie + `wp_rest` nonce from WP-CLI |
+| `mosaic_config.py` | the one place a tool resolves the site URL and session - environment (`MOSAIC_SITE_URL` / `MOSAIC_REST_COOKIE` / `MOSAIC_REST_NONCE`) over `--config` file, so a credential never has to be written to disk |
 | `check_tables.py` | re-extract all eleven source-derived tables and diff them against the shipped ones - the check for a table that is not wrong but STALE, which nothing else can see |
 
+## The session, and where it comes from
+
+Every tool that writes needs a site URL, a logged-in cookie and a matching
+`wp_rest` nonce. **Never go looking for them on the user's machine** - not in a
+browser profile, not in `wp-config.php`, not in a dotfile. Ask, or have the user
+mint them:
+
+```bash
+wp eval-file tools/mint_session.php        # on the server, prints COOKIE= and NONCE=
+```
+
+Then either export them, which keeps the credential off disk entirely:
+
+```bash
+export MOSAIC_SITE_URL=https://example.com
+export MOSAIC_REST_COOKIE='wordpress_logged_in_…=…'
+export MOSAIC_REST_NONCE=0a0326da96
+python tools/build_site.py --site sites/moksa.json
+```
+
+or pass a JSON file the user wrote:
+
+```bash
+python tools/build_site.py --config sweep.json --site sites/moksa.json
+```
+
+`tools/mosaic_config.py` is the single place that resolves this, and the
+environment wins over the file. Installed as a plugin, the three values are
+`userConfig` options - the cookie and the nonce `sensitive: true`, so Claude Code
+masks them and stores them in the platform credential store rather than in
+`settings.json`.
+
 ## Regenerating everything
 
 ```bash
@@ -848,6 +883,10 @@ python tools/capture_live.py             data/          # from data/raw/*.json +
 python tools/sweep_node_types.py --config sweep.json --setup
 python tools/sweep_node_types.py --config sweep.json --sweep --edition all
 python tools/sweep_properties.py --config sweep.json
+# `sites/moksa.json` is GENERATED - the package ships the readable modules it
+# comes from, not 2MB of built output. Regenerate it before anything reads it:
+python sites/_moksa.py
+
 python tools/verify_rwd.py --config sweep.json --site sites/moksa.json --csv data/rwd-verification.csv
 python tools/verify_browser.py --config sweep.json --site sites/moksa.json \
     --csv data/browser-verification.csv --audit data/design-audit.csv

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.29.1"
+    "version": "1.30.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.29.1"
+    "version": "1.30.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.29.1"
+    "version": "1.30.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.29.1"
+    "version": "1.30.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.29.1"
+    "version": "1.30.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/data/component-wall-verification.csv

@@ -10,6 +10,12 @@ FORM/required,PASS,required is set on 3 of them
 FORM/honeypot,PASS,"Mosaic adds its own spam trap: ['mosaic_hp_url', 'mosaic_hp_ts']"
 FORM/option_labels,SKIPPED,no select on this form
 FORM/required_blocks,PASS,"empty form reports invalid: ['name', 'email', 'message']"
+NAVBAR/wide,PASS,"at this width the links are shown and the toggle is not (nav=True toggle=False, 4 links)"
+NAVBAR/narrow,PASS,below buttonBreakpoint it collapses behind the toggle (dropdown-mode=True)
+NAVBAR/toggle_opens,PASS,clicking it reveals the links
+MEDIA/image_loaded,PASS,"1200px wide, natural 2500px"
+MEDIA/icons_inline,PASS,"3 inline <svg> - `icon` takes RAW SVG in its `svg` property, not a URL or a library name"
+WORDPRESS/shortcode_ran,PASS,"3 items from the shortcode - this is WooCommerce's own output, not a reimplementation"
 MULTISTEP,SKIPPED,not on this page
 COMPONENT/instances,PASS,"3 instances: ['cs-0-cs-card', 'cs-1-cs-card', 'cs-2-cs-card']"
 COMPONENT/one_definition,PASS,"all share the generated class ['_fm'] - one definition, not 3 copies"

package/data/mobile-audit.csv

@@ -1,7 +1,7 @@
 path,width,finding,element,detail
-forms/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 components/,390,GRID_NOT_COLLAPSED,cp-tabs-menu,2 columns at 390px
 components/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
+forms/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 content/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 dialogs/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 sliders/,390,SMALL_TARGET,sl-main-nav-dot,34x28: 
@@ -18,10 +18,11 @@ sliders/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 tokens/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 dynamic/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
 conversion/,390,GRID_NOT_COLLAPSED,mk-f-links,2 columns at 390px
-forms/,768,LONG_MEASURE,m-text,59 chars/line
-forms/,768,LONG_MEASURE,m-text,59 chars/line
 components/,768,LONG_MEASURE,m-text,44 chars/line
 components/,768,LONG_MEASURE,m-text,56 chars/line
+components/,768,LONG_MEASURE,m-text,56 chars/line
+forms/,768,LONG_MEASURE,m-text,59 chars/line
+forms/,768,LONG_MEASURE,m-text,59 chars/line
 content/,768,LONG_MEASURE,m-text,43 chars/line
 content/,768,LONG_MEASURE,m-text,58 chars/line
 dialogs/,768,LONG_MEASURE,m-text,46 chars/line

package/data/navigation-verification.csv

@@ -1,18 +1,18 @@
 check,result,detail
 FRONT_PAGE,PASS,"HTTP 200, 240832 bytes"
 MENU_IS_LINKS,PASS,1 real <a href> in #mk-nav
-NAV 首頁,PASS,"/ -> HTTP 200, 240832 bytes"
-PAGE moksa,PASS,"HTTP 200, 240833 bytes"
-PAGE my-account,PASS,"HTTP 200, 101037 bytes"
+NAV 首頁,PASS,"/ -> HTTP 200, 240834 bytes"
+PAGE moksa,PASS,"HTTP 200, 240832 bytes"
+PAGE my-account,PASS,"HTTP 200, 101036 bytes"
 PAGE intro,PASS,"HTTP 200, 134746 bytes"
 PAGE content,PASS,"HTTP 200, 102378 bytes"
 PAGE forms,PASS,"HTTP 200, 126731 bytes"
-PAGE components,PASS,"HTTP 200, 119522 bytes"
-PAGE conversion,PASS,"HTTP 200, 103205 bytes"
-PAGE dynamic,PASS,"HTTP 200, 112622 bytes"
-PAGE tokens,PASS,"HTTP 200, 125794 bytes"
-PAGE sliders,PASS,"HTTP 200, 151809 bytes"
-PAGE dialogs,PASS,"HTTP 200, 207347 bytes"
+PAGE components,PASS,"HTTP 200, 135123 bytes"
+PAGE conversion,PASS,"HTTP 200, 103204 bytes"
+PAGE dynamic,PASS,"HTTP 200, 113003 bytes"
+PAGE tokens,PASS,"HTTP 200, 125413 bytes"
+PAGE sliders,PASS,"HTTP 200, 152191 bytes"
+PAGE dialogs,PASS,"HTTP 200, 207349 bytes"
 ANCHORS moksa,PASS,every in-page link resolves
 ANCHORS my-account,PASS,every in-page link resolves
 ANCHORS intro,PASS,every in-page link resolves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.29.1",
+  "version": "1.30.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",
@@ -35,7 +35,14 @@
     "data/*.csv",
     "references/",
     "sites/_moksa.py",
-    "sites/moksa.json",
+    "sites/_components.py",
+    "sites/_content.py",
+    "sites/_conversion.py",
+    "sites/_dialogs.py",
+    "sites/_dynamic.py",
+    "sites/_forms.py",
+    "sites/_sliders.py",
+    "sites/_tokens.py",
     "tools/*.py",
     "tools/*.php",
     "SKILL.md",

package/references/placement.md

@@ -153,3 +153,34 @@ source the column was derived from rather than the one it was convenient to read
   an `*ElementMResourceFactory.php`; every extractor walked
   `*ElementTypeFactory.php` only, so they were absent from the catalog and a
   fieldset appeared to have no inner structure.
+
+## navbar, media and the two WordPress nodes
+
+```
+navbar            animation (none|fade|fadeDown|fadeUp|scaleDown|flipDown)
+                  buttonBreakpoint (a breakpoint id, or "none")
+                  disableScroll
+  navbar-toggle   the button that appears BELOW the breakpoint
+  navigation      the links, which collapse behind it
+```
+
+Measured: above `buttonBreakpoint` the links are shown and the toggle is hidden;
+below it the host gains `dropdown-mode`, the links disappear, and clicking the
+toggle adds `dropdown--opened` and reveals them. The breakpoint is named with the
+same ids the style system uses (`_t`, `_m`).
+
+**`icon` takes RAW SVG** in its `svg` property — not a URL, not an icon-library
+name. `autoScale` makes it follow the element's box, and `currentColor` inside the
+SVG picks up the node's `color`.
+
+**`image.image` takes the attachment protocol**:
+`wp-attachment://image/<id>/full/<uploads-relative path>`. The last segment is
+relative to the uploads directory and a full path is silently doubled; a plain URL
+also works and simply skips the width/height resolution.
+
+**`wpShortcode.shortcode`** runs a real shortcode — `[products limit="3"]` renders
+WooCommerce's own markup, not a reimplementation — and **`wpContent.content`** is a
+`ValidatorDynamicCodeObject`, so it takes the `{"v": "…"}` form; a bare string is
+dropped and the block renders empty. Its default is `@VAR('post/content')`, which
+is why the node usually sits inside a loop and needs nothing written at all, and
+the property is gated on the `unfiltered_html` capability.

package/references/responsive.md

@@ -136,6 +136,7 @@ mechanical check reads what the spec declared and what the site actually served,
 compares them key by key:
 
 ```bash
+python sites/_moksa.py          # moksa.json is generated, not shipped
 python tools/verify_rwd.py --config sweep.json --site sites/moksa.json --csv rwd.csv
 ```
 

package/scripts/check-release.mjs

@@ -35,7 +35,11 @@ const pkg = JSON.parse(read("package.json"));
 const want = pkg.version;
 
 const skill = read("SKILL.md");
-const fmVersion = /^version:\s*"?([^"\n]+)"?\s*$/m.exec(skill.split("---")[1] || "");
+// `version` sits under `metadata:`, hence the leading indent. The Agent Skills
+// spec allows only allowed-tools / compatibility / description / license /
+// metadata / name at the top level, and a stray `version` there does not get
+// ignored - it fails the upload.
+const fmVersion = /^\s+version:\s*"?([^"\n]+)"?\s*$/m.exec(skill.split("---")[1] || "");
 if (!fmVersion) fail("SKILL.md frontmatter has no version:");
 else if (fmVersion[1].trim() !== want)
   fail(`SKILL.md version ${fmVersion[1].trim()} != package.json ${want}`);
@@ -101,8 +105,8 @@ const counts = {
   "data/dialog-verification.csv": 19,
   "data/slider-verification.csv": 30,
   "data/token-verification.csv": 15,
-  "data/mobile-audit.csv": 64,
-  "data/component-wall-verification.csv": 20,
+  "data/mobile-audit.csv": 65,
+  "data/component-wall-verification.csv": 26,
   "data/form-surface-verification.csv": 15,
   "data/content-loop-verification.csv": 12,
   "data/navigation-verification.csv": 36,

package/scripts/sync-version.mjs

@@ -38,12 +38,13 @@ const head = skill.slice(0, end);
 const rest = skill.slice(end);
 // "already correct" and "line missing" are different answers, and conflating them
 // made this exit 1 on a release where the version happened to match already.
-const VERSION_LINE = /^version:\s*"?[^"\n]*"?\s*$/m;
+// indented: it lives under `metadata:` (see check-release.mjs for why)
+const VERSION_LINE = /^(\s+)version:\s*"?[^"\n]*"?\s*$/m;
 if (!VERSION_LINE.test(head)) {
   console.error("SKILL.md frontmatter has no version: line to update");
   process.exit(1);
 }
-const next = head.replace(VERSION_LINE, `version: "${v}"`);
+const next = head.replace(VERSION_LINE, (_m, indent) => `${indent}version: "${v}"`);
 if (next !== head) {
   fs.writeFileSync(skillPath, next + rest);
   touched.push("SKILL.md");