@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-replatform/scripts/lib/interaction-runtime.mjs

@@ -0,0 +1,194 @@
+// @generated-source wix-headless-replatform
+// Framework-neutral state mechanics for cloned interaction primitives.
+
+export function bindActiveItemRail(root, { activateOnHover = false, alignActive = false } = {}) {
+  requireRoot(root, "active-card-rail");
+  const items = Array.from(root.querySelectorAll("[data-rp-item]"));
+  const controls = Array.from(root.querySelectorAll("[data-rp-direction]"));
+  const track = root.querySelector("[data-rp-track]");
+  const viewport = root.querySelector("[data-rp-viewport]") || track?.parentElement || null;
+  const listeners = [];
+  const activate = (item) => {
+    if (!item || !items.includes(item)) return;
+    for (const candidate of items) {
+      const active = candidate === item;
+      candidate.setAttribute("data-rp-active", String(active));
+      candidate.setAttribute("aria-selected", String(active));
+    }
+    if (alignActive) alignItemInViewport(item, viewport);
+    root.dispatchEvent(new CustomEvent("rp:statechange", { detail: { index: items.indexOf(item) } }));
+  };
+  for (const item of items) {
+    const target = item.querySelector("[data-rp-activate]") || item;
+    listen(listeners, item, "click", (event) => {
+      const interactive = event.target?.closest?.("a,button,input,select,textarea,[role='button']");
+      if (interactive && interactive !== item && interactive !== target && !target.contains(interactive)) return;
+      activate(item);
+    });
+    listen(listeners, target, "keydown", (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        activate(item);
+      }
+    });
+    if (activateOnHover) listen(listeners, item, "pointerenter", () => activate(item));
+  }
+  for (const control of controls) {
+    listen(listeners, control, "click", () => {
+      const direction = Number(control.getAttribute("data-rp-direction")) || 0;
+      const activeIndex = Math.max(0, items.findIndex((item) => item.getAttribute("data-rp-active") === "true"));
+      activate(items[wrapIndex(activeIndex + direction, items.length)]);
+    });
+  }
+  const initialState = root.getAttribute("data-rp-initial-state") || "single-active";
+  if (initialState !== "all-collapsed" && !items.some((item) => item.getAttribute("data-rp-active") === "true") && items[0]) activate(items[0]);
+  markInitialized(root, "active-card-rail");
+  return { activate, destroy: () => removeListeners(listeners) };
+}
+
+export function bindContentSwitcher(root) {
+  requireRoot(root, "content-switcher");
+  const items = Array.from(root.querySelectorAll("[data-rp-item][data-rp-state]"));
+  const panels = Array.from(root.querySelectorAll("[data-rp-panel][data-rp-state]"));
+  const listeners = [];
+  const activate = (state) => {
+    for (const item of items) {
+      const active = item.getAttribute("data-rp-state") === state;
+      item.setAttribute("data-rp-active", String(active));
+      item.setAttribute("aria-selected", String(active));
+    }
+    for (const panel of panels) {
+      const active = panel.getAttribute("data-rp-state") === state;
+      panel.hidden = !active;
+      panel.setAttribute("aria-hidden", String(!active));
+    }
+    root.dispatchEvent(new CustomEvent("rp:statechange", { detail: { state } }));
+  };
+  for (const item of items) {
+    const target = item.querySelector("[data-rp-activate]") || item;
+    listen(listeners, item, "click", () => activate(item.getAttribute("data-rp-state")));
+  }
+  const initial = items.find((item) => item.getAttribute("data-rp-active") === "true")?.getAttribute("data-rp-state") || items[0]?.getAttribute("data-rp-state");
+  if (initial) activate(initial);
+  markInitialized(root, "content-switcher");
+  return { activate, destroy: () => removeListeners(listeners) };
+}
+
+export function bindScrollScene(root, { phases = defaultScrollPhases() } = {}) {
+  requireRoot(root, "scroll-scene");
+  const ordered = normalizePhases(phases);
+  let frame = 0;
+  const update = () => {
+    frame = 0;
+    const rect = root.getBoundingClientRect();
+    const travel = Math.max(1, rect.height - window.innerHeight);
+    const progress = clamp((-rect.top) / travel, 0, 1);
+    const entryProgress = clamp((window.innerHeight - rect.top) / Math.max(1, window.innerHeight), 0, 1);
+    const phase = phaseForProgress(progress, ordered);
+    root.setAttribute("data-rp-phase", phase.name);
+    root.style.setProperty("--rp-scroll-progress", String(progress));
+    root.style.setProperty("--rp-entry-progress", String(entryProgress));
+    root.dispatchEvent(new CustomEvent("rp:scrollphase", { detail: { phase: phase.name, progress, entryProgress } }));
+  };
+  const onScroll = () => {
+    if (!frame) frame = requestAnimationFrame(update);
+  };
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("resize", onScroll);
+  update();
+  markInitialized(root, "scroll-scene");
+  return {
+    update,
+    destroy: () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      if (frame) cancelAnimationFrame(frame);
+    },
+  };
+}
+
+export function autoBindInteractions(scope = document) {
+  const roots = Array.from(scope.querySelectorAll("[data-rp-scene]"));
+  const bindings = [];
+  for (const root of roots) {
+    if (root.querySelector("[data-rp-track]") && !isInitialized(root, "active-card-rail")) {
+      bindings.push(bindActiveItemRail(root, {
+        activateOnHover: root.getAttribute("data-rp-activate-on-hover") === "true",
+        alignActive: root.getAttribute("data-rp-align-active") !== "false",
+      }));
+    }
+    if (root.querySelector("[data-rp-item][data-rp-state]") && root.querySelector("[data-rp-panel][data-rp-state]") && !isInitialized(root, "content-switcher")) {
+      bindings.push(bindContentSwitcher(root));
+    }
+    if (root.querySelector("[data-rp-visual]") && !isInitialized(root, "scroll-scene")) {
+      bindings.push(bindScrollScene(root));
+    }
+  }
+  return { bindings, destroy: () => bindings.forEach((binding) => binding?.destroy?.()) };
+}
+
+export function phaseForProgress(progress, phases = defaultScrollPhases()) {
+  const ordered = normalizePhases(phases);
+  const value = clamp(Number(progress) || 0, 0, 1);
+  return [...ordered].reverse().find((phase) => value >= phase.at) || ordered[0];
+}
+
+function defaultScrollPhases() {
+  return [
+    { name: "approach", at: 0 },
+    { name: "active", at: 0.25 },
+    { name: "reveal", at: 0.65 },
+    { name: "release", at: 0.92 },
+  ];
+}
+
+function normalizePhases(phases) {
+  const normalized = (phases || []).map((phase, index) => ({
+    name: String(phase.name || phase.id || `phase-${index + 1}`),
+    at: clamp(Number(phase.at ?? phase.progress ?? 0), 0, 1),
+  })).sort((left, right) => left.at - right.at);
+  return normalized.length ? normalized : defaultScrollPhases();
+}
+
+function requireRoot(root, primitive) {
+  if (!root || typeof root.querySelectorAll !== "function") throw new Error(`Missing root element for ${primitive}.`);
+}
+
+function listen(listeners, target, type, handler) {
+  target.addEventListener(type, handler);
+  listeners.push([target, type, handler]);
+}
+
+function removeListeners(listeners) {
+  for (const [target, type, handler] of listeners) target.removeEventListener(type, handler);
+}
+
+function alignItemInViewport(item, viewport) {
+  if (!viewport || typeof viewport.scrollTo !== "function") return;
+  const viewportRect = viewport.getBoundingClientRect();
+  const itemRect = item.getBoundingClientRect();
+  const left = viewport.scrollLeft + itemRect.left - viewportRect.left - ((viewportRect.width - itemRect.width) / 2);
+  viewport.scrollTo({ left: Math.max(0, left), behavior: "smooth" });
+}
+
+function initializedTokens(root) {
+  return new Set(String(root.getAttribute("data-rp-initialized") || "").split(/\s+/).filter(Boolean));
+}
+
+function isInitialized(root, primitive) {
+  return initializedTokens(root).has(primitive);
+}
+
+function markInitialized(root, primitive) {
+  const tokens = initializedTokens(root);
+  tokens.add(primitive);
+  root.setAttribute("data-rp-initialized", Array.from(tokens).join(" "));
+}
+
+function wrapIndex(index, length) {
+  return length ? (index % length + length) % length : 0;
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, value));
+}

