mosaic-headless 1.2.1 → 1.4.0

package/references/failure-modes.md

@@ -193,6 +193,58 @@ disagree, you are not looking at what you wrote.
 document that was actually committed. Do the same in anything else that checks a page
 - including a browser: hard-reload is not always enough, a query string always is.
 
+## Changing a design token's VALUE leaves the old one in `:root`
+
+A collection variable is a row, and a row is identified by its ID. If the writer
+mints a fresh ID each run - which `build_page.py` did, because its `_varIDs` cache
+starts empty every time - then changing a token's value does not change the token.
+It adds a second one.
+
+The rows hang off the theme's collection, and `build_site.py` makes a fresh master
+per build while the collection persists, so nothing ever cleans them up. Both
+declarations reach `:root` and the later one wins:
+
+```css
+:root{ ... --mk-faint: rgb(107, 109, 113); ... --mk-faint: rgb(160, 162, 168); ... }
+```
+
+Measured: after changing `--mk-faint`, a rebuild reported OK, the new variable
+existed with the correct value, `verify_rwd.py` passed, and the page kept rendering
+the old grey. Ten stale rows had accumulated across earlier builds. **Every
+server-side check agreed with the intent and the page still disagreed** - only
+`verify_browser.py`, reading the computed colour off the element, could see it.
+
+The fix is that a token's row ID must be a function of its name -
+`uuid5(VAR_NAMESPACE, "--mk-faint")` - so a rebuild rebinds the row instead of
+adding one, plus a reap of anything on the collection claiming a managed custom
+property under an ID we did not derive. Both are in `theme_records()`.
+
+The general shape is worth remembering beyond tokens: **anything keyed by a random
+ID that you write repeatedly will accumulate**, and duplicates in a cascade fail
+silently in favour of whichever happens to be last.
+
+## A declaration can be present, correct, and still wrong
+
+The fourth failure mode in SKILL.md - "wrong value SHAPE, HTTP 200, and the CSS rule
+is simply absent" - has a quieter sibling: the rule is *present*, the value is what
+you asked for, and what the browser does with it is not what you meant.
+
+Three ways, all measured on the example page:
+
+- **The unit resolves against something you did not think about.**
+  `letter-spacing: -0.035em` is a normal amount of tightening for a Latin display
+  face. On a 62px headline it is -2.17px, and the headline was Chinese.
+- **The face cannot render the text.** `font-family: 'Space Grotesk', 'Noto Sans TC'`
+  is honoured exactly: Space Grotesk has no CJK coverage, so Han characters come from
+  Noto Sans TC - while still carrying the tracking that was chosen for the Latin
+  face. Nothing reports a fallback.
+- **The property was never in play.** `display: inline-block` on a flex item is
+  blockified by the spec. The declaration was in the stylesheet, correct, and
+  computed to `block`.
+
+None of these is visible to anything that reads the stylesheet, because the
+stylesheet is right. `verify_browser.py` asks the element instead.
+
 ## Reproducing all of this
 
 ```bash

package/references/interactions.md

@@ -68,16 +68,61 @@ Confirmed from it:
   it is a percentage of the scroll range, not milliseconds.
 - **`easing` is defaulted to `ease`** by the server.
 
-## What is NOT solved
+## What is NOT solved - and exactly how far it now goes
 
-**Property binding.** `propertyMetas` and per-keyframe `properties` did not survive
-into the payload in any shape tried: flat array of metas, metas nested one level
-deeper (which made the whole interaction vanish), properties as an object, properties
-as an array. The keyframes arrive with timing but with nothing to animate.
+`tools/sweep_interactions.py` commits candidate shapes to a live page and judges each
+against `var mosaicInteractions` in the delivered HTML **and** against the row read
+back out of the database, with negative controls. Results in
+`data/interaction-verification.csv`.
 
-Do not ship an interaction animation on the strength of this page. Use the CSS path,
-or drive the editor once by hand and read the stored row back out of `wp_mosaic_nodes`
-— that row is the authoritative example, and one look at it would settle the shape.
+**`propertyMetas` is NOT the problem, and the previous claim here was wrong.** It is
+accepted, stored, and keeps its order:
+
+```json
+"propertyMetas": [{"uuid": "<uuid>", "type": "predefined", "timelineKey": "_",
+                   "predefinedOptions": {"name": "opacity"}}]
+```
+
+`type` is one of `predefined | custom | static | collectionMode | collectionVariable
+| display`; the options key is that type plus `Options`
+(`KeyframePropertyMetaTypeFactoryAbstract::getPropertyMetaOptionsDataName()`), and
+for `predefined` the `name` is the property itself - the full list is
+`data/animatable-properties.csv`.
+
+**`uuid` is optional on create and REQUIRED on update.** `DataArray::initValues`
+mints one when it is missing, but `DataArray::applyCommitData` matches existing items
+by uuid and rebuilds `order` from `array_column($new, 'uuid')` - so on any later
+commit an item without a uuid is not matched, not carried into the new order, and
+disappears. Measured both ways: the same shape stored 1 meta on create and 0 after an
+update.
+
+**What still does not bind is `initial` and the keyframes' `properties`.** Four
+attempts, each with the row read back:
+
+| attempt | result |
+|---|---|
+| one commit carrying metas + values | metas stored, 0 property values |
+| second commit adding the values | metas stored, 0 property values |
+| second commit that also REORDERS the metas, so `propertyMetas/order` genuinely changes | reorder took effect in storage, still 0 property values |
+| the values written **straight into `wp_mosaic_nodes`**, all caches flushed | still absent from the payload |
+
+That last row is the informative one: it rules out the trust model, the commit
+validators and the cache. The gate is in the export itself -
+`KeyframePropertiesDataSub::exportForInteraction()` will only emit a property for
+which `$this->hasSubData($name)` is true, and those descriptors exist only where
+`AnimationActionOptionsDataSubAbstract::syncAttachedPropertyMetas()` has created
+them, on a shared `DataMeta` that starts empty every time the object is constructed.
+
+So the honest position is: **the envelope, the trigger, the timeline and the property
+metas can all be written headlessly; the property VALUES have not been.** Use the CSS
+path, which is fully verified - see `data/style-state-verification.csv`, where 36 of
+37 probed states compiled to exactly the selector the table promises.
+
+The one experiment left, and it is cheap: author a single interaction in the editor,
+then `SELECT data FROM wp_mosaic_nodes` for that node. One look settles it.
+
+**`pointerEnter` produced no `mosaicInteractions` entry at all**, so the timed family
+needs something the progress family does not - also unfinished.
 
 ## The failure mode that makes this hard
 

package/sites/_moksa.py

@@ -41,9 +41,10 @@ TOKENS = {
     "--mk-paper":   {"type": "color", "value": "rgb(250,250,247)"},
     "--mk-panel":   {"type": "color", "value": "rgb(243,243,239)"},
     "--mk-accent":  {"type": "color", "value": "rgb(255,90,54)"},
-    "--mk-muted":   {"type": "color", "value": "rgb(111,113,120)"},
+    "--mk-accent-ink": {"type": "color", "value": "rgb(191,68,40)"},
+    "--mk-muted":   {"type": "color", "value": "rgb(90,92,97)"},
     "--mk-rule":    {"type": "color", "value": "rgb(214,214,206)"},
-    "--mk-faint":   {"type": "color", "value": "rgb(160,162,168)"},
+    "--mk-faint":   {"type": "color", "value": "rgb(107,109,113)"},
 }
 
 RULE = "rgba(22,24,28,.16)"
@@ -71,10 +72,22 @@ def T(tag, text, _t=None, _m=None, **st):
             "style": bp(st, _t, _m) if (st or _t or _m) else None}
 
 
-def box(attr, style, children, hover=None, _t=None, _m=None):
+# The keyboard is a state too.
+#
+# `focus-visible` was verified by sweep_style_states.py to compile to
+# `.M_EL<n>:FOCUS-VISIBLE` - note the UPPERCASE pseudo-class Mosaic emits, which is
+# why grepping a delivered stylesheet for ":focus-visible" finds nothing at all. Of
+# the seven globally usable states this page used exactly one, `hover`, which means
+# every route through it was invisible to anyone not using a mouse.
+FOCUS_RING = {"customStyles": "outline:2px solid rgb(255,90,54);outline-offset:3px;"}
+
+
+def box(attr, style, children, hover=None, focus=None, _t=None, _m=None):
     s = bp(style, _t, _m) or {"&": {"_": {}}}
     if hover:
         s["hover"] = {"_": hover}
+    if focus:
+        s["focus-visible"] = {"_": focus}
     return {"type": "div", "data": {"attrID": attr}, "style": s, "children": children}
 
 
@@ -145,8 +158,13 @@ def figure(attr, num, size="56px", t="44px", m="34px"):
                                       "font-variant-numeric:tabular-nums;"}}},
             "children": [
                 {"type": "div", "data": {"attrID": attr + "-d%d" % j},
+                 # No `display:inline-block` here: these are flex items, and the
+                 # spec blockifies a flex item's display value. The declaration was
+                 # in the stylesheet, correct, and computed to `block` anyway -
+                 # which is exactly the class of dead code verify_browser.py exists
+                 # to find, and it found this one.
                  "style": {"&": {"_": {"customStyles":
-                                           "overflow:hidden;display:inline-block;"
+                                           "overflow:hidden;"
                                            "--d:%dms;" % (j * 70)}}},
                  "children": [T("h3", ch, color={"token": "--mk-ink"}, fontSize=size,
                                 fontWeight="600", letterSpacing="-0.03em",
@@ -168,7 +186,8 @@ def clause(num, en, zh, attr):
                       "customStyles": "border-top:1px solid " + RULE + ";"},
                _m={"gridCols": "48px 1fr"},
                children=[
-                   mono("§" + num, size="12px", color="--mk-accent", track="0.06em"),
+                   mono("§" + num, size="12px", color="--mk-accent-ink",
+                        track="0.06em"),
                    box(attr + "-t", {}, [
                        mono(en, size="11px", color="--mk-muted"),
                        T("h2", zh, color={"token": "--mk-ink"}, fontSize="34px",
@@ -625,7 +644,8 @@ HEADER = box("mk-shell-top", {}, [
                                              "transitionAll": "160ms ease",
                                              "cursor": "pointer"},
                                        "_m": {"fontSize": "12px"}},
-                                 "hover": {"_": {"color": {"token": "--mk-accent"}}}},
+                                 "hover": {"_": {"color": {"token": "--mk-accent"}}},
+                                 "focus-visible": {"_": FOCUS_RING}},
                        "text": text}
                       for i, (text, href) in enumerate(NAV)
                   ]},
@@ -634,8 +654,12 @@ HEADER = box("mk-shell-top", {}, [
                                              "url": "#contact"},
                   "style": {"&": {"_m": {"display": "none"},
                                   "_t": {"fontSize": "12px"},
+                                  # 13px of the bright orange on the glass header is
+                                  # 3.10:1; the darkened cut is 4.9:1. The BORDER
+                                  # stays bright, because a rule is not text and
+                                  # nobody has to read it.
                                   "_": {"backgroundColor": "rgba(0,0,0,0)",
-                                        "color": {"token": "--mk-accent"},
+                                        "color": {"token": "--mk-accent-ink"},
                                         "fontSize": "13px", "fontFamily": MONO,
                                         "letterSpacing": "0.06em",
                                         "paddingTop": "6px", "paddingBottom": "6px",
@@ -645,7 +669,8 @@ HEADER = box("mk-shell-top", {}, [
                                                    "color": "rgb(255,90,54)"},
                                         "transitionAll": "180ms ease"}},
                             "hover": {"_": {"backgroundColor": {"token": "--mk-accent"},
-                                            "color": {"token": "--mk-paper"}}}},
+                                            "color": {"token": "--mk-ink"}}},
+                            "focus-visible": {"_": FOCUS_RING}},
                   "text": "START A PROJECT"},
              ]}
         ])]),
@@ -684,7 +709,7 @@ FOOTER = box("mk-footer",
                 ]),
                 grid("mk-f-links", 2, "28px", tcols=2, mcols=2, children=[
                     box("mk-f-col-0", {}, [
-                        mono("PAGES", size="10px", color="rgb(122,124,132)",
+                        mono("PAGES", size="10px", color="rgb(128,130,138)",
                              track="0.2em"),
                         box("mk-f-col-0-list",
                             {"marginTop": "16px", "display": "grid", "rowGap": "9px"},
@@ -693,7 +718,7 @@ FOOTER = box("mk-footer",
                              for t in ["作品集", "團隊成員", "關於我們", "服務報價"]]),
                     ]),
                     box("mk-f-col-1", {}, [
-                        mono("LEARN", size="10px", color="rgb(122,124,132)",
+                        mono("LEARN", size="10px", color="rgb(128,130,138)",
                              track="0.2em"),
                         box("mk-f-col-1-list",
                             {"marginTop": "16px", "display": "grid", "rowGap": "9px"},
@@ -713,9 +738,9 @@ FOOTER = box("mk-footer",
                            "customStyles": "flex-wrap:wrap;"}, None, None),
               "children": [
                   mono("© 2026 MOKSA WEB — ALL RIGHTS RESERVED", size="10px",
-                       color="rgb(112,114,122)", track="0.1em"),
+                       color="rgb(128,130,138)", track="0.1em"),
                   mono("BUILT HEADLESS ON MOSAIC", size="10px",
-                       color="rgb(112,114,122)", track="0.1em"),
+                       color="rgb(128,130,138)", track="0.1em"),
               ]}]),
     ])])
 
@@ -767,7 +792,7 @@ MASTHEAD = section("mk-mast", [wrap("mk-mast-in", [
          {"type": "button", "data": {"attrID": "mk-cta-%d" % n, "url": href},
           "style": {"&": {"_": dict(
               {"backgroundColor": {"token": "--mk-accent"},
-               "color": {"token": "--mk-paper"},
+               "color": {"token": "--mk-ink"},
                "paddingLeft": "22px", "paddingRight": "22px",
                "paddingTop": "13px", "paddingBottom": "13px",
                "customStyles": "border:1px solid rgb(255,90,54);"}
@@ -779,6 +804,7 @@ MASTHEAD = section("mk-mast", [wrap("mk-mast-in", [
                                "border-bottom-color:rgb(22,24,28);"},
               fontSize="13px", fontFamily=MONO, letterSpacing="0.1em",
               radius="0px", cursor="pointer", transitionAll="180ms ease")},
+                    "focus-visible": {"_": FOCUS_RING},
                     "hover": {"_": ({"backgroundColor": {"token": "--mk-ink"},
                                      "customStyles": "border:1px solid rgb(22,24,28);"}
                                     if n == 1
@@ -831,7 +857,7 @@ MASTHEAD = section("mk-mast", [wrap("mk-mast-in", [
                          {"display": "flex", "alignItems": "baseline",
                           "columnGap": "3px", "marginTop": "12px"},
                          [figure("mk-fig-%d" % i, num),
-                          T("p", "+", color={"token": "--mk-accent"},
+                          T("p", "+", color={"token": "--mk-accent-ink"},
                             fontSize="22px", fontFamily=DISPLAY, fontWeight="600",
                             _m={"fontSize": "16px"})]),
                      T("p", zh, color={"token": "--mk-muted"}, fontSize="12px",
@@ -868,7 +894,8 @@ SERVICE_SEC = section("services", [wrap("mk-svc-in", [
                 children=[
                     mono(num, size="12px", color="--mk-faint", track="0.06em"),
                     box("mk-svc-t-%d" % i, {}, [
-                        mono(en, size="10px", color="--mk-accent", track="0.16em"),
+                        mono(en, size="10px", color="--mk-accent-ink",
+                             track="0.16em"),
                         T("h3", zh, color={"token": "--mk-ink"}, fontSize="19px",
                           fontWeight="500", marginTop="9px", fontFamily=CJK,
                           letterSpacing="0.01em"),
@@ -903,7 +930,8 @@ PROCESS_SEC = section("process", [wrap("mk-proc-in", [
                             T("h3", zh, color={"token": "--mk-ink"}, fontSize="19px",
                               fontWeight="500", fontFamily=CJK, marginTop="10px",
                               letterSpacing="0.01em"),
-                            mono(en, size="10px", color="--mk-accent", track="0.16em",
+                            mono(en, size="10px", color="--mk-accent-ink",
+                                 track="0.16em",
                                  marginTop="7px"),
                             T("p", body, color={"token": "--mk-muted"},
                               fontSize="13px", lineHeight="2", marginTop="12px"),
@@ -924,7 +952,15 @@ STACK_SEC = section("stack", [wrap("mk-stack-in", [
                     {"display": "grid", "gridCols": "160px 1fr", "columnGap": "24px",
                      "alignItems": "baseline",
                      "paddingTop": "18px", "paddingBottom": "18px",
-                     "customStyles": "border-top:1px solid " + RULE + ";"},
+                     # Each row arrives on its own, staggered by pushing its
+                     # animation-range further down the scroll rather than by a
+                     # delay: a scroll-driven animation has no clock to delay
+                     # against, so the offset has to live in the range.
+                     "customStyles":
+                         "border-top:1px solid " + RULE + ";"
+                         "animation:mk-rise both;animation-timeline:view();"
+                         "animation-range:entry %d%% cover %d%%;"
+                         % (2 + i * 4, 18 + i * 4)},
                     _m={"gridCols": "1fr", "rowGap": "10px",
                         "paddingTop": "16px", "paddingBottom": "16px"},
                     children=[
@@ -992,7 +1028,8 @@ WORK_SEC = section("works", [wrap("mk-works-in", [
                           fontWeight="500", fontFamily=CJK, letterSpacing="0.01em",
                           _m={"fontSize": "16px"}),
                         mono(cat, size="11px", color="--mk-muted", track="0.1em"),
-                        mono(domain, size="12px", color="--mk-accent", track="0.02em"),
+                        mono(domain, size="12px", color="--mk-accent-ink",
+                             track="0.02em"),
                     ])
                 for i, (name, cat, domain) in enumerate(WORKS)
             ]),
@@ -1034,7 +1071,7 @@ PRODUCT_SEC = section("products", [wrap("mk-prod-in", [
                             "paddingTop": "20px", "paddingBottom": "20px"},
                         children=[
                             mono("%02d" % (i + 1), size="12px",
-                                 color="rgb(122,124,132)", track="0.06em"),
+                                 color="rgb(128,130,138)", track="0.06em"),
                             box("mk-prod-t-%d" % i, {}, [
                                 mono(en, size="10px", color="--mk-accent",
                                      track="0.16em"),
@@ -1081,7 +1118,7 @@ VOICE_SEC = section("mk-voices", [wrap("mk-voice-in", [
                     "customStyles": "border-top:1px solid " + RULE + ";"
                                     "border-left:0;"},
                 children=[
-                    mono("“", size="24px", color="--mk-accent", track="0"),
+                    mono("“", size="24px", color="--mk-accent-ink", track="0"),
                     T("p", quote, color={"token": "--mk-ink"}, fontSize="14px",
                       lineHeight="2.05", marginTop="4px"),
                     box("mk-voice-a-%d" % i, {"marginTop": "22px"}, [
@@ -1104,7 +1141,8 @@ CONTACT = section("contact", [wrap("mk-contact-in", [
                  "customStyles": "border-top:1px solid " + RULE + ";"},
                 _m={"gridCols": "48px 1fr"},
                 children=[
-                    mono("§07", size="12px", color="--mk-accent", track="0.06em"),
+                    mono("§07", size="12px", color="--mk-accent-ink",
+                         track="0.06em"),
                     box("mk-contact-head-t", {}, [
                         mono("START A PROJECT", size="11px", color="--mk-muted"),
                         ml("h2", "準備好升級\n你的數位競爭力了嗎？",
@@ -1135,7 +1173,8 @@ CONTACT = section("contact", [wrap("mk-contact-in", [
                                           _m={"fontSize": "13px"}),
                                  ])
                              for i, (k, v, vc) in enumerate([
-                                 ("EMAIL", "services@moksaweb.com", "--mk-accent"),
+                                 ("EMAIL", "services@moksaweb.com",
+                                  "--mk-accent-ink"),
                                  ("PHONE", "+886-958-839-939", "--mk-ink"),
                                  ("LOCATION", "TAICHUNG, TAIWAN", "--mk-ink"),
                                  ("RESPONSE", "WITHIN 1 BUSINESS DAY", "--mk-ink"),
@@ -1160,7 +1199,8 @@ INDEX = box("mk-index", {}, [
                            "fontFamily": MONO, "fontSize": "10px",
                            "letterSpacing": "0.14em",
                            "transitionAll": "220ms ease"}},
-               "hover": {"_": {"color": {"token": "--mk-ink"}}}},
+               "hover": {"_": {"color": {"token": "--mk-ink"}}},
+               "focus-visible": {"_": FOCUS_RING}},
      "text": "§" + num + "  " + name}
     for i, (num, name, href, _tl) in enumerate(CLAUSES)
 ])