mosaic-headless 1.18.0 → 1.19.0

package/README.ja.md

@@ -159,6 +159,7 @@ commit の成功はページが動く証拠ではないし、正しいスタイ
 | **テーマの書き出し／読み込み** | 経路は二つ、どちらも往復検証済み。`theme_export.php` は WP-CLI で行を JSON として移し、id は不変。`theme_zip.py` は Mosaic **自身**の ZIP 書き出し／読み込みを駆動 — 読み込みは `--activate` を付けない限りテストモードに入る、既定がライブサイトの切り替えだからだ — **22 項目**でコピーを元とツリー単位で突き合わせる |
 | **スキル自身** | `claude plugin eval .` — ユーザーが実際に尋ねる 5 問を各 3 回、スキルあり／なしの 2 腕、1 回ごとに LLM 審査 3 名。**あり：5 問すべて 1.00。なし：5 問すべて 0.00。** ベースラインの最善の回答は回答拒否だった |
 | **ライブ計測** | REST ルート 114、variant 152、条件サブジェクト 59、23 テーブル / 210 カラム |
+| **カスタムフィールド** | ACF と Meta Box、1 ページに 40 フィールド、`@VAR` / `@LOOP` で配信 HTML から読み戻し：62 のうち 59 が解決、3 つの空は理由付き；複数値フィールドのループはフィールドの行数どおりに描画。`tools/list_fields.php` が Mosaic の実際の登録名を出す |
 | **ライブ更新** | 1.0.7 → 1.0.8 をプラグイン自身の milestone ルートで wp-admin の外から駆動：6 milestone、4 テーブル改名、出力クラス名は全部変わり、`customStyles` は全部書き換え — その結果に対して上の計測をすべて再実行 |
 
 `SKIPPED`、`NO_HOST`、`INCONCLUSIVE` は合格率に決して繰り込まない。自らの盲点を成功として
@@ -237,6 +238,7 @@ loop grid、フォーム、カウントダウン、サードパーティ addon
 | `verify_intro.py` / `verify_loop.py` | 「終わる」ロードアニメーション；ループし、何も隠さず、開く常時アニメーション |
 | `theme_export.php` / `theme_import.php` | テーマ全体を JSON 行として WP-CLI で移動、id は不変 |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic 自身の ZIP 書き出し／読み込みをエディタの外から駆動、コピーを元とツリー単位で照合、ライブテーマを拒否する完全削除 |
+| `list_fields.php` | ある投稿のカスタムフィールドが登録する `@VAR` / `@LOOP` 名をすべて、値付きで |
 | `data_upgrade.py` | プラグイン更新後、Mosaic のデータ移行を自身の milestone ルートで実行 — 終わるまでエディタ API は存在しない |
 | `sweep_*.py` / `probe_*.py` | 表を作った計測器そのもの |
 | `bootstrap_probe_theme.php` / `mint_session.php` | ライセンス不要の実験用テーマと、WP-CLI から作る REST セッション |

package/README.ko.md

@@ -155,6 +155,7 @@ commit 성공은 페이지가 동작한다는 증거가 아니고, 올바른 스
 | **테마 내보내기/가져오기** | 두 경로, 모두 왕복 검증. `theme_export.php`는 WP-CLI로 행을 JSON으로 옮기며 id는 그대로. `theme_zip.py`는 Mosaic **자체**의 ZIP 내보내기/가져오기를 구동 — 가져오기는 `--activate`가 없으면 테스트 모드에 놓이는데, 기본값이 라이브 사이트 전환이기 때문이다 — **22개 검사**로 사본을 원본과 트리 단위로 대조 |
 | **스킬 자체** | `claude plugin eval .` — 사용자가 실제로 묻는 5문항을 각 3회, 스킬 있음/없음 두 팔로, 매회 LLM 심사 3명. **있음: 5문항 모두 1.00. 없음: 5문항 모두 0.00.** 베이스라인의 최선은 답변 거부였다 |
 | **라이브 측정** | REST 라우트 114, variant 152, 조건 subject 59, 23 테이블 / 210 컬럼 |
