dreative 0.5.1 → 0.5.3

package/dist/shared/ruleSystem.js

@@ -0,0 +1,220 @@
+function normalized(value) {
+    return value.trim().toLocaleLowerCase().replace(/\s+/g, " ");
+}
+function distinct(values) {
+    return [...new Set(values.map(normalized).filter(Boolean))];
+}
+function specific(value, minLength) {
+    if (!value || value.trim().length < minLength)
+        return false;
+    return !/^(it |this )?(did not fit|didn't fit|felt better|was unnecessary|was not needed|looked better|fits? the design|restraint)$/i.test(value.trim());
+}
+function genericMotionOnly(value) {
+    const text = normalized(value);
+    const basic = /\b(fade|opacity|translate|slide|scale|zoom|parallax|reveal|stagger)\b/;
+    const structural = /\b(mask|fragment|tile|pixel|layer|depth|pin|persist|handoff|morph|reconstruct|sequence|canvas|svg|webgl|shader|state|composition|camera|clip-path|typography)\b/;
+    return basic.test(text) && !structural.test(text);
+}
+export function validateRuleControls(plan, registry, reflexFonts, verification) {
+    if (plan.doctrineVersion !== 2)
+        return [];
+    const errors = [];
+    const rules = new Map(registry.rules.map((rule) => [rule.id, rule]));
+    const evidence = new Map((verification?.evidence ?? []).map((item) => [item.id, item]));
+    for (const exception of plan.ruleExceptions ?? []) {
+        if (exception.decision !== "substituted")
+            errors.push(`${exception.ruleId || "unknown rule"}: decision must be substituted`);
+        const rule = rules.get(exception.ruleId);
+        if (!rule) {
+            errors.push(`unknown rule exception: ${exception.ruleId}`);
+            continue;
+        }
+        if (rule.category === "hard-gate" || !rule.exceptionAllowed) {
+            errors.push(`hard gate ${exception.ruleId} cannot be substituted`);
+            continue;
+        }
+        if (!specific(exception.reason, 30))
+            errors.push(`${exception.ruleId}: reason is vague or too short`);
+        if (!specific(exception.alternative, 40))
+            errors.push(`${exception.ruleId}: alternative is vague or too short`);
+        const criteria = Array.isArray(exception.successCriteria) ? exception.successCriteria : [];
+        if (distinct(criteria).length < 2 || criteria.some((criterion) => criterion.trim().length < 12))
+            errors.push(`${exception.ruleId}: needs at least two observable success criteria`);
+        if (!plan.implementationStartedAt || Number.isNaN(Date.parse(plan.implementationStartedAt)))
+            errors.push(`${exception.ruleId}: implementationStartedAt is required to prove planning-time declaration`);
+        else if (Number.isNaN(Date.parse(exception.declaredAt)) || Date.parse(exception.declaredAt) > Date.parse(plan.implementationStartedAt))
+            errors.push(`${exception.ruleId}: exception must be declared before implementation starts`);
+        const evidenceIds = Array.isArray(exception.evidenceIds) ? exception.evidenceIds : [];
+        if (evidenceIds.length === 0)
+            errors.push(`${exception.ruleId}: substitution requires verification evidence`);
+        for (const id of evidenceIds) {
+            const item = evidence.get(id);
+            if (!item)
+                errors.push(`${exception.ruleId}: missing verification evidence ${id}`);
+            else if (item.status !== "pass")
+                errors.push(`${exception.ruleId}: evidence ${id} is not passing`);
+        }
+    }
+    if (!plan.fontDecision) {
+        errors.push("fontDecision is required for doctrineVersion 2 plans");
+    }
+    else {
+        const decision = plan.fontDecision;
+        const candidates = Array.isArray(decision.candidates) ? decision.candidates : [];
+        if (distinct(candidates.map((candidate) => candidate.name)).length < 3)
+            errors.push("fontDecision requires at least three distinct candidates");
+        if (!candidates.some((candidate) => normalized(candidate.name) === normalized(decision.selected)))
+            errors.push("selected font must appear in font candidates");
+        const reflexSet = new Set(reflexFonts.fonts.map(normalized));
+        for (const candidate of candidates) {
+            if (candidate.reflex !== reflexSet.has(normalized(candidate.name)))
+                errors.push(`${candidate.name}: reflex marker does not match REFLEX_FONTS.json`);
+        }
+        const selectedIsReflex = reflexSet.has(normalized(decision.selected));
+        if (selectedIsReflex) {
+            const reason = decision.justification ?? "";
+            const validKinds = new Set(reflexFonts.validReasonKinds ?? []);
+            if (!(decision.reasonKinds ?? []).some((kind) => validKinds.has(kind)))
+                errors.push(`${decision.selected}: reflex font requires at least one registered reason kind`);
+            if (!specific(reason, 40) || reflexFonts.invalidGenericReasons.some((phrase) => normalized(reason).includes(normalized(phrase))))
+                errors.push(`${decision.selected}: reflex font requires a specific non-generic justification`);
+        }
+        if ((decision.recentDisplayFonts ?? []).map(normalized).includes(normalized(decision.selected)) && !specific(decision.repeatJustification, 40))
+            errors.push(`${decision.selected}: repeating a recent display font requires a stronger justification`);
+    }
+    if (plan.tier === "expressive" || plan.tier === "award") {
+        const strategy = plan.creativeStrategy;
+        if (!strategy)
+            errors.push(`${plan.tier} plans require a diversity-or-development creativeStrategy`);
+        else if (strategy.path === "diversity") {
+            if (distinct(strategy.mechanisms ?? []).length === 0)
+                errors.push("diversity path requires at least one concept-specific mechanism");
+            if (distinct(strategy.drivers ?? []).length === 0)
+                errors.push("diversity path requires at least one meaningful driver");
+        }
+        else {
+            if (!specific(strategy.signatureMechanism, 12))
+                errors.push("development path requires a named signature mechanism");
+            if (distinct(strategy.states ?? []).length < 2 || (strategy.states ?? []).some((state) => state.trim().length < 12))
+                errors.push("development path requires materially different described states");
+            if (!Array.isArray(strategy.secondaryMechanisms))
+                errors.push("development path must record its quieter supporting mechanisms");
+            if (distinct(strategy.drivers ?? []).length === 0)
+                errors.push("development path requires a meaningful driver");
+        }
+        const sections = plan.pages.flatMap((page) => page.sections);
+        const sectionIds = new Set(sections.map((section) => section.id));
+        const budget = plan.motionComplexityBudget;
+        if (!budget)
+            errors.push(`${plan.tier} plans require a contextual motionComplexityBudget`);
+        else {
+            if (budget.heroMoments.length === 0 || budget.heroMoments.length > 3)
+                errors.push("motion complexity must be concentrated into one to three hero moments");
+            for (const moment of budget.heroMoments) {
+                if (!sectionIds.has(moment.sectionId))
+                    errors.push(`motion hero moment references unknown section ${moment.sectionId}`);
+                if (!specific(moment.reason, 20))
+                    errors.push(`motion hero moment ${moment.sectionId} needs a concept-specific reason`);
+            }
+            for (const sectionId of budget.calmSectionIds) {
+                if (!sectionIds.has(sectionId))
+                    errors.push(`motion calm section references unknown section ${sectionId}`);
+            }
+            if (!specific(budget.sharedLanguage, 20) || !specific(budget.deviceLimits, 20) || !specific(budget.progressiveEnhancement, 20))
+                errors.push("motion complexity budget needs shared language, device limits, and progressive-enhancement decisions");
+            const antiDefault = budget.antiDefaultReview;
+            if (!antiDefault)
+                errors.push("motion complexity budget requires the anti-default review");
+            else
+                for (const [name, answer] of Object.entries(antiDefault)) {
+                    if (!specific(answer, 20))
+                        errors.push(`anti-default review ${name} needs a concrete answer`);
+                }
+        }
+        const treatments = sections.map((section) => section.motionTreatment);
+        if (treatments.some((treatment) => !treatment))
+            errors.push(`${plan.tier} plans require a motion treatment for every major section, including calm sections`);
+        const significant = treatments.filter((treatment) => Boolean(treatment && (treatment.class === "structural" || treatment.class === "transformational")));
+        if (significant.length === 0)
+            errors.push(`${plan.tier} motion cannot be decorative-only`);
+        if (significant.length > 0 &&
+            significant.every((treatment) => genericMotionOnly(`${treatment.mechanism} ${(treatment.changes ?? []).join(" ")} ${treatment.handoff}`)))
+            errors.push(`${plan.tier} motion still describes only generic fade/slide/scale behavior; revise the scene architecture`);
+        for (const [index, treatment] of treatments.entries()) {
+            if (!treatment)
+                continue;
+            const prefix = `motion treatment ${sections[index].id}`;
+            for (const [name, value] of Object.entries({
+                staticComposition: treatment.staticComposition,
+                startState: treatment.startState,
+                endState: treatment.endState,
+                handoff: treatment.handoff,
+                purpose: treatment.purpose,
+                mechanism: treatment.mechanism,
+                mobile: treatment.mobile,
+                reducedMotion: treatment.reducedMotion,
+            })) {
+                if (!specific(value, 12))
+                    errors.push(`${prefix}.${name} needs a concrete decision`);
+            }
+        }
+        if (verification) {
+            const timelineStates = new Set(verification.evidence.map((item) => item.timelineState).filter(Boolean));
+            const requiredStates = [
+                "initial",
+                "early",
+                "mid-transition",
+                "final",
+                "handoff",
+                "mobile",
+                "reduced-motion",
+            ];
+            if (treatments.some((treatment) => (treatment?.pinnedElements?.length ?? 0) > 0))
+                requiredStates.push("pinned-midpoint", "pinned-exit");
+            for (const state of requiredStates) {
+                if (!timelineStates.has(state))
+                    errors.push(`visual verification is missing timeline state ${state}`);
+            }
+            const refinement = verification.refinement;
+            if (!refinement || refinement.changes.length === 0 || refinement.evidenceIds.length === 0)
+                errors.push(`${plan.tier} verification requires a recorded refinement pass after visual inspection`);
+            else {
+                for (const id of refinement.evidenceIds) {
+                    const item = evidence.get(id);
+                    if (!item || item.status !== "pass")
+                        errors.push(`refinement references missing or failing evidence ${id}`);
+                }
+            }
+        }
+    }
+    if (plan.skills.includes("experimental")) {
+        const experimental = plan.experimentalPlan;
+        if (!experimental)
+            errors.push("experimental skill requires experimentalPlan");
+        else {
+            const candidates = Array.isArray(experimental.candidates) ? experimental.candidates : [];
+            const covered = new Set(candidates.map((candidate) => candidate.sectionId));
+            for (const sectionId of experimental.majorSectionIds ?? []) {
+                if (!covered.has(sectionId))
+                    errors.push(`experimental exploration is missing major section ${sectionId}`);
+            }
+            const selected = candidates.filter((candidate) => candidate.selected);
+            if (selected.length < 2 || selected.length > 3)
+                errors.push("experimental delivery must select only the strongest two or three provocations");
+            if (candidates.some((candidate) => candidate.idea.trim().length < 20))
+                errors.push("experimental candidates must be concrete, non-obvious ideas");
+        }
+    }
+    if ((plan.recipeAccess?.length ?? 0) > 0) {
+        if (!plan.conceptExploration || distinct(plan.conceptExploration.concepts.map((concept) => concept.concept)).length < 3)
+            errors.push("three original concepts must be recorded before recipe access");
+        else {
+            const exploredAt = Date.parse(plan.conceptExploration.recordedAt);
+            for (const access of plan.recipeAccess ?? []) {
+                if (Number.isNaN(Date.parse(access.loadedAt)) || Date.parse(access.loadedAt) < exploredAt)
+                    errors.push(`${access.file}: recipe was loaded before concept exploration was recorded`);
+            }
+        }
+    }
+    return errors;
+}

package/dist/shared/ruleSystem.test.js

@@ -0,0 +1,262 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { validateRuleControls } from "./ruleSystem.js";
+const registry = JSON.parse(fs.readFileSync(path.resolve("skill/dreative/references/RULES.json"), "utf-8"));
+const reflex = JSON.parse(fs.readFileSync(path.resolve("skill/dreative/references/REFLEX_FONTS.json"), "utf-8"));
+const planned = "2026-01-01T00:00:00.000Z";
+const started = "2026-01-01T01:00:00.000Z";
+function basePlan(tier = "award") {
+    return {
+        version: 2,
+        doctrineVersion: 2,
+        request: "Create an ambitious archival experience",
+        createdAt: planned,
+        implementationStartedAt: started,
+        tier,
+        depth: "reimagine",
+        skills: ["ux", "mobile", "motion", "media"],
+        skillPolicy: { mode: "hybrid", global: ["ux", "mobile"], routingApproved: true, userAssignments: [] },
+        designRead: { register: "archival editorial", concept: "living catalog", signature: "transforming specimen" },
+        fontDecision: {
+            selected: "Source Serif 4",
+            candidates: [
+                { name: "Source Serif 4", reflex: false, rationale: "Variable optical sizes support the archival scale shifts." },
+                { name: "Newsreader", reflex: false, rationale: "Editorial contrast supports document-led hierarchy." },
+                { name: "Archivo", reflex: false, rationale: "Catalog labeling connects directly to the archival subject." },
+            ],
+            recentDisplayFonts: [],
+        },
+        creativeStrategy: {
+            path: "diversity",
+            mechanisms: ["variable-type morph", "depth-stack", "drag-inertia", "mask-dissolve"],
+            drivers: ["scroll", "pointer", "time"],
+        },
+        motionComplexityBudget: {
+            heroMoments: [{ sectionId: "hero", reason: "The archival specimen becomes the navigation system and establishes the living-catalog concept." }],
+            calmSectionIds: [],
+            sharedLanguage: "Archival sheets fold, align, and become structural boundaries across the journey.",
+            deviceLimits: "Desktop uses the full pinned chapter while mobile shortens travel and removes continuous rendering.",
+            progressiveEnhancement: "Semantic catalog content renders first; masks and synchronized motion enhance it when supported.",
+            antiDefaultReview: {
+                basicMotionAssessment: "The key specimen changes role and geometry rather than only fading, sliding, or scaling.",
+                compositionHandoff: "The specimen edge becomes the next chapter's indexing rail instead of disappearing.",
+                visualStateChange: "Loose sheets become navigation, a research surface, and then the closing mark.",
+                conceptSpecificity: "The sheet behavior is derived from archival handling and would not fit an unrelated product.",
+                memorableMoment: "Dragging the specimen reorganizes the complete catalog into the next chapter.",
+            },
+        },
+        pages: [
+            {
+                id: "home",
+                name: "Home",
+                skills: ["ux", "mobile", "motion", "media"],
+                sections: [
+                    {
+                        id: "hero",
+                        name: "Hero",
+                        layoutFamily: "archival-index",
+                        skills: ["ux", "mobile", "motion", "media"],
+                        interactions: ["drag specimen"],
+                        motionTreatment: {
+                            class: "transformational",
+                            staticComposition: "A loose archival specimen sits beside the catalog index.",
+                            startState: "The specimen is centered and isolated as the page's primary subject.",
+                            endState: "The specimen unfolds into the structural rail for the next catalog chapter.",
+                            changes: ["The specimen mask expands and its edge becomes the next chapter rail."],
+                            pinnedElements: [],
+                            handoff: "The specimen edge persists as the indexing rail in the following composition.",
+                            purpose: "Turn passive archival viewing into active handling and establish continuity.",
+                            mechanism: "SVG mask migration synchronized with a GSAP scroll timeline.",
+                            mobile: "A shorter clip-path handoff preserves the specimen-to-rail transformation.",
+                            reducedMotion: "Render the specimen already aligned with the rail and use a direct section cut.",
+                        },
+                        mobile: "stacked specimen",
+                        fallback: "static catalog",
+                        verification: ["Signature responds to input"],
+                        assets: [],
+                        status: "shipped",
+                    },
+                ],
+            },
+        ],
+        preservationManifest: ".dreative/preservation.json",
+        decisionLedger: ".dreative/ledger.json",
+    };
+}
+function verification(...ids) {
+    const timelineStates = ["initial", "early", "mid-transition", "final", "handoff", "mobile", "reduced-motion"];
+    const timeline = timelineStates.map((timelineState) => ({
+        id: `timeline-${timelineState}`,
+        criterion: `Captured ${timelineState} visual state`,
+        status: "pass",
+        evidence: "Captured the production build at the planned visual state.",
+        timelineState,
+        proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+    }));
+    return {
+        version: 1,
+        generatedAt: started,
+        evidence: [
+            ...timeline,
+            ...ids.map((id) => ({
+                id,
+                criterion: id,
+                status: "pass",
+                evidence: "Captured runtime behavior in the production build.",
+                proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+            })),
+        ],
+        refinement: {
+            inspectedAt: started,
+            findings: ["The mid-transition index was too compressed to read."],
+            changes: ["Extended the mask handoff and delayed the rail compression."],
+            evidenceIds: ["timeline-mid-transition"],
+        },
+    };
+}
+test("valid default award plan", () => {
+    assert.deepEqual(validateRuleControls(basePlan(), registry, reflex, verification()), []);
+});
+test("valid key-asset substitution for a typography-only experience", () => {
+    const plan = basePlan();
+    plan.ruleExceptions = [
+        {
+            ruleId: "media.keyAssetTreatment",
+            decision: "substituted",
+            declaredAt: planned,
+            reason: "The archive contains no raster key imagery; inventing photography would misrepresent the supplied typographic material.",
+            alternative: "A persistent variable-type specimen becomes index, spatial architecture, and interactive control across the complete journey.",
+            successCriteria: ["The specimen appears in materially different structural roles", "Pointer and scroll input visibly reshape the specimen"],
+            evidenceIds: ["type-system-desktop", "type-system-mobile"],
+        },
+    ];
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification("type-system-desktop", "type-system-mobile")), []);
+});
+test("invalid vague creative-rule exception", () => {
+    const plan = basePlan();
+    plan.ruleExceptions = [
+        {
+            ruleId: "media.keyAssetTreatment",
+            decision: "substituted",
+            declaredAt: planned,
+            reason: "It did not fit",
+            alternative: "Typography felt better",
+            successCriteria: ["Looks good", "Feels spatial"],
+            evidenceIds: ["type"],
+        },
+    ];
+    const errors = validateRuleControls(plan, registry, reflex, verification("type"));
+    assert.ok(errors.some((error) => error.includes("vague")));
+});
+test("attempted hard-gate exception", () => {
+    const plan = basePlan();
+    plan.ruleExceptions = [
+        {
+            ruleId: "preservation.noLoss",
+            decision: "substituted",
+            declaredAt: planned,
+            reason: "The old form was intentionally removed to simplify the new conversion route for this campaign.",
+            alternative: "A replacement conversion control carries the same submitted data into the existing backend workflow.",
+            successCriteria: ["Users can submit the same required fields", "The existing backend receives an equivalent payload"],
+            evidenceIds: ["form"],
+        },
+    ];
+    assert.ok(validateRuleControls(plan, registry, reflex, verification("form")).some((error) => error.includes("cannot be substituted")));
+});
+test("valid diversity plan", () => {
+    const plan = basePlan("expressive");
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification()), []);
+});
+test("valid development plan", () => {
+    const plan = basePlan();
+    plan.creativeStrategy = {
+        path: "development",
+        signatureMechanism: "An archival sheet transforms across the complete journey",
+        states: ["Loose sheets form a catalog index", "Sheets become a draggable research surface", "Sheets collapse into a spatial tunnel"],
+        secondaryMechanisms: ["kinetic labels", "material lighting"],
+        drivers: ["scroll", "pointer"],
+    };
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification()), []);
+});
+test("invalid decorative-only expressive plan", () => {
+    const plan = basePlan();
+    plan.pages[0].sections[0].motionTreatment = {
+        ...plan.pages[0].sections[0].motionTreatment,
+        class: "decorative",
+        changes: ["The image fades upward and scales into view."],
+        mechanism: "CSS opacity, translateY, and scale transitions on scroll reveal.",
+    };
+    const errors = validateRuleControls(plan, registry, reflex, verification());
+    assert.ok(errors.some((error) => error.includes("decorative-only")));
+});
+test("expressive plan requires contextual motion budget", () => {
+    const plan = basePlan("expressive");
+    delete plan.motionComplexityBudget;
+    assert.ok(validateRuleControls(plan, registry, reflex, verification()).some((error) => error.includes("motionComplexityBudget")));
+});
+test("award verification requires timeline states and a refinement pass", () => {
+    const plan = basePlan();
+    const report = {
+        version: 1,
+        generatedAt: started,
+        evidence: [
+            {
+                id: "initial-only",
+                criterion: "Initial state",
+                status: "pass",
+                evidence: "Captured only the initial frame.",
+                timelineState: "initial",
+                proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+            },
+        ],
+    };
+    const errors = validateRuleControls(plan, registry, reflex, report);
+    assert.ok(errors.some((error) => error.includes("mid-transition")));
+    assert.ok(errors.some((error) => error.includes("refinement pass")));
+});
+test("valid reflex-font justification", () => {
+    const plan = basePlan("premium");
+    plan.fontDecision = {
+        selected: "Inter",
+        candidates: [
+            { name: "Inter", reflex: true, rationale: "Existing authenticated product metrics and density depend on it." },
+            { name: "Switzer", reflex: false, rationale: "Comparable product clarity with more character." },
+            { name: "Source Sans 3", reflex: false, rationale: "Broad language support and efficient variable delivery." },
+        ],
+        recentDisplayFonts: [],
+        reasonKinds: ["existing-brand", "design-system-metrics"],
+        justification: "Inter is embedded throughout the authenticated product, preserves established density metrics, and avoids layout regressions across translated views.",
+    };
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification()), []);
+});
+test("invalid generic font justification", () => {
+    const plan = basePlan("premium");
+    plan.fontDecision = {
+        selected: "Inter",
+        candidates: [
+            { name: "Inter", reflex: true, rationale: "A familiar interface choice." },
+            { name: "Switzer", reflex: false, rationale: "A product-oriented alternative." },
+            { name: "Source Sans 3", reflex: false, rationale: "A broad-language alternative." },
+        ],
+        recentDisplayFonts: [],
+        reasonKinds: [],
+        justification: "Inter looks clean and modern for this interface.",
+    };
+    assert.ok(validateRuleControls(plan, registry, reflex, verification()).some((error) => error.includes("non-generic")));
+});
+test("experimental exploration selects only two shipped provocations", () => {
+    const plan = basePlan("expressive");
+    plan.skills.push("experimental");
+    plan.pages[0].skills.push("experimental");
+    plan.experimentalPlan = {
+        majorSectionIds: ["hero", "archive", "closing"],
+        candidates: [
+            { id: "p1", sectionId: "hero", idea: "The title behaves as a physical catalog drawer opened by drag.", selected: true },
+            { id: "p2", sectionId: "archive", idea: "Research sheets reorganize into a navigable spatial evidence wall.", selected: true },
+            { id: "p3", sectionId: "closing", idea: "The final mark briefly assembles from all prior catalog coordinates.", selected: false },
+        ],
+    };
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification()), []);
+});

