mosaic-headless 1.21.2 → 1.23.0

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 (126 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.21.2"
+version: "1.23.0"
 ---
 
 # Headless Mosaic
@@ -533,6 +533,7 @@ so the pattern is in the data, not just in this paragraph.
 | `data/navigation-verification.csv` | 46 | **fetched and opened live** - every menu item is a real `<a href>`, every page of the nineteen answers 200, and no page scrolls sideways at 390 / 768 / 1280 |
 | `data/page-modal-verification.csv` | 19 | **read live** - one modal per page, and what each one's trigger, run rule, memory scope and dismissal policy actually came out as |
 | `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/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` |
@@ -807,11 +808,13 @@ post — `build_all.py` resets first for that reason.
 | `verify_slider.py` | the slider in a real browser: does it advance, do the arrows and bullets drive it, does the keyboard, does it stop when motion is not wanted |
 | `verify_navigation.py` | a multi-page site: is every menu item a real `<a href>`, does every page answer 200 (a template that was never bound answers 406 with an empty body, which only a logged-out visitor sees), and with `--viewports` does any page scroll SIDEWAYS - the one question no per-page checker asks |
 | `verify_dialog.py` | the 1.0.9 modal in a real browser: does it open, close, answer Esc, remember, cap - and does an OpenStreetMap carry the coordinates it was given |
+| `verify_dialog_lab.py` | the question after "does the modal work": can three nodes be made into a bottom sheet, a side drawer, a corner notice, a full takeover and a gate with no way out - and does each one still fit at phone width, which the page's own width check cannot see |
 | `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 |
 | `mint_session.php` | a matching cookie + `wp_rest` nonce from WP-CLI |
+| `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 |
 
 ## Regenerating everything
 
@@ -823,6 +826,12 @@ python tools/extract_default_children.py <plugin-root> data/
 python tools/extract_style_properties.py <plugin-root> data/
 python tools/extract_interactions.py     <plugin-root> data/
 python tools/extract_dynamic_variables.py <plugin-root> data/
+
+# and then, always: a table extracted BEFORE its extractor was repaired keeps
+# describing the old source and ships silently. Row counts cannot see it and the
+# release gate never sees the plugin. Run this after ANY change to an extractor,
+# not only after a plugin upgrade.
+python tools/check_tables.py              <plugin-root>
 python tools/capture_live.py             data/          # from data/raw/*.json + db-columns.txt
                                                         # (raw dumps are gitignored;
                                                         #  re-capture from a live site)

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.21.2"
+    "version": "1.23.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.21.2"
+    "version": "1.23.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.21.2"
+    "version": "1.23.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.21.2"
+    "version": "1.23.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.21.2"
+    "version": "1.23.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/dialog-form-verification.csv

@@ -0,0 +1,50 @@
+check,result,detail
+HOST/centre,PASS,"['dialog', 'everything']"
+HOST/sheet,PASS,"['dialog', 'clickOutside']"
+HOST/drawer,PASS,"['dialog', 'esc']"
+HOST/toast,PASS,"['dialog', 'everything']"
+HOST/takeover,PASS,"['dialog', 'everything']"
+HOST/gate,PASS,"['dialog', 'nothing']"
+HOST/exit,PASS,"['dialog', 'everything']"
+HOST/depth,PASS,"['dialog', 'clickOutside']"
+HOST/aba,PASS,"['dialog', 'everything']"
+HOST/abb,PASS,"['dialog', 'everything']"
+TOAST/pageLoad,PASS,opened on load
+TOAST/overlay-synthesised,PASS,authored none; heal inserted one
+TOAST/aria-modal-unavoidable,PASS,aria-modal='true' despite no authored overlay
+TOAST/top-right,PASS,x=911 y=114 w=330 vw=1280
+TOAST/wheel-blocked,PASS,"a corner toast is a LAYOUT, not a non-blocking modal"
+CLOSED_IS_HIDDEN,PASS,every closed modal is display:none
+CENTRE/centred,PASS,x=385 w=520 vw=1280
+CENTRE/aria-modal,PASS,aria-modal='true' (overlay=True)
+CENTRE/esc-closes,PASS,closedby=everything
+SHEET/at-bottom,PASS,y+h=900 vh=900
+SHEET/wide,PASS,w=720
+SHEET/esc-does-nothing,PASS,"closedby=clickOutside, so Esc must not close it"
+DRAWER/right-edge,PASS,x+w=1265  layer right=1265
+DRAWER/full-height,PASS,h=900 vh=900
+DRAWER/esc-closes,PASS,closedby=esc
+TAKEOVER/fills-viewport,PASS,1265x900 vs layer 1265x900
+GATE/esc-refused,PASS,closedby=nothing
+GATE/outside-refused,PASS,clicking the overlay must not close it
+GATE/button-closes,PASS,the modalClose inside is the only exit
+DEPTH/shut-at-rest,PASS,
+DEPTH/opens-past-75,PASS,scrollDepth threshold 75%
+EXIT/opens,PASS,exitIntent is desktop-only and synthetic leave is approximate
+LATCH/record-abb,PASS,"{""counter"":1,""firstAt"":1791091416059,""lastAt"":1791091416059,""lastID"":""2c17cec6-3"
+LATCH/B-first-wins,PASS,"6/6 as predicted, 0 lost clicks  {'abb>abb,aba>none': 6}"
+LATCH/record-aba,PASS,"{""counter"":1,""firstAt"":1791091466323,""lastAt"":1791091466323,""lastID"":""031d462e-7"
+LATCH/A-first-wins,PASS,"6/6 as predicted, 0 lost clicks  {'aba>aba,abb>none': 6}"
+LATCH/order-decides,PASS,"the winner flips with click order, so it is the first EVALUATED, not the first authored"
+FIT390/centre,PASS,scrollW=349/349 childOverflow=0 pageScrollsSideways=False
+FIT390/sheet,PASS,scrollW=373/373 childOverflow=0 pageScrollsSideways=False
+FIT390/drawer,PASS,scrollW=350/350 childOverflow=0 pageScrollsSideways=False
+FIT390/takeover,PASS,scrollW=375/375 childOverflow=0 pageScrollsSideways=False
+FIT390/gate,PASS,scrollW=349/349 childOverflow=0 pageScrollsSideways=False
+FIT390/aba,PASS,scrollW=349/349 childOverflow=0 pageScrollsSideways=False
+FIT768/centre,PASS,scrollW=518/518 childOverflow=0 pageScrollsSideways=False
+FIT768/sheet,PASS,scrollW=718/718 childOverflow=0 pageScrollsSideways=False
+FIT768/drawer,PASS,scrollW=399/399 childOverflow=0 pageScrollsSideways=False
+FIT768/takeover,PASS,scrollW=753/753 childOverflow=0 pageScrollsSideways=False
+FIT768/gate,PASS,scrollW=458/458 childOverflow=0 pageScrollsSideways=False
+FIT768/aba,PASS,scrollW=438/438 childOverflow=0 pageScrollsSideways=False

package/data/interaction-rules-verification.csv

@@ -0,0 +1,18 @@
+subject,case,result,detail
+pickOne,"12 fresh loads, remember=page",PASS,exactly one of the three modals opened every time; 4/6/2 across the group
+pickOne,"8 reloads of one tab, remember=page",PASS,re-drawn on every load: 6/1/1
+pickOne,"8 reloads of one tab, remember=forever",PASS,the same contender all 8 times
+pickOne,"6 fresh browser contexts, remember=forever",PASS,draws again in a new context: 1/3/2 - the record is per browser profile
+pickOne,storage record,PASS,"mos:v1:r:<name> gains lastID, naming the contender the draw chose"
+pickOne,"two buttons, group dl-ab, click B then A",PASS,"B opens, A then does nothing - 6/6 fresh visitors"
+pickOne,"same two buttons, click A then B",PASS,"A opens, B then does nothing - 6/6; the winner flips with the ORDER"
+pickOne,both interactions on ONE button,PASS,the same contender 14/14 - one evaluates first and records itself
+pickOne,what the rule actually does,PASS,"draws among contenders that evaluate TOGETHER; a click delivers one at a time, so click+pickOne is a latch, not a lottery"
+targetModifiers,plain element,PASS,"[{""type"":""all"",""selector"":""._e""}]"
+targetModifiers,plain variant,PASS,"[{""type"":""all"",""selector"":""h2,.m-heading-2""}] - a variant resolves to its own selectors"
+targetModifiers,children(variant),PASS,"appends {""type"":""children"",""selector"":""h2,.m-heading-2""}"
+targetModifiers,sibling(variant),PASS,"appends {""type"":""sibling"",...}"
+targetModifiers,parent(variant),PASS,"appends {""type"":""parent"",...}"
+targetModifiers,include(element),PASS,"appends {""type"":""include"",...}"
+targetModifiers,exclude(element),PASS,"appends {""type"":""exclude"",...}"
+targetModifiers,children then exclude,PASS,"three entries, in the order written - the list is a pipeline, not a filter set"

package/data/value-coercion-verification.csv

@@ -0,0 +1,13 @@
+validator,probed_on,sent,result,note
+ValidatorInteger,maxlength on textarea-input,"""12""",12,accepted
+ValidatorInteger,maxlength on textarea-input,"""12abc""",12,"trailing garbage ignored - parseInt semantics, new in 1.0.9"
+ValidatorInteger,maxlength on textarea-input,"""abc""",(absent),"no leading digits, rejected"
+ValidatorInteger,maxlength on textarea-input,"""-5x""",(absent),"parses to -5, then refused by the property's own min:0 - the parser accepted it"
+ValidatorInteger,maxlength on textarea-input,""" 7 """,7,leading and trailing whitespace tolerated
+ValidatorInteger,maxlength on textarea-input,"""0012""",12,"leading zeros are decimal, not octal"
+ValidatorInteger,maxlength on textarea-input,"""1e3""",1,NOT 1000 - the exponent is trailing garbage
+ValidatorInteger,maxlength on textarea-input,"""12.9""",12,"truncated toward zero, not rounded"
+stretch,width,"""stretch""",width:-webkit-fill-available then width:stretch,"both emitted, prefix first"
+stretch,height,"""stretch""",height:-webkit-fill-available then height:stretch,both emitted
+stretch,maxWidth,"""stretch""",max-width:-webkit-fill-available then max-width:stretch,both emitted
+stretch,width,"""STRETCH""",width:STRETCH,"kept as typed - the match is case-sensitive, and CSS keywords are not, so it still applies"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.21.2",
+  "version": "1.23.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/dialog-and-triggers.md

@@ -33,9 +33,23 @@ delivers
 </dialog>
 ```
 
-- **`aria-modal="true"` is emergent, not authored.** It appears exactly when the
-  modal has an overlay child, because the overlay is what actually blocks the page.
-  No overlay, no `aria-modal`.
+- **`aria-modal="true"` is emergent, not authored — and you cannot shed it.**
+  The render sets it exactly when the modal has an overlay child, because the
+  overlay is what actually blocks the page. An earlier version of this page drew
+  the obvious conclusion — *no overlay, no `aria-modal`* — and that conclusion is
+  **wrong**, because the overlay-less modal is unreachable. A modal committed with
+  no `modal-overlay` child comes back from the server with one: `onHeal()` inserts
+  it at the end of the child order, and the source says why — *"the overlay is a
+  required structural part — non-deletable, one per Modal"*. The synthetic one
+  carries no style token and no id, which is the only way to tell it from an
+  authored one.
+
+  Measured on a modal authored with no overlay: the delivered HTML contains
+  `<div class="m-modal-overlay" tabindex="-1">`, the host carries
+  `aria-modal="true"`, and a real wheel event over the page moves it 0px while the
+  same page scrolls 700px with nothing open. **There is no non-blocking modal in
+  1.0.9.** A corner notice that must not trap the reader has to be built from
+  ordinary nodes, not from `modal`.
 - **`closedby` is `everything` | `clickOutside` | `esc` | `nothing`**, and it is
   emitted as `data-mosaic-modal-closedby`, NOT as the native `closedby` attribute —
   Mosaic opens the host with `show()`, where the native light-dismiss does not
@@ -119,6 +133,63 @@ What that writes, measured: `localStorage` **and** `sessionStorage`, both under
 that opens a second tab to prove a cap is testing nothing — reload the same tab.
 That mistake made the cap look broken here until the tab was reused.
 
+### `pickOne`, measured
+
+`pickOne` is the one rule that is about a GROUP rather than one interaction, and the
+group is the `name`: give three modals the same `name` and exactly one of them opens.
+Three `pageLoad` modals sharing `probe-pick` were loaded repeatedly:
+
+| what | result |
+|---|---|
+| 12 fresh browser contexts, `remember: "page"` | one modal every time, 4 / 6 / 2 across the three |
+| 8 reloads of the SAME tab, `remember: "page"` | re-drawn each load — 6 / 1 / 1 |
+| 8 reloads of the same tab, `remember: "forever"` | the same contender all 8 times |
+| 6 fresh contexts, `remember: "forever"` | draws again — 1 / 3 / 2 |
+
+No load ever opened more than one. So `remember` on `pickOne` does not mean "how long
+until it may run again", it means **how long the draw is kept**: `page` re-rolls on
+every navigation, `session` and `forever` hand one visitor the same variant each time
+— which is the whole point, since a popup that changes on reload reads as a bug. The
+last row is the limit worth knowing: `forever` is localStorage, so it is per browser
+profile, and a fresh context is a fresh visitor who draws again.
+
+The record gains one field for this: alongside `counter` / `firstAt` / `lastAt`,
+`mos:v1:r:<name>` carries **`lastID`**, the uuid of the interaction that won the draw.
+That is what makes the choice stick, and it is also how you read the drawn variant
+back in a test without inspecting which modal is open.
+
+`data/interaction-rules-verification.csv` has the runs.
+
+### …and what `pickOne` does on a trigger that is NOT `pageLoad`
+
+Run rules apply to any `timed` interaction, and `click` is one, so the obvious
+next question is whether a click-driven `pickOne` is also a lottery. It is not,
+and the difference matters enough to state as a rule:
+
+> **`pickOne` draws among the contenders that evaluate TOGETHER.**
+
+`pageLoad` schedules every member of the group in the same pass, so the draw has
+a real field and a real winner. A click delivers one contender at a time: the
+first one to evaluate records itself and every other member of the group is then
+suppressed for as long as `remember` holds.
+
+Measured with two buttons, one modal each, both carrying the group `dl-ab`, six
+fresh visitors each way:
+
+| order clicked | result |
+|---|---|
+| B then A | B opens, then A does nothing — 6/6 |
+| A then B | A opens, then B does nothing — 6/6 |
+
+The winner flips with the click order, so it is the first *evaluated*, not the
+first authored. An earlier attempt with both interactions on ONE button drew the
+same contender 14 times out of 14, which is the same fact seen from a worse angle.
+
+So click + `pickOne` is a **latch**, not an A/B test: *whichever of these the
+visitor takes first, the others stop offering.* That is genuinely useful — one of
+several calls to action, a first-choice-wins offer — but if you want to split an
+audience, the rule has to sit on `pageLoad`.
+
 ## Memory: remember / forget
 
 Two actions that write and clear the same records a run rule reads, so one
@@ -303,3 +374,49 @@ The pattern is worth stating on its own: because the trigger lives in the modal'
 own `interactionShorthand`, a page's popup policy is one object in that page's data.
 Nothing else on the page changes, no trigger element is placed, and two pages of the
 same site can behave completely differently without sharing anything.
+
+## Five forms out of three nodes — and the one property you must not set
+
+"A modal" in most builders means one centred card, because the builder owns the
+chrome. Mosaic owns none of it: `.m-modal` is a `position:fixed; inset:0` layer
+with `pointer-events:none`, `.m-modal-overlay` is a second fixed layer that takes
+pointer events back, and `.m-modal-window` is an ordinary child of the first. The
+form is decided by where the window is pinned inside that layer.
+
+**Never set `display` on the `modal` host.** A `<dialog>`'s open/closed visibility
+*is* its display property — the UA stylesheet hides it with
+`dialog:not([open]) { display: none }` — so an author-level `display:flex` on the
+host wins the cascade and every modal on the page is permanently on screen. It is
+a tempting thing to write, because flex centring is the obvious way to place the
+window, and it fails in a way that no open-state check can see: a page built this
+way passed 36 of 36 modal checks while all ten of its dialogs sat open in the
+document. Lay the forms out by positioning the WINDOW instead, which leaves
+`display` alone:
+
+| form | host | window (`position:absolute`) |
+|---|---|---|
+| centred card | padding only | `top:50%; left:50%` + `translateX(-50%) translateY(-50%)`, `max-width` |
+| bottom sheet | no side/bottom padding | `left:0; right:0; bottom:0`, `margin-inline:auto`, `max-width` |
+| side drawer | no top/bottom/right padding | `top:0; right:0; bottom:0`, `max-width` |
+| corner notice | no padding | `top:90px; right:24px`, a small `max-width` |
+| full takeover | no padding | `top:0; right:0; bottom:0; left:0`, `max-width:none` |
+
+`transform` is a structured value, so the centring pull-back is two entries
+(`translateX`, `translateY`), not a string — `references/styling.md` has the shape.
+
+All five were built on one page and driven in a browser — 49 checks in
+`data/dialog-form-verification.csv`, written by `tools/verify_dialog_lab.py`,
+whose first assertion is now that a CLOSED modal has no box at all. Three more
+things that only showed up by building them:
+
+- **Measure the window against the LAYER, not the viewport.** `.m-modal` is inset
+  into the viewport *minus the scrollbar*, so a drawer flush against the right
+  edge sits at `innerWidth - 15` and a naive check calls it a 15px gap. Compare
+  the window's rect to the host's rect.
+- **Give `modal-window` `overflow: auto` and `max-height: 100%`.** Mosaic has no
+  `overflowX`/`overflowY` — only the shorthand — and without it a tall dialog
+  grows past the viewport instead of scrolling inside itself.
+- **A page that passes a width check says nothing about its modals.** They are a
+  layer that only exists once something opens them, so the document underneath can
+  measure clean at 390px while a takeover with desktop padding overflows. The
+  verifier re-opens every form at each `--viewports` width for this reason.

package/references/failure-modes.md

@@ -294,3 +294,53 @@ The other half of this finding is about the checkers: WordPress's "critical erro
 page is 2,697 bytes, above the 2,000-byte healthy floor, and `Client.page()` was
 returning an HTTPError's body as the page - so `build_site` announced `OK` over a
 500 and a whole batch believed it. A 5xx now returns an empty body.
+
+## A shipped table can be stale rather than wrong
+
+The failure this skill nearly shipped three times in a row is not a bad value, it is
+an old one. `data/node-types.csv` carried an empty `default_element_class` for three
+releases: the column's regex was repaired AFTER the extraction run that produced the
+table, so the file went on describing the previous source and nothing compared the
+two again.
+
+Nothing in place could see it. Row counts were right the whole time — the table had
+the correct number of rows, with one column quietly blank. The release gate counts
+verification tables but never sees the plugin source, because that source is licensed
+third-party code and is not in the repository, so it cannot re-derive anything. And a
+reader of the skill has no way to tell a legitimately-empty column from a lost one.
+
+`tools/check_tables.py` closes it: it re-runs all seven extractors into a tempdir and
+diffs every output against the shipped file, naming the first differing line rather
+than just the filename. The moment to run it is **after any change to a
+`tools/extract_*.py`**, not only after a plugin upgrade — the upgrade is the case
+everyone remembers.
+
+The general shape, worth carrying beyond this repo: a derived artifact checked into
+the tree is only as fresh as the last time someone re-derived it, and if the deriving
+input is not in the tree, no amount of CI will notice.
+
+## Setting `display` on a `<dialog>` pins it open, and open-state checks cannot see it
+
+The modal host is a `<dialog>`. Its open/closed visibility is not a class or an
+attribute Mosaic manages — it is the UA stylesheet rule
+`dialog:not([open]) { display: none }`. Any author-level `display` on that element
+wins the cascade, and every modal in the document is then on screen permanently,
+stacked over the page in DOM order.
+
+`display:flex` on the host is exactly what you reach for when you want to centre
+the window, so this is not an exotic mistake. What makes it worth its own section
+is that **it survives a thorough test suite**: 36 checks drove the modals' triggers,
+run rules, dismissal policies and geometry, every one of them PASSED, and the page
+they passed against had all ten of its dialogs open at once. Every check asked
+"when this is open, is it right?" — none asked "when it is closed, is it gone?"
+
+Two rules come out of it:
+
+- **Lay a modal's form out by positioning the window** (`position:absolute` plus
+  edges inside the fixed, `inset:0` host), never by making the host a flex or grid
+  container.
+- **Assert the closed state.** `tools/verify_dialog_lab.py` now closes everything
+  first and fails if any `dialog:not([open])` still has a box. The general form of
+  that lesson: for anything with a visible and an invisible state, a suite that
+  only exercises the visible one is testing half a component, and the half it
+  skips is the one the visitor sees most of the time.

package/references/interactions.md

@@ -143,6 +143,39 @@ Mosaic also *added* a `uuid` of its own. So on this data model:
 
 That check is worth applying to any deeply-nested Mosaic write, not just interactions.
 
+## Aiming an action somewhere else: `targetModifiers`
+
+Every pluggable action takes a `settings.target`, and a target is either
+`{"type": "element", "uuid": "<nodeID>"}` or `{"type": "variant", "uuid": "<variantID>"}`.
+`settings.targetModifiers` then narrows or widens it — a list of
+`{"uuid", "type", "data"}` where `data` is another target of the same two shapes and
+`type` is one of `children`, `sibling`, `parent`, `include`, `exclude`.
+
+The thing worth knowing is what that compiles to. The page hands the runtime a
+`targetSelectorData` **pipeline**: one entry for the base target, then one per
+modifier, applied in the order written.
+
+```
+plain element                 [{"type":"all","selector":"._e"}]
+plain variant                 [{"type":"all","selector":"h2,.m-heading-2"}]
+element + children(variant)   [{"type":"all","selector":"._e"},
+                               {"type":"children","selector":"h2,.m-heading-2"}]
+element + sibling(variant)    [... {"type":"sibling",   ...}]
+element + parent(variant)     [... {"type":"parent",    ...}]
+variant + include(element)    [... {"type":"include",   ...}]
+variant + exclude(element)    [... {"type":"exclude",   ...}]
+children then exclude         three entries, in that order
+```
+
+Two consequences. A **variant target resolves to the variant's own CSS selectors**,
+so "every H2" costs you nothing — you do not have to enumerate nodes. And because it
+is a pipeline rather than a filter set, **order matters**: `children` then `exclude`
+excludes from the children, while the reverse excludes from the base and then
+descends. Write the modifiers in the order you want them applied.
+
+All eight shapes above were committed and read back from the delivered page;
+`data/interaction-rules-verification.csv` has them.
+
 ## The surface, extracted
 
 `data/interaction-types.csv` — 12 trigger types in two families:

package/references/styling.md

@@ -184,3 +184,32 @@ down — at the cost of bypassing the collection-variable layer entirely.
 
 `tools/build_page.py` wraps the five shapes above as `radius`, `shadow`,
 `transitionAll`, `move` and `border` shorthands so a design spec cannot get them wrong.
+
+## Properties that exist in CSS but not in Mosaic
+
+`data/style-properties.csv` is the whole registry, and the fastest way to lose an
+hour is to assume a property is in it because CSS has it. Two that catch people,
+both found by writing a page rather than by reading the table:
+
+**`flexGrow` and `flexShrink` do not exist.** Mosaic models both as one
+type-switched group, `flexSizing`:
+
+```jsonc
+"flexSizing": {"type": "grow"}     // flex-grow:1; flex-shrink:0
+"flexSizing": {"type": "shrink"}
+"flexSizing": {"type": "none"}     // the fixed-width column in a flex row
+"flexSizing": {"type": "custom", "customOptions": {…}}
+```
+
+`none` is what you want for a label column that must not be squeezed, and `grow`
+for the cell that takes the slack — the pair that `flex-shrink:0` / `flex-grow:1`
+would have been.
+
+**There is no `overflowX` or `overflowY`** — only the shorthand `overflow`, with
+`visible | hidden | clip | scroll | auto`. One axis at a time is not expressible
+through the style system; it needs `customDeclarations`.
+
+Both of these are refused at build time by `build_page.py` rather than silently
+dropped, which is the only reason they cost minutes instead of a debugging session
+— a property that is not in the registry cannot be set at all, and Mosaic's own
+API accepts the write and discards it.

package/references/write-protocol.md

@@ -77,3 +77,34 @@ A failed validator does not return an HTTP error. The response is a
 `RESTJSONExceptionEnvelope`: HTTP 200 with an `exceptions` array in the body. Code
 that only checks the status code will report a clean save on a rejected write.
 Always read `exceptions` before believing a commit landed.
+
+## Validators coerce before they reject — a number need not arrive as a number
+
+Silent rejection is the documented hazard, but the quieter one is silent *acceptance*
+of something other than what you sent. As of 1.0.9 `ValidatorInteger` mirrors
+JavaScript's `parseInt()`: it takes the leading integer and discards the rest, where
+the previous release fell back to PHP's `intval()` and treated a zero result as a
+failure. Measured on `textarea-input`'s `maxlength`:
+
+| sent | stored | |
+|---|---|---|
+| `"12"` | 12 | |
+| `" 7 "` | 7 | whitespace tolerated |
+| `"0012"` | 12 | decimal, not octal |
+| `"12abc"` | **12** | trailing garbage ignored |
+| `"12.9"` | **12** | truncated toward zero, not rounded |
+| `"1e3"` | **1** | **not** 1000 — the exponent is trailing garbage |
+| `"abc"` | absent | no leading digits |
+| `"-5x"` | absent | parsed fine as −5; refused by the property's own `min: 0` |
+
+`"1e3"` is the row to remember: a value that looks numeric to a human, is numeric to
+`floatval()`, and lands as 1. A typo in a unit (`"16px"` where a bare integer was
+wanted) likewise stores 16 and never complains. Send integers as integers, and read
+the row back when you did not.
+
+The companion change is `ValidatorMimeType`, which now accepts any number of media
+type parameters including quoted values containing spaces — so
+`video/mp4; codecs="avc1.42E01E, mp4a.40.2"` is valid where 1.0.8 rejected it.
+
+`data/value-coercion-verification.csv` has these runs, along with the `stretch`
+keyword's emitted declarations.

package/scripts/check-release.mjs

@@ -102,6 +102,9 @@ const counts = {
   "data/slider-verification.csv": 19,
   "data/navigation-verification.csv": 46,
   "data/page-modal-verification.csv": 19,
+  "data/interaction-rules-verification.csv": 17,
+  "data/dialog-form-verification.csv": 49,
+  "data/value-coercion-verification.csv": 12,
 };
 for (const [file, expected] of Object.entries(counts)) {
   if (!fs.existsSync(path.join(ROOT, file))) { fail(`${file} missing`); continue; }

package/sites/_moksa.py

@@ -26,6 +26,7 @@ Run from this directory: python _moksa.py
 """
 import json
 import os
+import sys
 import uuid
 
 # Monospace leads. The grotesque is the display face and appears at three sizes only;
@@ -247,7 +248,8 @@ def mask_line(attr, text, tag="h1", **st):
 
 # ── content, all of it Moksa Web's own ───────────────────────────────────────
 NAV = [("服務", "#services"), ("作品", "#works"),
-       ("產品", "#products"), ("聯絡", "#contact")]
+       ("產品", "#products"), ("彈窗", "/dialogs/"),
+       ("聯絡", "#contact")]
 
 # key / figure / caption, read as a datasheet rather than as four big numbers
 SPEC = [
@@ -3050,6 +3052,15 @@ def clean(node):
 
 if __name__ == "__main__":
     here = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, here)
+    # Deferred on purpose. `_dialogs` imports this module's helpers, so importing
+    # it at the top would be circular; down here the file re-imports cleanly as
+    # `_moksa` (this copy is `__main__`), its own main block does not run, and the
+    # helpers it reads are pure functions - two copies produce identical dicts.
+    import _dialogs
+    SITE["pages"].append({"slug": "dialogs", "post_id": 268,
+                          "title": "彈窗實驗室",
+                          "tree": apply_type(_dialogs.TREE, DISPLAY, CJK, "600")})
     path = os.path.join(here, "moksa.json")
     with open(path, "w", encoding="utf-8") as fh:
         json.dump(clean(SITE), fh, indent=1, ensure_ascii=False)