mosaic-headless 1.19.0 → 1.20.0

package/data/variants.csv

@@ -143,11 +143,15 @@ eb830eeb-7a4e-05b7-9363-13f3d57d77a8,Cite,m-gutenberg-pullquote-cite,False,tag,"
 760f938d-5475-48de-a776-6a956df43d53,Outline button,m-gutenberg-outline-button,False,tag,":is(.entry-content, .wp-block-post-content) .wp-block-button__link:where(div.wp-block-button.is-style-outline > a.wp-element-button.wp-block-button__link)",,False,True,True,b1H
 8de49a77-f767-0054-b1ac-e913ac6562ba,Video,m-video,True,,.m-video,,False,True,False,b1I
 c637b22c-61b9-0964-bcdb-d5ae0d16986a,Google Maps,m-google-maps,True,,.m-google-maps,,False,True,False,b1J
-0dce60de-c4a6-0a2d-9990-b93070aeb7da,YouTube,m-youtube,True,,.m-youtube,,False,True,False,b1K
-be107226-ba10-0fc6-b22e-f984fb21d63b,Vimeo,m-vimeo,True,,.m-vimeo,,False,True,False,b1L
-ea692231-151b-02df-bea7-d567347d1422,List,m-list,True,,.m-list,,True,True,False,b1M
-69a8ab3f-dbdf-09bd-8449-6420570155b8,Horizontal list,m-list-horizontal,True,,.m-list-horizontal,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1N
-3a8cfda3-1ded-0a3c-9e55-b56510827850,Unordered list,m-list-unordered,True,,.m-list-unordered,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1O
-7dbba514-fd83-0e8f-ac46-68e6f651f2ff,Ordered list,m-list-ordered,True,,.m-list-ordered,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1P
-1864859b-2942-44db-b09d-c7073d1df01e,Item,m-list-item,True,,.m-list-item,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1Q
-fb0c2625-dd5a-43c5-82e2-22e8c09ca06c,Loop items,m-list-loop-items,True,,.m-list-loop-items,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1R
+1a360ae2-3d10-017a-9db6-cece7b44ce17,OpenStreet​Map,m-osm,True,,.m-osm,,False,True,False,b1K
+0dce60de-c4a6-0a2d-9990-b93070aeb7da,YouTube,m-youtube,True,,.m-youtube,,False,True,False,b1L
+be107226-ba10-0fc6-b22e-f984fb21d63b,Vimeo,m-vimeo,True,,.m-vimeo,,False,True,False,b1M
+ea692231-151b-02df-bea7-d567347d1422,List,m-list,True,,.m-list,,True,True,False,b1N
+69a8ab3f-dbdf-09bd-8449-6420570155b8,Horizontal list,m-list-horizontal,True,,.m-list-horizontal,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1O
+3a8cfda3-1ded-0a3c-9e55-b56510827850,Unordered list,m-list-unordered,True,,.m-list-unordered,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1P
+7dbba514-fd83-0e8f-ac46-68e6f651f2ff,Ordered list,m-list-ordered,True,,.m-list-ordered,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1Q
+1864859b-2942-44db-b09d-c7073d1df01e,Item,m-list-item,True,,.m-list-item,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1R
+fb0c2625-dd5a-43c5-82e2-22e8c09ca06c,Loop items,m-list-loop-items,True,,.m-list-loop-items,ea692231-151b-02df-bea7-d567347d1422,False,True,False,b1S
+d1a109c7-3b52-04ef-9a6c-11e0dc0d1a70,Modal,m-modal,True,,.m-modal,,False,True,False,b1T
+d1a1090d-6e4f-04ef-9a6c-11e0dc0d1a71,Window,m-modal-window,True,,.m-modal-window,d1a109c7-3b52-04ef-9a6c-11e0dc0d1a70,False,True,False,b1U
+d1a10004-e51a-04ef-9a6c-11e0dc0d1a72,Overlay,m-modal-overlay,True,,.m-modal-overlay,d1a109c7-3b52-04ef-9a6c-11e0dc0d1a70,False,True,False,b1V

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.19.0",
+  "version": "1.20.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

