dreative 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# Dreative
+
+Visual round-trip UI editing **skill for coding CLIs** (Claude Code etc.). The CLI agent extracts your app's current UI page-by-page into editable wireframes; you tweak them in the browser (drag-drop, ref images, text prompts); clicking **Finish** hands a compact layout **diff** back to the agent, which rewrites your real code to match.
+
+Dreative itself has **no AI** — the web UI is a dumb visual editor plus a request queue. Your coding agent is the intelligence: it services UI prompts via `dreative wait` / `dreative respond` and applies the finish diff. See `skill/dreative/SKILL.md` for the agent workflow (install it into `.claude/skills/dreative/`).
+
+## Run
+
+```sh
+npm install
+npm run build
+npm link          # once — makes the `dreative` command available globally
+```
+
+Then in any project folder:
+
+```sh
+dreative          # starts the local server and opens http://localhost:4820
+```
+
+State lives in `.dreative/` in that folder (`project.json`, `refs/`, `generated/`).
+
+## Workflow
+
+1. **Extract** — the CLI agent reads your app and writes `.dreative/project.json` (wireframe per page, real labels, `source` pointers to owning files), then snapshots it: `dreative baseline`.
+2. **Tweak** — in the browser: drag blocks, add/remove/duplicate, attach reference images and prompts per page/block/element. Prompt-driven actions (propose layouts, block edits, design passes) are queued for your agent, which services them via `dreative wait` → `dreative respond`.
+3. **Finish** — click ✅ Finish; the agent receives only the diff vs the baseline (changed/moved/added/removed blocks + annotations) and applies it to the real codebase using the `source` pointers — token-efficient by construction.
+
+CLI: `dreative` / `dreative start` (server+UI) · `dreative install-skill` (copy skill into ./.claude/skills) · `dreative wait` (block for next UI event) · `dreative respond <id> [result.json|--error msg]` · `dreative baseline`.
+
+## Dev
+
+```sh
+npm run dev       # server on :4820 (tsx watch) + Vite UI on :5199 with proxy
+```

