1#!/usr/bin/env node
2import path from "node:path";
3import { docsDir, parseArgs, readJson, resolveOutputDir, writeJson } from "./lib/common.mjs";
4
5async function main() {
6  const args = parseArgs();
7  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
8  const

generate-scene-contract.mjs on GitHub

contract

=

await

generateSceneContract

({ outputDir });

if (args.json) process.stdout.write(`${JSON.stringify(contract, null, 2)}\n`);

}

export async function generateSceneContract({ outputDir, pages: suppliedPages, interactionMap: suppliedInteractionMap } = {}) {

const docs = docsDir(outputDir);

const interactionMap = suppliedInteractionMap || await readJson(path.join(docs, "interaction-map.json"));

let sourceMap = null;

if (!suppliedPages) {

try {

sourceMap = await readJson(path.join(docs, "source-map.json"));

} catch {

// Standalone interaction extraction embeds enriched pages in interaction-map.json.

}

const pages = suppliedPages || sourceMap?.pages || interactionMap.pages || [];

const interactions = interactionMap.interactions || [];

const media = interactionMap.structural?.media || [];

const scenes = pages.flatMap((page) => (page.sections || []).map((section) => buildScene({ page, section, interactions, media }))).filter(Boolean);

const contract = {

schemaVersion: 3,

generatedAt: new Date().toISOString(),

sourceUrl: interactionMap.sourceUrl || pages[0]?.url || "",

scenes,

};

await writeJson(path.join(docs, "scene-contract.json"), contract);

return contract;

}

export function buildScene({ page, section, interactions, media }) {

const sectionInteractions = page.interactionDiscovery?.sectionInteractions?.find((entry) => entry.sectionId === section.id)?.interactions || [];

const kinds = new Set(sectionInteractions.map((item) => item.kind));

const classText = `${section.kind || ""} ${section.className || ""} ${(section.domRef?.classTokens || []).join(" ")} ${section.heading || ""}`.toLowerCase();

const isHero = section.kind === "hero" || /hero/.test(classText) || section === page.sections?.[0];

if (isHero && media.some((item) => item.role === "background")) kinds.add("embedded-media");

if (/carousel|slider|rail|gallery/.test(classText)) kinds.add("carousel");

if (/scroll|scene|sticky|pinned/.test(classText)) {

if (interactions.some((item) => item.kind === "scroll-state")) kinds.add("scroll-state");

if (interactions.some((item) => item.kind === "tabs")) kinds.add("tabs");

}

if (!kinds.size) return null;

const sceneInteractions = interactions.filter((item) =>

item.sectionIds?.includes(section.id) || sectionInteractions.some((summary) => interactionMatchesSummary(item, summary))

);

const sceneMedia = media.filter((item) => {

const tokenText = `${item.domRef?.id || ""} ${(item.domRef?.classTokens || []).join(" ")} ${(item.domRef?.parentClassTokens || []).join(" ")} ${(item.domRef?.sectionClassTokens || []).join(" ")}`.toLowerCase();

if (isHero) return item.id === media.find((candidate) => candidate.role === "background")?.id;

if (kinds.has("scroll-state")) return item.role === "background" && /scroll|scene|sticky|pin|embed/.test(tokenText);

return false;

});

const activeKinds = Array.from(kinds);

const primitive = modelFor(activeKinds);

const requirements = [];

if (sceneMedia.some((item) => item.src)) requirements.push("Render each listed source-backed media surface with the recorded playback flags and scene role.");

if (sceneMedia.some((item) => item.fallback?.policy === "fallback-only")) requirements.push("Treat recorded posters/backgrounds as loading, blocked-media, or error fallbacks only; do not visibly blend them behind active media.");

if (sceneMedia.some((item) => !item.src)) requirements.push("Recreate the recorded runtime visual surface and its scene behavior; do not replace it with unrelated static imagery.");

if (kinds.has("carousel")) requirements.push("Render a finite-width data-rp-viewport that clips or scrolls a wider data-rp-track, preserve the captured card geometry, separation mechanism, and exact initial active state, then manage the captured active-card state on click plus every captured hover state.");

if (kinds.has("scroll-state")) requirements.push("Implement both entry progress and internal scroll progress: preserve media framing/sideways expansion through the captured entry and pinned phases, while applying transforms only to the measured motion owner and keeping static copy outside the visual scale scope.");

if (kinds.has("tabs")) requirements.push("Implement visible labels as buttons and switch the captured content state without replacing the scene background.");

const acceptance = [];

if (sceneMedia.some((item) => item.src)) acceptance.push("The implementation references the exact source URLs and preserves applicable playback flags.");

if (sceneMedia.some((item) => item.fallback?.policy === "fallback-only")) acceptance.push("No full-cover poster or image remains visibly composited with the active video/iframe.");

if (sceneMedia.some((item) => !item.src)) acceptance.push("The implementation preserves the runtime surface's visual role and recorded state changes.");

if (kinds.has("carousel")) acceptance.push("The viewport is narrower than the content track, and clicking a card changes its active/expanded state rather than only scrolling.");

if (kinds.has("scroll-state")) acceptance.push("Each captured scroll phase produces the corresponding distinct media/copy geometry; add a midpoint phase if source evidence has only endpoints.");

if (kinds.has("tabs")) acceptance.push("Each visible tab changes the text/content state while the section remains a single scene.");

return {

id: `${safeId(page)}-${section.id}`,

sectionId: section.id,

heading: section.heading || section.tag || "Untitled scene",

sourceScreenshot: screenshotFor(section, page),

interactionIds: sceneInteractions.map((item) => item.id),

media: sceneMedia,

states: sceneInteractions.map(sceneStateFor),

implementation: {

model: primitive,

primitive,

runtimeAdapter: runtimeAdapterFor(primitive),

runtimeModule: "/site-clone/rp-interactions-bootstrap.mjs",

bootstrap: "<script type=\"module\" src=\"/site-clone/rp-interactions-bootstrap.mjs\"></script>",

markerContract: markerContractFor(primitive, sceneInteractions),

initialState: initialStateFor(primitive, sceneInteractions),

assertions: assertionsFor({ primitive, interactions: sceneInteractions, media: sceneMedia }),

recipe: recipeFor(primitive),

requirements,

acceptance,

},

manualContentInventory: kinds.has("carousel") && !(page.repeaters || []).length,

};

}

function sceneStateFor(item) {

return {

id: item.id,

kind: item.kind,

trigger: item.trigger,

importance: item.importance,

interactionMapRef: `interaction-map.json#${item.id}`,

states: item.states,

...(item.scope ? { scope: item.scope } : {}),

...(item.timeline ? {

timelineSummary: {

sampledAtMs: item.timeline.sampledAtMs,

observedSettleMs: item.timeline.observedSettleMs,

changedNodeCount: item.timeline.changedNodeCount,

changedNodes: (item.timeline.changes || []).slice(0, 16).map((change) => ({

path: change.path,

role: change.role,

changedProperties: change.changedProperties,

})),

animations: item.timeline.animations || [],

},

} : {}),

...(item.invariants ? { invariants: item.invariants } : {}),

screenshot: item.evidence?.screenshot || null,

};

}

function interactionMatchesSummary(interaction, summary) {

if (summary.id) return summary.id === interaction.id;

const interactionTrigger = typeof interaction.trigger === "string" ? interaction.trigger : interaction.trigger?.type;

const summaryTrigger = typeof summary.trigger === "string" ? summary.trigger : summary.trigger?.type;

return interaction.kind === summary.kind && interaction.label === summary.label && interactionTrigger === summaryTrigger;

}

function markerContractFor(primitive, interactions = []) {

const base = { scene: "data-rp-scene", initialized: "data-rp-initialized" };

if (primitive === "active-card-rail") {

const mode = interactions.find((item) => item.kind === "carousel")?.invariants?.initialState || "single-active";

return { ...base, initialState: `data-rp-initial-state=\"${mode}\"`, viewport: "data-rp-viewport", track: "data-rp-track", item: "data-rp-item", hoverTarget: "data-rp-hover-target", activate: "data-rp-activate", control: "data-rp-direction", active: "data-rp-active=true" };

}

if (primitive === "content-switcher") {

return { ...base, item: "data-rp-item", activate: "data-rp-activate", active: "data-rp-active=true", panel: "data-rp-panel", state: "data-rp-state" };

}

if (primitive === "scroll-scene") {

return { ...base, phase: "data-rp-phase", visual: "data-rp-visual", content: "data-rp-content", curtain: "data-rp-curtain", panel: "data-rp-panel", item: "data-rp-item", activate: "data-rp-activate", active: "data-rp-active=true", state: "data-rp-state" };

}

return base;

}

function initialStateFor(primitive, interactions) {

if (primitive !== "active-card-rail") return null;

const invariants = interactions.find((item) => item.kind === "carousel")?.invariants || {};

return {

mode: invariants.initialState || "single-active",

activeIndexes: invariants.initialActiveIndexes || [],

};

}

function runtimeAdapterFor(primitive) {

if (primitive === "active-card-rail") return "bindActiveItemRail";

if (primitive === "content-switcher") return "bindContentSwitcher";

if (primitive === "scroll-scene") return "bindScrollScene + bindContentSwitcher";

return null;

}

function assertionsFor({ primitive, interactions, media }) {

const assertions = [];

if (primitive === "active-card-rail") {

const observed = interactions.find((item) => item.kind === "carousel")?.invariants || {};

assertions.push(

{ kind: "scene-present" },

{ kind: "runtime-initialized", primitive: "active-card-rail" },

{ kind: "minimum-item-count", value: Math.max(3, Number(observed.itemCount) || 3) },

{ kind: "horizontal-overflow", minimumRatio: roundTolerance(observed.horizontalOverflowRatio, 0.8, 1.05) },

{ kind: "initial-active-item-count", value: Number(observed.initialActiveCount) || 0 },

{ kind: "single-active-item", value: 1 },

{ kind: "activation-changes-state" },

);

if (Number(observed.expandedWidthRatio) > 1.1) {

assertions.push({ kind: "active-item-width-ratio", minimumRatio: roundTolerance(observed.expandedWidthRatio, 0.8, 1.15) });

}

if (Number(observed.observedSettleMs) > 0) {

assertions.push({ kind: "transition-settles", maximumMs: Math.ceil(Number(observed.observedSettleMs) * 1.5 + 100) });

}

if (observed.separation) assertions.push({ kind: "item-separation", observed: observed.separation });

if (interactions.some((item) => (typeof item.trigger === "string" ? item.trigger : item.trigger?.type) === "hover")) {

assertions.push({ kind: "hover-changes-visual-state" });

}

if (primitive === "content-switcher" || primitive === "scroll-scene" && interactions.some((item) => item.kind === "tabs")) {

assertions.push({ kind: "runtime-initialized", primitive: "content-switcher" });

assertions.push({ kind: "activation-changes-content" }, { kind: "single-active-item", value: 1 });

}

if (primitive === "scroll-scene") {

assertions.push({ kind: "runtime-initialized", primitive: "scroll-scene" });

assertions.push({ kind: "scroll-produces-distinct-phases", minimumPhaseCount: 2 });

const scrollInteraction = interactions.find((item) => item.kind === "scroll-state") || {};

const phases = scrollInteraction.states || [];

if (JSON.stringify(phases).includes('"position":"fixed"')) assertions.push({ kind: "visual-pins-during-scroll" });

const expansion = scrollInteraction.invariants?.visualExpansion;

const expansionRatio = Math.max(Number(expansion?.score) || 1, Number(expansion?.widthRatio) || 1, Number(expansion?.transformScaleRatio) || 1);

if (expansionRatio > 1.1) {

assertions.push({

kind: "scroll-visual-expansion",

minimumRatio: rangeRatioTolerance(expansionRatio, 0.8, 1.05),

});

}

const contentMotion = scrollInteraction.invariants?.motionOwnership?.content;

if (contentMotion && contentMotion.scales === false) {

assertions.push({ kind: "scroll-content-scale-bound", maximumRatio: Number(contentMotion.maximumAllowedScaleRatio) || 1.03 });

}

for (const item of media.filter((entry) => entry.src)) {

assertions.push({ kind: "media-source-present", source: item.src, playback: item.playback || {} });

if (item.fallback?.policy === "fallback-only") assertions.push({ kind: "exclusive-media-layer", fallbackSource: item.fallback.src });

}

return assertions;

}

function recipeFor(primitive) {

const common = {

bootstrap: "Add exactly once near the end of the document: <script type=\"module\" src=\"/site-clone/rp-interactions-bootstrap.mjs\"></script>",

warning: "A raw browser script must not import a relative module from src/. Use the public bootstrap above, or use the framework's compiled source import without type=module.",

};

if (primitive === "active-card-rail") return {

...common,

steps: [

"Put data-rp-viewport on a finite-width overflow-x:auto or overflow:hidden element.",

"Put data-rp-track on its wider max-content flex/grid row; never put overflow on a max-content track.",

"Put data-rp-item on every card and data-rp-activate on the card activation control.",

"Set data-rp-initial-state to the captured invariant. Use all-collapsed when the source has no active item; never pre-open a card for visual variety.",

"Reproduce the recorded separation mechanism (track gap, margins, divider, or inner inset) rather than guessing a generic gap.",

"Mark the element with the source hover treatment as data-rp-hover-target and reproduce that treatment with :hover/:focus-visible CSS.",

"Style data-rp-active=true to reproduce the observed expanded/collapsed ratio; keep active links above any activation hit target.",

],

};

if (primitive === "scroll-scene") return {

...common,

steps: [

"Give the scene enough scroll height and mark only the measured pinned/scaled wrapper with data-rp-visual.",

"Mark independently positioned copy with data-rp-content. Do not nest it inside a scaling visual wrapper unless the source evidence explicitly records content scaling.",

"Use --rp-entry-progress for the approach expansion and --rp-scroll-progress for pinned/release phases.",

"When the source uses side curtains/masks, mark both with data-rp-curtain and reduce their widths as entry progress increases.",

"If tabs exist, give controls and panels matching data-rp-state values.",

"Do not render a fallback poster at the same time as an opaque active video/iframe.",

],

};

if (primitive === "content-switcher") return {

...common,

steps: [

"Give each visible control data-rp-item, data-rp-activate, and a unique data-rp-state.",

"Give its content panel the matching data-rp-panel and data-rp-state.",

],

};

return common;

}

function roundTolerance(value, factor, floor) {

const numeric = Number(value) || 0;

return Math.round(Math.max(floor, numeric * factor) * 1000) / 1000;

}

function rangeRatioTolerance(value, factor, floor) {

const numeric = Math.max(1, Number(value) || 1);

return Math.round(Math.max(floor, 1 + (numeric - 1) * factor) * 1000) / 1000;

}

function modelFor(kinds) {

if (kinds.includes("scroll-state")) return "scroll-scene";

if (kinds.includes("carousel")) return "active-card-rail";

if (kinds.includes("tabs")) return "content-switcher";

return "media-scene";

}

function screenshotFor(section, page) {

if (section.kind === "hero") return page.screenshots?.desktop || null;

return page.screenshots?.desktop || page.screenshots?.tablet || null;

}

function safeId(page) {

return `${page.area || "page"}-${String(page.path || "home").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "") || "home"}`;

}

if (import.meta.url === `file://${process.argv[1]}`) {

main().catch((error) => {

console.error(error.stack || error.message);

process.exit(1);

});

}