mosaic-headless 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moksa (https://moksaweb.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,94 @@
+# mosaic-headless
+
+[Mosaic Pro](https://mosaicbuilder.com)（Nextend）のサイトを、データモデルを直接書いて
+構築・変更する — ビジュアルエディタも DOM も使わない。
+
+*他の言語：[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md)*
+
+---
+
+Mosaic はページを **23 個のカスタムテーブル**に保持する。`post_content` でもなければ
+`postmeta` でもない。要素ひとつにつき 1 行、ツリー構造は `parentID` カラム、兄弟の順序は
+fractional-index の文字列。エディタはこのモデルの一クライアントにすぎない。
+フォーマットそのものではないし、使う必要もない。
+
+この skill はそのモデルの地図であり、**ソースを読んだものではなく、実際のインストールに
+対して測定したもの**である。
+
+## すべてに優先するただ一つの規則
+
+**ノードタイプ、プロパティ名、列挙値、スタイルキー、Free/Pro の判断を記憶で書かないこと。
+`data/` を引くこと。**
+
+そのうえでページを見る。Mosaic の失敗の仕方は 4 通りあり、
+**HTTP ステータスが変わるのはそのうち 1 つだけ**：
+
+```
+バリデータによる正常な拒否   HTTP 200  + body に exceptions 配列
+commit 中の PHP fatal        HTTP 500  （122 タイプ中 15、素の div の中でも起きる）
+構造的に不正なノード         HTTP 200、コミット済み、DB に行もある。そして
+                             公開ページ全体が 54 バイトのエラー文字列になる
+値の「形」が違う             HTTP 200、保存される。ただし CSS ルールが存在しない
+URL に対応するテンプレなし   HTTP 406、未ログインには空の body
+```
+
+**commit の成功は、ページが動いている証拠にはならない。**
+
+## 何を、どう検証したか
+
+すべて実際のインストール上で実行 — WordPress 7.1、WooCommerce 11.1、Mosaic Pro 1.0.7、
+**ライセンスなし**：ライセンスが制限するのはテーマライブラリと更新であってノードファクトリ
+ではないため、Pro のタイプも登録され描画される。
+
+| 対象 | 結果 |
+|---|---|
+| **ノードタイプ** | 122 / 122。1 ドキュメントにつき 1 タイプで commit → 描画 → 断言 → 削除。70 RENDERED、30 COMMITTED、15 COMMIT_5xx、7 BROKE_PAGE |
+| **スタイルプロパティ** | 98 / 98 を実ページに書き、コンパイル済み CSS と照合：58 COMPILED、18 ABSENT、21 SKIPPED |
+| **ノードプロパティ** | 181 / 181 を、各プロパティ自身の validator chain から導いた値で再測定：35 APPLIED、42 NO_EFFECT、55 NO_HOST、47 SKIPPED |
+| **レスポンシブ** | 2 サイト計 569 件の `_t`/`_m` 宣言を、サイトが実際に配信したスタイルシートに対して 1 件ずつ断言 — 全件検証済み |
+| **テーマの書き出し／読み込み** | 往復検証済み：テーマ全体を書き出し、コピーとして読み込み、そのコピーがバイト単位で同一のページを配信 |
+| **実測** | REST ルート 114、element class 151、条件サブジェクト 59、23 テーブル / 206 カラム |
+
+`SKIPPED`、`NO_HOST`、`INCONCLUSIVE` を合格率に混ぜることは決してしない。
+**自分の死角を成功として数えるスイープこそ、この skill が反対しているものである。**
+
+### 書き始める前に知っておく価値のある 2 つの結果
+
+**`group` を持つプロパティは、単独で設定しても効かない。** 両方向とも厳密：group を持たない
+78 個は 58 COMPILED / 0 ABSENT、group を持つ 20 個はすべて 0 COMPILED。つまり
+`borderLeftWidth`、`outlineColor`、`gridColumnStart` は 3 つの別々の奇癖ではなく
+**同一の規則の 3 つの実例**である。グループ形状を使うか（`border` は
+`{width, style, color}` を取る）、`customStyles` に落とす。
+
+**ブレークポイントの上書きはプロパティを「変える」ことはできても「消す」ことはできない。**
+狭い画面の `customStyles` が単に境界線を書いていないだけなら、広い画面の境界線は生き残り、
+1 カラムに畳まれたレイアウトの真ん中に線を引く。**`border-left:0` と明示すること。**
+
+## ツール
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php          # ライセンス不要の作業用テーマ
+python tools/build_site.py   --config c.json --site sites/moksa.json
+python tools/verify_rwd.py   --config c.json --site sites/moksa.json --csv rwd.csv
+python tools/copy_styles.py  --config c.json --from a --to-prefix b- --only "&._m"
+wp eval-file tools/theme_export.php active > theme.json
+wp eval-file tools/theme_import.php theme.json "名前" rebind activate
+```
+
+`sites/_moksa.py` が完全な実例：実在するスタジオのトップページ — マストヘッド、仕様ブロック、
+サービス、9 行の実績テーブル、プロセス、技術スタック、プロダクト、推薦の声、連絡先 —
+**590 ノードをすべてテーブル経由で commit**。名前付き view timeline で作った、スクロールに
+追随する条項インデックスも含め、JavaScript は一切使っていない。
+
+## どこから読むか
+
+1. `references/data-model.md` — ページが実際にどこにあるか。
+2. `references/write-protocol.md` — checkout / check / commit。
+3. `references/failure-modes.md` — Mosaic の壊れ方、すべて実測。**書く前に読む。**
+4. `references/responsive.md` — state / breakpoint / property という軸。
+5. `references/styling.md` — スタイル値が CSS になるまで。
+6. `references/design-system.md` — element class とデザイントークン。
+
+## ライセンス
+
+MIT。Mosaic Pro 自体はライセンス製品であり、この repo に**含まれていない**。

package/README.md

@@ -0,0 +1,133 @@
+# mosaic-headless
+
+Build and modify [Mosaic Pro](https://mosaicbuilder.com) (Nextend) sites by writing
+the data model directly — no visual editor, no DOM.
+
+*Read this in [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)*
+
+---
+
+Mosaic keeps a page in **23 custom database tables**, not in `post_content` and not
+in `postmeta`. One row per element, the tree carried by a `parentID` column, sibling
+order by a fractional-index string. The editor is one client of that model. It is not
+the format, and you do not need it.
+
+This skill is the map of that model — measured against a live install rather than
+read off the source.
+
+## The one rule
+
+**Never write a node type, property name, enum value, style key or Free/Pro claim
+from memory. Look it up in `data/`.**
+
+Then check the page. Mosaic has four failure modes and **only one of them changes the
+HTTP status code**:
+
+```
+clean validator rejection   HTTP 200  + an `exceptions` array in the body
+PHP fatal during commit     HTTP 500  (15 of 122 types do this from a plain div)
+structurally invalid node   HTTP 200, committed, row in the DB, and the whole
+                            public page becomes a 54-byte error string
+wrong value SHAPE           HTTP 200, stored, and the CSS rule is simply absent
+no template for the URL     HTTP 406 with an EMPTY BODY for anyone not logged in
+```
+
+A successful commit is not evidence of a working page.
+
+## What was verified, and how
+
+Everything ran against a live install — WordPress 7.1, WooCommerce 11.1, Mosaic Pro
+1.0.7, **unlicensed**: the licence gates the theme library and updates, not the node
+factories, so Pro types register and render regardless.
+
+| pass | result |
+|---|---|
+| **node types** | 122 / 122 swept one per document, committed → rendered → asserted → deleted: 70 RENDERED, 30 COMMITTED, 15 COMMIT_5xx, 7 BROKE_PAGE |
+| **style properties** | 98 / 98 written to a live page and checked against the compiled CSS: 58 COMPILED, 18 ABSENT, 21 SKIPPED |
+| **node properties** | 181 / 181 re-probed with a value shaped by each property's own validator chain: 35 APPLIED, 42 NO_EFFECT, 55 NO_HOST, 47 SKIPPED |
+| **responsive** | 569 `_t`/`_m` declarations across two sites asserted against the stylesheet the site actually served — all verified |
+| **theme export/import** | round-tripped: a full theme exported, re-imported as a copy, and the copy served byte-identical pages |
+| **measured live** | 114 REST routes, 151 element classes, 59 condition subjects, 23 tables / 206 columns |
+
+`SKIPPED`, `NO_HOST` and `INCONCLUSIVE` are never folded into a pass rate. A sweep
+that scores its own blind spots as successes is the thing this skill argues against.
+
+### Two results worth knowing before you write anything
+
+**A property that belongs to a `group` is inert when set on its own.** Exact in both
+directions: 78 ungrouped properties gave 58 COMPILED and 0 ABSENT; all 20 grouped
+ones gave 0 COMPILED. So `borderLeftWidth`, `outlineColor` and `gridColumnStart` are
+three instances of one rule, not three oddities. Use the grouped shape — `border`
+takes `{width, style, color}` — or `customStyles`.
+
+**A breakpoint override can CHANGE a property but never REMOVE one.** Narrow-screen
+`customStyles` that merely omits a border leaves the wide-screen border standing,
+drawing rules down the middle of a collapsed layout. Say `border-left:0` out loud.
+
+## Tools
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php          # licence-free scratch theme
+python tools/build_site.py   --config c.json --site sites/moksa.json
+python tools/verify_rwd.py   --config c.json --site sites/moksa.json --csv rwd.csv
+python tools/copy_styles.py  --config c.json --from a --to-prefix b- --only "&._m"
+wp eval-file tools/theme_export.php active > theme.json
+wp eval-file tools/theme_import.php theme.json "Name" rebind activate
+```
+
+`sites/_moksa.py` is the worked example: a real studio homepage — masthead, spec
+block, services, a nine-row work table, process, stack, products, testimonials,
+contact — 590 nodes committed entirely through the tables, with a scroll-tracking
+clause index built on named view timelines and no JavaScript.
+
+## Where to start
+
+1. `references/data-model.md` — where a page actually lives.
+2. `references/write-protocol.md` — checkout / check / commit.
+3. `references/failure-modes.md` — how Mosaic fails, measured. **Read before writing.**
+4. `references/responsive.md` — the state/breakpoint/property axis.
+5. `references/styling.md` — how a style value becomes CSS.
+6. `references/design-system.md` — element classes and design tokens.
+
+## Releasing
+
+One command. The version lives in three places — `package.json`, the SKILL.md
+frontmatter an agent reads, and the frontmatter each platform template writes on
+install — and nothing keeps them together on its own.
+
+```bash
+npm version patch      # or minor / major
+```
+
+That runs, in order:
+
+1. `preversion` → `bin/check-release.mjs`
+2. npm bumps `package.json`
+3. `version` → `bin/sync-version.mjs` writes the new number into SKILL.md and all
+   eight platform templates, and stages them
+4. npm commits and tags `vX.Y.Z`
+5. `postversion` → pushes the commit and the tag
+
+The tag push triggers `.github/workflows/release.yml`, which refuses to publish
+unless the tag matches `package.json`, re-runs the release checks, proves the
+installer runs, prints the tarball, then publishes with provenance and opens a
+GitHub release.
+
+`bin/check-release.mjs` is the gate, and it checks the things that are easy to get
+wrong rather than the things that are easy to check:
+
+- the three version numbers agree
+- every glob in `files` matches something
+- the row counts in the verification CSVs still equal the numbers SKILL.md quotes
+- `SKIPPED` labels survive into the shipped data, because a sweep that hides its
+  blind spots is the failure this skill argues against
+- **the tarball itself is inspected**, not the intent. npm's `files` allowlist
+  *overrides* `.gitignore`: naming a directory ships everything inside it, ignored
+  or not. Listing `sites/` once put a real client's generator and content into the
+  tarball — gitignored, and about to be published anyway.
+
+One-time setup: add the `NPM_TOKEN` repository secret.
+
+## Licence
+
+MIT. Mosaic Pro itself is licensed third-party software and is **not** included here.

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+# mosaic-headless
+
+直接写入数据模型来构建和修改 [Mosaic Pro](https://mosaicbuilder.com)（Nextend）网站——
+不开可视化编辑器，不碰 DOM。
+
+*其他语言：[English](README.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md)*
+
+---
+
+Mosaic 把一个页面放在 **23 张自定义数据表**里，不在 `post_content`，也不在 `postmeta`。
+一个元素一行，树状结构靠 `parentID` 字段，同层顺序是一个 fractional-index 字符串。
+编辑器只是这个模型的一个客户端。它不是格式本身，你也不需要它。
+
+这个 skill 就是那个模型的地图——**对着真实安装量出来的，不是从源码读出来的**。
+
+## 唯一一条凌驾一切的规则
+
+**绝不凭印象写节点类型、属性名、枚举值、样式键或 Free/Pro 的判断。去 `data/` 里查。**
+
+然后去看页面。Mosaic 有四种失效模式，**其中只有一种会改变 HTTP 状态码**：
+
+```
+校验器干净地拒绝      HTTP 200  + body 里一个 exceptions 数组
+commit 时 PHP fatal   HTTP 500  （122 种类型里有 15 种，光放在 div 里就会）
+结构无效的节点        HTTP 200、已写入、数据库有那一行，然后整个公开页面
+                      变成一段 54 字节的错误字符串
+值的「形状」错误      HTTP 200、已保存，而那条 CSS 规则就是不存在
+该网址没有对应模板    HTTP 406，且对未登录者是空白 body
+```
+
+**commit 成功不能当作页面正常的证据。**
+
+## 验证了什么，怎么验的
+
+全部跑在真实安装上——WordPress 7.1、WooCommerce 11.1、Mosaic Pro 1.0.7、**未授权**：
+授权管的是主题库和更新，不是节点工厂，所以 Pro 类型照样注册、照样渲染。
+
+| 项目 | 结果 |
+|---|---|
+| **节点类型** | 122 / 122，一份文档一种类型：写入 → 渲染 → 断言 → 删除。70 RENDERED、30 COMMITTED、15 COMMIT_5xx、7 BROKE_PAGE |
+| **样式属性** | 98 / 98 写进真实页面并对照编译后的 CSS：58 COMPILED、18 ABSENT、21 SKIPPED |
+| **节点属性** | 181 / 181，用每个属性自己的 validator chain 推导出的值重测：35 APPLIED、42 NO_EFFECT、55 NO_HOST、47 SKIPPED |
+| **响应式** | 两个站共 569 条 `_t`/`_m` 声明，对照网站实际送出的样式表逐条断言——全部通过 |
+| **主题导出／导入** | 完整往返验证：导出整个主题、以副本身份导入，副本送出的页面逐字节相同 |
+| **线上量测** | 114 条 REST 路由、151 个 element class、59 个条件主体、23 张表 / 206 个字段 |
+
+`SKIPPED`、`NO_HOST`、`INCONCLUSIVE` 永远不并入通过率。
+**一个把自己的盲点算成成功的扫描工具，正是这个 skill 要反对的东西。**
+
+### 动手之前值得先知道的两个结果
+
+**带有 `group` 的属性，单独设置一律无效。** 两个方向都精确：78 个无 group 的属性得到
+58 COMPILED、0 ABSENT；20 个有 group 的全部 0 COMPILED。所以 `borderLeftWidth`、
+`outlineColor`、`gridColumnStart` 是**同一条规则的三个实例**，不是三个各自的怪毛病。
+要用就用分组形状——`border` 收 `{width, style, color}`——或者退回 `customStyles`。
+
+**断点覆盖只能「改变」属性，永远不能「移除」。** 窄屏的 `customStyles` 如果只是
+没写某条边框，宽屏那条边框会活下来，在塌成单列的版面正中间画一条线。
+**要把 `border-left:0` 明确写出来。**
+
+## 工具
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php          # 免授权的测试主题
+python tools/build_site.py   --config c.json --site sites/moksa.json
+python tools/verify_rwd.py   --config c.json --site sites/moksa.json --csv rwd.csv
+python tools/copy_styles.py  --config c.json --from a --to-prefix b- --only "&._m"
+wp eval-file tools/theme_export.php active > theme.json
+wp eval-file tools/theme_import.php theme.json "名称" rebind activate
+```
+
+`sites/_moksa.py` 是完整示例：一个真实工作室的首页——报头、规格区块、服务、九行作品表格、
+流程、技术栈、产品、客户评价、联系——**590 个节点全部通过数据表写入**，
+还有一个用具名 view timeline 做的、会跟随滚动的条款索引，完全没有 JavaScript。
+
+## 从哪里开始读
+
+1. `references/data-model.md` —— 页面到底住在哪里。
+2. `references/write-protocol.md` —— checkout / check / commit。
+3. `references/failure-modes.md` —— Mosaic 怎么坏的，都是量出来的。**动笔前先读。**
+4. `references/responsive.md` —— state / breakpoint / property 这个轴。
+5. `references/styling.md` —— 一个样式值怎么变成 CSS。
+6. `references/design-system.md` —— element class 与设计 token。
+
+## 许可
+
+MIT。Mosaic Pro 本身是有授权的第三方软件，**不包含**在这个 repo 里。

package/README.zh-TW.md

@@ -0,0 +1,87 @@
+# mosaic-headless
+
+直接寫入資料模型來建置與修改 [Mosaic Pro](https://mosaicbuilder.com)（Nextend）網站——
+不開視覺編輯器，不碰 DOM。
+
+*其他語言：[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)*
+
+---
+
+Mosaic 把一個頁面放在 **23 張自訂資料表**裡，不在 `post_content`，也不在 `postmeta`。
+一個元素一列，樹狀結構靠 `parentID` 欄位，同層順序是一個 fractional-index 字串。
+編輯器只是這個模型的其中一個客戶端。它不是格式本身，而且你不需要它。
+
+這個 skill 就是那個模型的地圖——**對著真實安裝量出來的，不是從原始碼讀出來的**。
+
+## 唯一一條凌駕一切的規則
+
+**絕不憑印象寫節點型別、屬性名稱、列舉值、樣式鍵或 Free/Pro 的判斷。到 `data/` 裡查。**
+
+然後去看頁面。Mosaic 有四種失效模式，**其中只有一種會改變 HTTP 狀態碼**：
+
+```
+驗證器乾淨地拒絕      HTTP 200  + body 裡一個 exceptions 陣列
+commit 時 PHP fatal   HTTP 500  （122 種型別裡有 15 種，光放在 div 裡就會）
+結構無效的節點        HTTP 200、已寫入、資料庫有那一列，然後整個公開頁面
+                      變成一段 54 bytes 的錯誤字串
+值的「形狀」錯誤      HTTP 200、已儲存，而那條 CSS 規則就是不存在
+該網址沒有對應範本    HTTP 406，而且對未登入者是空白 body
+```
+
+**commit 成功不能當作頁面正常的證據。**
+
+## 驗證了什麼，怎麼驗的
+
+全部跑在真實安裝上——WordPress 7.1、WooCommerce 11.1、Mosaic Pro 1.0.7、**未授權**：
+授權管的是主題庫與更新，不是節點工廠，所以 Pro 型別照樣註冊、照樣渲染。
+
+| 項目 | 結果 |
+|---|---|
+| **節點型別** | 122 / 122，一份文件一種型別：寫入 → 渲染 → 斷言 → 刪除。70 RENDERED、30 COMMITTED、15 COMMIT_5xx、7 BROKE_PAGE |
+| **樣式屬性** | 98 / 98 寫進真實頁面並對照編譯後的 CSS：58 COMPILED、18 ABSENT、21 SKIPPED |
+| **節點屬性** | 181 / 181，用每個屬性自己的 validator chain 推導出的值重測：35 APPLIED、42 NO_EFFECT、55 NO_HOST、47 SKIPPED |
+| **響應式** | 兩個站共 569 條 `_t`/`_m` 宣告，對照網站實際送出的樣式表逐條斷言——全數通過 |
+| **主題匯出／匯入** | 完整來回驗證：匯出整個主題、以副本身分匯入，副本送出的頁面逐位元組相同 |
+| **線上量測** | 114 條 REST 路由、151 個 element class、59 個條件主體、23 張表 / 206 個欄位 |
+
+`SKIPPED`、`NO_HOST`、`INCONCLUSIVE` 永遠不併進通過率。
+**一支把自己的盲點算成成功的掃描工具，正是這個 skill 要反對的東西。**
+
+### 動手之前值得先知道的兩個結果
+
+**帶有 `group` 的屬性，單獨設定一律無效。** 兩個方向都精確：78 個無 group 的屬性得到
+58 COMPILED、0 ABSENT；20 個有 group 的全部 0 COMPILED。所以 `borderLeftWidth`、
+`outlineColor`、`gridColumnStart` 是**同一條規則的三個實例**，不是三個各自的怪毛病。
+要用就用群組形狀——`border` 收 `{width, style, color}`——或者退回 `customStyles`。
+
+**斷點覆寫只能「改變」屬性，永遠不能「移除」。** 窄螢幕的 `customStyles` 如果只是
+沒寫某條框線，寬螢幕那條框線會活下來，在塌成單欄的版面正中間畫一條線。
+**要把 `border-left:0` 明講出來。**
+
+## 工具
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php          # 免授權的測試主題
+python tools/build_site.py   --config c.json --site sites/moksa.json
+python tools/verify_rwd.py   --config c.json --site sites/moksa.json --csv rwd.csv
+python tools/copy_styles.py  --config c.json --from a --to-prefix b- --only "&._m"
+wp eval-file tools/theme_export.php active > theme.json
+wp eval-file tools/theme_import.php theme.json "名稱" rebind activate
+```
+
+`sites/_moksa.py` 是完整範例：一個真實工作室的首頁——刊頭、規格區塊、服務、九列作品表格、
+流程、技術堆疊、產品、客戶見證、聯絡——**590 個節點全部透過資料表寫入**，
+還有一個用具名 view timeline 做的、會跟著捲動的條款索引，完全沒有 JavaScript。
+
+## 從哪裡開始讀
+
+1. `references/data-model.md` —— 頁面到底住在哪裡。
+2. `references/write-protocol.md` —— checkout / check / commit。
+3. `references/failure-modes.md` —— Mosaic 怎麼壞的，都是量出來的。**動筆前先讀。**
+4. `references/responsive.md` —— state / breakpoint / property 這個軸。
+5. `references/styling.md` —— 一個樣式值怎麼變成 CSS。
+6. `references/design-system.md` —— element class 與設計 token。
+
+## 授權
+
+MIT。Mosaic Pro 本身是有授權的第三方軟體，**不包含**在這個 repo 裡。