package/dist/cli/index.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline";
+import { createServer } from "../server/index.js";
+import open from "open";
+const port = Number(process.env.DREATIVE_PORT || 4820);
+const base = `http://localhost:${port}`;
+const args = process.argv.slice(2);
+const cmd = args[0] && !args[0].startsWith("-") ? args[0] : "start";
+const USAGE = `usage: dreative [command]
+  start            serve the visual editor for the current project (default)
+  install-skill    copy the dreative skill into ./.claude/skills/dreative/
+                   --list             show available specialist skills
+                   --skills a,b       install only these specialist skills (no flag: interactive picker, Enter = all)
+                   --codex            install for Codex CLI instead (.codex/skills/ + AGENTS.md pointer)
+  wait             (agent) block until the UI needs something; prints one JSON event
+  respond <id> [result.json | --error msg]   (agent) answer a request
+  baseline         (agent) snapshot project.json as the finish-diff baseline`;
+async function main() {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    switch (cmd) {
+        case "start": {
+            const app = createServer(process.cwd());
+            const server = app.listen(port, () => {
+                console.log(`\n  Dreative running for ${process.cwd()}`);
+                console.log(`  ${base}\n`);
+                if (!args.includes("--no-open"))
+                    open(base).catch(() => { });
+            });
+            server.on("error", (err) => {
+                console.error(`failed to start on :${port} — ${String(err)}\n(set DREATIVE_PORT to use another port)`);
+                process.exit(1);
+            });
+            return;
+        }
+        case "install-skill": {
+            const srcDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skill", "dreative");
+            const skillsDir = path.join(srcDir, "skills");
+            const available = fs.existsSync(skillsDir)
+                ? fs.readdirSync(skillsDir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
+                : [];
+            if (args.includes("--list")) {
+                console.log(`specialist skills (installed by default, pick with --skills a,b):`);
+                for (const s of available) {
+                    const firstLine = fs.readFileSync(path.join(skillsDir, `${s}.md`), "utf-8").split("\n")[0].replace(/^#\s*/, "");
+                    console.log(`  ${s.padEnd(14)} ${firstLine}`);
+                }
+                return;
+            }
+            const sArg = args.indexOf("--skills");
+            let picked = available;
+            if (sArg > -1) {
+                picked = (args[sArg + 1] || "").split(",").map((t) => t.trim()).filter(Boolean);
+                const unknown = picked.filter((p) => !available.includes(p));
+                if (unknown.length)
+                    throw new Error(`unknown skill(s): ${unknown.join(", ")} — available: ${available.join(", ")}`);
+            }
+            else if (process.stdin.isTTY && available.length) {
+                console.log("specialist skills:");
+                available.forEach((s, i) => {
+                    const firstLine = fs.readFileSync(path.join(skillsDir, `${s}.md`), "utf-8").split("\n")[0].replace(/^#\s*/, "");
+                    console.log(`  ${i + 1}. ${s.padEnd(14)} ${firstLine}`);
+                });
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = (await new Promise((res) => rl.question("install which? (numbers/names, comma-separated; Enter = all): ", res))).trim();
+                rl.close();
+                if (answer && answer.toLowerCase() !== "all") {
+                    picked = answer.split(",").map((t) => t.trim()).filter(Boolean).map((t) => {
+                        const n = Number(t);
+                        return Number.isInteger(n) && n >= 1 && n <= available.length ? available[n - 1] : t;
+                    });
+                    const unknown = picked.filter((p) => !available.includes(p));
+                    if (unknown.length)
+                        throw new Error(`unknown skill(s): ${unknown.join(", ")} — available: ${available.join(", ")}`);
+                }
+            }
+            const forCodex = args.includes("--codex");
+            const destDir = forCodex
+                ? path.join(process.cwd(), ".codex", "skills", "dreative")
+                : path.join(process.cwd(), ".claude", "skills", "dreative");
+            fs.mkdirSync(destDir, { recursive: true });
+            for (const f of fs.readdirSync(srcDir)) {
+                if (fs.statSync(path.join(srcDir, f)).isFile())
+                    fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
+            }
+            if (picked.length) {
+                fs.mkdirSync(path.join(destDir, "skills"), { recursive: true });
+                for (const s of picked) {
+                    fs.copyFileSync(path.join(skillsDir, `${s}.md`), path.join(destDir, "skills", `${s}.md`));
+                }
+            }
+            if (forCodex) {
+                // Codex may not auto-discover skills — leave a pointer in AGENTS.md (idempotent).
+                const agentsMd = path.join(process.cwd(), "AGENTS.md");
+                const marker = "<!-- dreative-skill -->";
+                const pointer = `\n${marker}\n## Dreative (frontend design skill)\nFor ANY frontend design work (redesign, restyle, build pages, animations, motion, 3D, micro-interactions) or when the user says "open dreative" / wants to edit the UI visually: read \`.codex/skills/dreative/SKILL.md\` first and follow it.\n`;
+                const existing = fs.existsSync(agentsMd) ? fs.readFileSync(agentsMd, "utf-8") : "";
+                if (!existing.includes(marker))
+                    fs.writeFileSync(agentsMd, existing + pointer);
+            }
+            console.log(`installed skill to ${destDir}${forCodex ? " (Codex mode: AGENTS.md pointer added)" : ""}`);
+            console.log(`  core: SKILL.md, DESIGN.md`);
+            console.log(`  specialist skills: ${picked.length ? picked.join(", ") : "(none)"}`);
+            console.log(`next: ask your coding agent to "open dreative" or "redesign my app's UI visually"`);
+            return;
+        }
+        // Agent: block until the UI needs something; print one event as JSON.
+        // Output: {"kind":"request",...} | {"kind":"finish","diff":...} | {"kind":"none"}
+        case "wait": {
+            const tArg = args.indexOf("--timeout");
+            const timeoutMs = (tArg > -1 ? Number(args[tArg + 1]) : 480) * 1000;
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                const res = await fetch(`${base}/api/agent/next`);
+                if (res.status === 204)
+                    continue; // server long-polls 25s per round
+                if (!res.ok)
+                    throw new Error(`server error ${res.status}`);
+                console.log(JSON.stringify(await res.json()));
+                return;
+            }
+            console.log(JSON.stringify({ kind: "none" }));
+            return;
+        }
+        // Agent: answer a request. `dreative respond <id> <result.json>` or --error "msg"
+        case "respond": {
+            const id = args[1];
+            if (!id)
+                throw new Error("usage: dreative respond <requestId> [resultFile] [--error msg]");
+            const eArg = args.indexOf("--error");
+            const body = { id };
+            if (eArg > -1)
+                body.error = args[eArg + 1] || "agent error";
+            else if (args[2])
+                body.result = JSON.parse(fs.readFileSync(args[2], "utf-8"));
+            else
+                body.result = { ok: true };
+            const res = await fetch(`${base}/api/agent/respond`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok)
+                throw new Error(`respond failed: ${await res.text()}`);
+            console.log("ok");
+            return;
+        }
+        // Agent: snapshot current project.json as the finish-diff baseline
+        case "baseline": {
+            const res = await fetch(`${base}/api/baseline`, { method: "POST" });
+            if (!res.ok)
+                throw new Error(`baseline failed: ${await res.text()}`);
+            console.log("ok");
+            return;
+        }
+        default:
+            console.error(`unknown command: ${cmd}\n${USAGE}`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(String(err));
+    process.exit(1);
+});

package/dist/server/agentQueue.js

@@ -0,0 +1,70 @@
+import { newId } from "./store.js";
+const queue = [];
+const pending = new Map();
+let waiter = null;
+function deliver(ev) {
+    if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w(ev);
+    }
+    else {
+        queue.push(ev);
+    }
+}
+/** Enqueue a request for the agent; resolves when the agent responds. */
+export function requestAgent(type, payload, onStatus) {
+    const event = { kind: "request", id: newId("req"), type, payload };
+    onStatus?.("Waiting for agent… (run `dreative wait` in your coding CLI)");
+    return new Promise((resolve, reject) => {
+        pending.set(event.id, { event, resolve: resolve, reject, onStatus, taken: false });
+        deliver(event);
+    });
+}
+export function pushFinish(diff) {
+    deliver({ kind: "finish", diff });
+}
+/** Long-poll: resolve with the next event, or null after timeoutMs. */
+export function nextEvent(timeoutMs) {
+    const ev = queue.shift();
+    if (ev) {
+        markTaken(ev);
+        return Promise.resolve(ev);
+    }
+    if (waiter)
+        waiter(null); // only one agent poller at a time
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (waiter === wrapped)
+                waiter = null;
+            resolve(null);
+        }, timeoutMs);
+        const wrapped = (e) => {
+            clearTimeout(timer);
+            if (e)
+                markTaken(e);
+            resolve(e);
+        };
+        waiter = wrapped;
+    });
+}
+function markTaken(ev) {
+    if (ev.kind !== "request")
+        return;
+    const p = pending.get(ev.id);
+    if (p && !p.taken) {
+        p.taken = true;
+        p.onStatus?.("Agent working…");
+    }
+}
+export function respond(id, body) {
+    const p = pending.get(id);
+    if (!p)
+        return false;
+    pending.delete(id);
+    if (body.error)
+        p.reject(new Error(body.error));
+    else
+        p.resolve(body.result);
+    return true;
+}

