dreative 0.5.3 → 0.5.4

package/dist/shared/design.js

@@ -17,16 +17,6 @@ const AESTHETIC_DIALS = {
     "dark-tech": [6, 5, 5],
     trust: [3, 2, 5],
 };
-/** Layout families rotated across sections so no page repeats itself. */
-const FAMILIES = [
-    "asymmetric-split",
-    "bento-grid",
-    "full-width-statement",
-    "stacked-vertical",
-    "offset-two-col",
-    "horizontal-scroll-strip",
-    "editorial-columns",
-];
 function resolveDials(brief) {
     const base = AESTHETIC_DIALS[brief?.aesthetic ?? ""] ?? [7, 5, 4];
     return {
@@ -106,24 +96,36 @@ export function lintLayout(layout) {
         lints.push(`${buttons} buttons on one page — consolidate duplicate CTA intents (one label per intent)`);
     return lints;
 }
+const STYLE_ONLY = /\b(colou?r|font|typograph|radius|shadow|gradient|animation|fade|slide|scale|hover|spacing|token)\b/i;
+const STRUCTURAL_LANGUAGE = /\b(architecture|boundary|workflow|navigation|hierarchy|order|interaction|task|workspace|model|rebuild|recompose|replace|merge|move|remove)\b/i;
+/** Blocking contract lints used by tests and agent-facing runtime plans. */
+export function lintDesignPlan(plan) {
+    const lints = [];
+    const delta = plan.structuralDelta;
+    const deltaText = [delta.proposedModel, delta.proposedParadigm, delta.depthHonesty, ...delta.materialChanges].join(" ");
+    if ((plan.depth === "restructure" || plan.depth === "reimagine") && (!STRUCTURAL_LANGUAGE.test(deltaText) || (STYLE_ONLY.test(deltaText) && !STRUCTURAL_LANGUAGE.test(delta.materialChanges.join(" ")))))
+        lints.push(`${plan.depth} requires a concrete architectural or interaction-model delta; stylesheet and generic motion changes cannot satisfy it`);
+    if (plan.depth !== "restyle" && delta.materialChanges.length < 2)
+        lints.push(`${plan.depth} requires multiple concrete changes to composition, hierarchy, architecture, or interaction`);
+    const mobileText = [plan.mobileBlueprint.mobileOnlyComposition, plan.mobileBlueprint.composition390, plan.mobileBlueprint.fallback320, plan.mobileBlueprint.stackingRejection].join(" ");
+    if (/^\s*stack(?:ed)?(?:\s+vertically)?\s*$/i.test(plan.mobileBlueprint.mobileOnlyComposition) || !/\b(order|disclosure|navigation|task|action|media|thumb|viewport|recompose|context)\b/i.test(mobileText))
+        lints.push("mobile blueprint must define a mobile-native composition; ‘stack vertically’ alone is blocking");
+    if ((plan.tier === "expressive" || plan.tier === "award") && !plan.expression)
+        lints.push(`${plan.tier} requires a project-specific expression contract or a documented intentional-calm exception in the direct plan`);
+    if (plan.expression && /\b(fade|slide|scale|hover|gradient|large typography)\b/i.test(plan.expression.mechanism) && !/\b(state|selection|progress|navigation|transform|content|spatial)\b/i.test(plan.expression.communicates))
+        lints.push("expression mechanism is decorative-only and does not communicate content, state, progression, selection, navigation, or transformation");
+    return lints;
+}
 /** Build the compact, executable plan sent to the agent with design-page. */
 export function buildDesignPlan(page, brief, assignedSkills) {
     const dials = resolveDials(brief);
     const aesthetic = brief?.aesthetic || "auto (infer per DESIGN.md, then commit)";
     const allowedSkills = assignedSkills ? new Set(resolveSkillDependencies(assignedSkills)) : undefined;
-    const sections = (page.layout.children ?? []).map((s, i) => {
-        let family;
-        if (s.type === "nav")
-            family = "nav-single-line";
-        else if (s.type === "hero")
-            family = dials.variance > 4 ? "asymmetric-split-hero" : "centered-hero";
-        else if (s.type === "footer")
-            family = "footer";
-        else
-            family = FAMILIES[i % FAMILIES.length];
+    const sections = (page.layout.children ?? []).map((s) => {
         const detected = resolveSkillDependencies(detectSpecialistSkills(blockTexts(s)));
         const secSkills = allowedSkills ? detected.filter((skill) => allowedSkills.has(skill)) : detected;
-        return secSkills.length ? { id: s.id, label: s.label, family, skills: secSkills } : { id: s.id, label: s.label, family };
+        const role = s.type === "nav" ? "navigation" : s.type === "footer" ? "closure" : s.type === "form" ? "task-input" : s.type === "hero" ? "orientation-or-promotion" : "content-or-task-support";
+        return secSkills.length ? { id: s.id, label: s.label, role, skills: secSkills } : { id: s.id, label: s.label, role };
     });
     // page-level specialist skills: brief/prompt keywords + section hits + motion dial
     const requestedSkills = new Set([
@@ -138,6 +140,11 @@ export function buildDesignPlan(page, brief, assignedSkills) {
         aesthetic,
         texts: [brief?.vibe, brief?.notes, page.designPrompt, ...blockTexts(page.layout)],
     });
+    const depth = depthFor(brief, page);
+    const register = inferRegister(page);
+    const delta = structuralDelta(page, depth, register);
+    const mobile = mobileBlueprint(page, register);
+    const expression = expressionContract(page, tier, register);
     const spacing = dials.density <= 3 ? "py-24/py-32 section gaps" : dials.density <= 6 ? "py-16/py-20" : "py-8/py-12, hairline dividers, mono numerals";
     const motionBudget = dials.motion <= 3
         ? "hover/active states only, no scroll animation"
@@ -148,9 +155,12 @@ export function buildDesignPlan(page, brief, assignedSkills) {
         `aesthetic: ${aesthetic}; dials variance=${dials.variance} motion=${dials.motion} density=${dials.density}`,
         `spacing scale: ${spacing}`,
         `motion budget: ${motionBudget}`,
+        `transformation depth: ${depth}; source strategy: ${sourceStrategyFor(depth)}; ambition remains independently ${tier}`,
+        `page register: ${register}; compose for this page's task model rather than inheriting a shared marketing shell`,
         "choose the simplest mechanism that makes each intended transformation convincing; do not default blindly to fade/slide/scale or to WebGL/3D",
         "one accent color, one neutral family, one radius system, locked across ALL pages of this project",
-        "section layout families are assigned below — follow them, do not default to repeated card rows",
+        "section entries describe existing semantic roles only; author the proposed composition from the structural delta instead of cycling through layout families",
+        "preserve routes, handlers, data flow, fields, states, accessibility, analytics, required copy, and public APIs; do not preserve DOM hierarchy, card shells, section order, desktop composition, visual grouping, or motion by default",
         ...(dials.variance > 4 ? ["avoid centered-hero-over-gradient; use split or asymmetric composition"] : []),
         ...(skills.length
             ? [
@@ -159,17 +169,191 @@ export function buildDesignPlan(page, brief, assignedSkills) {
             : []),
     ];
     return {
-        version: 1,
+        version: 2,
         dials,
         aesthetic,
         tier,
+        depth,
+        sourceStrategy: sourceStrategyFor(depth),
+        register,
+        structuralDelta: delta,
+        mobileBlueprint: mobile,
+        ...(expression ? { expression } : {}),
         sections,
         directives,
-        lints: lintLayout(page.layout),
+        lints: [...lintLayout(page.layout), ...lintDesignPlan({ depth, structuralDelta: delta, mobileBlueprint: mobile, tier, expression })],
         skills,
         verification: TIER_REQUIREMENTS[tier],
     };
 }
+function depthFor(brief, page) {
+    if (brief?.transformationDepth)
+        return brief.transformationDepth;
+    const text = `${page.designPrompt ?? ""} ${brief?.notes ?? ""}`;
+    if (/\breimagine\b/i.test(text))
+        return "reimagine";
+    if (/\brestructure\b|\brebuild\b/i.test(text))
+        return "restructure";
+    if (/\brelayout\b|\brecompose\b/i.test(text))
+        return "relayout";
+    return "restyle";
+}
+export function sourceStrategyFor(depth) {
+    if (depth === "restyle")
+        return "patch";
+    if (depth === "relayout")
+        return "recompose";
+    return "rebuild-from-contracts";
+}
+export function buildDesignSourceContext(depth, generatedFile) {
+    const strategy = sourceStrategyFor(depth);
+    if (strategy === "patch") {
+        return { strategy, previousFile: generatedFile, compositionDirective: "Patch the existing composition while preserving its markup and interaction architecture." };
+    }
+    if (strategy === "recompose") {
+        return {
+            strategy,
+            behaviorReferenceFile: generatedFile,
+            compositionDirective: "Use the existing file for behavior and content inventory, but recompose ordering, hierarchy, and layout before styling.",
+        };
+    }
+    return {
+        strategy,
+        behaviorReferenceFile: generatedFile,
+        compositionDirective: "Create the blueprint independently from the previous visual tree. Read the reference only for routes, handlers, data flow, fields, states, accessibility, analytics, copy, and public APIs; rebuild markup and component boundaries from the approved contracts.",
+    };
+}
+function inferRegister(page) {
+    const text = [page.name, page.designPrompt, ...blockTexts(page.layout)].join(" ").toLowerCase();
+    if (/\b(login|sign in|sign up|password|authentication)\b/.test(text))
+        return "authentication";
+    if (/\b(admin|moderation|manage users|cms)\b/.test(text))
+        return "administration";
+    if (/\b(account|profile|order status|billing|settings)\b/.test(text))
+        return "account-status";
+    if (/\b(search|select|checkout|order|booking|form|continue|payment|outlet)\b/.test(text))
+        return "task-transaction";
+    if (/\b(error|empty|loading|not found)\b/.test(text))
+        return "system-state";
+    if (/\b(dashboard|table|analytics|report|data)\b/.test(text))
+        return "data-dense-utility";
+    if (/\b(catalog|browse|collection|discover|filter)\b/.test(text))
+        return "discovery-browse";
+    return "marketing-storytelling";
+}
+function describeExisting(page) {
+    const sections = (page.layout.children ?? []).map((section) => section.label).filter(Boolean);
+    return sections.length ? sections.join(" followed by ") : page.layout.label;
+}
+function taskFor(page) {
+    const form = (page.layout.children ?? []).find((section) => section.type === "form");
+    const action = blockTexts(page.layout).find((text) => /\b(select|continue|submit|search|choose|buy|book|save|sign in)\b/i.test(text));
+    return action ?? form?.label ?? `complete ${page.name}`;
+}
+function structuralDelta(page, depth, register) {
+    const existing = describeExisting(page);
+    const task = taskFor(page);
+    if (depth === "restyle") {
+        return {
+            existingModel: existing,
+            proposedModel: `${existing}, retained intentionally with a newly authored visual and state language`,
+            existingParadigm: "Existing DOM order, component boundaries, and interaction flow",
+            proposedParadigm: "The same interaction architecture with a coherent visual, type, surface, and authored-state treatment",
+            materialChanges: ["Restyle tokens, typography, surfaces, responsive polish, and state presentation without claiming structural transformation"],
+            survivingBoundaries: (page.layout.children ?? []).map((section) => section.label),
+            rebuiltBoundaries: [],
+            preservedContracts: ["Routes, handlers, data flow, field names, states, accessibility, analytics, copy, and public APIs"],
+            retainedPatterns: [{ pattern: "Existing section and task order", rationale: "Restyle explicitly permits structural continuity." }],
+            forbiddenCarryovers: ["Unexamined accessibility defects", "Decorative motion presented as structural change"],
+            depthHonesty: "This is a restyle: structure is retained and the plan makes no relayout, restructure, or reimagine claim.",
+        };
+    }
+    const proposedModel = register === "task-transaction"
+        ? `A task-first ${page.name} workspace organized around “${task}”, with supporting context revealed at the point of decision`
+        : depth === "reimagine"
+            ? `A new ${page.name} experience model organized around its ${register.replaceAll("-", " ")} purpose rather than the inherited section sequence`
+            : `A recomposed ${page.name} hierarchy organized by user intent rather than the inherited ${existing}`;
+    const deep = depth === "restructure" || depth === "reimagine";
+    return {
+        existingModel: existing,
+        proposedModel,
+        existingParadigm: `Linear inherited composition: ${existing}`,
+        proposedParadigm: register === "task-transaction" ? "Task-first contextual workspace with action and decision state in one flow" : "Intent-led page composition with page-specific hierarchy",
+        materialChanges: deep
+            ? [
+                `Rebuild the page architecture around “${task}” instead of preserving the inherited section tree`,
+                "Move supporting or promotional content after the primary task unless it is required for the decision",
+                "Reconcile preserved behavior only after the new component boundaries exist",
+            ]
+            : ["Change section order and hierarchy", "Replace the inherited layout family with an intent-led composition", "Translate desktop grouping deliberately for mobile"],
+        survivingBoundaries: ["Behavior, data, route, and accessibility contracts"],
+        rebuiltBoundaries: deep ? (page.layout.children ?? []).filter((section) => !["nav", "footer"].includes(section.type)).map((section) => section.label) : ["Page composition boundary"],
+        preservedContracts: ["Routes, handlers, data flow, field names, states, accessibility, analytics, required copy, and public APIs"],
+        retainedPatterns: [{ pattern: "Semantic task controls", rationale: "Their behavior is contractual even when their visual grouping and DOM position change." }],
+        forbiddenCarryovers: ["Inherited DOM hierarchy as the composition source", "Card shells and section order without page-specific rationale", "Desktop grouping copied directly to mobile"],
+        depthHonesty: deep
+            ? `${depth} changes page architecture and component boundaries; token, font, color, radius, shadow, and entrance-animation changes cannot satisfy it.`
+            : "Relayout changes ordering, hierarchy, and layout family while preserving the underlying workflow and most component responsibilities.",
+    };
+}
+function mobileBlueprint(page, register) {
+    const task = taskFor(page);
+    const taskFirst = register === "task-transaction" || register === "authentication" || register === "data-dense-utility";
+    return {
+        primaryTask: task,
+        firstViewportPurpose: taskFirst ? `Let the user begin “${task}” immediately, before promotional or decorative material` : `Establish the ${page.name} purpose and expose its primary next action`,
+        contentOrder: taskFirst ? ["compact navigation/context", `controls and information required to ${task}`, "current state or result", "supporting explanation", "promotional or decorative material"] : ["identity and purpose", "primary action or navigation", "core content", "supporting content"],
+        beforeFirstScroll: ["Page identity", `The control or information needed to ${task}`, "Primary action or current selection state"],
+        primaryThumbAction: { action: task, placement: "Within the lower-thumb reach zone; sticky only when it does not cover content or duplicate navigation" },
+        stickyElements: ["Only task-critical action or compact navigation; never duplicate the same CTA"],
+        safeArea: "Inset fixed controls with env(safe-area-inset-bottom) and reserve matching content padding",
+        navigationModel: "Compact mobile navigation appropriate to this page register, with no duplicate desktop navigation row",
+        mobileOnlyComposition: taskFirst ? "Collapse supporting context into contextual disclosure while keeping task controls and state in one continuous decision surface" : "Use mobile pacing and disclosure designed around reading and thumb reach, not desktop columns",
+        desktopTranslation: { retained: ["Required functionality and semantic content"], translated: ["Spatial grouping, navigation, media, and state transitions"], removed: ["Nonessential decorative blockers before the task"], replaced: ["Hover-only affordances with visible tap/focus controls"] },
+        mediaStrategy: "Use task-supporting media at mobile scale; defer or remove decorative media that delays the primary task",
+        motionStrategy: "Translate authored state changes to short, interruptible mobile transitions; preserve visible defaults and reduced motion",
+        keyboardAndForms: "Keep focused fields and the primary action visible above the software keyboard; use appropriate input modes and no focus traps",
+        composition390: `At 390×844, ${taskFirst ? "the task begins in the first viewport and its action remains reachable" : "identity, purpose, and primary navigation form a complete first viewport"}`,
+        fallback320: "At 320px, remove nonessential decoration, allow labels to wrap, keep controls within the viewport, and avoid fixed minimum typography or widths",
+        stackingRejection: "The mobile content order, disclosure, navigation, task action, and media treatment are explicitly recomposed; desktop columns are not merely stacked.",
+        verificationChecks: [
+            "no-horizontal-overflow", "no-clipped-content", "fixed-elements-clear-content", "safe-area-spacing",
+            "primary-task-discoverable", "primary-action-reachable", "touch-targets", "software-keyboard-usable",
+            "no-hover-only", "intentional-mobile-composition", "mobile-content-order", "motion-media-translated",
+            "no-decorative-task-blocker",
+        ],
+    };
+}
+function expressionContract(page, tier, register) {
+    if (tier !== "expressive" && tier !== "award")
+        return undefined;
+    const task = taskFor(page);
+    return {
+        mechanism: register === "task-transaction" ? `The user’s current “${task}” selection becomes the persistent context for the next task state` : `${page.name} navigation changes form to reflect the user’s current content or progression state`,
+        communicates: register === "task-transaction" ? "Selection, operational state, and readiness to continue" : "Position, progression, and relationship between content states",
+        projectFit: `The behavior is derived from ${page.name} and its ${register.replaceAll("-", " ")} role, rather than a reusable reveal effect.`,
+        location: `The primary ${page.name} task and its transition to the next meaningful state`,
+        mobileTranslation: "Keep the state-carrying behavior, shorten travel, and place feedback beside the thumb action",
+        reducedMotion: "Render the communicated state directly with a short cross-state update and no spatial travel",
+        fallback: "Semantic state text and conventional navigation preserve the complete task without animation",
+        verification: "Verify that content or application state—not only opacity, translate, scale, color, or decoration—changes and remains understandable on mobile and reduced motion",
+    };
+}
+export function buildRuntimeCoherence(pages, brief) {
+    return {
+        globalVisualLanguage: "Share tokens, type roles, material logic, and state markers without sharing one page composition.",
+        globalInteractionLanguage: "Use consistent control feedback and continuity; let each page register define navigation, density, and task flow.",
+        pages: pages.map((page) => {
+            const register = inferRegister(page);
+            return { pageId: page.id, name: page.name, register, primaryTask: taskFor(page) };
+        }),
+        prohibitedRepeatedShells: [
+            "Oversized headline plus decorative image panel plus rounded card container on unrelated routes",
+            "The same layout family assigned by page or section array position",
+            "Pages differing only by headline, color, and image",
+        ],
+    };
+}
 /** Build page plans from a user-approved pool. Unselected optional skills are
  * suggestions only; explicit page assignments win. */
 export function buildMultiPageDesignPlans(pages, brief, selection) {
@@ -182,6 +366,7 @@ export function buildMultiPageDesignPlans(pages, brief, selection) {
     });
     return {
         routing,
+        coherence: buildRuntimeCoherence(pages, brief),
         pages: pages.map((page) => ({ pageId: page.id, plan: buildDesignPlan(page, brief, routing.byPage[page.id]) })),
     };
 }

package/dist/shared/design.test.js

@@ -0,0 +1,70 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildDesignPlan, buildDesignSourceContext, buildRuntimeCoherence, lintDesignPlan } from "./design.js";
+function transactionalPage() {
+    const section = (id, type, label, children = []) => ({ id, type, label, direction: "column", children });
+    return {
+        id: "outlet-selection",
+        name: "Choose an outlet",
+        status: "designed",
+        canvasPos: { x: 0, y: 0 },
+        generatedFile: "generated/outlet-selection.tsx",
+        layout: section("root", "column", "Outlet selection page", [
+            section("header", "nav", "Standard header"),
+            section("intro", "hero", "Promotional chicken-rice introduction"),
+            section("search", "form", "Search outlets", [{ id: "search-button", type: "button", label: "Search nearby outlets", text: "Search" }]),
+            section("cards", "card-grid", "Repeated outlet cards"),
+            section("continue", "section", "Continuation action", [{ id: "continue-button", type: "button", label: "Continue with selected outlet", text: "Continue" }]),
+        ]),
+    };
+}
+function plan(brief) {
+    return buildDesignPlan(transactionalPage(), brief);
+}
+test("case A: restyle + expressive retains structure without claiming transformation", () => {
+    const result = plan({ transformationDepth: "restyle", variance: 8, motion: 8 });
+    assert.equal(result.depth, "restyle");
+    assert.equal(result.tier, "expressive");
+    assert.equal(result.sourceStrategy, "patch");
+    assert.equal(result.structuralDelta.rebuiltBoundaries.length, 0);
+    assert.match(result.structuralDelta.depthHonesty, /restyle/i);
+});
+test("case B: restructure + solid produces a task-specific architecture", () => {
+    const result = plan({ transformationDepth: "restructure", aesthetic: "trust", variance: 3, motion: 2 });
+    assert.equal(result.tier, "solid");
+    assert.equal(result.depth, "restructure");
+    assert.equal(result.register, "task-transaction");
+    assert.match(result.structuralDelta.proposedModel, /task-first.*workspace/i);
+    assert.ok(result.structuralDelta.materialChanges.length >= 3);
+    assert.equal(lintDesignPlan(result).length, 0);
+});
+test("case C: restructure + expressive carries structural, expression, mobile, preservation, and verification directives", () => {
+    const result = plan({ transformationDepth: "restructure", variance: 8, motion: 8 });
+    assert.equal(result.sourceStrategy, "rebuild-from-contracts");
+    assert.ok(result.expression);
+    assert.match(result.expression.mechanism, /selection.*persistent context/i);
+    assert.match(result.mobileBlueprint.firstViewportPurpose, /immediately.*before promotional/i);
+    assert.match(result.structuralDelta.preservedContracts.join(" "), /routes.*handlers.*data flow/i);
+    assert.ok(result.verification.length > 0);
+});
+test("case D: stack-only mobile plan is blocking", () => {
+    const result = plan({ transformationDepth: "restructure", variance: 3, motion: 2 });
+    result.mobileBlueprint.mobileOnlyComposition = "stack vertically";
+    assert.ok(lintDesignPlan(result).some((message) => message.includes("mobile-native")));
+});
+test("case E: deep redesign treats previous file as behavior reference, never composition source", () => {
+    const deep = buildDesignSourceContext("restructure", "generated/outlet-selection.tsx");
+    assert.equal(deep.strategy, "rebuild-from-contracts");
+    assert.equal(deep.previousFile, undefined);
+    assert.equal(deep.behaviorReferenceFile, "generated/outlet-selection.tsx");
+    assert.match(deep.compositionDirective, /independently from the previous visual tree/i);
+    const light = buildDesignSourceContext("restyle", "generated/outlet-selection.tsx");
+    assert.equal(light.previousFile, "generated/outlet-selection.tsx");
+});
+test("multi-page coherence records page registers without assigning a repeated shell", () => {
+    const outlet = transactionalPage();
+    const account = { ...transactionalPage(), id: "account", name: "Account status", designPrompt: "Profile and billing settings" };
+    const coherence = buildRuntimeCoherence([outlet, account], { transformationDepth: "restructure" });
+    assert.deepEqual(coherence.pages.map((item) => item.register), ["task-transaction", "account-status"]);
+    assert.ok(coherence.prohibitedRepeatedShells.some((item) => item.includes("unrelated routes")));
+});

package/dist/shared/ruleSystem.js

@@ -16,7 +16,7 @@ function genericMotionOnly(value) {
     return basic.test(text) && !structural.test(text);
 }
 export function validateRuleControls(plan, registry, reflexFonts, verification) {
-    if (plan.doctrineVersion !== 2)
+    if (plan.doctrineVersion !== 2 && plan.doctrineVersion !== 3)
         return [];
     const errors = [];
     const rules = new Map(registry.rules.map((rule) => [rule.id, rule]));