dreative 0.5.1 → 0.5.2

package/skill/dreative/skills/ux.md

@@ -1,144 +1,155 @@
-# Dreative Specialist Skill — Functional UX (everything works)
-
-Load this file when `plan.skills` includes `ux`, for ANY product-register page,
-and whenever a redesign touches navigation, forms, or stateful views. It EXTENDS
-DESIGN.md §9 (the product floor) into a full working-page contract. Its premise:
-a beautiful page where the menu doesn't open, a link 404s, or an effect eats
-clicks is a FAILED page — visual craft cannot compensate for broken function.
-This skill is the reason "immersive but broken" never ships: it defines what
-"works" means, mechanically, and the runtime verification pass (SKILL.md) tests
-against it.
-
-## 0. The working-page contract
-
-Every page you ship satisfies, verifiably:
-
-1. Every visible control does something real (or is explicitly disabled with a
-   reason). No dead buttons, no `href="#"`, no `onClick={() => {}}`.
-2. Every navigation target resolves — internal routes exist, anchors match real
-   ids, external links open safely (`rel="noopener"`, `target="_blank"` only
-   for true externals).
-3. Every stateful view renders all its states (loading/empty/error/success),
-   not just the happy path.
-4. Keyboard alone can operate everything a pointer can.
-5. Nothing decorative intercepts input, blocks scroll, or steals focus.
-
-## 1. Navigation
-
-- **Links resolve.** Before shipping, list every `href`/`to`/`navigate` target
-  and check each exists (route table, file, or real URL). A designed 404 is
-  still a 404.
-- **Active state**: the nav marks the current page/section (aria-current +
-  visual). Section-scroll pages update it via IntersectionObserver.
-- **Mobile menu is a component, not a hope**: opens AND closes (button, Esc,
-  backdrop click, and on route change); scroll-locks the body while open
-  (`overflow:hidden` on html, restore on close — with scrollbar-gutter
-  compensation so the page doesn't shift); traps focus while open and returns
-  focus to the trigger on close; the toggle reflects state
-  (`aria-expanded`, icon morph). Test the open→navigate→back sequence — stale
-  open menus after route changes are the #1 shipped-menu bug.
-- **Anchors under fixed headers**: every in-page anchor target gets
-  `scroll-margin-top` ≥ header height; smooth-scroll respects reduced-motion.
-- **Logo → home. Back button works** — spatial/SPA transitions must not break
-  history (immersive.md §1); modals and drawers close on back where users
-  expect it (mobile especially).
-- **Custom scroll (Lenis)** must not break anchors, keyboard scrolling
-  (space/PgDn/arrows), or focus-into-view; wire `lenis.scrollTo` for anchor
-  clicks and leave native behavior for the rest.
-
-## 2. Forms
-
-- Every form submits somewhere real, or is explicitly wired to a stub with a
-  visible success simulation — never a button that swallows the click.
-- Labels above inputs (placeholder-as-label banned, DESIGN.md §9);
-  autocomplete attributes on identity fields; correct `type`/`inputmode`
-  (email, tel, numeric) so mobile keyboards match.
-- Validate on submit first (not on first keystroke); after first submit,
-  re-validate per field on blur/change. Errors inline, next to the field,
-  specific ("Enter a valid email"), with `aria-describedby` wiring and focus
-  moved to the first invalid field.
-- Submit feedback: button enters loading state (spinner inside, fixed width,
-  interaction.md §5), double-submit prevented, success confirmed visibly
-  (inline message or state change — not just a toast that may be missed),
-  failure recoverable (inputs keep their values; never wipe a form on error).
-- Enter submits single-field forms (newsletter). Required fields marked; the
-  disabled-until-valid pattern only when errors show on hover/focus of the
-  disabled button, otherwise keep the button enabled and validate on click.
-
-## 3. State coverage (every data view)
-
-For each list/table/feed/detail view, all four states are designed and
-reachable: **loading** (skeleton shaped like the content, DESIGN.md §9),
-**empty** (teaches the interface: what this will show + the action that fills
-it — never a blank area or a lonely "No data"), **error** (what happened + a
-retry affordance), **populated** (including the long-content case: 100 items,
-40-character names, overflow handled per DESIGN.md §15). Async actions get
-optimistic UI only when low-stakes (DESIGN.md §6); destructive actions get
-confirmation and, ideally, undo instead of a scary modal.
-
-## 4. Keyboard, focus, and the hit-area audit
-
-- Full tab walk: every interactive element reachable in visual order, operable
-  (Enter/Space), with a visible `:focus-visible` ring (interaction.md §0), and
-  escapable (no traps outside intentional modal traps).
-- Whatever hover reveals, focus reveals (cards' secondary actions, hover-woken
-  media, dropdown menus). Custom gestures (drag, click-and-hold) always have a
-  plain keyboard/click equivalent (cinematic.md §2).
-- **The pointer-events audit** (the #1 cause of "cool but broken"): walk every
-  overlay in the stacking order — canvases, gradient/grain layers, custom
-  cursor layers, transition curtains, closed menus, preloaders — and verify
-  each is `pointer-events: none` (or removed from the DOM) whenever it is not
-  actively being interacted with. A finished preloader or a closed fullscreen
-  menu sitting at `opacity:0` with pointer-events on is an invisible wall over
-  the whole page. Then hit-test the controls: click every button/link at its
-  visual position — if something above it swallows the click, that's a §15
-  spatial-integrity fail, fix the layer not the button.
-- Modals/drawers: focus trapped inside, Esc closes, focus returns to trigger,
-  `aria-modal` + labelled; scrim click closes (unless data-loss risk).
-- Semantic HTML first: real `<button>`/`<a>`/`<nav>`/`<main>`/headings in
-  order — divs-with-onClick fail half this section automatically.
-
-## 5. Scroll and layout stability
-
-- Zero layout shift from async content: media boxes sized up front (media.md
-  §5), fonts `swap` with metric-compatible fallbacks, skeletons the same size
-  as what replaces them, no banners that push content after load.
-- Scroll restoration: back/forward returns to the previous position (default
-  browser behavior — don't break it with manual scroll-to-top on every route;
-  scroll to top only on forward navigation to a NEW page).
-- Fixed bars: content padded so nothing hides beneath them (DESIGN.md §15);
-  100dvh not 100vh; no horizontal body scroll at 320px.
-- Long pages get orientation aids: sticky nav or progress indication, and a
-  footer that actually ends the page (no infinite-feeling voids).
-
-## 6. Feedback and perceived performance
-
-- Every async action acknowledges input within 100ms (pressed state, spinner,
-  optimistic change) — silence after a click reads as broken even when it
-  works.
-- Toasts only for transient global events; they stack in ONE corner slot
-  (DESIGN.md §15), auto-dismiss ≥ 4s, pause on hover, and are `aria-live`.
-- Destructive/irreversible actions: confirm with specifics ("Delete 3 items?"),
-  never bare "Are you sure?"; prefer undo-toast over confirm-modal when safe.
-- Copy per DESIGN.md §8's UX-writing rules: buttons say what they do, errors
-  say what to do next.
-
-## 7. The functional audit (run at verification time)
-
-This is the checklist the runtime verification pass (SKILL.md) executes with
-browser tools — or walks mentally, file by file, when no browser exists:
-
-1. Click every nav link + the logo; confirm each lands where labeled.
-2. Open and close the mobile menu (both directions, plus Esc, plus navigate-
-   while-open) at 390px width.
-3. Submit each form empty → see inline errors; submit valid → see success
-   state; confirm no double-submit.
-4. Tab through the page start to finish; note any unreachable/invisible-focus/
-   trapped stop.
-5. Hit-test 5+ controls in effect-heavy regions (hero, canvas overlays,
-   floating elements) — every click must land.
-6. Trigger each data view's empty/error state if reachable (or verify the
-   branch exists in code).
-7. Console: zero uncaught errors during all of the above.
-
-Report the result as a pass/fail list, fix fails, re-run the failed items once.
+# Dreative Specialist Skill — Functional UX (everything works)
+
+## Contract
+
+Universal foundation: ux and baseline mobile apply to every web page.
+
+Follow `../references/SKILL_CONTRACT.md`. This universal foundation has no
+specialist dependency; pair it with `mobile` for all web delivery. Deliver the
+preservation manifest, state inventory, semantic/keyboard behavior, feedback,
+and functional audit evidence. It may never be deselected to fund visual work.
+Done means routes, controls, forms, states, focus, hit areas, and failure paths
+work without visual effects.
+
+Load this file when `plan.skills` includes `ux`, for ANY product-register page,
+and whenever a redesign touches navigation, forms, or stateful views. It EXTENDS
+DESIGN.md §9 (the product floor) into a full working-page contract. Its premise:
+a beautiful page where the menu doesn't open, a link 404s, or an effect eats
+clicks is a FAILED page — visual craft cannot compensate for broken function.
+This skill is the reason "immersive but broken" never ships: it defines what
+"works" means, mechanically, and the runtime verification pass (SKILL.md) tests
+against it.
+
+## 0. The working-page contract
+
+Every page you ship satisfies, verifiably:
+
+1. Every visible control does something real (or is explicitly disabled with a
+   reason). No dead buttons, no `href="#"`, no `onClick={() => {}}`.
+2. Every navigation target resolves — internal routes exist, anchors match real
+   ids, external links open safely (`rel="noopener"`, `target="_blank"` only
+   for true externals).
+3. Every stateful view renders all its states (loading/empty/error/success),
+   not just the happy path.
+4. Keyboard alone can operate everything a pointer can.
+5. Nothing decorative intercepts input, blocks scroll, or steals focus.
+
+## 1. Navigation
+
+- **Links resolve.** Before shipping, list every `href`/`to`/`navigate` target
+  and check each exists (route table, file, or real URL). A designed 404 is
+  still a 404.
+- **Active state**: the nav marks the current page/section (aria-current +
+  visual). Section-scroll pages update it via IntersectionObserver.
+- **Mobile menu is a component, not a hope**: opens AND closes (button, Esc,
+  backdrop click, and on route change); scroll-locks the body while open
+  (`overflow:hidden` on html, restore on close — with scrollbar-gutter
+  compensation so the page doesn't shift); traps focus while open and returns
+  focus to the trigger on close; the toggle reflects state
+  (`aria-expanded`, icon morph). Test the open→navigate→back sequence — stale
+  open menus after route changes are the #1 shipped-menu bug.
+- **Anchors under fixed headers**: every in-page anchor target gets
+  `scroll-margin-top` ≥ header height; smooth-scroll respects reduced-motion.
+- **Logo → home. Back button works** — spatial/SPA transitions must not break
+  history (immersive.md §2); modals and drawers close on back where users
+  expect it (mobile especially).
+- **Custom scroll (Lenis)** must not break anchors, keyboard scrolling
+  (space/PgDn/arrows), or focus-into-view; wire `lenis.scrollTo` for anchor
+  clicks and leave native behavior for the rest.
+
+## 2. Forms
+
+- Every form submits somewhere real, or is explicitly wired to a stub with a
+  visible success simulation — never a button that swallows the click.
+- Labels above inputs (placeholder-as-label banned, DESIGN.md §9);
+  autocomplete attributes on identity fields; correct `type`/`inputmode`
+  (email, tel, numeric) so mobile keyboards match.
+- Validate on submit first (not on first keystroke); after first submit,
+  re-validate per field on blur/change. Errors inline, next to the field,
+  specific ("Enter a valid email"), with `aria-describedby` wiring and focus
+  moved to the first invalid field.
+- Submit feedback: button enters loading state (spinner inside, fixed width,
+  interaction.md §5), double-submit prevented, success confirmed visibly
+  (inline message or state change — not just a toast that may be missed),
+  failure recoverable (inputs keep their values; never wipe a form on error).
+- Enter submits single-field forms (newsletter). Required fields marked; the
+  disabled-until-valid pattern only when errors show on hover/focus of the
+  disabled button, otherwise keep the button enabled and validate on click.
+
+## 3. State coverage (every data view)
+
+For each list/table/feed/detail view, all four states are designed and
+reachable: **loading** (skeleton shaped like the content, DESIGN.md §9),
+**empty** (teaches the interface: what this will show + the action that fills
+it — never a blank area or a lonely "No data"), **error** (what happened + a
+retry affordance), **populated** (including the long-content case: 100 items,
+40-character names, overflow handled per DESIGN.md §15). Async actions get
+optimistic UI only when low-stakes (DESIGN.md §6); destructive actions get
+confirmation and, ideally, undo instead of a scary modal.
+
+## 4. Keyboard, focus, and the hit-area audit
+
+- Full tab walk: every interactive element reachable in visual order, operable
+  (Enter/Space), with a visible `:focus-visible` ring (interaction.md §0), and
+  escapable (no traps outside intentional modal traps).
+- Whatever hover reveals, focus reveals (cards' secondary actions, hover-woken
+  media, dropdown menus). Custom gestures (drag, click-and-hold) always have a
+  plain keyboard/click equivalent (cinematic.md §3).
+- **The pointer-events audit** (the #1 cause of "cool but broken"): walk every
+  overlay in the stacking order — canvases, gradient/grain layers, custom
+  cursor layers, transition curtains, closed menus, preloaders — and verify
+  each is `pointer-events: none` (or removed from the DOM) whenever it is not
+  actively being interacted with. A finished preloader or a closed fullscreen
+  menu sitting at `opacity:0` with pointer-events on is an invisible wall over
+  the whole page. Then hit-test the controls: click every button/link at its
+  visual position — if something above it swallows the click, that's a §15
+  spatial-integrity fail, fix the layer not the button.
+- Modals/drawers: focus trapped inside, Esc closes, focus returns to trigger,
+  `aria-modal` + labelled; scrim click closes (unless data-loss risk).
+- Semantic HTML first: real `<button>`/`<a>`/`<nav>`/`<main>`/headings in
+  order — divs-with-onClick fail half this section automatically.
+
+## 5. Scroll and layout stability
+
+- Zero layout shift from async content: media boxes sized up front (media.md
+  §5), fonts `swap` with metric-compatible fallbacks, skeletons the same size
+  as what replaces them, no banners that push content after load.
+- Scroll restoration: back/forward returns to the previous position (default
+  browser behavior — don't break it with manual scroll-to-top on every route;
+  scroll to top only on forward navigation to a NEW page).
+- Fixed bars: content padded so nothing hides beneath them (DESIGN.md §15);
+  100dvh not 100vh; no horizontal body scroll at 320px.
+- Long pages get orientation aids: sticky nav or progress indication, and a
+  footer that actually ends the page (no infinite-feeling voids).
+
+## 6. Feedback and perceived performance
+
+- Every async action acknowledges input within 100ms (pressed state, spinner,
+  optimistic change) — silence after a click reads as broken even when it
+  works.
+- Toasts only for transient global events; they stack in ONE corner slot
+  (DESIGN.md §15), auto-dismiss ≥ 4s, pause on hover, and are `aria-live`.
+- Destructive/irreversible actions: confirm with specifics ("Delete 3 items?"),
+  never bare "Are you sure?"; prefer undo-toast over confirm-modal when safe.
+- Copy per DESIGN.md §8's UX-writing rules: buttons say what they do, errors
+  say what to do next.
+
+## 7. The functional audit (run at verification time)
+
+This is the checklist the runtime verification pass (SKILL.md) executes with
+browser tools — or walks mentally, file by file, when no browser exists:
+
+1. Click every nav link + the logo; confirm each lands where labeled.
+2. Open and close the mobile menu (both directions, plus Esc, plus navigate-
+   while-open) at 390px width.
+3. Submit each form empty → see inline errors; submit valid → see success
+   state; confirm no double-submit.
+4. Tab through the page start to finish; note any unreachable/invisible-focus/
+   trapped stop.
+5. Hit-test 5+ controls in effect-heavy regions (hero, canvas overlays,
+   floating elements) — every click must land.
+6. Trigger each data view's empty/error state if reachable (or verify the
+   branch exists in code).
+7. Console: zero uncaught errors during all of the above.
+
+Report the result as a pass/fail list, fix fails, re-run the failed items once.

package/dist/server/ai.js

@@ -1,177 +0,0 @@
-import { query } from "@anthropic-ai/claude-agent-sdk";
-const BLOCK_SCHEMA = `
-A block is a JSON object:
-{
-  "id": "string (short unique id)",
-  "type": "section|row|column|nav|hero|card-grid|list|form|footer|text|image|button",
-  "label": "short human label, e.g. 'Hero', 'Pricing cards'",
-  "direction": "row" | "column" (optional, layout of children),
-  "sizeHint": "sm" | "md" | "lg" (optional, relative vertical size),
-  "intents": ["optional behavior notes, e.g. 'CTA scrolls to pricing'"],
-  "children": [ ...nested blocks ] (optional)
-}
-Keep trees shallow (max depth 3) and wireframe-level: structure, not styling.`;
-/** Run an Agent SDK query and return the final result text, reporting progress. */
-async function run(prompt, opts = {}) {
-    let result = "";
-    const q = query({
-        prompt,
-        options: {
-            allowedTools: opts.allowRead ? ["Read"] : [],
-            permissionMode: "bypassPermissions",
-            maxTurns: opts.allowRead ? 6 : 2,
-        },
-    });
-    for await (const message of q) {
-        if (message.type === "assistant") {
-            const blocks = message.message?.content ?? [];
-            for (const b of blocks) {
-                if (b.type === "tool_use")
-                    opts.progress?.("Looking at the reference image...");
-                else if (b.type === "text")
-                    opts.progress?.("Writing...");
-            }
-        }
-        else if (message.type === "result") {
-            if (message.subtype === "success")
-                result = message.result;
-            else
-                throw new Error(`AI call failed: ${message.subtype}`);
-        }
-    }
-    if (!result)
-        throw new Error("AI call returned no result");
-    return result;
-}
-/** Run + parse, with one retry that feeds the failure back to the model. */
-async function runParsed(prompt, parse, opts = {}) {
-    const text = await run(prompt, opts);
-    try {
-        return parse(text);
-    }
-    catch (err) {
-        opts.progress?.("Output was malformed - retrying...");
-        const retryText = await run(`${prompt}\n\nIMPORTANT: Your previous response could not be parsed (${String(err)}). Respond again, strictly following the output format instructions.`, opts);
-        return parse(retryText);
-    }
-}
-/** Extract the first JSON value (object or array) from model output. */
-function extractJson(text) {
-    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
-    const candidate = fenced ? fenced[1] : text;
-    const start = candidate.search(/[[{]/);
-    if (start === -1)
-        throw new Error("No JSON found in AI response");
-    for (let end = candidate.length; end > start; end--) {
-        const ch = candidate[end - 1];
-        if (ch !== "}" && ch !== "]")
-            continue;
-        try {
-            return JSON.parse(candidate.slice(start, end));
-        }
-        catch {
-            /* keep scanning */
-        }
-    }
-    throw new Error("Could not parse JSON from AI response");
-}
-function extractCode(text) {
-    const fence = text.match(/```(?:tsx|jsx|typescript|ts)?\s*([\s\S]*?)```/);
-    const code = fence ? fence[1].trim() : text.trim();
-    if (!code.includes("export default"))
-        throw new Error("Generated code has no default export");
-    return code;
-}
-export async function proposeSkeletons(userPrompt, progress) {
-    progress?.("Proposing page layouts...");
-    return runParsed(`You are a UX/information-architecture expert. Propose 3 distinct page layout skeletons (wireframe-level) for this request:
-
-"${userPrompt}"
-
-${BLOCK_SCHEMA}
-
-Respond with ONLY a JSON array of 3 items, each: {"name": "page variant name", "layout": <block tree with root type "section">}. No prose.`, (t) => extractJson(t), { progress });
-}
-export async function proposeVariants(pageName, layout, progress) {
-    progress?.(`Proposing variants of "${pageName}"...`);
-    return runParsed(`You are a UX expert. Here is the current wireframe skeleton for the page "${pageName}":
-
-${JSON.stringify(layout, null, 2)}
-
-Propose 2 meaningfully different alternative layouts for the SAME content and purpose (e.g. different section order, grid vs list, split vs stacked). Preserve all "intents" values, attached to the equivalent blocks. Use fresh ids.
-
-${BLOCK_SCHEMA}
-
-Respond with ONLY a JSON array of 2 items: {"name": "<pageName> - <variant descriptor>", "layout": <block tree>}. No prose.`, (t) => extractJson(t), { progress });
-}
-export async function editBlock(block, instruction, progress) {
-    progress?.("Editing block...");
-    return runParsed(`You are editing one block of a page wireframe. Current block subtree:
-
-${JSON.stringify(block, null, 2)}
-
-User instruction: "${instruction}"
-
-${BLOCK_SCHEMA}
-
-Apply the instruction. Structural changes go into the tree; behavior/functionality changes go into "intents" arrays on the relevant blocks. If the instruction replaces an existing behavior, replace the corresponding intent instead of appending. Keep existing ids where blocks are unchanged; give new blocks new ids.
-Respond with ONLY the updated block subtree as JSON. No prose.`, (t) => extractJson(t), { progress });
-}
-export async function designPage(args) {
-    const { progress } = args;
-    progress?.("Designing page...");
-    const refPart = args.refImagePath
-        ? `First, use the Read tool to view the reference image at: ${args.refImagePath}\nMatch its visual style (colors, typography feel, spacing, mood) closely.`
-        : "No page-level reference image provided; choose a distinctive, non-generic visual style appropriate to the content.";
-    const blockRefPart = args.blockRefs?.length
-        ? `These specific blocks have their own style reference images. Use the Read tool to view each, and match that image's style for that block specifically (it overrides the page-level style for that block):\n${args.blockRefs
-            .map((r) => `- block "${r.id}" (${r.label}): ${r.path}`)
-            .join("\n")}`
-        : "";
-    const previousPart = args.previousCode
-        ? `A previous version of this page exists below. The user may have made deliberate element-level edits to it. Where a block from the skeleton already exists in the previous version, PRESERVE its styling and content choices; only restructure/add/remove what the updated skeleton requires.
-
-Previous version:
-\`\`\`tsx
-${args.previousCode}
-\`\`\`
-`
-        : "";
-    const siblingPart = args.siblingPages?.length
-        ? `Other pages in this project (use these names for nav/footer links, href="#"): ${args.siblingPages.join(", ")}.`
-        : "";
-    return runParsed(`${refPart}
-${blockRefPart}
-
-Then generate a complete React component for the page "${args.pageName}" implementing this wireframe skeleton exactly (same structure and order of blocks):
-
-${JSON.stringify(args.layout, null, 2)}
-
-${previousPart}
-Every "intents" entry describes required behavior - implement it with React state/handlers (mock data is fine, no network calls).
-${args.designPrompt ? `Additional design direction: "${args.designPrompt}"` : ""}
-${siblingPart}
-
-Requirements:
-- Single self-contained .tsx file, default-exporting the page component.
-- Import only from "react". Style with Tailwind CSS utility classes (Tailwind is available globally).
-- Put data-dreative-id="<block id>" on the top-level element rendered for each block from the skeleton.
-- Realistic placeholder copy, no lorem ipsum. For images use https://picsum.photos placeholders or CSS.
-
-Respond with ONLY the .tsx source in a single \`\`\`tsx code fence. No prose.`, extractCode, { allowRead: !!args.refImagePath || !!args.blockRefs?.length, progress });
-}
-export async function editDesignedElement(args) {
-    args.progress?.("Editing element...");
-    const refPart = args.refImagePath
-        ? `First, use the Read tool to view the style reference image at: ${args.refImagePath}\nMatch its visual style when applying the change.\n\n`
-        : "";
-    return runParsed(`${refPart}Here is a React+Tailwind page component:
-
-\`\`\`tsx
-${args.code}
-\`\`\`
-
-Modify ONLY the element (and its contents) marked data-dreative-id="${args.elementId}" according to this instruction: "${args.instruction}". Keep everything else byte-identical where possible, keep all data-dreative-id attributes.
-
-Respond with ONLY the full updated .tsx source in a single \`\`\`tsx code fence. No prose.`, extractCode, { allowRead: !!args.refImagePath, progress: args.progress });
-}