@wix/himalaya-cli 0.1018.0 → 0.1020.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/tokens.d.ts

@@ -18,6 +18,8 @@ export interface DesignTokens {
     motions?: Record<string, MotionToken>;
     /** RFC 0021 — named surface materials (flat / glass / frosted). */
     materials?: Record<string, MaterialToken>;
+    /** RFC 0059 / #2931 — named surface elevations, paint only. A `Card` wears `card`. */
+    elevations?: Record<string, ElevationToken>;
     /** RFC 0021 (bottom-nav extension) — kit-driven tab bar styling. */
     tabBar?: TabBarStyle;
     /** RFC 0010/0021 — kit-driven slide-in drawer styling. */
@@ -264,6 +266,40 @@ export interface ShadowToken {
     x?: number;
     y?: number;
 }
+/**
+ * RFC 0059 / #2931 — how raised a surface is, as PAINT: nothing here moves a box, so the
+ * structural diff stays blind to it. A `Card` wears the `card` elevation; declare none and every
+ * Card stays flat, as before. Each field is drawn the same way on every renderer — what makes a
+ * Card read as Material on Android and as iOS on an iPhone is the idiom overlay choosing different
+ * fields for the one token:
+ *
+ *   "elevations": { "card": {} },
+ *   "idiom": {
+ *     "material": { "elevations": { "card": { "level": 1 } } },
+ *     "ios":      { "elevations": { "card": { "border": { "color": "border" }, "shadow": "card" } } }
+ *   }
+ */
+export interface ElevationToken {
+    /** Material 3 tonal elevation, 0–5: the surface is tinted with `tint` at M3's alpha for that
+     *  level (1 → 5%, 2 → 8%, 3 → 11%, 4 → 12%, 5 → 14% — `TONAL_ELEVATION_ALPHA`). 0 = none. */
+    level?: number;
+    /** The tonal tint — a colour token, M3's surfaceTint. Default `accentPrimary`. */
+    tint?: string;
+    /** A `shadows` token drawn behind the surface, in the surface's own shape. */
+    shadow?: string;
+    /** A hairline drawn just inside the surface's edge, so it never grows the box. `width` in
+     *  points, default 0.5; 0 = none. */
+    border?: {
+        color: string;
+        width?: number;
+    };
+}
+/** M3's tonal-elevation tint alpha by level (0–5), as `surfaceColorAtElevation` computes it for
+ *  levels 1–5 (1, 3, 6, 8, 12 dp). Mirrored by Tokens.swift and Tokens.kt. */
+export declare const TONAL_ELEVATION_ALPHA: readonly number[];
+/** The tint alpha an `ElevationToken.level` asks for: rounded and clamped to 0–5; anything
+ *  non-numeric is 0 (no tint). */
+export declare function tonalElevationAlpha(level: number | undefined): number;
 /** RFC 0020 — a linear gradient. `colors` are color-token NAMES (theme-aware);
  *  `angle` is degrees clockwise from top (0 = top→bottom, 90 = left→right).
  *  `locations` (0..1) optionally positions each stop. */

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/core.mjs

@@ -7796,6 +7796,11 @@ function resolveResponsiveSize(rs, width) {
   return rs.base;
 }
 var SYSTEM_FONT_FAMILY = "$system";
+var TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
+function tonalElevationAlpha(level) {
+  if (typeof level !== "number" || !Number.isFinite(level)) return 0;
+  return TONAL_ELEVATION_ALPHA[Math.min(5, Math.max(0, Math.round(level)))];
+}
 function buildTokenRegistry(tokens) {
   return {
     colors: new Set(Object.keys(tokens.colors ?? {})),
@@ -12975,6 +12980,7 @@ export {
   SURFACE_GROUPS,
   SURFACE_VIEW_LADDER,
   SYSTEM_FONT_FAMILY,
+  TONAL_ELEVATION_ALPHA,
   UNIVERSAL_LAUNCH_NAMESPACES,
   WIDGET_COMPONENTS,
   WIDGET_FAMILIES,
@@ -13047,6 +13053,7 @@ export {
   surfaceFrozenFamily,
   surfaceRenderMode,
   surfacesForApp,
+  tonalElevationAlpha,
   validate,
   validateAll,
   validateDistribution,

package/dist/cli.mjs

@@ -5293,6 +5293,10 @@ var init_quickjs_web_globals = __esm({
 });
 
 // ../../core/ts/src/tokens.ts
+function tonalElevationAlpha(level) {
+  if (typeof level !== "number" || !Number.isFinite(level)) return 0;
+  return TONAL_ELEVATION_ALPHA[Math.min(5, Math.max(0, Math.round(level)))];
+}
 function buildTokenRegistry(tokens) {
   return {
     colors: new Set(Object.keys(tokens.colors ?? {})),
@@ -5342,10 +5346,12 @@ function walk(node, registry, path2, out) {
     walk(value, registry, `${path2}.${key2}`, out);
   }
 }
-var SYSTEM_FONT_FAMILY;
+var SYSTEM_FONT_FAMILY, TONAL_ELEVATION_ALPHA;
 var init_tokens = __esm({
   "../../core/ts/src/tokens.ts"() {
+    "use strict";
     SYSTEM_FONT_FAMILY = "$system";
+    TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
   }
 });
 
@@ -11078,6 +11084,29 @@ function tokenColorIssues(dir, tokensPathOverride) {
       );
     }
   }
+  const shadowNames = (layer) => {
+    const sh = layer?.shadows;
+    return new Set(sh !== null && typeof sh === "object" && !Array.isArray(sh) ? Object.keys(sh) : []);
+  };
+  const checkElevations = (layer, where, declared) => {
+    const els = layer?.elevations;
+    if (els === null || typeof els !== "object" || Array.isArray(els)) return;
+    for (const [name, token] of Object.entries(els)) {
+      const shadow = token?.shadow;
+      if (shadow === void 0 || typeof shadow === "string" && declared.has(shadow)) continue;
+      error(
+        `${tokensPath}: ${where}elevations.${name}.shadow is ${JSON.stringify(shadow)}, which names no \`shadows\` token \u2014 every renderer would paint it with no shadow at all. Declare shadows.${typeof shadow === "string" ? shadow : "<name>"} or name one that exists.`
+      );
+    }
+  };
+  const baseShadows = shadowNames(raw);
+  checkElevations(raw, "", baseShadows);
+  const idiom = raw.idiom;
+  if (idiom !== null && typeof idiom === "object" && !Array.isArray(idiom)) {
+    for (const [overlay, layer] of Object.entries(idiom)) {
+      checkElevations(layer, `idiom.${overlay}.`, /* @__PURE__ */ new Set([...baseShadows, ...shadowNames(layer)]));
+    }
+  }
   const colors = raw.colors;
   if (colors === void 0) return issues;
   if (colors === null || typeof colors !== "object" || Array.isArray(colors)) {
@@ -12843,6 +12872,32 @@ function resolveSchemeColor(o, scheme) {
   if (typeof o?.light === "string") return o.light;
   return typeof o?.dark === "string" ? o.dark : void 0;
 }
+function mixColor(base, over, alpha2) {
+  const a = hexToRgba(base), b = hexToRgba(over);
+  if (a && b) {
+    const t = alpha2 * b[3];
+    const hex2 = (v) => Math.round(v).toString(16).padStart(2, "0");
+    const rgb = [0, 1, 2].map((i) => hex2(a[i] * (1 - t) + b[i] * t)).join("");
+    return a[3] < 1 ? `#${rgb}${hex2(a[3] * 255)}` : `#${rgb}`;
+  }
+  return `color-mix(in srgb, ${over} ${+(alpha2 * 100).toFixed(2)}%, ${base})`;
+}
+function hexToRgba(hex2) {
+  const h = hex2.trim().replace(/^#/, "");
+  if (/^[\da-f]{8}$/i.test(h)) {
+    const rgb2 = hexToRgb2(h.slice(0, 6));
+    return rgb2 ? [...rgb2, parseInt(h.slice(6), 16) / 255] : null;
+  }
+  const rgb = hexToRgb2(h);
+  return rgb ? [...rgb, 1] : null;
+}
+function elevationBoxShadow(e) {
+  const parts = [
+    ...e.border && e.border.width > 0 ? [`inset 0 0 0 ${e.border.width}px ${e.border.color}`] : [],
+    ...e.shadow ? [e.shadow] : []
+  ];
+  return parts.length ? parts.join(", ") : void 0;
+}
 function makeTokenResolvers(source, scheme, idiom = WEB_IDIOM_CONTEXT) {
   const tokens = resolveIdiom(source, idiom);
   const color = (name, fallback = "#1a1a1a") => {
@@ -12933,6 +12988,17 @@ function makeTokenResolvers(source, scheme, idiom = WEB_IDIOM_CONTEXT) {
     }
     return tint ? { background: rgba(tint, m.opacity ?? 1) } : void 0;
   };
+  const elevation = (name) => {
+    const e = name ? tokens.elevations?.[name] : void 0;
+    if (!e) return void 0;
+    const alpha2 = tonalElevationAlpha(e.level);
+    const width = e.border ? typeof e.border.width === "number" && Number.isFinite(e.border.width) ? Math.max(0, e.border.width) : 0.5 : 0;
+    return {
+      ...alpha2 > 0 ? { tint: { color: color(e.tint ?? "accentPrimary", "#6F3BFF"), alpha: alpha2 } } : {},
+      ...e.shadow && shadow(e.shadow) ? { shadow: shadow(e.shadow) } : {},
+      ...e.border && width > 0 ? { border: { color: color(e.border.color, "#E0E0E0"), width } } : {}
+    };
+  };
   const densityScale = (density) => {
     switch (density) {
       case "compact":
@@ -12974,6 +13040,7 @@ function makeTokenResolvers(source, scheme, idiom = WEB_IDIOM_CONTEXT) {
     gradient,
     meshGradient,
     material,
+    elevation,
     densityScale,
     motionTransition,
     appearMotion,
@@ -19815,6 +19882,7 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
+    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -23239,6 +23307,7 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
+    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,
@@ -24956,8 +25025,17 @@ function renderInner(node, ctx) {
     }
     case "Grid":
       return /* @__PURE__ */ jsx6(GridNode, { props, ctx, wrap, gap });
-    case "Card":
-      return /* @__PURE__ */ jsx6("div", { style: { display: "flex", flexDirection: "column", gap: props.spacing == null ? 8 : ctx.sp(props.spacing), padding: props.padding == null ? 12 : ctx.sp(props.padding), background: C(props.background ?? "surfaceSecondary", "#f5f7fa"), borderRadius: ctx.radius(props.cornerRadius ?? "md", 10), overflow: "hidden", alignSelf: "stretch", ...props.alignment ? { alignItems: props.alignment === "center" ? "center" : props.alignment === "trailing" ? "flex-end" : "flex-start" } : {}, ...wrap }, children: kids(props.children, ctx) });
+    case "Card": {
+      const m = modifiers;
+      const ownSurface = !!(m?.backgroundGradient ?? m?.background_gradient ?? m?.material) || m?.animatedGradient === true || m?.meshGradient === true;
+      const fill = C(props.background ?? "surfaceSecondary", "#f5f7fa");
+      const card = ctx.elevation("card");
+      const elevation = card && ownSurface ? { border: card.border } : card;
+      const wrapShadow = wrap.boxShadow;
+      const explicit = m?.shadow != null || m?.boxShadow != null || m?.box_shadow != null;
+      const elevationShadow = !elevation ? wrapShadow : explicit ? elevationBoxShadow({ border: elevation.border, shadow: wrapShadow }) : [elevationBoxShadow(elevation), wrapShadow].filter(Boolean).join(", ") || void 0;
+      return /* @__PURE__ */ jsx6("div", { style: { display: "flex", flexDirection: "column", gap: props.spacing == null ? 8 : ctx.sp(props.spacing), padding: props.padding == null ? 12 : ctx.sp(props.padding), background: elevation?.tint ? mixColor(fill, elevation.tint.color, elevation.tint.alpha) : fill, borderRadius: ctx.radius(props.cornerRadius ?? "md", 10), overflow: "hidden", alignSelf: "stretch", ...props.alignment ? { alignItems: props.alignment === "center" ? "center" : props.alignment === "trailing" ? "flex-end" : "flex-start" } : {}, ...wrap, ...elevationShadow ? { boxShadow: elevationShadow } : {} }, children: kids(props.children, ctx) });
+    }
     case "SplitView":
       return /* @__PURE__ */ jsx6(SplitViewNode, { props, ctx, wrap });
     case "Divider":
@@ -28891,6 +28969,7 @@ __export(render_descriptor_exports, {
   clientEnvFor: () => clientEnvFor,
   collectNativeOnly: () => collectNativeOnly,
   isMissingPlaywrightExecutable: () => isMissingPlaywrightExecutable,
+  nodeHidden: () => nodeHidden,
   pngAvailable: () => pngAvailable,
   pngPageHtml: () => pngPageHtml,
   renderDescriptorWeb: () => renderDescriptorWeb,
@@ -35061,6 +35140,7 @@ __export(screen_crawl_exports, {
   netTransport: () => netTransport,
   parseWorkerAction: () => parseWorkerAction,
   recordScreenTraffic: () => recordScreenTraffic,
+  renderedNameGaps: () => renderedNameGaps,
   rootOnAppear: () => rootOnAppear,
   snapshot: () => snapshot,
   structuralSignature: () => structuralSignature,
@@ -35490,6 +35570,185 @@ function scanTreeValues(node, hit) {
   }
   node.children?.forEach((child) => scanTreeValues(child, hit));
 }
+function joinPath(base, rel) {
+  if (!base) return rel;
+  if (!rel) return base;
+  return rel.startsWith("[") ? `${base}${rel}` : `${base}.${rel}`;
+}
+function withinPath(p, root) {
+  return !root || p === root || p.startsWith(`${root}.`) || p.startsWith(`${root}[`);
+}
+function resolveNameBinding(v, ctx) {
+  if (v.startsWith("$service:")) return ctx.provider.value(v);
+  if (v.startsWith("$item") && ctx.scope) {
+    const key2 = v.replace(/^\$item\.?/, "");
+    return key2 ? pathValue(ctx.scope, key2) : void 0;
+  }
+  return void 0;
+}
+function collapsesWhenEmpty(n, path2, ctx) {
+  const wire = !!n.body && typeof n.body === "object" && !Array.isArray(n.body);
+  const body = wire ? n.body : n;
+  if (body.type !== "Text") return false;
+  const props = body.props;
+  if (!props || props.collapseWhenEmpty !== true) return false;
+  const raw = props.text;
+  const bound = typeof raw === "string" && (raw.startsWith("$service:") || raw.startsWith("$item"));
+  if (bound && raw.startsWith("$item") && !ctx.scope) return false;
+  const eff = bound ? resolveNameBinding(raw, ctx) : raw;
+  const s = eff == null ? "" : String(eff).trim();
+  if (s !== "" && s !== "\u2014") return false;
+  if (bound && typeof eff === "string" && s === "") {
+    ctx.emptied.push({ at: joinPath(path2, wire ? "body.props" : "props"), field: "text", binding: raw });
+  }
+  return true;
+}
+function resolveGateValue(raw, ctx) {
+  return typeof raw === "string" && (raw.startsWith("$service:") || raw.startsWith("$item")) ? resolveNameBinding(raw, ctx) : raw;
+}
+function sheetNotPresented(n, ctx) {
+  const body = n.body && typeof n.body === "object" && !Array.isArray(n.body) ? n.body : n;
+  if (body.type !== "BottomSheet") return false;
+  const props = body.props;
+  if (!props || props.presentedPath == null && props.presented == null) return false;
+  const presented = resolveGateValue(props.presentedPath != null ? props.presentedPath : props.presented, ctx);
+  return presented !== true && presented !== "true";
+}
+function selectedFragmentCase(props, ctx) {
+  const cases = Array.isArray(props.cases) ? props.cases : [];
+  if (!cases.length) return null;
+  const casePath = props.casePath ?? props.case_path;
+  if (typeof casePath === "string" && casePath.startsWith("$") && !casePath.startsWith("$service:") && !casePath.startsWith("$item")) return null;
+  const disc = resolveGateValue(casePath, ctx);
+  const wanted = typeof disc === "string" ? disc : void 0;
+  const idOf = (c) => c && typeof c === "object" ? c.id : void 0;
+  let i = cases.findIndex((c) => idOf(c) === wanted);
+  if (i < 0) {
+    const fallback = props.defaultCase ?? props.default_case;
+    i = cases.findIndex((c) => idOf(c) === fallback);
+  }
+  return i < 0 ? 0 : i;
+}
+function projectRenderedNames(node, path2, key2, ctx) {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((v, i) => projectRenderedNames(v, `${path2}[${i}]`, key2, ctx));
+  if (isActionEnvelope(node) || key2 === "args") return node;
+  const n = node;
+  const rawMods = n.modifiers;
+  const mods = rawMods && typeof rawMods === "object" && !Array.isArray(rawMods) ? rawMods : {};
+  if (mods.accessibilityHidden === true) return node;
+  if (ctx.unrendered.has(path2) || nodeHidden(mods, ctx.provider, ctx.scope, null) || collapsesWhenEmpty(n, path2, ctx) || sheetNotPresented(n, ctx)) {
+    return { ...n, modifiers: { ...mods, accessibilityHidden: true } };
+  }
+  const props = n.props && typeof n.props === "object" && !Array.isArray(n.props) ? n.props : null;
+  if (props && n.type === "FragmentSlot") {
+    const selected = selectedFragmentCase(props, ctx);
+    if (selected !== null) {
+      props.cases.forEach((_, i) => {
+        if (i !== selected) ctx.unrendered.add(joinPath(path2, `props.cases[${i}]`));
+      });
+    }
+  }
+  let boundTemplate = false;
+  if (props && (n.type === "LazyList" || n.type === "Grid")) {
+    const itemsPath = props.itemsPath ?? props.items_path;
+    const template = Array.isArray(props.items) ? props.items[0] : void 0;
+    if (typeof itemsPath === "string" && template !== void 0) {
+      boundTemplate = true;
+      const local = itemsPath.startsWith("$item.");
+      const rows = local ? ctx.scope ? pathValue(ctx.scope, itemsPath.slice("$item.".length)) : void 0 : itemsPath.startsWith("$service:") ? ctx.provider.value(itemsPath) : void 0;
+      if (Array.isArray(rows) || local) {
+        const paintsRows = Array.isArray(rows) && rows.length > 0;
+        props.items.forEach((_, i) => {
+          const at = joinPath(path2, `props.items[${i}]`);
+          if (i === 0 && paintsRows) ctx.rowTemplates.push(at);
+          else ctx.unrendered.add(at);
+        });
+      }
+      if (Array.isArray(rows) && rows.length) {
+        ctx.lists.push({
+          templatePath: joinPath(path2, "props.items[0]"),
+          template,
+          rows: rows.slice(0, A11Y_ROWS_PER_LIST)
+        });
+      }
+    }
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(n)) {
+    if (NAME_KEYS.has(k) && typeof v === "string" && (v.startsWith("$service:") || v.startsWith("$item"))) {
+      const r = resolveNameBinding(v, ctx);
+      if (typeof r === "string") {
+        if (r.trim() === "") ctx.emptied.push({ at: path2, field: k, binding: v });
+        out[k] = r;
+      } else if (typeof r === "number" || typeof r === "boolean") {
+        out[k] = String(r);
+      } else {
+        out[k] = v;
+      }
+      continue;
+    }
+    if (k === "props" && boundTemplate && props) {
+      const p = {};
+      for (const [pk, pv] of Object.entries(props)) {
+        p[pk] = projectRenderedNames(
+          pv,
+          joinPath(path2, `props.${pk}`),
+          pk,
+          pk === "items" ? { ...ctx, scope: void 0 } : ctx
+        );
+      }
+      out[k] = p;
+      continue;
+    }
+    out[k] = projectRenderedNames(v, joinPath(path2, k), k, ctx);
+  }
+  return out;
+}
+function renderedNameGaps(descriptor, state) {
+  const provider = new FakeServiceProvider(state);
+  const found = /* @__PURE__ */ new Map();
+  const rowsJudged = /* @__PURE__ */ new Map();
+  const rowTemplateOf = /* @__PURE__ */ new Map();
+  const judge = (root, base, scope, depth, inRow) => {
+    if (inRow) rowsJudged.set(base, (rowsJudged.get(base) ?? 0) + 1);
+    const ctx = { provider, scope, emptied: [], lists: [], unrendered: /* @__PURE__ */ new Set(), rowTemplates: [] };
+    const projected = projectRenderedNames(root, "", "", ctx);
+    for (const g of accessibleNameGaps(projected)) {
+      const rel = g.at === "root" ? "" : g.at;
+      const at = joinPath(base, rel) || "root";
+      if (g.reason !== "interactive" && !CONTROL_ROLES.has(g.role)) continue;
+      if (ctx.rowTemplates.some((t) => withinPath(rel, t))) continue;
+      const cause = ctx.emptied.find((e) => withinPath(e.at, rel));
+      if (!cause) continue;
+      const prev = found.get(at);
+      if (prev) {
+        if (prev.rows && inRow) prev.rows.hit += 1;
+        continue;
+      }
+      if (inRow) rowTemplateOf.set(at, base);
+      found.set(at, {
+        gap: { ...g, at },
+        binding: cause.binding,
+        field: cause.field,
+        ...inRow ? { rows: { hit: 1, of: 0 } } : {}
+      });
+    }
+    if (depth >= A11Y_LIST_DEPTH) return;
+    for (const list of ctx.lists) {
+      list.rows.forEach((el, i) => {
+        const rowScope = el && typeof el === "object" && !Array.isArray(el) ? { ...el, __index: i } : { value: el, __index: i };
+        judge(list.template, joinPath(base, list.templatePath), rowScope, depth + 1, true);
+      });
+    }
+  };
+  judge(descriptor, "", void 0, 0, false);
+  for (const [at, template] of rowTemplateOf) {
+    const rows = found.get(at)?.rows;
+    if (rows) rows.of = rowsJudged.get(template) ?? rows.hit;
+  }
+  return [...found.values()];
+}
 function collectObservations(descriptorOrPayload, state) {
   const out = [];
   const walk2 = (node) => {
@@ -35919,6 +36178,21 @@ async function crawlScreenInner(opts) {
         });
       });
     }
+    for (const r of renderedNameGaps(descriptor, state)) {
+      findings.push({
+        screen: screenId,
+        trigger,
+        invariant: "unnamed-control",
+        severity: "error",
+        // Stable across states on purpose: the row count lives in `actual`, so the same control
+        // seen empty after boot and after a tap dedupes to one finding.
+        message: `${r.gap.type} renders no accessible name: its only name, ${r.binding}, resolved to "" \u2014 a screen reader announces an unnamed \`${r.gap.role}\``,
+        at: r.gap.at,
+        field: r.field,
+        actual: r.rows ? `"" on ${r.rows.hit} of ${r.rows.of} row(s)` : '""',
+        hint: "`himi validate` counts a bound name as a name \u2014 it becomes copy on device \u2014 so only the crawl can see it come out empty. Give the control a name that cannot be empty: a literal `modifiers.accessibilityLabel` (an icon-only control can use `Icon.contentDescription`), or have the worker fall back to real copy instead of an empty string"
+      });
+    }
     for (const ref of collectServiceBindings(descriptor)) {
       if (!(ref.svc in state)) {
         findings.push({
@@ -36700,11 +36974,12 @@ async function crawlScreenRelations(opts) {
     return { findings: dedupe(findings), checked, byKind };
   });
 }
-var ACTION_KEYS, UNTRACKED_ITEMS, NESTED_ITEMS_SEP, REJECT_ALL_MESSAGE, VLQ, WIX_DATA_QUERY, WIX_DATA_ANY, CAPABILITY_ACTION, detached, CRAWL_CLOCK, MEMBER_IDENTITY_ACTION, BLANK_WHEN_BOUND, STALE_SNAPSHOT_HINT, UNBINDABLE_ROW;
+var ACTION_KEYS, UNTRACKED_ITEMS, NESTED_ITEMS_SEP, REJECT_ALL_MESSAGE, VLQ, WIX_DATA_QUERY, WIX_DATA_ANY, CAPABILITY_ACTION, detached, CRAWL_CLOCK, MEMBER_IDENTITY_ACTION, BLANK_WHEN_BOUND, CONTROL_ROLES, NAME_KEYS, A11Y_ROWS_PER_LIST, A11Y_LIST_DEPTH, STALE_SNAPSHOT_HINT, UNBINDABLE_ROW;
 var init_screen_crawl = __esm({
   "../../core/dev-server/src/screen-crawl.ts"() {
     init_validate_descriptor_core();
     init_render_descriptor();
+    init_a11y_contract();
     init_net_scenario();
     init_media_value();
     init_FakeServiceProvider();
@@ -36740,6 +37015,24 @@ var init_screen_crawl = __esm({
       Marquee: ["items", "itemsPath", "text"],
       MediaPlayer: ["items", "itemsPath"]
     };
+    CONTROL_ROLES = /* @__PURE__ */ new Set([
+      "button",
+      "link",
+      "toggle",
+      "checkbox",
+      "radio",
+      "tab",
+      "tablist",
+      "adjustable",
+      "search",
+      "textfield",
+      "combobox",
+      "menu",
+      "menuitem"
+    ]);
+    NAME_KEYS = new Set(ACCESSIBLE_NAME_KEYS);
+    A11Y_ROWS_PER_LIST = 20;
+    A11Y_LIST_DEPTH = 3;
     STALE_SNAPSHOT_HINT = 'if every path already does, look for a stale-snapshot write-back: `return s` (or `{ ...s }`) after an await or from an early-return guard writes back the state as it was BEFORE the await, loading flag included \u2014 to change nothing, return `undefined` instead (not `null` or `{}`); see `himi docs tier-5-add-a-screen`, "Should this result be committed at all?"';
     UNBINDABLE_ROW = Symbol("unbindable-row");
   }
@@ -46100,6 +46393,16 @@ function assembleLedger(r, options = {}) {
       remedy: "renders on device only \u2014 himi push a preview and check by eye"
     });
   }
+  if ((r.crawled ?? []).length) {
+    const found = [...r.failures, ...r.warnings].filter((f) => f.invariant === "unnamed-control").length;
+    out.push({
+      key: "a11y|app",
+      kind: "a11y",
+      screen: null,
+      gap: `accessibility is judged for ONE property only \u2014 an operable control whose bound name rendered empty (\`unnamed-control\`, ${found} this run). NOT judged: names authored statically in the descriptor, role/state announcement, focus order, contrast, touch-target size \u2014 a clean run is not an accessibility pass`,
+      remedy: "run `himi validate` for statically authored names (its a11y pass), then `himi push` a preview and walk every screen with VoiceOver and TalkBack"
+    });
+  }
   if (!/(^|\+ )mocked/.test(r.transport) && !r.transport.startsWith("offline")) {
     out.push({
       key: "no-user-mocks|app",
@@ -46474,7 +46777,7 @@ var init_assets = __esm({
 async function checkPinnedRead(input) {
   const { secret, token, app, releaseId, screenId, authorizePreview } = input;
   if (!secret) return authorizePreview ? { status: 503, body: { error: "preview_token_unavailable" } } : null;
-  if (!token) return await input.isLive() ? null : { status: 401, body: { error: "preview_token_required", app, releaseId } };
+  if (!token) return await input.isPublic() ? null : { status: 401, body: { error: "preview_token_required", app, releaseId } };
   const verified = await verifyPreviewToken({ token, secret, app, releaseId, screenId });
   if (verified.ok) {
     if (authorizePreview ? !await authorizePreview(verified.claims) : !!verified.claims.siteLease) {
@@ -46756,9 +47059,30 @@ function makeServeHandler(opts) {
   function resolvePin(request, url) {
     return request.headers.get("x-himalaya-release") || url.searchParams.get("release") || null;
   }
+  const RELEASE_SOURCE_HEADER = "x-himalaya-release-source";
   function resolvePreviewToken(request, url) {
     return request.headers.get("x-himalaya-preview-token") || url.searchParams.get("pvt") || null;
   }
+  const RING_CACHE_CAP = 500;
+  const ringCache = /* @__PURE__ */ new Map();
+  async function isRingRelease(app, releaseId) {
+    if (!opts.ringReleases) return false;
+    const hit = ringCache.get(app);
+    let ids = hit && Date.now() - hit.at < manifestCacheTtlMs ? hit.ids : void 0;
+    if (!ids) {
+      try {
+        ids = new Set(await opts.ringReleases(app));
+      } catch {
+        ids = /* @__PURE__ */ new Set();
+      }
+      if (!ringCache.has(app) && ringCache.size >= RING_CACHE_CAP) {
+        const oldest = ringCache.keys().next().value;
+        if (oldest !== void 0) ringCache.delete(oldest);
+      }
+      ringCache.set(app, { ids, at: Date.now() });
+    }
+    return ids.has(releaseId);
+  }
   async function pinnedManifest(app, releaseId) {
     const key2 = `${app}
 ${releaseId}`;
@@ -46843,11 +47167,40 @@ ${releaseId}`;
       app,
       releaseId,
       screenId,
-      isLive: async () => (await manifest(app))?.releaseId === releaseId,
+      isPublic: async () => (await manifest(app))?.releaseId === releaseId || await isRingRelease(app, releaseId),
       authorizePreview: opts.authorizePreview
     });
     return denied && json3(denied.status, denied.body);
   }
+  async function honourRingPin(request) {
+    const kept = { request, dropped: false };
+    if (request.method !== "GET" && request.method !== "HEAD") return kept;
+    if (request.headers.get(RELEASE_SOURCE_HEADER) !== "ring") return kept;
+    const pin = request.headers.get("x-himalaya-release");
+    if (!pin) return kept;
+    const url = new URL(request.url);
+    const app = /^\/v1\/app-config\/([^/]+)$/.exec(url.pathname)?.[1] ?? resolveApp(request, url);
+    if (!app) return kept;
+    const drop = () => {
+      const headers2 = new Headers(request.headers);
+      headers2.delete("x-himalaya-release");
+      headers2.delete(RELEASE_SOURCE_HEADER);
+      return { request: new Request(request, { headers: headers2 }), dropped: true };
+    };
+    if (/^\/v1\/app-config\/[^/]+$/.test(url.pathname)) return drop();
+    let servable;
+    try {
+      const live2 = await manifest(app);
+      const eligible = live2?.releaseId === pin || await isRingRelease(app, pin);
+      const pinned = eligible ? await pinnedManifest(app, pin) : null;
+      servable = pinned !== null;
+      const screenId = /^\/v1\/screen\/([^/]+)$/.exec(url.pathname)?.[1];
+      if (servable && screenId && !pinned?.screens[screenId]) servable = false;
+    } catch {
+      return kept;
+    }
+    return servable ? kept : drop();
+  }
   const corsHeaders = (request) => {
     const origin = request.headers.get("origin");
     if (!origin) return {};
@@ -46856,7 +47209,7 @@ ${releaseId}`;
       "access-control-allow-origin": origin,
       vary: "Origin",
       "access-control-allow-methods": "GET, HEAD, POST, PUT, DELETE, OPTIONS",
-      "access-control-allow-headers": "Content-Type, If-None-Match, X-Himalaya-Schema-Versions, Accept-Language, X-Himalaya-Session, X-Himalaya-User, X-Himalaya-Platform, X-Himalaya-App-Version, X-Himalaya-App, X-Himalaya-Release, X-Himalaya-Preview-Token",
+      "access-control-allow-headers": "Content-Type, If-None-Match, X-Himalaya-Schema-Versions, Accept-Language, X-Himalaya-Session, X-Himalaya-User, X-Himalaya-Platform, X-Himalaya-App-Version, X-Himalaya-App, X-Himalaya-Release, X-Himalaya-Release-Source, X-Himalaya-Preview-Token",
       "access-control-expose-headers": "ETag, X-Himalaya-Bundle-Integrity, X-Himalaya-App",
       "access-control-allow-credentials": "true"
     };
@@ -47396,7 +47749,8 @@ ${releaseId}`;
         }
         const mm = m;
         const readDoc = (hash, live2) => pin ? hash ? pinnedBody(app, hash, live2) : Promise.resolve(null) : live2();
-        const cfgBytes = await readDoc(mm.appConfigHash, () => store.getAppConfig(app));
+        const ringPinned = pin !== null && request.headers.get(RELEASE_SOURCE_HEADER) === "ring";
+        const cfgBytes = ringPinned ? await store.getAppConfig(app) : await readDoc(mm.appConfigHash, () => store.getAppConfig(app));
         if (!cfgBytes) return json3(404, { error: "app_config_not_found", app });
         let appConfig;
         try {
@@ -47404,7 +47758,7 @@ ${releaseId}`;
         } catch {
           return json3(500, { error: "app_config_invalid", app });
         }
-        const bootOverlay = !pin && opts.devControl ? devControlOverlay.get(app) : void 0;
+        const bootOverlay = (!pin || ringPinned) && opts.devControl ? devControlOverlay.get(app) : void 0;
         if (bootOverlay) appConfig.control = { ...appConfig.control ?? {}, ...bootOverlay };
         const tokensBytes = await readDoc(mm.tokensHash, () => store.getTokens(app));
         let tokens = null;
@@ -47421,9 +47775,18 @@ ${releaseId}`;
         let screen = null;
         let screenHash = "";
         let homeBundle = null;
-        const homeMeta = homeScreenId ? mm.screens[homeScreenId] : void 0;
+        let homeFrom = mm;
+        let readHome = readDoc;
+        if (ringPinned && homeScreenId && !mm.screens[homeScreenId]) {
+          const live2 = await manifest(app);
+          if (live2?.screens[homeScreenId]) {
+            homeFrom = live2;
+            readHome = (_hash, liveSlot) => liveSlot();
+          }
+        }
+        const homeMeta = homeScreenId ? homeFrom.screens[homeScreenId] : void 0;
         if (homeScreenId && homeMeta) {
-          const body = await readDoc(homeMeta.descriptorHash, () => store.getScreen(app, homeScreenId));
+          const body = await readHome(homeMeta.descriptorHash, () => store.getScreen(app, homeScreenId));
           if (body) {
             try {
               screen = JSON.parse(utf8Decode(body));
@@ -47433,7 +47796,7 @@ ${releaseId}`;
             }
           }
           if (homeMeta.bundle) {
-            const entry = mm.bundles[homeMeta.bundle];
+            const entry = homeFrom.bundles[homeMeta.bundle];
             if (entry?.sha256 && entry?.sri) {
               homeBundle = {
                 sha256: entry.sha256,
@@ -47443,9 +47806,10 @@ ${releaseId}`;
             }
           }
         }
-        const etag = strongEtag(`${mm.releaseId}:${mm.appConfigHash ?? ""}:${mm.tokensHash ?? ""}:${screenHash}:${homeBundle?.sha256 ?? ""}`);
-        const cache = pin ? PINNED_CACHE_CONTROL : DOC_CACHE_CONTROL;
-        const vary = pin ? { vary: "x-himalaya-release" } : {};
+        const cfgTag = ringPinned ? sha256hex(JSON.stringify(appConfig)) : mm.appConfigHash ?? "";
+        const etag = strongEtag(`${mm.releaseId}:${cfgTag}:${mm.tokensHash ?? ""}:${screenHash}:${homeBundle?.sha256 ?? ""}`);
+        const cache = pin && !ringPinned ? PINNED_CACHE_CONTROL : DOC_CACHE_CONTROL;
+        const vary = pin ? { vary: ringPinned ? `x-himalaya-release, ${RELEASE_SOURCE_HEADER}` : "x-himalaya-release" } : {};
         if (request.headers.get("if-none-match") === etag) {
           return new Response(null, { status: 304, headers: { etag, "cache-control": cache, ...vary } });
         }
@@ -47626,7 +47990,14 @@ ${releaseId}`;
     if (request.method === "OPTIONS") {
       return new Response(null, { status: 204, headers: { ...corsHeaders(request), "content-length": "0" } });
     }
-    const response = await handle(request);
+    const ring = await honourRingPin(request);
+    const response = await handle(ring.request);
+    if (ring.dropped) {
+      const parts = new Set(
+        [...response.headers.get("vary")?.split(",") ?? [], "x-himalaya-release", RELEASE_SOURCE_HEADER].map((s) => s.trim()).filter(Boolean)
+      );
+      response.headers.set("vary", [...parts].join(", "));
+    }
     if (resolvePreviewToken(request, new URL(request.url))) {
       response.headers.set("cache-control", "private, no-store");
       response.headers.set("vary", "x-himalaya-preview-token, x-himalaya-release");
@@ -47996,19 +48367,19 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-DRerTUYc.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1016478, sha256: "42a5b901a0a58a495e5261f68782d28d12aa95cf64df33d9d8d14236e8ea6ead" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 1016486, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1107410, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1198394, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1289374, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1380246, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1471226, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1579862, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1688946, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1797994, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1905694, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1993802, length: 4448, sha256: "98239860f1289aebffdb28d2b9f5ce15fbb95a657bb63d262c650ca21513dde3" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 1998250, length: 17209, sha256: "dffc9718e2faa63ae2cc919e0a842f585ed565aaaa7c53778e90379442c731b6" }
+      { key: "assets/index-DkRimsxm.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1020087, sha256: "4cb472d9d6d952d85166c025544c8bae669215c1a5eafbb800cec32d199bad14" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 1020095, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1111019, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1202003, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1292983, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1383855, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1474835, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1583471, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1692555, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1801603, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1909303, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1997411, length: 4448, sha256: "22fbd62116f9571c6b01c1960990e392cce62198610eea2f661cb4d97bc05787" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 2001859, length: 17209, sha256: "dffc9718e2faa63ae2cc919e0a842f585ed565aaaa7c53778e90379442c731b6" }
     ];
   }
 });

package/guides/himi-test.md

@@ -120,6 +120,22 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `list-shrank-on-load-more` | **warning** | A "load more" returned FEWER rows than before it ran: the new page replaced the list instead of extending it. |
 | `list-grew-on-filter` | **warning** | A filter, search or sort made a list longer. Narrowing can reorder or remove, never add. |
 | `typed-value-ignored` | **warning** | The crawl typed the value a control really carries — the payload key every renderer injects for that control — and the dispatch changed **nothing**: no state, no navigation, no request. The value is read off the app itself (an id from the control's own options, or a word from the worker's seeded state) and is always one the control is *not* already showing, so a reducer that ignores it cannot work on device. A warning because the input is the crawl's: a reducer that legitimately no-ops on a value is possible, and `himi-test.json` `skip[]` takes the invariant. |
+| `unnamed-control` | error | **Accessibility.** An operable control — a `Button`, `Toggle`, `TextField`, `Chip`, … or any node an `onTap` promotes to a button — whose *only* accessible name is a binding the worker resolved to an empty string, so a screen reader announces an unnamed control. `himi validate`'s a11y pass cannot see this: it counts `$service:` / `$item` as a name, because on device it becomes copy. Only the crawl has run the worker. Judged per real row inside a bound list, and reported once at the row template. Silent on a name authored empty (that is `himi validate`'s finding, not repeated here), on `null` / absent values (other invariants'), on content that is not a control (a bound `Text` that came out empty), and on nodes collapsed in that state. |
+
+**Accessibility: what a clean run does NOT mean.** `unnamed-control` is the only
+accessibility property the crawl judges, and it is deliberately the narrow one: the name a
+worker actually produced for a control. It does not judge names authored in the descriptor
+(`himi validate` does — its `a11y` pass is on by default, and the crawl never repeats what it
+reports), role or state announcement, focus order, contrast, or touch-target size. The gap
+ledger says so on every run with an `a11y` entry, because a headless crawl cannot close it —
+before that entry existed, a clean crawl with an empty ledger read as an accessibility pass.
+It ships at `error`: a control a screen reader cannot name is unusable, not a matter of taste.
+Swept before it did, over 53 apps and templates: one false positive (a tap-to-dismiss `Text`
+that `collapseWhenEmpty` removes, now honoured) and one real defect — a blank download button
+on a lesson screen whose id resolves to no lesson. That last one is also why an input-less boot's
+finding is **not** retired the way `no-request-issued` is: a detail screen reached with a stale
+or unknown id renders exactly the state the crawl's input-less boot does, so a label that goes
+blank there goes blank for a real user too.
 
 **Deliberately never reported:** an empty collection · an `error` state (often the correct
 answer to empty input) · a `null` optional.

package/guides/tokens.md

@@ -20,6 +20,7 @@ one registry, mirrored byte-for-byte by the iOS + Android decoders.
 | `tabBar` / `drawer` / `sidebar` | nav-chrome style blocks | optional |
 | `kit` | { material?, variant?, density?, motion? } | optional — the active design kit |
 | `contentMaxWidth` | { base, medium?, expanded? } | optional |
+| `elevations` | name → { level?, tint?, shadow?, border? } | optional — a Card wears `card` |
 
 ## ⚠️ Typography requires `size`, `weight`, AND `line`
 
@@ -86,3 +87,12 @@ Alternative full token sets ship with the CLI as design kits (material, shadcn,
 liquid-glass, brutalist, dark-luxe, neumorphic, skeuomorphic, minimal-editorial). Adopt a kit
 by copying its `tokens` into tokens.json; the active kit's app-wide axes
 (material/variant/density/motion) live in the top-level `kit` block.
+
+## Elevation
+
+`elevations.card` is the depth every `Card` wears — paint only, never a layout change:
+`level` 0–5 is Material 3 tonal elevation (the fill tinted with `tint`, default `accentPrimary`),
+`shadow` names a `shadows` token cast in the Card's own shape, and `border: { color, width? }`
+is a hairline inside the edge (default 0.5). Declare none and Cards stay flat. To look native on
+each platform, declare `"card": {}` and let the idiom overlays fill it: `material` a `level`,
+`ios` a `border` + `shadow`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1018.0",
+  "version": "0.1020.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -65,5 +65,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "94fed53fcfc6d8dbb2472ab3ebd2f6fc24d2cbe457604bc1f3601f2d"
+  "falconPackageHash": "74688239abb5b83cdc592a78513066472b921f1273d54470d9796cab"
 }