package/skills/wix-headless-replatform/scripts/lib/interaction-timeline.mjs

@@ -0,0 +1,348 @@
+const DEFAULT_STYLE_KEYS = [
+  "className",
+  "ariaSelected",
+  "ariaExpanded",
+  "hidden",
+  "display",
+  "visibility",
+  "opacity",
+  "transform",
+  "width",
+  "height",
+  "flexBasis",
+  "gridTemplateColumns",
+  "overflow",
+  "clipPath",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "marginLeft",
+  "marginRight",
+  "paddingLeft",
+  "paddingRight",
+  "borderLeftWidth",
+  "borderRightWidth",
+  "borderLeftColor",
+  "borderRightColor",
+];
+
+export const DEFAULT_INTERACTION_TIMELINE_MS = [0, 80, 180, 400, 900, 1400];
+
+export function compactInteractionTimeline(frames, { maxChangedNodes = 36 } = {}) {
+  const normalized = (frames || []).filter(Boolean).map((frame, index) => ({
+    ...frame,
+    atMs: Number.isFinite(frame.atMs) ? frame.atMs : index === 0 ? -1 : 0,
+    nodes: Array.isArray(frame.nodes) ? frame.nodes : [],
+  }));
+  if (normalized.length < 2) {
+    return {
+      sampledAtMs: normalized.map((frame) => frame.atMs),
+      observedSettleMs: 0,
+      changedNodeCount: 0,
+      changes: [],
+    };
+  }
+
+  const paths = new Set(normalized.flatMap((frame) => frame.nodes.map((node) => node.path).filter(Boolean)));
+  const changes = [];
+  for (const path of paths) {
+    const states = normalized.map((frame) => {
+      const node = frame.nodes.find((candidate) => candidate.path === path);
+      return node ? { atMs: frame.atMs, ...pickState(node) } : { atMs: frame.atMs, missing: true };
+    });
+    const changedProperties = changedKeys(states);
+    if (!changedProperties.length) continue;
+    changes.push({
+      path,
+      role: states.find((state) => state.role)?.role || "descendant",
+      changedProperties,
+      states: compactStates(states, changedProperties),
+    });
+  }
+
+  changes.sort((left, right) => changePriority(right) - changePriority(left));
+  const retained = changes.slice(0, maxChangedNodes);
+  return {
+    sampledAtMs: normalized.map((frame) => frame.atMs),
+    observedSettleMs: observedSettleMs(retained),
+    changedNodeCount: changes.length,
+    truncated: changes.length > retained.length,
+    changes: retained,
+    animations: compactAnimations(normalized),
+  };
+}
+
+export function deriveCarouselInvariants({ frames, timeline } = {}) {
+  const normalized = (frames || []).filter(Boolean);
+  const before = normalized[0] || {};
+  const after = normalized[normalized.length - 1] || {};
+  const beforeItems = itemNodes(before);
+  const afterItems = itemNodes(after);
+  const beforeWidths = beforeItems.map(widthOf).filter((value) => value > 0);
+  const afterWidths = afterItems.map(widthOf).filter((value) => value > 0);
+  const collapsedWidth = median(beforeWidths);
+  const expandedWidth = afterWidths.length ? Math.max(...afterWidths) : 0;
+  const initialActiveIndexes = beforeItems.map((item, index) => isActive(item) ? index : -1).filter((index) => index >= 0);
+  const activeIndexes = afterItems.map((item, index) => isActive(item) ? index : -1).filter((index) => index >= 0);
+  const activeCount = afterItems.filter(isActive).length;
+  const beforeTrack = before.nodes?.find((node) => node.role === "track");
+  const afterTrack = after.nodes?.find((node) => node.role === "track") || beforeTrack;
+  const clientWidth = numberOr(afterTrack?.clientWidth, 0);
+  const scrollWidth = numberOr(afterTrack?.scrollWidth, 0);
+  const geometricGaps = consecutiveGaps(beforeItems);
+  const measuredGap = median(geometricGaps);
+  const trackGap = px(beforeTrack?.columnGap || beforeTrack?.gap);
+  const borderWidths = beforeItems.flatMap((item) => [px(item.borderLeftWidth), px(item.borderRightWidth)]).filter((value) => value > 0);
+  const marginWidths = beforeItems.flatMap((item) => [px(item.marginLeft), px(item.marginRight)]).filter((value) => value > 0);
+  const separationMechanism = trackGap > 0 ? "track-gap"
+    : measuredGap > 0.5 ? "geometric-gap"
+      : marginWidths.length ? "item-margin"
+        : borderWidths.length ? "divider"
+          : "flush";
+  return {
+    itemCount: Math.max(beforeItems.length, afterItems.length),
+    activeCount,
+    activeIndexes,
+    singleActive: activeCount === 1,
+    initialState: initialActiveIndexes.length === 0 ? "all-collapsed" : initialActiveIndexes.length === 1 ? "single-active" : "multiple-active",
+    initialActiveCount: initialActiveIndexes.length,
+    initialActiveIndexes,
+    collapsedItemWidth: round(collapsedWidth),
+    expandedItemWidth: round(expandedWidth),
+    expandedWidthRatio: collapsedWidth > 0 ? round(expandedWidth / collapsedWidth, 3) : 0,
+    horizontalOverflowRatio: clientWidth > 0 ? round(scrollWidth / clientWidth, 3) : 0,
+    separation: {
+      mechanism: separationMechanism,
+      trackGap: round(trackGap, 2),
+      geometricGap: round(measuredGap, 2),
+      minimumGeometricGap: geometricGaps.length ? round(Math.min(...geometricGaps), 2) : 0,
+      maximumGeometricGap: geometricGaps.length ? round(Math.max(...geometricGaps), 2) : 0,
+      dividerWidth: round(median(borderWidths), 2),
+      itemMargin: round(median(marginWidths), 2),
+      contentInset: round(median(beforeItems.flatMap((item) => [px(item.paddingLeft), px(item.paddingRight)]).filter((value) => value > 0)), 2),
+    },
+    observedSettleMs: timeline?.observedSettleMs || 0,
+  };
+}
+
+export function deriveScrollInvariants(phases = []) {
+  const samples = (phases || []).filter(Boolean);
+  const chainCount = Math.max(0, ...samples.map((phase) => phase.visualChain?.length || 0));
+  let strongest = null;
+  for (let index = 0; index < chainCount; index += 1) {
+    const nodes = samples.map((phase) => phase.visualChain?.[index]).filter(Boolean);
+    const widths = nodes.map((node) => numberOr(node.width, 0)).filter((value) => value > 0);
+    const scales = nodes.map((node) => transformScale(node.transform)).filter((value) => value > 0);
+    const widthRatio = rangeRatio(widths);
+    const scaleRatio = rangeRatio(scales);
+    const score = Math.max(widthRatio, scaleRatio);
+    if (!strongest || score > strongest.score) {
+      const representative = nodes.find((node) => node.className) || nodes[0] || {};
+      strongest = {
+        score,
+        chainIndex: index,
+        tag: representative.tag || "",
+        classTokens: String(representative.className || "").split(/\s+/).filter(Boolean).slice(0, 6),
+        minimumWidth: widths.length ? Math.min(...widths) : 0,
+        maximumWidth: widths.length ? Math.max(...widths) : 0,
+        widthRatio: round(widthRatio, 3),
+        transformScaleRatio: round(scaleRatio, 3),
+      };
+    }
+  }
+  const curtainTotals = samples.map((phase) => (phase.sceneLayers || [])
+    .filter((layer) => layer.role === "curtain")
+    .reduce((total, layer) => total + Math.max(0, numberOr(layer.width, 0)), 0));
+  const rootWidths = samples.map((phase) => numberOr(phase.rootWidth, 0)).filter((value) => value > 0);
+  const viewportWidth = median(rootWidths);
+  const curtainRevealFraction = curtainTotals.length && viewportWidth > 0
+    ? (Math.max(...curtainTotals) - Math.min(...curtainTotals)) / viewportWidth
+    : 0;
+  const curtainRevealRatio = 1 + Math.max(0, curtainRevealFraction);
+  const contentWidths = samples.map((phase) => numberOr(phase.copy?.width, 0)).filter((value) => value > 0);
+  const contentHeights = samples.map((phase) => numberOr(phase.copy?.height, 0)).filter((value) => value > 0);
+  const contentScales = samples.map((phase) => transformScale(phase.copy?.transform)).filter((value) => value > 0);
+  const contentWidthRatio = rangeRatio(contentWidths);
+  const contentHeightRatio = rangeRatio(contentHeights);
+  const contentScaleRatio = rangeRatio(contentScales);
+  if (strongest && curtainRevealRatio > strongest.score) {
+    strongest = {
+      ...strongest,
+      score: round(curtainRevealRatio, 3),
+      mechanism: "curtain-reveal",
+    };
+  } else if (strongest) {
+    strongest.mechanism = strongest.widthRatio >= strongest.transformScaleRatio ? "geometry" : "transform";
+  }
+  return {
+    entryPhaseCount: samples.filter((phase) => Number(phase.progress) < 0).length,
+    pinnedPhaseCount: samples.filter((phase) => (phase.visualChain || []).some((node) => node.position === "fixed" || node.position === "sticky")).length,
+    visualExpansion: strongest || {
+      score: 1,
+      chainIndex: 0,
+      tag: "",
+      classTokens: [],
+      minimumWidth: 0,
+      maximumWidth: 0,
+      widthRatio: 1,
+      transformScaleRatio: 1,
+      mechanism: "none",
+    },
+    curtainReveal: {
+      observed: curtainRevealFraction > 0.05,
+      maximumCombinedWidth: curtainTotals.length ? Math.max(...curtainTotals) : 0,
+      minimumCombinedWidth: curtainTotals.length ? Math.min(...curtainTotals) : 0,
+      viewportFraction: round(Math.max(0, curtainRevealFraction), 3),
+    },
+    motionOwnership: {
+      visual: {
+        expands: Number(strongest?.score || 1) > 1.05,
+        mechanism: strongest?.mechanism || "none",
+      },
+      content: {
+        widthRatio: round(contentWidthRatio, 3),
+        heightRatio: round(contentHeightRatio, 3),
+        transformScaleRatio: round(contentScaleRatio, 3),
+        scales: Math.max(contentWidthRatio, contentHeightRatio, contentScaleRatio) > 1.05,
+        maximumAllowedScaleRatio: Math.max(contentWidthRatio, contentHeightRatio, contentScaleRatio) > 1.05 ? null : 1.03,
+      },
+    },
+  };
+}
+
+function consecutiveGaps(items) {
+  return items.slice(1).map((item, index) => {
+    const previous = items[index];
+    return numberOr(item?.rect?.left, 0) - (numberOr(previous?.rect?.left, 0) + numberOr(previous?.rect?.width, 0));
+  }).filter((value) => Number.isFinite(value) && value >= -0.5);
+}
+
+function px(value) {
+  const numeric = Number.parseFloat(String(value || "0"));
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+function pickState(node) {
+  const state = {
+    role: node.role || "descendant",
+    text: String(node.text || "").slice(0, 160),
+    rect: node.rect || null,
+  };
+  for (const key of DEFAULT_STYLE_KEYS) {
+    if (node[key] !== undefined) state[key] = node[key];
+  }
+  if (node.clientWidth !== undefined) state.clientWidth = node.clientWidth;
+  if (node.scrollWidth !== undefined) state.scrollWidth = node.scrollWidth;
+  return state;
+}
+
+function changedKeys(states) {
+  const keys = new Set(states.flatMap((state) => Object.keys(state)).filter((key) => !["atMs", "role"].includes(key)));
+  return Array.from(keys).filter((key) => {
+    const values = states.map((state) => stable(state[key]));
+    return values.some((value) => value !== values[0]);
+  });
+}
+
+function compactStates(states, changedProperties) {
+  let previous = null;
+  const compacted = [];
+  for (const state of states) {
+    const next = { atMs: state.atMs };
+    for (const key of changedProperties) next[key] = state[key];
+    const signature = stable(next, ["atMs"]);
+    if (signature === previous) continue;
+    compacted.push(next);
+    previous = signature;
+  }
+  return compacted;
+}
+
+function observedSettleMs(changes) {
+  let settled = 0;
+  for (const change of changes) {
+    const states = change.states || [];
+    if (states.length < 2) continue;
+    settled = Math.max(settled, numberOr(states[states.length - 1].atMs, 0));
+  }
+  return settled;
+}
+
+function compactAnimations(frames) {
+  const seen = new Map();
+  for (const frame of frames) {
+    for (const animation of frame.animations || []) {
+      const key = `${animation.path || "unknown"}\u0000${animation.name || ""}\u0000${animation.duration || 0}\u0000${animation.easing || ""}`;
+      const existing = seen.get(key) || { ...animation, firstSeenAtMs: frame.atMs, lastSeenAtMs: frame.atMs };
+      existing.lastSeenAtMs = frame.atMs;
+      seen.set(key, existing);
+    }
+  }
+  return Array.from(seen.values()).slice(0, 24);
+}
+
+function itemNodes(frame) {
+  return (frame?.nodes || []).filter((node) => node.role === "item");
+}
+
+function widthOf(node) {
+  return numberOr(node?.rect?.width, numberOr(node?.width?.replace?.("px", ""), 0));
+}
+
+function isActive(node) {
+  return node?.ariaSelected === "true" || node?.ariaExpanded === "true" || node?.active === true || hasActiveToken(node?.className);
+}
+
+function hasActiveToken(value) {
+  return String(value || "").split(/\s+/).some((token) => /(?:^|[-_:])(active|selected|expanded)$|^(active|selected|expanded)$/i.test(token));
+}
+
+function median(values) {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+function changePriority(change) {
+  const properties = new Set(change.changedProperties || []);
+  let score = change.role === "item" ? 30 : change.role === "track" ? 25 : 0;
+  if (properties.has("className") || properties.has("ariaSelected") || properties.has("ariaExpanded")) score += 20;
+  if (properties.has("rect") || properties.has("transform") || properties.has("opacity")) score += 15;
+  if (properties.has("text") || properties.has("display") || properties.has("visibility")) score += 10;
+  return score;
+}
+
+function stable(value, ignoredKeys = []) {
+  if (value === undefined) return "__undefined__";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stable(item, ignoredKeys)).join(",")}]`;
+  return `{${Object.keys(value).filter((key) => !ignoredKeys.includes(key)).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key], ignoredKeys)}`).join(",")}}`;
+}
+
+function numberOr(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function round(value, precision = 1) {
+  const factor = 10 ** precision;
+  return Math.round(value * factor) / factor;
+}
+
+function rangeRatio(values) {
+  if (!values.length) return 1;
+  const minimum = Math.min(...values);
+  return minimum > 0 ? Math.max(...values) / minimum : 1;
+}
+
+function transformScale(value) {
+  const text = String(value || "");
+  const matrix = text.match(/^matrix\(([^)]+)\)$/);
+  if (matrix) {
+    const [a, b] = matrix[1].split(",").map(Number);
+    return Math.sqrt((a || 0) ** 2 + (b || 0) ** 2) || 1;
+  }
+  const scale = text.match(/scale(?:X)?\(([-+\d.]+)\)/);
+  return scale ? Number(scale[1]) || 1 : 1;
+}