@@ -0,0 +1,201 @@
+# Modal, OpenStreetMap, the new triggers and run rules (1.0.9), measured
+
+1.0.9 is the first release since this skill began that adds *features* rather than
+renaming things: four node types, three interaction triggers, a rule engine that
+decides whether a trigger is allowed to run, two memory actions, and a shorthand
+that collapses "open this modal when …" into one object.
+
+Everything below was built on the live site and read back out of the delivered page
+or out of the browser. `data/dialog-verification.csv`, 19 checks, all passing.
+
+## Modal — a real `<dialog>`
+
+Three node types: `modal`, and inside it `modal-window` and `modal-overlay`.
+
+```json
+{"type": "modal", "nodeID": "<uuid you mint>",
+ "data": {"role": "dialog", "accessibleLabel": "Feature probe dialog",
+          "closedby": "everything"},
+ "children": [
+   {"type": "modal-overlay", "data": {}},
+   {"type": "modal-window", "style": {"&": {"_": {"flexDirection": "column"}}},
+    "children": [ … ]}]}
+```
+
+delivers
+
+```html
+<dialog class="m-modal M_Dialog M_IJ _g" id="pr-modal" role="dialog"
+        aria-label="Feature probe dialog" aria-modal="true"
+        data-mosaic-modal-closedby="everything">
+  <div class="m-modal-overlay _h" tabindex="-1"></div>
+  <div class="m-modal-window _i" tabindex="-1"> … </div>
+</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`.
+- **`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
+  apply, so its own controller reads the attribute. Measured: with `everything`,
+  Esc closes it. `nothing` is the cookie-gate case, where the only way out is a
+  `modalClose` action you place yourself.
+- **`role` has no default.** A `<dialog>` already carries an implicit dialog role;
+  the property only emits when you set one (`dialog`, `alertdialog`).
+- **`accessibleLabel` always emits `aria-label`**, empty if you leave it blank — so
+  an unlabelled modal ships an empty accessible name. Set it.
+- **`modal-window` arrives as `display:flex`, row.** Three children in a row squeeze
+  a `width: max-content` button to zero and Playwright reports it as not visible,
+  which is what a reader would see too. Set `flexDirection: "column"`.
+
+## Opening and closing it
+
+`modalOpen` and `modalClose` are interaction actions. Their target is the modal's
+**node id**, not its `attrID`:
+
+```json
+{"type": "modalOpen", "uuid": "<uuid>",
+ "settings": {"target": {"type": "element", "uuid": "<the modal's node id>"}}}
+```
+
+which the page resolves to `{"targetSelectorData": [{"type": "all", "selector": "._g"}]}`
+— the modal's generated class. Two consequences:
+
+- **The spec has to know the node id before either node is written**, because the
+  button and the modal are committed in the same pass. `build_page.py` takes a
+  `nodeID` on any spec node for exactly this.
+- **That id must be unique in the THEME, not the document.** `wp_mosaic_nodes`'
+  primary key is `(ID, themeID)`, so a hard-coded id collides with whatever an
+  earlier build left behind — the commit answers HTTP 500 on a duplicate key. Mint
+  it per run.
+
+`type` accepts `element`, `variant` or `universalClass` — the last two aim an action
+at every element of a class.
+
+## The three new triggers
+
+| id | family | fires | default settings |
+|---|---|---|---|
+| `exitIntent` | timed | the pointer leaves the page through the top. **Desktop only** — it never runs on a touch device | `awayFor: 600ms` |
+| `scrollDepth` | timed | the visitor scrolls this far down | `threshold: 50%` |
+| `modal` | timed | the modal opens or closes | — |
+
+They are ordinary interaction types, so they take the envelope the rest of the
+language uses (`references/interactions.md`). The interaction type list is also
+re-grouped in 1.0.9 — Mouse / Page & scroll / Element events — which changes the
+`family` column of `data/interaction-types.csv` and nothing else.
+
+## Run rules: how often a trigger may run
+
+A timed interaction can carry `runs`, and that is what makes a popup shippable:
+
+```json
+"runs": {"rules": [{"uuid": "<uuid>", "type": "cap",
+                    "capOptions": {"max": "1", "remember": "session",
+                                   "name": "probe-exit-modal"}}]}
+```
+
+| type | options | what it means |
+|---|---|---|
+| `cap` | `max` | run at most N times |
+| `cooldown` | `duration`, `durationUnit` | wait this long between runs |
+| `firstRunWindow` | `duration`, `durationUnit` | only within this long of the first run |
+| `pickOne` | — | one of several interactions sharing a name runs; the name is the group, so it is required here |
+
+`durationUnit` is `minute` | `hour` | `day`. `remember` is `page` | `session` |
+`forever`, and `name` must match `^[a-z][a-z0-9_-]*$` — a rule with a name outside
+that grammar is skipped rather than stored.
+
+What that writes, measured: `localStorage` **and** `sessionStorage`, both under
+`mos:v1:r:<name>`, holding `{"counter":1,"firstAt":<ms>,"lastAt":<ms>}`. Only
+`timed` interactions support run rules; a progress interaction has no "run" to count.
+
+**`remember: "session"` is sessionStorage, which browsers scope per TAB.** A test
+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.
+
+## Memory: remember / forget
+
+Two actions that write and clear the same records a run rule reads, so one
+interaction can decide what another is allowed to do.
+
+```json
+{"type": "remember", "uuid": "<uuid>",
+ "rememberOptions": {"settings": {"name": "probe-seen"}}}
+```
+
+**The `name` goes under `<type>Options.settings`.** Four other placements were
+committed and silently dropped — `rememberOptions.name`, `settings.name`,
+`rememberOptions.timelines._.name`, and a bare top-level `name` — and the action
+then runs as a no-op that writes nothing, because the source skips an unnamed
+memory rather than inventing a key. The server reshapes the accepted one into
+`rememberOptions.timelines._.name`, which is what the payload shows.
+
+## The interaction shorthand — modals only
+
+Every element's data can carry `interactionShorthand`, but `ModalElementMResourceData`
+is the only class that overrides `getInteractionShorthandActionTypes()` (it returns
+`['modalOpen']`), so it is the only element the shorthand does anything for. The
+feature is "open this modal when …" in the modal's own settings:
+
+```json
+"interactionShorthand": {
+  "type": "exitIntent",
+  "exitIntentOptions": {
+    "settings": {"awayFor": "400ms"},
+    "runs": {"rules": [{"uuid": "<uuid>", "type": "cap",
+                        "capOptions": {"max": "1", "remember": "session",
+                                       "name": "probe-exit-modal"}}]}}}
+```
+
+At render that expands into a full interaction on the modal itself — trigger from
+the type, action from the element — and the page's `mosaicInteractions` gains
+`{"type":"exitIntent","triggerSelector":"._0","action":{"exitIntent":{"actions":[{"type":"modalOpen"…`
+with the cap attached. No trigger element, no action, no target: an exit-intent
+popup that fires once a session is one object.
+
+`"type": "manual"` is the stored answer for "nothing opens this automatically" —
+spelled as a word rather than left absent, because absent means *inherit* on a
+component instance.
+
+The shorthand cannot carry conditions, and that is a property of the data shape
+rather than a rule to remember: it has no field for them.
+
+## OpenStreetMap
+
+`openstreetmap` renders `<mosaic-openstreetmap>` wrapping an `<iframe>` at
+openstreetmap.org's own embed endpoint. Five properties:
+
+| property | shape | values |
+|---|---|---|
+| `latitude`, `longitude` | **`{"v": "25.0330"}`** | −90..90, −180..180 |
+| `zoom` | **`{"v": "15"}`** | 0..19 |
+| `layer` | bare string | `mapnik`, `cyclosm`, `cyclemap`, `transportmap`, `hot` |
+| `lazyLoad` | bare string | `"0"` / `"1"` → `loading="lazy"` on the iframe |
+
+The first three carry `ValidatorDynamicCodeObject` in their chain, so they take the
+`{"v": …}` object form the rest of the dynamic language uses — a bare string is
+dropped and the map quietly shows its default location (Times Square) with no error
+anywhere. That is the skill's existing rule (`ValidatorDynamicCode` = bare string,
+`ValidatorDynamicCodeObject` = `{"v": …}`) applying to a new element, and it is also
+why those three can hold `@VAR('post/meta_lat')` and a custom field can drive the map.
+
+## What else moved in the delivered page
+
+**The three per-breakpoint stylesheets became one.** Through 1.0.8 a page carried
+`mosaic-theme-block-editor-styles_-inline-css`, `…_t-…` and `…_m-…`; 1.0.9 emits a
+single `mosaic-theme-document-styles-inline-css` with the breakpoints as `@media`
+blocks inside it. Any tool that read a breakpoint by block id reads nothing now —
+`document_styles()` in `tools/sweep_node_types.py` handles both, and the base is now
+"everything outside an at-rule" rather than "its own block".
+
+**An element whose styles compile to nothing gets no generated class.**
+`<div class="m-div" id="sp-015">` — no `_token`. On 1.0.8 every element had one. So
+the twenty inert grouped properties are now visible in the markup as well as absent
+from the CSS, and a checker must not read "no token" as "the node did not render".
+
+**`youtube`'s `privacy` property suppresses the element.** Set on its own it emits
+nothing at all, where 1.0.8 rendered the element and recorded NO_EFFECT. One row of
+`data/node-property-verification.csv`, the only `NO_OUTPUT` in the table.

package/tools/build_page.py

@@ -238,7 +238,15 @@ def flatten(node, parent_id, master_id, surface, force, ordering="a0", parent_ty
     if problems:
         raise SystemExit("refusing to build:\n  " + "\n  ".join(problems))
 
-    nid = str(uuid.uuid4())
+    # `nodeID` pins the node's own id instead of minting one. An interaction that
+    # targets another element stores that element's NODE id (`settings.target =
+    # {"type": "element", "uuid": <nodeID>}`), not its attrID, so the two have to be
+    # written in the same pass - there is no way to point at a node whose id the
+    # spec never sees. The id must be unique in the THEME, not the document:
+    # wp_mosaic_nodes' primary key is (ID, themeID), so a hard-coded one collides
+    # with whatever a previous build left behind and the commit 500s on a duplicate
+    # key. Mint it per run.
+    nid = node.get("nodeID") or str(uuid.uuid4())
     data = dict(node.get("data") or {})
     style = to_style(node.get("style"))
     if style:

package/tools/sweep_node_properties.py

@@ -132,7 +132,11 @@ def searchable(tag):
 def judge(prop, value, tag):
     """Did this property change the delivered markup the way it claims to?"""
     if tag is None:
-        return "NO_ELEMENT", ""
+        # The probe was committed and the page rendered, so the node exists; the
+        # property suppressed its own element's output. `youtube.privacy` does
+        # exactly this since 1.0.9 - on 1.0.8 the same probe rendered and read
+        # NO_EFFECT - so it is its own outcome, not a missing host.
+        return "NO_OUTPUT", "the element emitted nothing with this property set"
     body = searchable(tag)
     if prop == "cssClasses":
         return ("APPLIED" if MARK + "-cls" in tag else "NO_EFFECT"), tag[:110]
@@ -265,9 +269,21 @@ def main():
         # from an earlier run share the id space, and two runs can give the same id
         # to different node types. If the page does not carry exactly the probes
         # this run planned, nothing measured from it means anything.
-        sys.exit("expected %d probes on the page, found %d - clear previous probes "
-                 "and re-run before believing any measurement"
-                 % (len(live) - len(moved), rendered))
+        on_page = set(re.findall(r'id="(np-\d+)"', html))
+        extra = sorted(on_page - {attr for attr, _h, _p, _v in live})
+        # An id this run did not plan is contamination: two runs can give the same
+        # id to different node types and nothing measured from the page would mean
+        # anything. A probe that this run DID plan and that is simply not there is
+        # a result, not contamination - the property suppressed its own element -
+        # so it is recorded as NO_OUTPUT below instead of aborting the run.
+        if extra:
+            sys.exit("probes on the page that this run did not plan: %s\n"
+                     "clear them and re-run before believing any measurement"
+                     % ", ".join(extra))
+        missing = [(attr, host, prop) for attr, host, prop, _v in live
+                   if attr not in on_page and attr not in moved]
+        print("  %d planned probe(s) rendered nothing: %s"
+              % (len(missing), ", ".join("%s.%s" % (h, p) for _a, h, p in missing)))
 
     rows = []
     for attr, host, prop, value in live:
@@ -291,7 +307,7 @@ def main():
     for r in rows:
         counts[r[3]] = counts.get(r[3], 0) + 1
     print()
-    for k in ("APPLIED", "NO_EFFECT", "EDITOR_ONLY", "NO_ELEMENT", "NO_HOST",
+    for k in ("APPLIED", "NO_EFFECT", "NO_OUTPUT", "EDITOR_ONLY", "NO_ELEMENT", "NO_HOST",
               "INSTRUMENT", "SKIPPED"):
         if counts.get(k):
             print("  %-12s %d" % (k, counts[k]))

package/tools/sweep_node_types.py

@@ -117,6 +117,91 @@ def token_by_id(html, id_pattern):
     return out
 
 
+def document_styles(html, suffix=""):
+    """{generated element class: {css property: value}} for one breakpoint's rules.
+
+    `suffix` is the breakpoint's own key with the leading underscore dropped: "" is
+    the base, "t" tablet, "m" mobile - the same spelling the three separate style
+    blocks used before 1.0.9.
+
+    1.0.9 merged those three blocks into ONE `mosaic-theme-document-styles-inline-css`
+    with the breakpoints as `@media` blocks inside it, so a suffix is now a position
+    in one stylesheet rather than a block id. The old ids are still read first, so
+    the same tool measures a 1.0.8 site unchanged.
+
+    The base is everything OUTSIDE any at-rule: scanning the whole block for `._x{...}`
+    would read a tablet override as if it were the base, which is exactly the error
+    the three-block layout made impossible.
+    """
+    old = re.search(
+        r'<style id="mosaic-theme-block-editor-styles_%s-inline-css">(.*?)</style>'
+        % re.escape(suffix), html, re.S)
+    if old:
+        css = old.group(1)
+        inner = re.search(r"@media[^{]*\{(.*)\}\s*$", css, re.S)
+        return _rules_of(inner.group(1) if inner else css)
+
+    one = re.search(r'<style id="mosaic-theme-document-styles-inline-css">(.*?)</style>',
+                    html, re.S)
+    if not one:
+        return None
+    css = one.group(1)
+    blocks = _at_rule_blocks(css)
+    if suffix == "":
+        outside = css
+        for start, end, _head in blocks:
+            outside = outside.replace(css[start:end], " ")
+        return _rules_of(outside)
+    # a breakpoint block is a max-width media query; they appear widest-first, the
+    # order Mosaic emits them in, so "t" is the first and "m" the second
+    media = [(s, e, h) for s, e, h in blocks if "max-width" in h]
+    want = {"t": 0, "m": 1}.get(suffix)
+    if want is None or want >= len(media):
+        return None
+    s, e, _h = media[want]
+    body = css[css.index("{", s) + 1:e - 1]
+    return _rules_of(body)
+
+
+def _at_rule_blocks(css):
+    """[(start, end, header)] for every top-level at-rule, found by brace depth."""
+    out, i, n = [], 0, len(css)
+    while True:
+        at = css.find("@", i)
+        if at < 0:
+            return out
+        brace = css.find("{", at)
+        if brace < 0:
+            return out
+        depth, j = 0, brace
+        while j < n:
+            if css[j] == "{":
+                depth += 1
+            elif css[j] == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        out.append((at, j + 1, css[at:brace]))
+        i = j + 1
+
+
+def _rules_of(css):
+    """{class: {prop: value}} from flat CSS, ignoring anything nested in an at-rule."""
+    rules = {}
+    for sel, decls in re.findall(r"([^{}]+)\{([^{}]*)\}", css):
+        props = {}
+        for decl in decls.split(";"):
+            if ":" in decl:
+                k, v = decl.split(":", 1)
+                props[k.strip()] = v.strip()
+        for one in sel.split(","):
+            cls = re.match(r"^\.(_[a-z0-9_-]+)$", one.strip())
+            if cls:
+                rules.setdefault(cls.group(1), {}).update(props)
+    return rules
+
+
 def envelopes(doc):
     return {k: [[x["ID"], x["revision"]] for x in v] for k, v in doc.items()}
 

package/tools/sweep_style_properties.py

@@ -55,7 +55,8 @@ import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from build_page import Surface, flatten, ordering_for  # noqa: E402
-from sweep_node_types import Client, envelopes, exceptions_of, token_by_id, unwrap  # noqa: E402
+from sweep_node_types import (  # noqa: E402
+    Client, document_styles, envelopes, exceptions_of, token_by_id, unwrap)
 
 MARK_LEN = "37px"
 MARK_COLOR = "rgb(9, 99, 199)"
@@ -130,27 +131,6 @@ def test_value(row):
     return None
 
 
-def parse_rules(html, suffix=""):
-    """{generated element class: {css property: value}} for one compiled stylesheet."""
-    m = re.search(
-        r'<style id="mosaic-theme-block-editor-styles_%s-inline-css">(.*?)</style>'
-        % suffix, html, re.S)
-    rules = {}
-    if not m:
-        return rules
-    for sel, decls in re.findall(r"([^{}]+)\{([^{}]*)\}", m.group(1)):
-        cls = re.match(r"^\.(_[a-z0-9_-]+)$", sel.strip())
-        if not cls:
-            continue
-        props = {}
-        for d in decls.split(";"):
-            if ":" in d:
-                k, v = d.split(":", 1)
-                props[k.strip()] = v.strip()
-        rules.setdefault(cls.group(1), {}).update(props)
-    return rules
-
-
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--config", required=True)
@@ -204,7 +184,7 @@ def main():
     if not classes:
         sys.exit("no probe rendered - check ordering and parent before trusting a run")
 
-    rules = parse_rules(html)
+    rules = document_styles(html) or {}
 
     rows = []
     for attr, key_name, value in planned:
@@ -217,7 +197,13 @@ def main():
                 (v for k, v in got.items() if k.startswith(name)), None)
         want = value if isinstance(value, str) else None
         if cls is None:
-            status = "NO_ELEMENT"
+            # Since 1.0.9 an element whose local styles compile to NOTHING is
+            # emitted without a generated class at all - `<div class="m-div"
+            # id="sp-015">`, no `_token`. So "no class" no longer means the node
+            # failed to render; for a probe that did render it means the property
+            # produced no CSS, which is what ABSENT has always meant. The two are
+            # told apart by looking for the id in the markup.
+            status = "ABSENT" if ('id="%s"' % attr) in html else "NO_ELEMENT"
         elif hit is None:
             status = "ABSENT"
         elif want is None or want.replace(" ", "") in hit.replace(" ", ""):