package/dist/server/ai.js

@@ -0,0 +1,177 @@
+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 });
+}

package/dist/server/diff.js

@@ -0,0 +1,97 @@
+/**
+ * Compact layout diff sent to the agent on "finish". Token efficiency is the
+ * point: only changed pages/blocks appear, changed blocks list only the props
+ * that differ (children compared structurally via the added/removed/moved
+ * lists, not by inclusion).
+ */
+const BLOCK_PROPS = ["type", "label", "direction", "sizeHint", "intents", "refImage", "source"];
+function flatten(root) {
+    const map = new Map();
+    const walk = (b, parentId, index) => {
+        map.set(b.id, { block: b, parentId, index });
+        b.children?.forEach((c, i) => walk(c, b.id, i));
+    };
+    walk(root, null, 0);
+    return map;
+}
+function diffPage(before, after) {
+    const d = { id: after.id, name: after.name, source: after.source };
+    let changed = false;
+    if (before.name !== after.name) {
+        d.renamedFrom = before.name;
+        changed = true;
+    }
+    if (before.refImage !== after.refImage && after.refImage) {
+        d.refImage = after.refImage;
+        changed = true;
+    }
+    if (before.designPrompt !== after.designPrompt && after.designPrompt) {
+        d.designPrompt = after.designPrompt;
+        changed = true;
+    }
+    const a = flatten(before.layout);
+    const b = flatten(after.layout);
+    for (const [id, fb] of b) {
+        const fa = a.get(id);
+        if (!fa) {
+            // report only the topmost added block (its subtree comes along)
+            if (!fb.parentId || a.has(fb.parentId)) {
+                (d.blocksAdded ??= []).push({ parentId: fb.parentId, index: fb.index, block: fb.block });
+                changed = true;
+            }
+            continue;
+        }
+        if (fa.parentId !== fb.parentId || fa.index !== fb.index) {
+            (d.blocksMoved ??= []).push({ id, label: fb.block.label, toParent: fb.parentId, index: fb.index });
+            changed = true;
+        }
+        const delta = {};
+        for (const key of BLOCK_PROPS) {
+            const va = fa.block[key];
+            const vb = fb.block[key];
+            if (JSON.stringify(va) !== JSON.stringify(vb))
+                delta[key] = vb ?? null;
+        }
+        if (Object.keys(delta).length) {
+            (d.blocksChanged ??= []).push({ id, label: fb.block.label, ...delta });
+            changed = true;
+        }
+    }
+    for (const [id, fa] of a) {
+        if (!b.has(id)) {
+            // report only topmost removed block
+            if (!fa.parentId || b.has(fa.parentId)) {
+                (d.blocksRemoved ??= []).push({ id, label: fa.block.label });
+                changed = true;
+            }
+        }
+    }
+    return changed ? d : null;
+}
+export function computeDiff(baseline, current) {
+    const beforePages = new Map(baseline.pages.map((p) => [p.id, p]));
+    const afterPages = new Map(current.pages.map((p) => [p.id, p]));
+    const diff = { pagesAdded: [], pagesRemoved: [], pagesChanged: [] };
+    for (const page of current.pages) {
+        const before = beforePages.get(page.id);
+        if (!before) {
+            diff.pagesAdded.push({
+                id: page.id,
+                name: page.name,
+                refImage: page.refImage,
+                designPrompt: page.designPrompt,
+                layout: page.layout,
+            });
+        }
+        else {
+            const d = diffPage(before, page);
+            if (d)
+                diff.pagesChanged.push(d);
+        }
+    }
+    for (const page of baseline.pages) {
+        if (!afterPages.has(page.id))
+            diff.pagesRemoved.push({ id: page.id, name: page.name, source: page.source });
+    }
+    return diff;
+}