package/skills/wix-headless-replatform/scripts/lib/layout-blueprint/classifiers.mjs

@@ -0,0 +1,141 @@
+import { horizontalRelation, overlapRatio, placementFor } from "./geometry.mjs";
+
+export function classifyCanvas(section, scene) {
+  const viewport = section.layoutEvidence?.viewport || { width: 1440, height: 900 };
+  const rect = section.rect || {};
+  const fullWidth = section.layoutHints?.fullWidth ?? Number(rect.width) >= Number(viewport.width) * 0.88;
+  let heightMode = "content";
+  if (scene?.implementation?.primitive === "scroll-scene") heightMode = "scroll-driven";
+  else if (Number(rect.height) >= Number(viewport.height) * 0.82 && Number(rect.height) <= Number(viewport.height) * 1.35) heightMode = "viewport";
+  else if (section.layoutEvidence?.canvas?.minHeight?.includes?.("vh")) heightMode = "viewport";
+  return {
+    widthMode: fullWidth ? "full-bleed" : "bounded",
+    heightMode,
+    sourceRect: rect,
+    viewport,
+    positioningContext: section.layoutEvidence?.canvas?.position || "static",
+    overflow: {
+      x: section.layoutEvidence?.canvas?.overflowX || "visible",
+      y: section.layoutEvidence?.canvas?.overflowY || "visible",
+    },
+    pinned: scene?.implementation?.primitive === "scroll-scene",
+  };
+}
+
+export function classifyBackground(section, scene) {
+  const color = section.background?.color || section.layoutEvidence?.canvas?.background?.color || "";
+  const cssImage = section.background?.image || section.layoutEvidence?.canvas?.background?.image || "";
+  const media = (scene?.media || []).find((item) => item.role === "background") || null;
+  const measuredMedia = (section.layoutEvidence?.layers || []).find((layer) =>
+    ["video", "image"].includes(layer.kind)
+    && layer.position === "absolute"
+    && Number(layer.normalizedRect?.width) >= 0.75
+    && Number(layer.normalizedRect?.height) >= 0.25
+  ) || null;
+  const isGradient = /gradient\(/i.test(cssImage);
+  const hasColor = Boolean(color && !/transparent|rgba\(0,\s*0,\s*0,\s*0\)/i.test(color));
+  const hasImage = Boolean((cssImage && cssImage !== "none") || (!media && measuredMedia?.kind === "image"));
+  const hasVideo = Boolean((media && ["video", "iframe"].includes(media.tag)) || (!media && measuredMedia?.kind === "video"));
+  const signalCount = [hasColor, hasImage || Boolean(media?.fallback?.src), hasVideo].filter(Boolean).length;
+  const kind = signalCount > 1 ? "composite" : hasVideo ? "video" : isGradient ? "gradient" : hasImage ? "image" : hasColor ? "color" : "none";
+  const layers = [];
+  if (hasColor) layers.push({ role: "base", kind: "color", color });
+  if (hasVideo) layers.push({
+    role: "media",
+    kind: "video",
+    src: media?.src || measuredMedia?.src || "",
+    provider: media?.provider || media?.tag || "native",
+    fit: measuredMedia?.objectFit || "cover",
+    position: "center",
+    playback: media?.playback || {},
+  });
+  if (!hasVideo && hasImage) layers.push({ role: "media", kind: isGradient ? "gradient" : "image", src: cssImage || measuredMedia?.src || "", fit: measuredMedia?.objectFit || "cover", position: "center" });
+  if (media?.fallback?.src) layers.push({
+    role: "media",
+    kind: "image",
+    src: media.fallback.src,
+    fit: "cover",
+    position: "center",
+    policy: media.fallback.policy || "fallback-only",
+  });
+  const scrollStates = (scene?.states || []).find((state) => state.kind === "scroll-state")?.states || [];
+  const observedSceneLayers = scrollStates.flatMap((state) => state.sceneLayers || []);
+  for (const layer of section.layoutEvidence?.layers || []) {
+    const layerClass = (layer.classTokens || []).join(" ");
+    const canvasLayer = layer.kind === "pseudo-layer"
+      || (Number(layer.normalizedRect?.width) >= 0.75 && Number(layer.normalizedRect?.height) >= 0.25);
+    if (canvasLayer && (layer.kind === "pseudo-layer" || /overlay|curtain|mask/i.test(layerClass))) {
+      if (/curtain/i.test(layerClass) && observedSceneLayers.some((candidate) => candidate.role === "curtain")) continue;
+      const scrim = layer.kind === "pseudo-layer" || /overlay|mask/i.test(layerClass);
+      layers.push({ role: scrim ? "scrim" : "decoration", kind: layer.kind, ...layer });
+    }
+  }
+  const dynamicLayerKeys = new Set();
+  for (const layer of observedSceneLayers) {
+    if (!['curtain', 'background'].includes(layer.role)) continue;
+    const key = `${layer.role}:${layer.className || layer.tag}`;
+    if (dynamicLayerKeys.has(key)) continue;
+    dynamicLayerKeys.add(key);
+    const peers = observedSceneLayers.filter((candidate) => `${candidate.role}:${candidate.className || candidate.tag}` === key);
+    layers.push({
+      role: layer.role === "curtain" ? "decoration" : "scrim",
+      kind: layer.role === "curtain" ? "curtain" : "scene-layer",
+      position: layer.position,
+      color: layer.backgroundColor,
+      motion: "scroll-driven",
+      observedWidthPx: {
+        minimum: Math.min(...peers.map((candidate) => Number(candidate.width) || 0)),
+        maximum: Math.max(...peers.map((candidate) => Number(candidate.width) || 0)),
+      },
+      className: layer.className || "",
+    });
+  }
+  const resolvedKind = new Set(layers.map((layer) => `${layer.role}:${layer.kind}`)).size > 1 ? "composite" : kind;
+  return { kind: resolvedKind, color: hasColor ? color : null, layers };
+}
+
+export function buildRegions(section) {
+  return (section.layoutEvidence?.regions || []).map((region, index) => ({
+    id: `${section.id}-region-${String(index + 1).padStart(2, "0")}`,
+    role: region.role || "content",
+    text: region.text || "",
+    placement: placementFor(region.normalizedRect),
+    normalizedRect: region.normalizedRect,
+    sourceRect: region.rect,
+    positioning: region.position || "static",
+    alignment: region.textAlign || "start",
+    zIndex: region.zIndex || "auto",
+    textGeometry: region.textGeometry || null,
+    domRef: region.domRef || null,
+  }));
+}
+
+export function classifyComposition({ section, scene, background, regions }) {
+  const primitive = scene?.implementation?.primitive;
+  if (primitive === "active-card-rail" || section.capabilities?.isCarouselLike) return "rail";
+  if (primitive === "scroll-scene") return "scroll-narrative";
+  if (section.kind === "card-collection") return "grid";
+  const mediaIsBackground = background.layers.some((layer) => layer.role === "media" && ["video", "image", "gradient"].includes(layer.kind));
+  const contentRegions = regions.filter((region) => !["media", "navigation"].includes(region.role));
+  const mediaRegions = regions.filter((region) => region.role === "media");
+  if (mediaIsBackground && (contentRegions.length || section.heading || section.text)) return "layered-overlay";
+  if (mediaRegions.length && contentRegions.length) {
+    const pairs = mediaRegions.flatMap((media) => contentRegions.map((content) => horizontalRelation(media.normalizedRect, content.normalizedRect)));
+    if (pairs.some((relation) => relation === "before" || relation === "after")) return "split";
+    if (mediaRegions.some((media) => contentRegions.some((content) => overlapRatio(media.normalizedRect, content.normalizedRect) >= 0.2))) return "layered-overlay";
+  }
+  return regions.length ? "stack" : "freeform";
+}
+
+export function relationshipsFor(composition, regions) {
+  const relationships = [];
+  const headings = regions.filter((region) => region.role === "heading");
+  const body = regions.filter((region) => region.role === "body-copy");
+  const actions = regions.filter((region) => region.role === "action");
+  const tabs = regions.filter((region) => region.role === "tabs");
+  if (headings.length && body.length) relationships.push("heading-before-body");
+  if (actions.length && body.length) relationships.push(horizontalRelation(body[0].normalizedRect, actions[0].normalizedRect) === "before" ? "action-right-of-copy" : "action-near-copy");
+  if (tabs.some((region) => region.placement.startsWith("bottom"))) relationships.push("tabs-bottom-anchored");
+  if (["layered-overlay", "scroll-narrative"].includes(composition)) relationships.push("content-over-background-media");
+  return [...new Set(relationships)];
+}