@gemboss/gem-framework 0.9.3 → 0.10.0

package/dist/index.js

@@ -191,7 +191,7 @@ function gemPlanShapeKnobs(plan) {
 }
 
 // ../../packages/gem-framework/src/tokens.ts
-var gemFrameworkVersion = "0.1.0";
+var gemFrameworkVersion = "0.10.0";
 var GEM_FOCUS_RING_CSS_VAR = "--gem-focus-ring: 2px solid var(--gem-color-accent);";
 var GEM_TAP_MIN_CSS_VAR = "--gem-tap-min: 44px;";
 var GEM_FOCUS_OFFSET_CSS_VAR = "--gem-focus-offset: 3px;";
@@ -225,6 +225,73 @@ var GEM_ROW_CSS_VARIABLES = [
   "--gem-row-gap",
   "--gem-row-gap-y"
 ];
+var GEM_BUTTON_TOKEN_KEYS = {
+  radius: ["button"],
+  typography: ["buttonWeight", "buttonTransform", "buttonLetterSpacing"]
+};
+var GEM_BUTTON_TOKEN_SHAPES = {
+  "radius.button": /^(0|\d*\.?\d+(px|rem|em|%)|var\(--gem-radius-[a-z0-9-]+\))$/i,
+  "typography.buttonWeight": /^(normal|bold|\d{1,4})$/i,
+  "typography.buttonTransform": /^(none|uppercase|lowercase|capitalize)$/i,
+  "typography.buttonLetterSpacing": /^(normal|0|-?\d*\.?\d+(em|px|rem))$/i
+};
+var buttonKeyNorm = (k) => k.toLowerCase().replace(/[_-]/g, "");
+function buttonTokenValue(group, key, value) {
+  const shape = GEM_BUTTON_TOKEN_SHAPES[`${group}.${key}`];
+  if (!shape) return null;
+  const v = typeof value === "number" ? String(value) : typeof value === "string" ? stripImportant(value).trim() : "";
+  if (!shape.test(v)) return null;
+  if (key === "buttonWeight" && /^\d+$/.test(v) && (Number(v) < 1 || Number(v) > 1e3)) return null;
+  if (key === "button" && v === "0") return "0px";
+  return /^[a-z]+$/i.test(v) ? v.toLowerCase() : v.replace(/(px|rem|em)$/i, (u) => u.toLowerCase());
+}
+function readButtonTokens(tokens) {
+  const out = { groups: {}, values: {}, invalid: [] };
+  for (const [group, keys] of Object.entries(GEM_BUTTON_TOKEN_KEYS)) {
+    const values = tokens?.[group];
+    if (!values || typeof values !== "object" || Array.isArray(values)) continue;
+    const byNorm = new Map(keys.map((k) => [buttonKeyNorm(k), k]));
+    let copy = null;
+    for (const [rawKey, raw] of Object.entries(values)) {
+      const key = byNorm.get(buttonKeyNorm(rawKey));
+      if (!key) continue;
+      copy ??= { ...values };
+      delete copy[rawKey];
+      const v = buttonTokenValue(group, key, raw);
+      if (v === null) out.invalid.push({ path: `${group}.${rawKey}`, value: raw });
+      else {
+        copy[key] = v;
+        out.values[key] = v;
+      }
+    }
+    if (copy) out.groups[group] = copy;
+  }
+  return out;
+}
+function splitSelectorList(selector) {
+  const parts = [];
+  let depth = 0, cur = "";
+  for (const ch of selector) {
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(cur.trim());
+      cur = "";
+    } else cur += ch;
+  }
+  if (cur.trim()) parts.push(cur.trim());
+  return parts;
+}
+function gemButtonCaseCss(tokens, selector = ":root") {
+  const { values } = readButtonTokens(tokens);
+  const decls = [
+    values.buttonTransform && "text-transform: var(--gem-font-button-transform);",
+    values.buttonLetterSpacing && "letter-spacing: var(--gem-font-button-letter-spacing);"
+  ].filter(Boolean);
+  if (!decls.length) return "";
+  const scope = splitSelectorList(selector).map((sel) => `${sel} .gem-button:not(.gem-button--link)`).join(", ");
+  return `:where(${scope}) { ${decls.join(" ")} }`;
+}
 var requiredGemTokenKeys = {
   color: ["background", "surface", "text", "muted", "accent", "accentText", "border", "success", "warning", "danger"],
   typography: ["body", "heading", "mono"],
@@ -237,6 +304,52 @@ var requiredGemTokenKeys = {
   component: ["headerHeight", "cardPadding", "buttonPaddingInline", "buttonPaddingBlock", "inputHeight"],
   morphology: ["campaignDensity", "mediaRhythm", "proofIntensity", "commerceEmphasis", "policyTone"]
 };
+var GEM_PHONE_TOKEN_TARGETS = {
+  spacing: [...requiredGemTokenKeys.spacing, ...Object.keys(GEM_DERIVED_SPACE_STEPS)],
+  layout: ["section"]
+};
+var tokenKeyNorm = (k) => k.toLowerCase().replace(/[^a-z0-9]/g, "");
+var PHONE_TARGET_BY_KEY = Object.fromEntries(
+  Object.entries(GEM_PHONE_TOKEN_TARGETS).map(([group, targets]) => [group, new Map(targets.map((t) => [`${tokenKeyNorm(t)}mobile`, t]))])
+);
+function gemPhoneTokenTarget(group, key) {
+  return PHONE_TARGET_BY_KEY[group]?.get(tokenKeyNorm(key)) ?? null;
+}
+function readPhoneTokens(tokens) {
+  const out = { spacing: {}, layout: {}, invalid: [] };
+  for (const group of ["spacing", "layout"]) {
+    const ownGroup = group === "spacing" ? /var\(\s*--gem-space-/i : /var\(\s*--gem-layout-/i;
+    for (const [key, raw] of Object.entries(tokens?.[group] ?? {})) {
+      const target = gemPhoneTokenTarget(group, key);
+      if (target == null) continue;
+      const v = stripImportant(String(raw ?? "")).trim();
+      const kind = gemSpaceMdKind(v);
+      if (kind === "absent") continue;
+      if (kind === "zero") out[group][target] = "0px";
+      else if (kind === "length" && !ownGroup.test(v)) out[group][target] = v;
+      else out.invalid.push({ path: `${group}.${key}`, value: raw, why: kind === "length" ? `it reads a ${group} variable, which re-declared on :root is a cycle` : "not a length (a number needs a unit, e.g. 70px)" });
+    }
+  }
+  return out;
+}
+var GEM_LINE_HEIGHT_TOKEN_KEYS = ["headingLineHeight", "bodyLineHeight"];
+var LINE_HEIGHT_SHAPE = /^(normal|\d*\.?\d+(px|rem|em|%)?|(var|calc|clamp|min|max)\(.*\))$/i;
+var isLineHeightKey = (k) => GEM_LINE_HEIGHT_TOKEN_KEYS.some((l) => tokenKeyNorm(l) === tokenKeyNorm(k));
+var badLineHeight = (k, v) => isLineHeightKey(k) && !LINE_HEIGHT_SHAPE.test(stripImportant(String(v ?? "")).trim());
+var desktopEntries = (group, values) => values ? Object.fromEntries(Object.entries(values).filter(([key]) => gemPhoneTokenTarget(group, key) == null)) : values;
+var GEM_TYPE_RAMP_KEYS = ["base", "scale", "baseMobile"];
+var optionalGemTokenKeys = {
+  typography: [...GEM_TYPE_RAMP_KEYS, ...GEM_LINE_HEIGHT_TOKEN_KEYS, ...GEM_BUTTON_TOKEN_KEYS.typography],
+  spacing: [...Object.keys(GEM_DERIVED_SPACE_STEPS), ...GEM_PHONE_TOKEN_TARGETS.spacing.map((k) => `${k}Mobile`)],
+  layout: GEM_PHONE_TOKEN_TARGETS.layout.map((k) => `${k}Mobile`),
+  radius: [...GEM_BUTTON_TOKEN_KEYS.radius]
+};
+var GEM_HEADING_SIZE_CSS_VARS = [
+  "--gem-section-heading-size: calc(var(--gem-h2) * var(--gem-typography-heading-scale, 1));",
+  "--gem-hero-heading-size: calc(var(--gem-h1) * var(--gem-typography-heading-scale, 1));",
+  "--gem-section-heading-size-mobile: min(var(--gem-section-heading-size), var(--gem-heading-phone-cap, clamp(1.75rem, 9vw, 2.75rem)));",
+  "--gem-hero-heading-size-mobile: min(var(--gem-hero-heading-size), var(--gem-heading-phone-cap, clamp(1.75rem, 9vw, 2.75rem)));"
+];
 var defaultGemTokens = {
   color: {
     background: "#f6f6f3",
@@ -342,23 +455,37 @@ function validateGemTokens(tokens) {
       }
     }
   }
+  for (const bad of readButtonTokens(tokens).invalid) {
+    const shape = GEM_BUTTON_TOKEN_SHAPES[bad.path.replace(/\.[^.]+$/, (k) => "." + (Object.values(GEM_BUTTON_TOKEN_KEYS).flat().find((c) => buttonKeyNorm(c) === buttonKeyNorm(k.slice(1))) ?? k.slice(1)))];
+    issues.push(tokenIssue("warn", "invalid_button_token", `Gem token ${bad.path} = ${JSON.stringify(bad.value)} is not a valid value (${shape}); the button keeps its default.`, bad.path));
+  }
+  for (const bad of readPhoneTokens(tokens).invalid) {
+    issues.push(tokenIssue("warn", "invalid_phone_token", `Gem token ${bad.path} = ${JSON.stringify(bad.value)} is not used: ${bad.why}. Phones keep the desktop value.`, bad.path));
+  }
+  for (const [key, value] of Object.entries(tokens.typography ?? {})) {
+    if (badLineHeight(key, value)) issues.push(tokenIssue("warn", "invalid_line_height_token", `Gem token typography.${key} = ${JSON.stringify(value)} is not a line-height (1.2, 120%, 24px, normal); headings keep their default.`, `typography.${key}`));
+  }
   return {
     valid: !issues.some((issue) => issue.severity === "error"),
     issues
   };
 }
 function createGemTokenCss(tokens, selector = ":root") {
+  const button = readButtonTokens(tokens);
+  const phone = readPhoneTokens(tokens);
+  const spacing = desktopEntries("spacing", tokens.spacing);
   const declarations = [
     ...toCssVars("color", tokens.color),
-    ...toCssVars("font", Object.fromEntries(Object.entries(tokens.typography ?? {}).filter(([k]) => !isRampKey(k)))),
+    ...toCssVars("font", Object.fromEntries(Object.entries(button.groups.typography ?? tokens.typography ?? {}).filter(([k, v]) => !isRampKey(k) && !badLineHeight(k, v)))),
     // Space ramp is scaled by the global density knob --gem-style-space (default 1),
     // so a style pack can make the WHOLE storefront airier or denser without touching
     // any section — every section already consumes --gem-space-*. Knob unset → identical.
-    ...toScaledCssVars("space", tokens.spacing, "--gem-style-space"),
-    ...gemDerivedSpaceCssVars(tokens.spacing),
+    // Phone keys (`3xlMobile`) are not desktop variables: they go to the phone block below (GEM_PHONE_TOKEN_TARGETS).
+    ...toScaledCssVars("space", spacing, "--gem-style-space"),
+    ...gemDerivedSpaceCssVars(spacing),
     // Radius ramp scaled by --gem-style-radius (default 1): a 'sharp' style sets it to
     // 0 (square everything), 'pill' rounds further — across every section, no edits.
-    ...toScaledCssVars("radius", tokens.radius, "--gem-style-radius"),
+    ...toScaledCssVars("radius", button.groups.radius ?? tokens.radius, "--gem-style-radius"),
     // Border widths get the --gem-style-border knob injected into their leading length,
     // whatever value the plan provides (e.g. "1px solid …" → "calc(1px * var(...)) solid …").
     ...toBorderCssVars("border", tokens.border, "--gem-style-border"),
@@ -367,7 +494,8 @@ function createGemTokenCss(tokens, selector = ":root") {
     // and marquee primitives consume; unrecognised keys fall back to the --gem-motion-* namespace,
     // so duration/easing keep emitting --gem-motion-duration/easing exactly as before (back-compat).
     ...toMotionCssVars(tokens.motion),
-    ...toCssVars("layout", tokens.layout),
+    ...toCssVars("layout", desktopEntries("layout", tokens.layout)),
+    ...phone.layout.section ? [`--gem-layout-section-mobile: ${phone.layout.section};`] : [],
     ...toCssVars("component", tokens.component),
     ...toCssVars("morphology", tokens.morphology),
     // THE GOVERNED TYPE RAMP — --gem-h1..h6 / --gem-body / --gem-text-sm.
@@ -377,6 +505,8 @@ function createGemTokenCss(tokens, selector = ":root") {
     // variables that resolved to nothing. One modular scale, retuned by overriding --gem-type-base
     // or --gem-type-scale (see gemTypeRampCssVars).
     ...gemTypeRampCssVars(tokens.typography),
+    // Heading sizes from the ramp, only for a plan that chose a ramp (GEM_HEADING_SIZE_CSS_VARS).
+    ...typeRampValue(tokens.typography, "base") || typeRampValue(tokens.typography, "scale") ? GEM_HEADING_SIZE_CSS_VARS : [],
     // Focus ring (gemfactory request #3, 28/09/2026): 11 sections wrote `outline: 2px solid
     // var(--gem-color-accent)` by hand. Not a token GROUP (a group would name it --gem-border-focus-ring
     // and a required key would fail every stored plan/preset without it), so it is emitted here like the
@@ -386,16 +516,25 @@ function createGemTokenCss(tokens, selector = ":root") {
     GEM_FOCUS_OFFSET_CSS_VAR
   ];
   const formBlock = gemFormCssBlock(tokens.form);
-  const baseMobile = typeRampValue(tokens.typography, "baseMobile");
+  const buttonCase = gemButtonCaseCss(tokens, selector);
+  const mobile = gemMobileTokenCssVars(tokens, phone);
   return [
     `${selector} {`,
     ...declarations.map((line) => `  ${line}`),
     "}",
-    ...baseMobile ? [`@media (max-width: ${GEM_TYPE_MOBILE_MAX}) {`, `  ${selector} {`, `    --gem-type-base: ${baseMobile};`, "  }", "}"] : [],
-    ...formBlock ? [formBlock] : []
+    ...mobile.length ? [`@media (max-width: ${GEM_TYPE_MOBILE_MAX}) {`, `  ${selector} {`, ...mobile.map((line) => `    ${line}`), "  }", "}"] : [],
+    ...formBlock ? [formBlock] : [],
+    ...buttonCase ? [buttonCase] : []
   ].join("\n");
 }
-var GEM_TYPE_RAMP_KEYS = ["base", "scale", "baseMobile"];
+function gemMobileTokenCssVars(tokens, phone = readPhoneTokens(tokens)) {
+  const baseMobile = typeRampValue(tokens.typography, "baseMobile");
+  return [
+    ...baseMobile ? [`--gem-type-base: ${baseMobile};`] : [],
+    ...toScaledCssVars("space", phone.spacing, "--gem-style-space"),
+    ...toCssVars("layout", phone.layout)
+  ];
+}
 var rampKey = (k) => k.toLowerCase().replace(/[^a-z0-9]/g, "");
 var isRampKey = (k) => GEM_TYPE_RAMP_KEYS.some((r) => rampKey(r) === rampKey(k));
 var LENGTH = /^\d*\.?\d+(px|rem|em)$/;
@@ -879,10 +1018,10 @@ function createGemFrameworkManifest() {
     package_name: "@gemtheme/gem-framework",
     framework_version: gemFrameworkVersion,
     namespace: "gem",
-    token_groups: Object.entries(requiredGemTokenKeys).map(([group, keys]) => ({
-      group,
-      keys: [...keys]
-    })),
+    token_groups: Object.entries(requiredGemTokenKeys).map(([group, keys]) => {
+      const optional = [...optionalGemTokenKeys[group] ?? []];
+      return { group, keys: [...keys], ...optional.length ? { optional_keys: optional } : {} };
+    }),
     primitive_groups: gemFrameworkPrimitiveGroups.map((group) => ({
       group: group.group,
       classes: [...group.classes]
@@ -1186,7 +1325,6 @@ var GEM_AMBIENT_CSS_LINES = [
   "@media (prefers-reduced-motion: reduce) {",
   "  [data-gem-ambient] { --gem-ambient-amp: 2px; animation-duration: 12s; }",
   "  [data-gem-reveal] { transition: none; opacity: 1; transform: none; }",
-  "  .gem-marquee__track { animation-duration: calc(var(--gem-marquee-duration, 40s) * 2.5); }",
   "}"
 ];
 var GEM_AMBIENT_CSS = GEM_AMBIENT_CSS_LINES.join("\n");
@@ -1376,9 +1514,13 @@ function createPrimitiveCss() {
     "  justify-content: center;",
     "  min-height: var(--gem-component-input-height, 44px);",
     "  border: var(--gem-button-border-width, 1px) solid var(--gem-color-border);",
-    "  border-radius: var(--gem-radius-md);",
+    // Button tokens (GEM_BUTTON_TOKEN_KEYS, optional): unset, radius and weight fall back to exactly what this rule always
+    // drew. --gem-radius-button is the button's own radius, so a pill button does not turn every card into a pill
+    // (radius-md is shared). Case and tracking are NOT declared here: <button> gets `none` / `normal` from the UA sheet
+    // while <a> inherits, so createGemTokenCss adds them only when a token sets them (gemButtonCaseCss).
+    "  border-radius: var(--gem-radius-button, var(--gem-radius-md));",
     "  padding: var(--gem-component-button-padding-block, 12px) var(--gem-component-button-padding-inline, 18px);",
-    "  font-weight: 700;",
+    "  font-weight: var(--gem-font-button-weight, 700);",
     "  text-decoration: none;",
     "  transition: background var(--gem-motion-duration, 160ms) var(--gem-motion-easing, ease), color var(--gem-motion-duration, 160ms) var(--gem-motion-easing, ease);",
     "}",
@@ -1641,28 +1783,6 @@ function createPrimitiveCss() {
     "  border-radius: var(--gem-radius-md);",
     "  background: color-mix(in srgb, var(--gem-color-text) 8%, var(--gem-color-background));",
     "}",
-    ".gem-marquee {",
-    "  overflow: hidden;",
-    "  border-block: var(--gem-border-subtle, 1px solid var(--gem-color-border));",
-    "}",
-    // Consumer contract: render the track's children TWICE (like the site's `.mq-row`) so the
-    // -50% translate lands on an identical second copy and the loop is seamless with no visible jump.
-    // The animation reuses the gem-marquee-scroll keyframe defined with the ambient primitive.
-    ".gem-marquee__track {",
-    "  display: flex;",
-    "  gap: var(--gem-space-lg);",
-    "  min-width: max-content;",
-    "  animation: gem-marquee-scroll var(--gem-marquee-duration, 40s) linear infinite;",
-    "  will-change: transform;",
-    "}",
-    // Pause-on-hover lets a shopper read a badge/logo they want to inspect.
-    ".gem-marquee:hover .gem-marquee__track {",
-    "  animation-play-state: paused;",
-    "}",
-    // Opt-in reverse direction (e.g. a second row scrolling the other way).
-    ".gem-marquee[data-gem-marquee-reverse] .gem-marquee__track {",
-    "  animation-direction: reverse;",
-    "}",
     ".gem-carousel {",
     "  display: grid;",
     "  gap: var(--gem-space-md);",
@@ -1798,9 +1918,20 @@ function createPrimitiveCss() {
     "  overflow: hidden;",
     "  color: var(--gem-color-accent);",
     "}",
-    // Marquee primitive — CSS-only and deliberately so (no JS to init, works on every render path).
-    // The one requirement is a DUPLICATED track: a single track scrolls off and leaves a gap.
-    ".gem-marquee { overflow: hidden; }",
+    // Marquee primitive. CSS-only and deliberately so (no JS to init, works on every render path).
+    // Contract: `.gem-marquee > .gem-marquee__viewport > .gem-marquee__track` TWICE (the second copy
+    // aria-hidden); each track is at least the viewport wide and moves -100% of itself, so the second
+    // copy is what makes the loop seamless. gemcapture's clone kit and GemFactory build exactly this.
+    // ONE definition (0.9.11): until then a second, earlier one (gemtheme #124: one track with its
+    // children doubled, -50%) sat above this and lost every property both set, so its contract never
+    // worked. What it set that still took effect (the border, will-change, pause on hover of the whole
+    // marquee, the data-attribute reverse) is kept here, so a marquee built to either contract computes
+    // the same style as before (Chromium, 08/10/2026). The one exception would be a track that also
+    // carries data-gem-ambient, which nothing renders.
+    ".gem-marquee {",
+    "  overflow: hidden;",
+    "  border-block: var(--gem-border-subtle, 1px solid var(--gem-color-border));",
+    "}",
     ".gem-marquee__viewport { display: flex; overflow: hidden; }",
     ".gem-marquee__track {",
     "  flex: 0 0 auto;",
@@ -1811,9 +1942,12 @@ function createPrimitiveCss() {
     "  gap: var(--gem-space-lg);",
     "  white-space: nowrap;",
     "  animation: gem-marquee var(--gem-marquee-duration, 24s) linear infinite;",
+    "  will-change: transform;",
     "}",
-    ".gem-marquee__viewport:hover .gem-marquee__track { animation-play-state: paused; }",
-    ".gem-marquee--reverse .gem-marquee__track { animation-direction: reverse; }",
+    // Pause-on-hover lets a shopper read a badge/logo they want to inspect.
+    ".gem-marquee:hover .gem-marquee__track, .gem-marquee__viewport:hover .gem-marquee__track { animation-play-state: paused; }",
+    // Opt-in reverse direction (e.g. a second row scrolling the other way).
+    ".gem-marquee--reverse .gem-marquee__track, .gem-marquee[data-gem-marquee-reverse] .gem-marquee__track { animation-direction: reverse; }",
     "@keyframes gem-marquee { from { transform: translateX(0); } to { transform: translateX(-100%); } }",
     "@media (prefers-reduced-motion: reduce) {",
     "  .gem-marquee__track { animation: none; }",
@@ -2831,10 +2965,10 @@ function createGemSectionRuntimeContractCss(selector = "[data-gem-section-librar
     "}"
   ].join("\n");
 }
-var OPT_IN_EYEBROW = ":where(.gem-section[data-gem-eyebrow='show']) .gem-section__eyebrow { display: block; letter-spacing: 0.12em; }";
-var OPT_IN_HEADING = ":where(.gem-section[data-gem-heading='section']) .gem-section__heading { margin: 0; font-family: var(--gem-font-heading); font-size: var(--gem-h2); line-height: 1.1; letter-spacing: -0.01em; text-wrap: balance; }";
+var OPT_IN_EYEBROW = ":where(.gem-section[data-gem-eyebrow='show']) .gem-section__eyebrow { display: block; font-size: var(--gem-text-sm); letter-spacing: 0.12em; }";
+var OPT_IN_HEADING = ":where(.gem-section[data-gem-heading='section']) .gem-section__heading { margin: 0; font-family: var(--gem-font-heading); font-size: var(--gem-section-heading-size, var(--gem-h2)); line-height: var(--gem-font-heading-line-height, 1.1); letter-spacing: -0.01em; text-wrap: balance; }";
 var OPT_IN_BODY = ":where(.gem-section[data-gem-body='section']) .gem-section__body { margin: 0; color: var(--gem-color-muted); font-size: var(--gem-body); line-height: var(--gem-font-body-line-height, 1.5); }";
-var OPT_IN_HEADING_MOBILE = "  :where(.gem-section[data-gem-heading='section']) .gem-section__heading { font-size: min(var(--gem-h2), clamp(1.75rem, 9vw, 2.75rem)); }";
+var OPT_IN_HEADING_MOBILE = "  :where(.gem-section[data-gem-heading='section']) .gem-section__heading { font-size: var(--gem-section-heading-size-mobile, min(var(--gem-h2), clamp(1.75rem, 9vw, 2.75rem))); }";
 function createSectionCss() {
   return [
     ".gem-section {",
@@ -3026,8 +3160,8 @@ function createSectionCss() {
     ".gem-section__heading {",
     "  margin: 0;",
     "  font-family: var(--gem-font-heading);",
-    "  font-size: clamp(calc(2rem * var(--gem-typography-heading-scale, 1)), calc(4vw * var(--gem-typography-heading-scale, 1)), calc(4rem * var(--gem-typography-heading-scale, 1)));",
-    "  line-height: 1.04;",
+    "  font-size: var(--gem-section-heading-size, clamp(calc(2rem * var(--gem-typography-heading-scale, 1)), calc(4vw * var(--gem-typography-heading-scale, 1)), calc(4rem * var(--gem-typography-heading-scale, 1))));",
+    "  line-height: var(--gem-font-heading-line-height, 1.04);",
     "}",
     ".gem-section__body {",
     "  margin: 0;",
@@ -3144,9 +3278,10 @@ function createSectionCss() {
     "  }",
     "}",
     "@media (max-width: 760px) {",
-    "  .gem-section { padding-block: calc(var(--gem-layout-section, 64px) * 0.72); }",
+    // A declared layout.sectionMobile is final (tokens.ts GEM_PHONE_TOKEN_TARGETS); otherwise the desktop value × 0.72.
+    "  .gem-section { padding-block: var(--gem-layout-section-mobile, calc(var(--gem-layout-section, 64px) * 0.72)); }",
     "  .gem-section__inner, .gem-container { width: min(100% - 32px, var(--gem-layout-page, 1180px)); }",
-    "  .gem-section__heading { font-size: clamp(1.75rem, 9vw, 2.75rem); }",
+    "  .gem-section__heading { font-size: var(--gem-section-heading-size-mobile, clamp(1.75rem, 9vw, 2.75rem)); }",
     "  .gem-section__grid { grid-template-columns: minmax(0, 1fr); }",
     "  .gem-section:is([data-gem-composition-mode='split-collage'], [data-gem-editorial-band-mode='media-story']) .gem-section__grid { grid-template-columns: minmax(0, 1fr); }",
     "  .gem-product-main[data-gem-product-main-layout='dawn-main'] .gem-product-main__inner { grid-template-columns: minmax(0, 1fr); }",
@@ -3166,7 +3301,7 @@ function createSectionCss() {
 function createDawnParityCss() {
   return [
     "/* Dawn parity profile: locked default baseline; morph presets must opt out before applying Gem visual identity. */",
-    ":root { --gem-profile-mode: dawn-parity; --gem-layout-page: 1100px; --gem-layout-gutter: 32px; --gem-layout-section: 52px; --gem-radius-md: 0px; --gem-card-radius: 0px; --gem-media-radius: 0px; --gem-grid-column-gap: 8px; --gem-grid-row-gap: 8px; }",
+    ":root { --gem-profile-mode: dawn-parity; --gem-layout-page: 1100px; --gem-layout-gutter: 32px; --gem-layout-section: 52px; --gem-radius-md: 0px; --gem-card-radius: 0px; --gem-media-radius: 0px; --gem-grid-column-gap: 8px; --gem-grid-row-gap: 8px; --gem-heading-phone-cap: clamp(2rem, 11vw, 3.6rem); }",
     ".utility-bar, .announcement-bar, .utility-bar__grid { min-height: 38px; }",
     ".announcement-bar__message { margin: 0; min-height: 38px; padding-block: 10px; font-size: 0.75rem; font-weight: 400; letter-spacing: 0.04em; }",
     // The pair of rules here used to blank the real message (font-size: 0) and inject a FIXED
@@ -3242,7 +3377,12 @@ function createDawnParityCss() {
     ".gem-hero-banner--split-proof .gem-hero-banner__media, .gem-hero-banner--editorial .gem-hero-banner__media { position: relative; inset: auto; min-height: 26rem; height: 100%; overflow: hidden; border-radius: 6px; background: rgb(244 244 244); }",
     ".gem-hero-banner--split-proof .gem-hero-banner__image, .gem-hero-banner--split-proof .gem-hero-banner__placeholder, .gem-hero-banner--editorial .gem-hero-banner__image, .gem-hero-banner--editorial .gem-hero-banner__placeholder { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; display: block; }",
     ".gem-hero-banner .gem-section__content { max-width: 78rem; margin-inline: auto; }",
-    ".gem-hero-banner h1, .gem-hero-banner h2, .gem-section__heading { margin: 0 0 1.5rem; font-size: clamp(calc(2.5rem * var(--gem-typography-heading-scale, 1)), calc(4vw * var(--gem-typography-heading-scale, 1)), calc(5.2rem * var(--gem-typography-heading-scale, 1))); font-weight: 400; line-height: 1.08; letter-spacing: 0; }",
+    ".gem-hero-banner h1, .gem-hero-banner h2, .gem-section__heading { margin: 0 0 1.5rem; font-weight: 400; line-height: var(--gem-font-heading-line-height, 1.08); letter-spacing: 0; }",
+    // Font size has ONE owner per selector (one-owner-per-selector.test.ts): section headings take H2 of the plan's ramp,
+    // the hero's own title H1 (tokens.ts GEM_HEADING_SIZE_CSS_VARS). Same position and specificity as the shared rule above,
+    // so with no ramp both resolve to the clamp that rule used to set.
+    ".gem-section__heading { font-size: var(--gem-section-heading-size, clamp(calc(2.5rem * var(--gem-typography-heading-scale, 1)), calc(4vw * var(--gem-typography-heading-scale, 1)), calc(5.2rem * var(--gem-typography-heading-scale, 1)))); }",
+    ".gem-hero-banner h1, .gem-hero-banner h2 { font-size: var(--gem-hero-heading-size, clamp(calc(2.5rem * var(--gem-typography-heading-scale, 1)), calc(4vw * var(--gem-typography-heading-scale, 1)), calc(5.2rem * var(--gem-typography-heading-scale, 1)))); }",
     ".gem-section__eyebrow { display: none; }",
     ".gem-hero-banner--compact-collection { min-height: auto; display: block; text-align: left; padding-block: 25px; }",
     ".gem-hero-banner--compact-collection .gem-section__content, .gem-product-card-grid--quick-view-grid > .gem-section__inner { width: min(var(--gem-layout-page, 1200px), calc(100% - var(--gem-layout-gutter, 32px))); margin-inline: auto; }",
@@ -3257,7 +3397,13 @@ function createDawnParityCss() {
     ".gem-rich-text--dawn-intro .gem-section__body { width: 100%; max-width: none; margin: 20px 0 0; font-size: 16px; line-height: 28.8px; }",
     ".gem-rich-text--dawn-intro .gem-section__body p { margin: 0; }",
     ".gem-rich-text--dawn-intro .gem-rich-text__blocks { display: block; width: 100%; }",
-    ".gem-button { min-width: 12rem; border-radius: 0; font-weight: 400; box-shadow: none; }",
+    // Dawn's square, regular-weight button stays the default; the button tokens (radius.button, typography.buttonWeight)
+    // override it, or this rule (same specificity, later) would pin every button square at 400 whatever the plan says.
+    // The weight sits in its own rule that skips link buttons, which keep today's 400 here: the rule above it is what
+    // overrides `.gem-button--link { font-weight: inherit }` in this profile, and a weight token must not reach a link.
+    // `:where()` keeps both at one class of specificity, so a section's own CTA rule still wins.
+    ".gem-button { min-width: 12rem; border-radius: var(--gem-radius-button, 0); font-weight: 400; box-shadow: none; }",
+    ".gem-button:where(:not(.gem-button--link)) { font-weight: var(--gem-font-button-weight, 400); }",
     ".gem-product-card-wrapper { display: block; min-width: 0; }",
     ".gem-card, .gem-product-card { border: 0; border-radius: 0; box-shadow: none; background: transparent; padding: 0; }",
     ".gem-product-card__media, .gem-media { border: 0; border-radius: 0; box-shadow: none; background: rgb(244 244 244); }",
@@ -3453,7 +3599,9 @@ function createDawnParityMobileCss() {
     "  .gem-product-card__content { padding-top: 8px; gap: 4px; }",
     "  .gem-product-card__title { font-size: 15px; line-height: 24px; }",
     "  .gem-product-card__price, .gem-product-card__price .gem-price { font-size: 16px; line-height: 24px; }",
-    "  .gem-hero-banner h1, .gem-hero-banner h2, .gem-section__heading { font-size: clamp(2rem, 11vw, 3.6rem); }",
+    // Fallback = the profile's own phone heading, declared once as --gem-heading-phone-cap on the :root above.
+    "  .gem-section__heading { font-size: var(--gem-section-heading-size-mobile, var(--gem-heading-phone-cap)); }",
+    "  .gem-hero-banner h1, .gem-hero-banner h2 { font-size: var(--gem-hero-heading-size-mobile, var(--gem-heading-phone-cap)); }",
     "  .gem-featured-collection--editorial-grid .gem-section__grid, .gem-product-card-grid--quick-view-grid .gem-section__grid, .gem-main-search .gem-section__grid { grid-template-columns: repeat(var(--gem-product-card-grid-mobile-columns, 2), minmax(0, 1fr)); }",
     "  .gem-product-main[data-gem-product-main-layout='dawn-main'] > .gem-section__inner { width: calc(100% - 30px); }",
     "  .gem-product-main[data-gem-product-main-layout='dawn-main'] .gem-product-media-gallery__frame { display: flex; gap: 0; overflow-x: auto; scroll-snap-type: x mandatory; }",
@@ -4555,7 +4703,38 @@ var mediaGalleryPluginRegistrationLines = [
   "    const galleries = document.querySelectorAll('[data-gem-media-gallery], .gem-media-gallery, .gem-product-media-gallery');",
   "    let bound = 0;",
   "    galleries.forEach((gallery) => {",
+  // A wrapper matched only by its class (the thumbnail-stack <section class="gem-product-media-gallery">) around a
+  // [data-gem-media-gallery] hook is not a second gallery: binding both ran every click twice and the outer one
+  // renumbered the thumbnails' data-gem-media-index by counting every <img>, the main image included.
+  "      const hooked = !!(gallery.hasAttribute && gallery.hasAttribute('data-gem-media-gallery'));",
+  "      if (!hooked && gallery.querySelector && gallery.querySelector('[data-gem-media-gallery]')) return;",
   "      if (!mark(gallery, 'media-gallery')) return;",
+  // Main image + thumbnails (product-media-gallery.thumbnail-stack.v1): a thumbnail click puts its
+  // data-gem-media-src / -alt on [data-gem-media-main], as the section's behavior.js did. Without this the plugin
+  // only moved aria-current and the big image never changed. The markup's data-gem-media-index is kept.
+  "      const main = gallery.querySelector && gallery.querySelector('[data-gem-media-main]');",
+  "      const thumbs = main && gallery.querySelectorAll ? Array.prototype.slice.call(gallery.querySelectorAll('[data-gem-media-item]')) : [];",
+  "      if (main && thumbs.length) {",
+  "        gallery.dataset.gemMediaState = 'ready';",
+  "        const choose = (item, reason) => {",
+  "          const src = item.getAttribute('data-gem-media-src');",
+  "          const alt = item.getAttribute('data-gem-media-alt');",
+  "          if (src) { main.setAttribute('src', src); main.removeAttribute('srcset'); if (alt != null) main.setAttribute('alt', alt); }",
+  "          const index = Number(item.getAttribute('data-gem-media-index') || thumbs.indexOf(item));",
+  "          thumbs.forEach((thumb) => { const on = thumb === item; thumb.setAttribute('aria-current', String(on)); if (thumb.dataset) thumb.dataset.gemMediaActive = on ? 'true' : 'false'; });",
+  "          gallery.dataset.gemMediaActiveIndex = String(index);",
+  "          if (gallery.dispatchEvent && typeof window.CustomEvent === 'function') gallery.dispatchEvent(new window.CustomEvent('gem:media:select', { bubbles: true, detail: { index } }));",
+  "          api.emit('gem:media:change', { source: 'gem-runtime', index, galleryId: gallery.id || undefined, reason });",
+  "        };",
+  "        if (canListen(gallery)) gallery.addEventListener('click', (event) => {",
+  "          const item = event.target && event.target.closest ? event.target.closest('[data-gem-media-item]') : null;",
+  "          if (!item || !gallery.contains(item)) return;",
+  "          if (event.preventDefault) event.preventDefault();",
+  "          choose(item, 'click');",
+  "        });",
+  "        bound += 1;",
+  "        return;",
+  "      }",
   "      const items = gallery.querySelectorAll('[data-gem-media-item], img, video, model-viewer');",
   "      const thumbControls = gallery.querySelectorAll('[data-gem-media-thumb]');",
   "      const controls = thumbControls.length ? thumbControls : items;",
@@ -4667,7 +4846,11 @@ var heroSlideshowPluginRegistrationLines = [
   "        else if (k === 'Home') { if (e.preventDefault) e.preventDefault(); focusDot(0); }",
   "        else if (k === 'End') { if (e.preventDefault) e.preventDefault(); focusDot(dots.length - 1); }",
   "      }); });",
-  "      if (canListen(pause)) pause.addEventListener('click', () => { paused = !paused; if (pause.setAttribute) pause.setAttribute('aria-pressed', String(paused)); start(); });",
+  "      // The visible label follows the state like the section's own behavior did: the button's own text while playing",
+  "      // (kept, so a translated label survives), data-gem-hero-play-label (or 'Play') while paused. Only a text-only button.",
+  "      const pauseText = pause && pause.childElementCount === 0 ? pause.textContent : null;",
+  "      const playText = (pause && pause.getAttribute && pause.getAttribute('data-gem-hero-play-label')) || 'Play';",
+  "      if (canListen(pause)) pause.addEventListener('click', () => { paused = !paused; if (pause.setAttribute) pause.setAttribute('aria-pressed', String(paused)); if (pauseText !== null) pause.textContent = paused ? playText : pauseText; start(); });",
   "      show(active); start(); bound += 1;",
   "    });",
   "    api.emit('gem:hero-slideshow:ready', { source: 'gem-runtime', count: bound });",
@@ -4882,8 +5065,27 @@ var stickyAtcPluginRegistrationLines = [
   "      };",
   "      update();",
   "      if (canListen(target)) target.addEventListener('scroll', update, { passive: true });",
+  // The price follows the variant <select> (each <option> carries its own data-gem-variant-price), as the section's
+  // behavior.js did: otherwise the bar shows the first variant's price whatever the shopper picked.
+  "      const priceEl = bar.querySelector && bar.querySelector('[data-gem-sticky-atc-price]');",
+  "      const select = bar.querySelector && bar.querySelector('select');",
+  "      const syncPrice = () => { if (!priceEl || !select) return; const opt = select.options && select.selectedIndex > -1 ? select.options[select.selectedIndex] : null; const price = opt && opt.getAttribute && opt.getAttribute('data-gem-variant-price'); if (price) priceEl.textContent = price; };",
+  "      if (canListen(select)) select.addEventListener('change', syncPrice);",
+  "      syncPrice();",
+  // A form WITHOUT an action (the headless bar) has nowhere to post: the plugin adds to cart by dispatching
+  // gem:cart:add with the SELECTED variant (the button's data-gem-variant-id is only the first one), which the
+  // storefront's cart bridge consumes. A form WITH an action (a Liquid /cart/add form) is left to the browser.
   "      const form = bar.querySelector && bar.querySelector('form');",
-  "      if (canListen(form)) form.addEventListener('submit', () => api.emit('gem:sticky-atc:submit', { source: 'gem-runtime', id: bar.id || undefined }));",
+  "      if (canListen(form)) form.addEventListener('submit', (event) => {",
+  "        if (!(form.hasAttribute && form.hasAttribute('action'))) {",
+  "          if (event && event.preventDefault) event.preventDefault();",
+  "          const choice = form.querySelector && form.querySelector('select');",
+  "          const trigger = bar.querySelector && bar.querySelector('[data-gem-variant-id]');",
+  "          const variantId = (choice && choice.value) || (trigger && trigger.getAttribute('data-gem-variant-id')) || undefined;",
+  "          if (bar.dispatchEvent && typeof window.CustomEvent === 'function') bar.dispatchEvent(new window.CustomEvent('gem:cart:add', { bubbles: true, detail: { variantId, quantity: 1 } }));",
+  "        }",
+  "        api.emit('gem:sticky-atc:submit', { source: 'gem-runtime', id: bar.id || undefined });",
+  "      });",
   "      bound += 1;",
   "    });",
   "    api.emit('gem:sticky-atc:ready', { source: 'gem-runtime', count: bound });",
@@ -5662,8 +5864,41 @@ function isAllowedUntokenizedValue(property, value) {
 function hasRawVisualValue(value) {
   return /#[0-9a-f]{3,8}\b|rgb\(|hsl\(|\b\d+(?:\.\d+)?(?:px|rem|em)\b/i.test(value);
 }
+var frameworkPublicVariables;
+function gemFrameworkPublicCssVariables() {
+  if (!frameworkPublicVariables) {
+    const css = [
+      createGemThemeCss(defaultGemTokens, ":root", { profile: "dawn-parity" }),
+      createGemThemeCss(defaultGemTokens, ":root", { profile: "morph" }),
+      createThemeProfileCss("dawn-parity"),
+      createMorphProfileCss(),
+      createPrimitiveCss(),
+      String(createSectionCss()),
+      String(createShellCss()),
+      String(createGemSectionRuntimeContractCss()),
+      // The button case rule only exists when a token sets it; a section may still read its variables (a CTA rule
+      // beats the zero-specificity rule, so opting in means `text-transform: var(--gem-font-button-transform, none)`).
+      gemButtonCaseCss({ typography: { buttonTransform: "none", buttonLetterSpacing: "normal" } })
+    ].join("\n").replace(/\/\*[\s\S]*?\*\//g, " ");
+    frameworkPublicVariables = gemPublicCssVariablesFrom(css);
+  }
+  return frameworkPublicVariables;
+}
+var ROOT_SELECTOR = /^\s*(?::root|html|:host)(?:\[[^\]]*\]|:[a-z-]+(?:\([^()]*\))?)*\s*$/;
+function gemPublicCssVariablesFrom(stylesheet) {
+  const css = stylesheet.replace(/\/\*[\s\S]*?\*\//g, " ");
+  const declaredOnRoot = /* @__PURE__ */ new Set();
+  const declaredElsewhere = /* @__PURE__ */ new Set();
+  for (const [, selector, body] of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    const onRoot = selector.split(",").every((part) => ROOT_SELECTOR.test(part));
+    for (const [, name] of body.matchAll(/(--gem-[a-z0-9-]+)\s*:/g)) (onRoot ? declaredOnRoot : declaredElsewhere).add(name);
+  }
+  const mentioned = new Set([...css.matchAll(/--gem-[a-z0-9-]+/g)].map((match) => match[0]));
+  return new Set([...mentioned].filter((name) => declaredOnRoot.has(name) || !declaredElsewhere.has(name)));
+}
 function isKnownGemCssVariable(variableName, options) {
   if (canonicalCssVariableNames.has(variableName)) return true;
+  if (gemFrameworkPublicCssVariables().has(variableName)) return true;
   const allowedPrefixes = [
     "--gem-seasonal-",
     // Global style-variant knobs (--gem-style-space/radius/text/weight/stroke): the
@@ -6814,6 +7049,8 @@ function stringSetting(value) {
 export {
   COUNTDOWN_END_RUNTIME_LINES,
   GEM_AMBIENT_CSS,
+  GEM_BUTTON_TOKEN_KEYS,
+  GEM_BUTTON_TOKEN_SHAPES,
   GEM_COUNTDOWN_ENDED_CSS,
   GEM_FIELD_JOINS,
   GEM_FIELD_SHAPES,
@@ -6824,6 +7061,8 @@ export {
   GEM_FORM_TOKEN_KEYS,
   GEM_FORM_VAR_SCOPE,
   GEM_GRID_COLUMNS_ROW_KNOB_CSS,
+  GEM_HEADING_SIZE_CSS_VARS,
+  GEM_LINE_HEIGHT_TOKEN_KEYS,
   GEM_PART_CLASS,
   GEM_POPUP_SHELL_CSS,
   GEM_REVEAL_CSS,
@@ -6855,6 +7094,7 @@ export {
   createThemeProfileCss,
   defaultGemTokens,
   defaultSelection,
+  gemButtonCaseCss,
   gemFormAttributes,
   gemFormCssBlock,
   gemFormCssVars,
@@ -6863,7 +7103,9 @@ export {
   gemFrameworkRuntimePlugins,
   gemFrameworkValidationRules,
   gemFrameworkVersion,
+  gemMobileTokenCssVars,
   gemPartClass,
+  gemPhoneTokenTarget,
   gemPlanShapeKnobs,
   gemRuntimePluginModuleKeys,
   gemRuntimePluginSources,
@@ -6874,6 +7116,7 @@ export {
   motionCssVarAliases,
   normalizeGemTokens,
   offerEngineRuntimeScript,
+  optionalGemTokenKeys,
   planToRuntimeBootstrapConfig,
   renderGemFrameworkManifest,
   renderGemPreviewDocument,

package/dist/plugins/hero-slideshow.js

@@ -42,7 +42,11 @@ function install({ document, window, target, mark, canListen, listen: __gemListe
         else if (k === 'Home') { if (e.preventDefault) e.preventDefault(); focusDot(0); }
         else if (k === 'End') { if (e.preventDefault) e.preventDefault(); focusDot(dots.length - 1); }
       }); });
-      if (canListen(pause)) __gemListen(pause, 'click', () => { paused = !paused; if (pause.setAttribute) pause.setAttribute('aria-pressed', String(paused)); start(); });
+      // The visible label follows the state like the section's own behavior did: the button's own text while playing
+      // (kept, so a translated label survives), data-gem-hero-play-label (or 'Play') while paused. Only a text-only button.
+      const pauseText = pause && pause.childElementCount === 0 ? pause.textContent : null;
+      const playText = (pause && pause.getAttribute && pause.getAttribute('data-gem-hero-play-label')) || 'Play';
+      if (canListen(pause)) __gemListen(pause, 'click', () => { paused = !paused; if (pause.setAttribute) pause.setAttribute('aria-pressed', String(paused)); if (pauseText !== null) pause.textContent = paused ? playText : pauseText; start(); });
       show(active); start(); bound += 1;
     });
     api.emit('gem:hero-slideshow:ready', { source: 'gem-runtime', count: bound });

package/dist/plugins/media-gallery.js

@@ -10,7 +10,32 @@ function install({ document, window, target, mark, canListen, listen: __gemListe
     const galleries = document.querySelectorAll('[data-gem-media-gallery], .gem-media-gallery, .gem-product-media-gallery');
     let bound = 0;
     galleries.forEach((gallery) => {
+      const hooked = !!(gallery.hasAttribute && gallery.hasAttribute('data-gem-media-gallery'));
+      if (!hooked && gallery.querySelector && gallery.querySelector('[data-gem-media-gallery]')) return;
       if (!mark(gallery, 'media-gallery')) return;
+      const main = gallery.querySelector && gallery.querySelector('[data-gem-media-main]');
+      const thumbs = main && gallery.querySelectorAll ? Array.prototype.slice.call(gallery.querySelectorAll('[data-gem-media-item]')) : [];
+      if (main && thumbs.length) {
+        gallery.dataset.gemMediaState = 'ready';
+        const choose = (item, reason) => {
+          const src = item.getAttribute('data-gem-media-src');
+          const alt = item.getAttribute('data-gem-media-alt');
+          if (src) { main.setAttribute('src', src); main.removeAttribute('srcset'); if (alt != null) main.setAttribute('alt', alt); }
+          const index = Number(item.getAttribute('data-gem-media-index') || thumbs.indexOf(item));
+          thumbs.forEach((thumb) => { const on = thumb === item; thumb.setAttribute('aria-current', String(on)); if (thumb.dataset) thumb.dataset.gemMediaActive = on ? 'true' : 'false'; });
+          gallery.dataset.gemMediaActiveIndex = String(index);
+          if (gallery.dispatchEvent && typeof window.CustomEvent === 'function') gallery.dispatchEvent(new window.CustomEvent('gem:media:select', { bubbles: true, detail: { index } }));
+          api.emit('gem:media:change', { source: 'gem-runtime', index, galleryId: gallery.id || undefined, reason });
+        };
+        if (canListen(gallery)) __gemListen(gallery, 'click', (event) => {
+          const item = event.target && event.target.closest ? event.target.closest('[data-gem-media-item]') : null;
+          if (!item || !gallery.contains(item)) return;
+          if (event.preventDefault) event.preventDefault();
+          choose(item, 'click');
+        });
+        bound += 1;
+        return;
+      }
       const items = gallery.querySelectorAll('[data-gem-media-item], img, video, model-viewer');
       const thumbControls = gallery.querySelectorAll('[data-gem-media-thumb]');
       const controls = thumbControls.length ? thumbControls : items;