+| **커스텀 필드** | ACF와 Meta Box, 한 페이지에 40개 필드, `@VAR` / `@LOOP`로 전달된 HTML에서 읽어냄: 62개 중 59개 해석, 빈 3개는 이유 있음; 다중값 필드 루프는 필드의 행 수 그대로 렌더링. `tools/list_fields.php`가 Mosaic이 실제 등록하는 이름을 출력 |
 | **라이브 업그레이드** | 1.0.7 → 1.0.8을 플러그인 자체 milestone 라우트로 wp-admin 밖에서 구동: 6 milestone, 테이블 4개 이름 변경, 출력 클래스 이름 전부 변경, `customStyles` 전부 재작성 — 그 결과 위에서 위의 측정을 전부 다시 실행 |
 
 `SKIPPED`, `NO_HOST`, `INCONCLUSIVE`는 결코 합격률에 섞지 않는다. 자기 사각지대를 성공으로
@@ -231,6 +232,7 @@ loop grid, 폼, 카운트다운, 서드파티 addon — 은 동적이라 될 노
 | `verify_intro.py` / `verify_loop.py` | "끝나는" 로드 애니메이션; 루프하고, 아무것도 가리지 않고, 열리는 상시 애니메이션 |
 | `theme_export.php` / `theme_import.php` | 테마 전체를 JSON 행으로 WP-CLI를 통해 이동, id 그대로 |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic 자체 ZIP 내보내기/가져오기를 에디터 밖에서 구동, 사본을 원본과 트리 단위로 대조, 라이브 테마를 거부하는 깨끗한 삭제 |
+| `list_fields.php` | 한 글의 커스텀 필드가 등록하는 모든 `@VAR` / `@LOOP` 이름을 값과 함께 |
 | `data_upgrade.py` | 플러그인 업데이트 후 Mosaic의 데이터 이관을 자체 milestone 라우트로 실행 — 끝나기 전까지 에디터 API는 존재하지 않는다 |
 | `sweep_*.py` / `probe_*.py` | 표를 만든 계측기 그 자체 |
 | `bootstrap_probe_theme.php` / `mint_session.php` | 라이선스 없는 실험용 테마와 WP-CLI에서 만드는 REST 세션 |

package/README.md

@@ -164,6 +164,7 @@ factories, so Pro types register and render regardless.
 | **theme export/import** | two paths, both round-tripped. `theme_export.php` moves rows as JSON over WP-CLI, ids intact. `theme_zip.py` drives Mosaic's **own** ZIP export/import — import lands in test mode unless told `--activate`, because the default is to switch the live site — and **22 checks** hold the copy against the source tree for tree |
 | **the skill itself** | `claude plugin eval .` — five cases a user would ask, three runs each, with and without the skill loaded, three LLM judges a run. **With: 1.00 on all five. Without: 0.00 on all five.** The baseline's best answer was to refuse |
 | **measured live** | 114 REST routes, 152 variants, 59 condition subjects, 23 tables / 210 columns |
+| **custom fields** | ACF and Meta Box, forty fields on a page, read back through `@VAR` / `@LOOP` off the delivered HTML: 59 of 62 resolve, 3 empties explained; loops over multi-value fields rendered exactly the field's rows. `tools/list_fields.php` prints the names Mosaic actually registers |
 | **upgraded live** | 1.0.7 -> 1.0.8 over the plugin's own milestone route, from outside wp-admin: 6 milestones, four tables renamed, every emitted class name changed, every `customStyles` rewritten - then every sweep above re-run on the result |
 
 `SKIPPED`, `NO_HOST` and `INCONCLUSIVE` are never folded into a pass rate. A sweep
@@ -246,6 +247,7 @@ and heading level — and it earned its place at once: it caught the converter l
 | `verify_intro.py` / `verify_loop.py` | a page-load sequence that ENDS; a perpetual one that loops, hides nothing, and opens |
 | `theme_export.php` / `theme_import.php` | a whole theme as JSON rows over WP-CLI, ids intact |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic's own ZIP export/import from outside the editor, the copy held against the source, and a clean delete that refuses the live theme |
+| `list_fields.php` | every `@VAR` / `@LOOP` name a post's custom fields register, with values |
 | `data_upgrade.py` | after a plugin update, Mosaic's data migration over its own milestone route - the editor API is gone until it runs |
 | `sweep_*.py` / `probe_*.py` | the instruments the tables were made with |
 | `bootstrap_probe_theme.php` / `mint_session.php` | a licence-free scratch theme and a REST session from WP-CLI |

package/README.zh-TW.md