package/dist/shared/skillSystem.js

@@ -0,0 +1,173 @@
+export const SKILL_DEFINITIONS = [
+    {
+        name: "ux",
+        description: "Working navigation, forms, states, keyboard access, focus, and interaction audits.",
+        dependencies: [],
+        signature: /\b(ux|accessib|a11y|forms?|navigation|keyboard|focus|states?|dashboard|product ui)\b/i,
+    },
+    {
+        name: "mobile",
+        description: "Mobile-native composition, touch ergonomics, responsive effects, and phone verification.",
+        dependencies: ["ux"],
+        signature: /\b(mobile|phone|tablet|responsive|touch|thumb|small screen)\b/i,
+    },
+    {
+        name: "refined",
+        description: "Premium clean business, DTC, and commerce design with restraint and strong photography.",
+        dependencies: ["ux", "mobile"],
+        signature: /\b(clean (and )?(modern|professional)|modern clean|business (site|website|use)|corporate|professional look|premium (minimal|clean)|dtc|d2c|e[- ]?commerce|ecommerce|shopify|calm|understated)\b/i,
+    },
+    {
+        name: "motion",
+        description: "Scroll choreography, entrances, kinetic type, springs, parallax, and transitions.",
+        dependencies: ["ux", "mobile"],
+        signature: /\b(animat|motion|parallax|scroll[- ]?(driven|trigger|story|choreo)|gsap|framer|lenis|marquee|kinetic|stagger|reveal|transition)\b/i,
+    },
+    {
+        name: "interaction",
+        description: "Hover craft, magnetic controls, cursor effects, tactile feedback, and state morphs.",
+        dependencies: ["ux", "mobile"],
+        signature: /\b(micro[- ]?interaction|hover (effect|state)s?|cursor|magnetic|tilt|spotlight|glow|ripple|tactile|interactive|draggable)\b/i,
+    },
+    {
+        name: "media",
+        description: "Generated and sourced image/video production, grading, motion treatments, and media planes.",
+        dependencies: ["ux", "mobile"],
+        signature: /\b(generated? (image|video|media)|hero video|image treatment|media plane|gallery|photography|video loop|distortion|living thumbnail)\b/i,
+    },
+    {
+        name: "3d",
+        description: "Three.js/R3F, WebGL, shaders, particles, models, lighting, and robust fallbacks.",
+        dependencies: ["ux", "mobile"],
+        signature: /\b(3d|three\.?js|webgl|r3f|shader|glsl|particles?|point ?cloud|globe|mesh gradient|orbit|spline)\b/i,
+    },
+    {
+        name: "immersive",
+        description: "Persistent spatial stages, preloaders, scene transitions, and scroll-as-journey.",
+        dependencies: ["motion", "interaction", "media", "ux", "mobile"],
+        signature: /\b(immersive|award[- ]?(site|winning)|awwwards|spatial|scene[- ]?based|world|camera (move|travel|path)|preloader|scroll (journey|story|as travel)|explorable|experience site)\b/i,
+    },
+    {
+        name: "cinematic",
+        description: "Shader-graded experiential interfaces, living surfaces, gesture exploration, and sound.",
+        dependencies: ["motion", "interaction", "media", "ux", "mobile"],
+        signature: /\b(cinematic|experiential|unseen\.co|fluid (sim(ulation)?|distortion)|gpgpu|drag[- ]to[- ]explore|click ?(&|and) ?hold|film grain|graded|velocity[- ]reactive|sound design|ambient (audio|sound))\b/i,
+    },
+    {
+        name: "experimental",
+        description: "Unconventional composition, material shifts, provocations, and high-variance creative direction.",
+        dependencies: ["motion", "interaction", "media", "ux", "mobile"],
+        signature: /\b(experimental|crazy|bizarre|never seen before|more creative|wow factor|unconventional|unexpected|provocation)\b/i,
+    },
+];
+const BY_NAME = new Map(SKILL_DEFINITIONS.map((skill) => [skill.name, skill]));
+export function detectSpecialistSkills(texts) {
+    const haystack = texts.filter(Boolean).join("\n");
+    return SKILL_DEFINITIONS.filter((skill) => skill.signature.test(haystack)).map((skill) => skill.name);
+}
+export function resolveSkillDependencies(requested) {
+    const resolved = new Set(["ux", "mobile"]);
+    const visit = (name) => {
+        if (resolved.has(name))
+            return;
+        for (const dependency of BY_NAME.get(name)?.dependencies ?? [])
+            visit(dependency);
+        resolved.add(name);
+    };
+    for (const name of requested)
+        visit(name);
+    return SKILL_DEFINITIONS.map((skill) => skill.name).filter((name) => resolved.has(name));
+}
+function skillScore(name, texts) {
+    const definition = BY_NAME.get(name);
+    if (!definition)
+        return 0;
+    const haystack = texts.filter(Boolean).join("\n");
+    const flags = definition.signature.flags.includes("g") ? definition.signature.flags : `${definition.signature.flags}g`;
+    return [...haystack.matchAll(new RegExp(definition.signature.source, flags))].length;
+}
+/**
+ * Hybrid multi-page routing: user selection is authoritative, explicit page
+ * assignments are locked, and only selected-but-unassigned treatments are
+ * placed automatically. Detected unselected skills are returned as suggestions
+ * and never activated silently.
+ */
+export function routeSkillsAcrossPages(request) {
+    const selected = [...new Set(request.selected)];
+    const resolved = resolveSkillDependencies(selected);
+    const byPageSets = new Map(request.pages.map((page) => [page.id, new Set(["ux", "mobile"])]));
+    for (const [pageId, skills] of Object.entries(request.assignments ?? {})) {
+        const target = byPageSets.get(pageId);
+        if (!target)
+            continue;
+        for (const skill of skills) {
+            if (!resolved.includes(skill))
+                continue;
+            for (const dependency of resolveSkillDependencies([skill]))
+                target.add(dependency);
+        }
+    }
+    const optionalSelected = selected.filter((skill) => skill !== "ux" && skill !== "mobile");
+    const unassigned = optionalSelected.filter((skill) => ![...byPageSets.values()].some((skills) => skills.has(skill)));
+    if (request.autoRouteUnassigned !== false && request.pages.length > 0) {
+        for (const skill of unassigned) {
+            const ranked = request.pages
+                .map((page, index) => ({
+                page,
+                index,
+                score: skillScore(skill, page.texts),
+                load: [...(byPageSets.get(page.id) ?? [])].filter((name) => name !== "ux" && name !== "mobile").length,
+            }))
+                .sort((a, b) => b.score - a.score || a.load - b.load || a.index - b.index);
+            const target = byPageSets.get(ranked[0].page.id);
+            for (const dependency of resolveSkillDependencies([skill]))
+                target.add(dependency);
+        }
+    }
+    const suggestions = {};
+    for (const page of request.pages) {
+        suggestions[page.id] = detectSpecialistSkills(page.texts).filter((skill) => !resolved.includes(skill));
+    }
+    const byPage = Object.fromEntries(request.pages.map((page) => [
+        page.id,
+        SKILL_DEFINITIONS.map((definition) => definition.name).filter((name) => byPageSets.get(page.id)?.has(name)),
+    ]));
+    return {
+        selected,
+        resolved,
+        byPage,
+        suggestions,
+        unassigned: request.autoRouteUnassigned === false ? unassigned : [],
+    };
+}
+export function resolveAmbitionTier(input) {
+    const haystack = [input.aesthetic, ...(input.texts ?? [])].filter(Boolean).join(" ");
+    if (/\b(award|awwwards|immersive|cinematic|experimental|unseen\.co)\b/i.test(haystack) || input.motion >= 9)
+        return "award";
+    if (input.motion >= 7 || input.variance >= 8)
+        return "expressive";
+    if (input.motion >= 4 || input.variance >= 5)
+        return "premium";
+    return "solid";
+}
+export const TIER_REQUIREMENTS = {
+    solid: [
+        "All existing behavior is preserved and the UX audit passes.",
+        "Desktop and mobile layouts are verified with keyboard and reduced-motion coverage.",
+    ],
+    premium: [
+        "Solid-tier requirements pass.",
+        "The page has a clear design read, one signature detail, and a completed craft pass.",
+        "Media is intentionally cropped/graded and interaction states are designed.",
+    ],
+    expressive: [
+        "Premium-tier requirements pass.",
+        "At least three distinct, purposeful motion or interaction moments ship with fallbacks.",
+        "Heavy effects are measured on desktop and translated deliberately for mobile.",
+    ],
+    award: [
+        "Expressive-tier requirements pass.",
+        "The experience has a distinctive spatial or media system, not isolated decoration.",
+        "Runtime, asset-weight, frame-time, occlusion, and fallback evidence is recorded.",
+    ],
+};