@@ -148,6 +148,7 @@ commit 成功不代表頁面能用，樣式表正確也不代表。這裡每個
 | **主題匯出／匯入** | 兩條路徑，都來回驗證過。`theme_export.php` 用 WP-CLI 把資料列搬成 JSON、ID 不變。`theme_zip.py` 驅動 Mosaic **自己**的 ZIP 匯出匯入——匯入預設進 test mode，要 `--activate` 才上線，因為它的預設是直接切換 live 站——**22 項檢查**逐表、逐樹比對副本與來源 |
 | **技能本身** | `claude plugin eval .`——五個使用者真的會問的問題，各跑三次，有載技能和沒載各一臂，每次三個 LLM 裁判。**有：五題全 1.00。沒有：五題全 0.00。** 基準線最好的回答是拒答 |
 | **線上量測** | 114 條 REST 路由、152 個 variant、59 個條件主體、23 張表 / 210 個欄位 |
+| **自訂欄位** | ACF 與 Meta Box，一頁四十個欄位，透過 `@VAR` / `@LOOP` 從送達的 HTML 讀回：62 個裡 59 個解析正確、3 個空值有解釋；多值欄位的迴圈剛好渲染出欄位的列數。`tools/list_fields.php` 列出 Mosaic 真正註冊的名字 |
 | **線上升級** | 1.0.7 → 1.0.8 走外掛自己的 milestone 路由、在 wp-admin 之外驅動：6 個 milestone、四張表改名、每個輸出 class 名稱都變、每個 `customStyles` 都重寫——然後上面每一項掃描在結果上重跑 |
 
 `SKIPPED`、`NO_HOST`、`INCONCLUSIVE` 從不折算進通過率。把自己的盲點算成成功的掃描，
@@ -220,6 +221,7 @@ button / html / icon-list / divider / image 佔了全部元素的 99.6%。長尾
 | `verify_intro.py` / `verify_loop.py` | 會「結束」的載入動畫；會循環、不遮東西、能打開的永續動畫 |
 | `theme_export.php` / `theme_import.php` | 整個主題以 JSON 資料列透過 WP-CLI 搬移，ID 不變 |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | 在編輯器外驅動 Mosaic 自己的 ZIP 匯出匯入、副本對來源逐樹比對、以及拒絕刪 live 主題的乾淨刪除 |
+| `list_fields.php` | 一篇文章的自訂欄位註冊了哪些 `@VAR` / `@LOOP` 名字，連值一起列出 |
 | `data_upgrade.py` | 外掛更新後，走 Mosaic 自己的 milestone 路由跑資料遷移——沒跑完之前編輯器 API 是不存在的 |
 | `sweep_*.py` / `probe_*.py` | 那些表格是用這些儀器量出來的 |
 | `bootstrap_probe_theme.php` / `mint_session.php` | 免授權的實驗主題，以及從 WP-CLI 鑄出 REST session |

package/SKILL.md

@@ -4,7 +4,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 with `mo.py`, which joins every source table to the live sweeps so a lookup leads with the measured verdict rather than the declaration (122 node types, 182 properties, 98 style properties with 20 structured value shapes pinned down, 53 style states, 152 variants, 74 dynamic variables, 12 interaction triggers, 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, 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.8, with the 1.0.7 -> 1.0.8 migration (variants, universal classes, `m-` class names, customDeclarations) run and re-verified.
 license: "MIT"
 author: "moksa (https://moksaweb.com)"
-version: "1.18.0"
+version: "1.19.0"
 ---
 
 # Headless Mosaic
@@ -171,6 +171,16 @@ DESIGN SYS   variants and collection variables both verified against compiled
              :root{--brand: rgb(9, 99, 199)} with background-color:var(--brand).
              references/design-system.md
 
+FIELDS       ACF 6.8 and Meta Box 5.15, forty fields registered in code on a page,
+             read back off the delivered HTML: 59 of 62 expressions resolve to the
+             value expected, the 3 empties explained (select label needs ACF's
+             array format; oEmbed dies in a text node, lives in a code node).
+             Loops over relationship / checkbox / taxonomy / gallery / clone /
+             group fields rendered exactly the rows the field holds. The names
+             are not guessable (meta_k, meta_k__label, loopk, loop-k for a
+             group, item/value_sub) - tools/list_fields.php prints them.
+             data/custom-fields-verification.csv, references/custom-fields.md
+
 DYNAMIC      the @VAR('namespace/name') language verified against rendered output -
              @VAR('post/title') produced the real post title, @concat/@substr/
              @fallback all compose over it. 74 variables in
@@ -446,7 +456,10 @@ so the pattern is in the data, not just in this paragraph.
 10. `references/interactions.md` — the JavaScript animation system, and how far it is
    verified.
 11. `references/vs-elementor-gutenberg.md` — which builder habits transfer.
-12. `references/upgrading.md` — what a plugin update does to the data and to the
+12. `references/custom-fields.md` — ACF and Meta Box fields as `@VAR` / `@LOOP`:
+   the names, what each field type resolves to, and the loop element that walks
+   a multi-value field. Measured, 62 rows.
+13. `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.
 
@@ -477,6 +490,7 @@ so the pattern is in the data, not just in this paragraph.
 | `data/conversion-verification.csv` | 8 | **converted then checked live** - an Elementor page rebuilt as Mosaic and held against its source (text, images, links, heading levels), then put through rwd, browser and the design audit with every finding classified inherited-or-introduced |
 | `data/conversion-batch.csv` | 19 | **converted, built and checked live, one page after another** - every Elementor page of a production site through the converter, with per-page element and content counts |
 | `data/token-benchmark.csv` | 6 | **measured with tiktoken** - the same six lookups priced three ways: reading the plugin source, loading every table, querying `mo.py`. 71-99.5% fewer tokens than the source and 99.6%+ fewer than the tables, which total 259,539 - never load them, query them |
+| `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 |
 | `data/theme-zip-verification.csv` | 22 | **round-tripped live** - Mosaic's own ZIP export imported in test mode and compared to its source, table by table and tree by tree |
 | `data/node-type-notes.csv` | 8 | where a sweep outcome is true but misleading on its own, why. Surfaced by `mo.py type` |
 | `data/interaction-verification.csv` | 7 | **probed live** - interaction animation shapes, with negative controls and the stored row beside the payload |
@@ -638,6 +652,13 @@ post — `build_all.py` resets first for that reason.
   the same import took under two minutes and compared 22 of 22. Prune before you
   export; `wp_mosaic_template_assigns.parentID` -> template -> `masterID` is the
   bound set, plus any `assign="auto"` template.
+- **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
+  `loop-k` (hyphen) with `item/value_<sub>` rows; ACF puts the ID in a
+  reference's primary slot where Meta Box puts the title. Run
+  `tools/list_fields.php` on the post rather than guessing - a name it does not
+  print does not exist. references/custom-fields.md
 - **A variant row cannot be deleted, only emptied.** `status:"delete"` on a
   variant is accepted and ignored - the row is catalog-backed. Commit it back with
   `{"states": {"&": {"_": {}}}}` and the rule disappears; measured on Heading 2.
@@ -698,6 +719,7 @@ post — `build_all.py` resets first for that reason.
 | `theme_zip.py` | drive Mosaic's OWN export/import - the ZIP the editor makes, attachments included, over the milestone protocol; import lands in test mode unless told `--activate` |
 | `theme_zip_compare.php` | hold an imported copy against its source, tree for tree - every scoped table, the (parentType, type) shape, which ids survive, and orphans named rather than counted |
 | `theme_delete.php` | remove a theme completely through the plugin's own routine; refuses the live one |
+| `list_fields.php` | every `@VAR` / `@LOOP` name Mosaic registers for one post - custom fields, their derived `__label` / `__url` / `__id` properties, the row variables of each loop - with the value each resolves to (`wp eval-file`) |
 | `data_upgrade.py` | after a plugin update, run Mosaic's data migration over its own milestone route - the step wp-admin does from a screen - and set the config's version when the editor API is back |
 | `copy_styles.py` | push one node's style onto others, by attrID or prefix |
 | `bootstrap_probe_theme.php` | a licence-free scratch theme |

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.18.0"
+    "version": "1.19.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.18.0"
+    "version": "1.19.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.18.0"
+    "version": "1.19.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.18.0"
+    "version": "1.19.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.18.0"
+    "version": "1.19.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/bin/check-release.mjs

@@ -83,6 +83,7 @@ const counts = {
   "data/style-state-verification.csv": 52,
   "data/interaction-verification.csv": 7,
   "data/data-class-hierarchy.csv": 121,
+  "data/custom-fields-verification.csv": 62,
 };
 for (const [file, expected] of Object.entries(counts)) {
   if (!fs.existsSync(path.join(ROOT, file))) { fail(`${file} missing`); continue; }

package/data/custom-fields-verification.csv

@@ -0,0 +1,63 @@
+provider,field,expression,expected,rendered,result
+ACF,text,@VAR('post/meta_acf_text'),ACF plain text,ACF plain text,PASS
+ACF,"textarea (newline kept, no <br>)",@VAR('post/meta_acf_area'),line one\nline two,line one\nline two,PASS
+ACF,number,@VAR('post/meta_acf_num'),42,42,PASS
+ACF,true_false,@VAR('post/meta_acf_bool'),1,1,PASS
+ACF,url,@VAR('post/meta_acf_url'),https://example.com/acf,https://example.com/acf,PASS
+ACF,email,@VAR('post/meta_acf_email'),acf@example.com,acf@example.com,PASS
+ACF,color_picker,@VAR('post/meta_acf_color'),#ff5a36,#ff5a36,PASS
+ACF,date_picker (return Y-m-d),@VAR('post/meta_acf_date'),2026-09-15,2026-09-15,PASS
+ACF,wysiwyg,@VAR_RAW('post/meta_acf_wys'),Rich text,Rich text,PASS
+ACF,select (return value),@VAR('post/meta_acf_select'),b,b,PASS
+ACF,select (return value) __label,@VAR('post/meta_acf_select__label'),,,EMPTY
+ACF,radio,@VAR('post/meta_acf_radio'),r2,r2,PASS
+ACF,image (return array),@VAR('post/meta_acf_img'),https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,PASS
+ACF,image (return array) __id,@VAR('post/meta_acf_img__id'),5,5,PASS
+ACF,image (return id),@VAR('post/meta_acf_img_id'),https://mosaic.moksaweb.com/wp-content/uploads/2026/09/richmenu-a.png,https://mosaic.moksaweb.com/wp-content/uploads/2026/09/richmenu-a.png,PASS
+ACF,image (return id) __id,@VAR('post/meta_acf_img_id__id'),37,37,PASS
+ACF,file (return url),@VAR('post/meta_acf_file'),https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,PASS
+ACF,link (return array),@VAR('post/meta_acf_link'),https://example.com/link,https://example.com/link,PASS
+ACF,link __title,@VAR('post/meta_acf_link__title'),Link title,Link title,PASS
+ACF,link __target,@VAR('post/meta_acf_link__target'),_blank,_blank,PASS
+ACF,page_link,@VAR('post/meta_acf_pl'),https://mosaic.moksaweb.com/sample-page/,https://mosaic.moksaweb.com/sample-page/,PASS
+ACF,post_object,@VAR('post/meta_acf_po'),6,6,PASS
+ACF,post_object __label,@VAR('post/meta_acf_po__label'),Shop,Shop,PASS
+ACF,post_object __url,@VAR('post/meta_acf_po__url'),https://mosaic.moksaweb.com/shop/,https://mosaic.moksaweb.com/shop/,PASS
+ACF,user,@VAR('post/meta_acf_user'),1,1,PASS
+ACF,user __label,@VAR('post/meta_acf_user__label'),Cheng-Chun Chang,Cheng-Chun Chang,PASS
+ACF,user __url,@VAR('post/meta_acf_user__url'),https://mosaic.moksaweb.com/author/moksa/,https://mosaic.moksaweb.com/author/moksa/,PASS
+ACF,oembed in a text node,@VAR_RAW('post/meta_acf_oembed'),,,EMPTY
+Meta Box,text,@VAR('post/meta_mb_text'),MB plain text,MB plain text,PASS
+Meta Box,number,@VAR('post/meta_mb_num'),17,17,PASS
+Meta Box,checkbox,@VAR('post/meta_mb_check'),1,1,PASS
+Meta Box,select,@VAR('post/meta_mb_select'),a,a,PASS
+Meta Box,select __label,@VAR('post/meta_mb_select__label'),Alpha,Alpha,PASS
+Meta Box,date,@VAR('post/meta_mb_date'),2026-09-15,2026-09-15,PASS
+Meta Box,color,@VAR('post/meta_mb_color'),#0a84ff,#0a84ff,PASS
+Meta Box,url,@VAR('post/meta_mb_url'),https://example.com/mb,https://example.com/mb,PASS
+Meta Box,wysiwyg,@VAR('post/meta_mb_wys'),MB rich,MB rich,PASS
+Meta Box,single_image,@VAR('post/meta_mb_single'),https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,https://mosaic.moksaweb.com/wp-content/uploads/woocommerce-placeholder.webp,PASS
+Meta Box,single_image __id,@VAR('post/meta_mb_single__id'),5,5,PASS
+Meta Box,user,@VAR('post/meta_mb_user'),Cheng-Chun Chang,Cheng-Chun Chang,PASS
+Meta Box,user __id,@VAR('post/meta_mb_user__id'),1,1,PASS
+Meta Box,user __url,@VAR('post/meta_mb_user__url'),https://mosaic.moksaweb.com/author/moksa/,https://mosaic.moksaweb.com/author/moksa/,PASS
+Meta Box,oembed in a text node,@VAR_RAW('post/meta_mb_oembed'),,,EMPTY
+Meta Box,oembed __url,@VAR('post/meta_mb_oembed__url'),https://www.youtube.com/watch?v=dQw4w9WgXcQ,https://www.youtube.com/watch?v=dQw4w9WgXcQ,PASS
+ACF,"relationship, one row inline (index 1)","@LOOP('post/loopacf_rel', 1, 'value__url')",https://mosaic.moksaweb.com/sample-page/,https://mosaic.moksaweb.com/sample-page/,PASS
+ACF,"relationship, every row inline (index 0)","@LOOP('post/loopacf_rel', 0, 'value__label')","Sample Page, Shop","Sample Page, Shop",PASS
+ACF,"group, one row inline","@LOOP('post/loop-acf_group', 1, 'value_ga')",group text,group text,PASS
+ACF,relationship loop row value (= ID),loop post/loopacf_rel -> @VAR('item/value'),2 | 6,2 | 6,PASS
+ACF,relationship loop row __label,loop post/loopacf_rel -> @VAR('item/value__label'),Sample Page | Shop,Sample Page | Shop,PASS
+ACF,relationship loop row __url,loop post/loopacf_rel -> @VAR('item/value__url'),https://mosaic.moksaweb.com/sample-page/ | https://mosaic.moksaweb.com/shop/,https://mosaic.moksaweb.com/sample-page/ | https://mosaic.moksaweb.com/shop/,PASS
+ACF,relationship loop row index,loop post/loopacf_rel -> @VAR('item/index'),1 | 2,1 | 2,PASS
+ACF,checkbox loop row value,loop post/loopacf_check -> @VAR('item/value'),x | z,x | z,PASS
+ACF,taxonomy loop row __label,loop post/loopacf_tax -> @VAR('item/value__label'),Uncategorized,Uncategorized,PASS
+ACF,taxonomy loop row __url,loop post/loopacf_tax -> @VAR('item/value__url'),https://mosaic.moksaweb.com/category/uncategorized/,https://mosaic.moksaweb.com/category/uncategorized/,PASS
+ACF,group loop row sub-field,loop post/loop-acf_group -> @VAR('item/value_ga'),group text,group text,PASS
+ACF,group loop row sub-field (number),loop post/loop-acf_group -> @VAR('item/value_gb'),7,7,PASS
+Meta Box,image_advanced loop row __id,loop post/loopmb_img -> @VAR('item/value__id'),5 | 37,5 | 37,PASS
+Meta Box,checkbox_list loop row value,loop post/loopmb_multi -> @VAR('item/value'),x | y,x | y,PASS
+Meta Box,checkbox_list loop row __label,loop post/loopmb_multi -> @VAR('item/value__label'),Ex | Why,Ex | Why,PASS
+Meta Box,cloneable text loop row value,loop post/loopmb_text_clone -> @VAR('item/value'),clone one | clone two,clone one | clone two,PASS
+ACF,oembed through a code node,code: @VAR_RAW('post/meta_acf_oembed'),<iframe,"<iframe title=""Rick Astley - Never Gonna Give You Up (Offici",PASS
+Meta Box,wysiwyg through a code node,code: @VAR_RAW('post/meta_mb_wys'),<p>MB <em>rich</em></p>,"<div class=""wp-site-blocks""><div class=""entry-content alignf",PASS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.18.0",
+  "version": "1.19.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/custom-fields.md

@@ -0,0 +1,112 @@
+# Custom fields: ACF and Meta Box through `@VAR` and `@LOOP`, measured
+
+Mosaic 1.0.8 reads custom fields through one provider-neutral core with two
+providers wired in: **ACF** (free or Pro) and **Meta Box** (free; Group,
+Relationships, Term/User/Settings add-ons have handlers too). Plain `post_meta`
+without either plugin is read as well, as a bare string. There is no public hook to
+add a provider - `CustomFields/AUTHORING.md` in the plugin says so in its first
+paragraph.
+
+Everything below was measured on a live 1.0.8 install: ACF 6.8.10 and Meta Box
+5.15.0, forty fields registered in code on a page, values written with
+`update_field()` / `rwmb_set_meta()`, then read back **off the delivered HTML** of
+a Mosaic page built through the tables. `data/custom-fields-verification.csv`, 62
+rows: 59 resolve to the value expected, 3 are empty for a reason given below.
+
+## The names
+
+A field with meta key `k` on the current post is
+
+```
+@VAR('post/meta_k')          the field's primary value
+@VAR('post/meta_k__label')   derived properties, when the field type has them
+@VAR('post/meta_k__url')
+@VAR('post/meta_k__id')
+@VAR('post/meta_k__title')   ACF link
+@VAR('post/meta_k__target')  ACF link
+```
+
+A field that holds MANY values (checkbox, relationship, taxonomy, gallery,
+image_advanced, cloneable, group, repeater) is not a variable at all. It is a
+**loop**, named `loop` + key - `@LOOP('post/loopk')` - and its rows carry the same
+properties under the loop node's namespace (`item` unless `loopNamespace` says
+otherwise): `@VAR('item/value')`, `@VAR('item/value__label')`, `@VAR('item/index')`.
+An ACF **group** is the exception in spelling: `loop-k` with a hyphen, one row, and
+its sub-fields are `item/value_<subfield>` with a single underscore.
+
+Do not guess any of this. `wp eval-file tools/list_fields.php <post_id>` prints the
+exact variable and loop names Mosaic registers for that post with the value each
+resolves to and the row variables of every loop - the same schema the frontend
+evaluates, so a name it does not print does not exist:
+
+```
+variable post/meta_acf_po           ACF / Post object / ID     6
+variable post/meta_acf_po__label    ACF / Post object / 標題   Shop
+variable post/meta_acf_po__url      ACF / Post object / 網址   https://…/shop/
+loop     post/loopacf_rel           ACF / Relationship         2 items; first row: value=2 | value__label=Sample Page | value__url=… | index=1
+loop     post/loop-acf_group        ACF / Group                1 items; first row: value_ga=group text | value_gb=7 | index=1
+```
+
+## What each field type resolves to
+
+| field | `meta_k` | derived |
+|---|---|---|
+| text, textarea, number, url, email, color, date, select, radio, true_false | the stored value, as a string; a textarea keeps its newline and gets no `<br>`; a date honours ACF's `return_format` | select/radio: `__label` **only when ACF's return format is `array`** - with the default `value` format the label variable is not registered (measured empty) |
+| image, file | the URL, whatever ACF's return format says (`array` and `id` both rendered the URL) | `__id` |
+| link (ACF, array) | the URL | `__title`, `__target` |
+| page_link | the permalink | - |
+| post_object (ACF) | **the ID** | `__label` = title, `__url` = permalink |
+| post (Meta Box) | **the title** | `__id`, `__url` - the two providers put opposite things in the primary slot |
+| user (ACF) | the ID | `__label` = display name, `__url` = author archive |
+| user (Meta Box) | the display name | `__id`, `__url` |
+| oembed | the `<iframe>` HTML - **but see below** | Meta Box adds `__url`, the source URL |
+| wysiwyg | the HTML; Meta Box's arrives wrapped in Mosaic's own `wp-site-blocks` / `entry-content` divs because its value runs through `the_content` | - |
+| checkbox (ACF), checkbox_list (Meta Box), relationship, taxonomy, image_advanced, file_advanced, post (multiple), cloneable | a loop | rows: `value` (ACF reference rows: the ID; Meta Box: the title / URL), `value__label`, `value__url`, `value__id`, `index` |
+| group (ACF) | a loop of one row, named `loop-k` | `value_<sub>` per sub-field |
+
+## Inline access to a loop
+
+`@LOOP` takes `(loop, index, row-variable)` pairs and works inside a text node
+without a loop element:
+
+```
+@LOOP('post/loopacf_rel', 1, 'value__label')   ->  Sample Page        row 1 (1-based)
+@LOOP('post/loopacf_rel', 0, 'value__label')   ->  Sample Page, Shop  index 0 = every row, joined ", "
+@LOOP('post/loop-acf_group', 1, 'value_ga')     ->  group text
+```
+
+A **loop element** is the real thing: `loop > loop-items > loop-item > …`, with
+the source on the loop node:
+
+```json
+{"type": "loop",
+ "data": {"loopType": "localContext",
+          "localContextOptions": {"loopSource": {"v": "@LOOP('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')"}}]}
+ ]}]}]}
+```
+
+`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,
+2 rows), and an empty field renders `m-loop--no-result` with the `loop-no-result`
+child rather than nothing.
+
+## The three empties, explained
+
+- `@VAR('post/meta_acf_select__label')` with ACF's default `value` return format: the
+  handler registers `__label` only for `return_format: array`. Switch the field or
+  use `@VAR('post/meta_k')` and map it yourself.
+- **oEmbed inside a text node is empty**, with `@VAR` and with `@VAR_RAW` alike - the
+  wysiwyg text pipeline strips the `<iframe>`. Put it in a `code` node instead:
+  `<div>@VAR_RAW('post/meta_acf_oembed')</div>` delivered the full YouTube iframe.
+  The same route carries Meta Box's wysiwyg HTML intact.
+
+## What did not need a field plugin
+
+`meta_footnotes` appeared in the list on a page with neither ACF nor Meta Box
+registering it: every non-underscore `post_meta` key present on the post type is
+exposed as `meta_<key>` (`MetaFieldUnknown`, a plain string). A site that stores
+its data with `update_post_meta()` and nothing else is already readable.

package/tools/list_fields.php

@@ -0,0 +1,88 @@
+<?php
+/**
+ * Every dynamic variable and loop Mosaic exposes for one post - the exact names
+ * `@VAR('post/<name>')` and `@LOOP('post/<name>')` take - with the value each
+ * resolves to on that post. Custom fields (ACF, Meta Box, plain post meta) included,
+ * with the derived properties a structured field grows (`__label`, `__url`, `__id`,
+ * `__title`, `__target`) and the row variables inside each loop.
+ *
+ *     wp eval-file tools/list_fields.php <post_id> [csv]
+ *
+ * Reads the same schema the frontend evaluates (VariableProviderPost), so a name that
+ * is not printed here does not exist for that post, whatever the field plugin calls it.
+ * Loop names are the plugin's own: `loop<key>` for most fields, `loop-<key>` for an ACF
+ * group. Row variables live under the loop node's `loopNamespace` (default `item`).
+ */
+
+use Mosaic\Compatibility\VariableProvider\AbstractVariableProvider;
+use Mosaic\Compatibility\VariableProvider\VariableProvider;
+use Mosaic\Compatibility\WordPress\PathContext\VariableProviderPost;
+
+$postID = (int)($args[0] ?? 0);
+$asCsv  = ($args[1] ?? '') === 'csv';
+$post   = get_post($postID);
+if (!$post) {
+    WP_CLI::error("no post $postID");
+}
+
+$provider = new VariableProvider(VariableProviderPost::getVariableProviderDefinition(get_post_type_object($post->post_type), $postID));
+$ref      = new ReflectionClass(AbstractVariableProvider::class);
+$vars     = $ref->getProperty('schemaVariables');
+$vars->setAccessible(true);
+$loops = $ref->getProperty('schemaLoops');
+$loops->setAccessible(true);
+$record = $ref->getProperty('currentRecord');
+$record->setAccessible(true);
+$record->setValue($provider, $post);
+
+$rows = [];
+foreach ($vars->getValue($provider) as $name => $variable) {
+    $value = '';
+    try {
+        $value = (string)$variable->getValue($post);
+    } catch (Throwable $e) {
+        $value = 'ERR ' . $e->getMessage();
+    }
+    $rows[] = ['variable', "post/$name", $variable->getLabel(), $value];
+}
+foreach ($loops->getValue($provider) as $name => $loop) {
+    $count = 0;
+    $inner = [];
+    try {
+        $lp = $loop->toLoop($post);
+        if ($lp) {
+            $count = $lp->getTotalItems();
+            if ($count > 0) {
+                // read row 1 the way the evaluator does: seek, then getVariable per name
+                $lp->seek(0);
+                $lv = $ref->getProperty('schemaVariables');
+                $lv->setAccessible(true);
+                foreach (array_keys($lv->getValue($lp)) as $n) {
+                    $val = '';
+                    try {
+                        $val = (string)$lp->getVariable($n);
+                    } catch (Throwable $e) {
+                        $val = '?';
+                    }
+                    $inner[] = "$n=" . mb_substr(str_replace(PHP_EOL, ' ', $val), 0, 30);
+                }
+            }
+        }
+    } catch (Throwable $e) {
+        $inner = ['ERR ' . $e->getMessage()];
+    }
+    $rows[] = ['loop', "post/$name", $loop->getLabel(), $count . ' items; first row: ' . implode(' | ', $inner)];
+}
+
+if ($asCsv) {
+    $out = fopen('php://output', 'w');
+    fputcsv($out, ['kind', 'name', 'label', 'value']);
+    foreach ($rows as $r) {
+        fputcsv($out, $r);
+    }
+    fclose($out);
+} else {
+    foreach ($rows as [$kind, $name, $label, $value]) {
+        printf("%-8s %-34s %-28s %s\n", $kind, $name, mb_substr($label, 0, 28), mb_substr(str_replace("\n", ' ', $value), 0, 80));
+    }
+}