nudge-ui 0.2.2 → 0.2.4

package/dist/project/artifacts.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface HtmlArtifactMetadata {
+    id: string;
+    sourceUrl: string;
+    title: string;
+    capturedAt: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+/** Handles only the reserved artifact namespace. A false return lets the host continue. */
+export declare function handleHtmlArtifactRequest(request: IncomingMessage, response: ServerResponse, root: string, transformHtml?: (html: string) => Promise<string>): Promise<boolean>;

package/dist/project/artifacts.js

@@ -0,0 +1,253 @@
+import { HTML_ARTIFACT_REVISION_ATTRIBUTE, HTML_ITERATION_CONFLICT, isHtmlArtifactRevision } from "../transport/artifacts.js";
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { NUDGE_UI_ARTIFACTS_PATH } from "../transport/routes.js";
+import { injectStandaloneBootstrap } from "../hosts/static/html/bootstrap.js";
+const artifactOperations = new Map();
+async function withArtifactLock(path, operation) {
+    const previous = artifactOperations.get(path) ?? Promise.resolve();
+    const pending = previous.catch(() => undefined).then(operation);
+    artifactOperations.set(path, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        if (artifactOperations.get(path) === pending)
+            artifactOperations.delete(path);
+    }
+}
+function revision(html) {
+    return createHash("sha256").update(html).digest("hex");
+}
+async function readRevision(target) {
+    const [document, preview] = await Promise.all([
+        readFile(join(target, "document.html")), readFile(join(target, "preview.html")),
+    ]);
+    return { document: revision(document), preview: revision(preview) };
+}
+function sameRevision(left, right) {
+    return left.document === right.document && left.preview === right.preview;
+}
+const ID = /^[a-f0-9-]{36}$/i;
+const MAX_BYTES = 12 * 1024 * 1024;
+const INERT_INTERACTIONS = `<script data-nudge-artifact-guard>
+document.addEventListener("submit", event => event.preventDefault(), true);
+document.addEventListener("click", event => {
+  if (event.target instanceof Element && event.target.closest("a")) event.preventDefault();
+}, true);
+</script>`;
+async function directory(root, id) {
+    const project = await realpath(root);
+    const artifacts = join(project, ".nudge", "artifacts");
+    await mkdir(artifacts, { recursive: true });
+    const actual = await realpath(artifacts);
+    const pathFromRoot = relative(project, actual);
+    if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+        throw new Error("Artifact storage must remain inside the project root");
+    }
+    return join(actual, id);
+}
+async function body(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += data.byteLength;
+        if (size > MAX_BYTES)
+            throw new Error("HTML artifact exceeds 12 MB");
+        chunks.push(data);
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    return text.length === 0 ? {} : JSON.parse(text);
+}
+function respond(response, status, content, type = "text/plain; charset=utf-8") {
+    response.writeHead(status, {
+        "content-type": type,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+    });
+    response.end(content);
+}
+/** Handles only the reserved artifact namespace. A false return lets the host continue. */
+export async function handleHtmlArtifactRequest(request, response, root, transformHtml) {
+    const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
+    if (pathname !== NUDGE_UI_ARTIFACTS_PATH && !pathname.startsWith(`${NUDGE_UI_ARTIFACTS_PATH}/`))
+        return false;
+    const parts = pathname.slice(NUDGE_UI_ARTIFACTS_PATH.length).split("/").filter(Boolean);
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        const origin = request.headers.origin;
+        const host = request.headers.host;
+        if (origin && host) {
+            try {
+                if (new URL(origin).host !== host) {
+                    respond(response, 403, "Cross-origin artifact writes are not allowed");
+                    return true;
+                }
+            }
+            catch {
+                respond(response, 403, "Invalid request origin");
+                return true;
+            }
+        }
+    }
+    const id = parts[0];
+    if (parts.length > 2 || (id && !ID.test(id)) || (parts.length === 2 && !["document", "baseline", "preview", "commit", "revision"].includes(parts[1]))) {
+        respond(response, 404, "Not Found");
+        return true;
+    }
+    try {
+        if (request.method === "POST" && parts.length === 0) {
+            const input = await body(request);
+            if (!validArtifact(input)) {
+                respond(response, 400, "Invalid artifact");
+                return true;
+            }
+            const target = await directory(root, input.id);
+            const temporary = `${target}.create-${crypto.randomUUID()}`;
+            const metadata = {
+                id: input.id,
+                sourceUrl: input.sourceUrl,
+                title: input.title,
+                capturedAt: Date.now(),
+                viewport: input.viewport,
+            };
+            await mkdir(temporary);
+            try {
+                await writeFile(join(temporary, "baseline.html"), input.html);
+                await writeFile(join(temporary, "preview.html"), input.html);
+                await writeFile(join(temporary, "document.html"), input.html);
+                await writeFile(join(temporary, "metadata.json"), JSON.stringify(metadata));
+                await rename(temporary, target);
+            }
+            catch (error) {
+                await rm(temporary, { recursive: true, force: true });
+                throw error;
+            }
+            respond(response, 201, JSON.stringify(metadata), "application/json; charset=utf-8");
+            return true;
+        }
+        if (!id) {
+            respond(response, 405, "Method Not Allowed");
+            return true;
+        }
+        const target = await directory(root, id);
+        return await withArtifactLock(target, async () => {
+            if (request.method !== "DELETE") {
+                const actual = await realpath(target);
+                if (actual !== target)
+                    throw new Error("Artifact directory must not be a symbolic link");
+            }
+            if (request.method === "GET" && parts[1] === "revision") {
+                respond(response, 200, JSON.stringify(await readRevision(target)), "application/json; charset=utf-8");
+                return true;
+            }
+            if (request.method === "GET" && parts.length === 2 && parts[1] !== "commit") {
+                const file = parts[1] === "baseline" ? "baseline.html" : parts[1] === "preview" ? "preview.html" : "document.html";
+                const html = await readFile(join(target, file), "utf8");
+                const stamped = html.replace(/<html\b/i, `<html ${HTML_ARTIFACT_REVISION_ATTRIBUTE}="${revision(html)}"`);
+                const bootstrapped = injectStandaloneBootstrap(stamped).html;
+                const guarded = bootstrapped.replace(/<\/body>/i, `${INERT_INTERACTIONS}</body>`);
+                respond(response, 200, transformHtml ? await transformHtml(guarded) : guarded, "text/html; charset=utf-8");
+                return true;
+            }
+            if (request.method === "GET" && parts.length === 1) {
+                respond(response, 200, await readFile(join(target, "metadata.json"), "utf8"), "application/json; charset=utf-8");
+                return true;
+            }
+            if ((request.method === "PUT" && parts[1] === "document")
+                || (request.method === "POST" && parts[1] === "commit")) {
+                const input = await body(request);
+                if (!input || typeof input !== "object") {
+                    respond(response, 400, "Invalid document");
+                    return true;
+                }
+                const item = input;
+                if (!isHtmlArtifactRevision(item.expected)) {
+                    respond(response, 428, "An expected iteration revision is required");
+                    return true;
+                }
+                if ((item.html !== undefined && typeof item.html !== "string")
+                    || (request.method === "PUT" && typeof item.html !== "string")) {
+                    respond(response, 400, "Invalid document");
+                    return true;
+                }
+                const expected = item.expected;
+                if (!sameRevision(await readRevision(target), expected)) {
+                    respond(response, 409, HTML_ITERATION_CONFLICT);
+                    return true;
+                }
+                const html = typeof item.html === "string" ? item.html : await readFile(join(target, "document.html"), "utf8");
+                const writes = request.method === "POST" ? ["preview.html"] : [];
+                if (typeof item.html === "string")
+                    writes.push("document.html");
+                const previewBefore = await readFile(join(target, "preview.html"));
+                const temporaryFiles = [];
+                try {
+                    for (const file of writes) {
+                        const temporary = join(target, `${file}-${crypto.randomUUID()}.tmp`);
+                        temporaryFiles.push({ temporary, destination: join(target, file) });
+                        await writeFile(temporary, html);
+                    }
+                    // Keep the final check and replacements in one controller critical section.
+                    // External tools must finish their file writes before handoff; they do
+                    // not participate in this process's request queue.
+                    const latest = {
+                        document: revision(readFileSync(join(target, "document.html"))),
+                        preview: revision(readFileSync(join(target, "preview.html"))),
+                    };
+                    if (!sameRevision(latest, expected)) {
+                        respond(response, 409, HTML_ITERATION_CONFLICT);
+                        return true;
+                    }
+                    let replacedPreview = false;
+                    try {
+                        for (const file of temporaryFiles) {
+                            renameSync(file.temporary, file.destination);
+                            replacedPreview ||= file.destination === join(target, "preview.html");
+                        }
+                    }
+                    catch (error) {
+                        // A failed document replacement must not advance the editing base.
+                        if (replacedPreview) {
+                            const rollback = join(target, `preview-rollback-${crypto.randomUUID()}.tmp`);
+                            writeFileSync(rollback, previewBefore);
+                            renameSync(rollback, join(target, "preview.html"));
+                        }
+                        throw error;
+                    }
+                }
+                finally {
+                    await Promise.all(temporaryFiles.map((file) => rm(file.temporary, { force: true }).catch(() => undefined)));
+                }
+                const saved = revision(html);
+                respond(response, 200, JSON.stringify({ document: saved, preview: request.method === "POST" ? saved : expected.preview }), "application/json; charset=utf-8");
+                return true;
+            }
+            if (request.method === "DELETE" && parts.length === 1) {
+                await rm(target, { recursive: true, force: true });
+                respond(response, 204, "");
+                return true;
+            }
+            respond(response, 405, "Method Not Allowed");
+            return true;
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        respond(response, code === "ENOENT" ? 404 : code === "EEXIST" || code === "ENOTEMPTY" ? 409 : 500, code === "ENOENT" ? "Artifact not found" : error instanceof Error ? error.message : "Artifact storage failed");
+    }
+    return true;
+}
+function validArtifact(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    const viewport = item.viewport;
+    return typeof item.id === "string" && ID.test(item.id)
+        && typeof item.sourceUrl === "string" && item.sourceUrl.length < 4096
+        && typeof item.title === "string" && item.title.length < 512
+        && typeof item.html === "string" && item.html.length > 0
+        && !!viewport && typeof viewport.width === "number" && typeof viewport.height === "number";
+}

package/dist/transport/artifacts.d.ts

@@ -0,0 +1,8 @@
+/** Revisions cover both the agent-editable file and the browser editing base. */
+export interface HtmlArtifactRevision {
+    readonly document: string;
+    readonly preview: string;
+}
+export declare const HTML_ARTIFACT_REVISION_ATTRIBUTE = "data-nudge-artifact-revision";
+export declare const HTML_ITERATION_CONFLICT = "This iteration changed outside Nudge. Your visual edits are still pending. Create another iteration to keep your design, then clear this iteration\u2019s changes to load the external update.";
+export declare function isHtmlArtifactRevision(value: unknown): value is HtmlArtifactRevision;

package/dist/transport/artifacts.js

@@ -0,0 +1,9 @@
+export const HTML_ARTIFACT_REVISION_ATTRIBUTE = "data-nudge-artifact-revision";
+export const HTML_ITERATION_CONFLICT = "This iteration changed outside Nudge. Your visual edits are still pending. Create another iteration to keep your design, then clear this iteration’s changes to load the external update.";
+export function isHtmlArtifactRevision(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    return typeof item.document === "string" && /^[a-f0-9]{64}$/.test(item.document)
+        && typeof item.preview === "string" && /^[a-f0-9]{64}$/.test(item.preview);
+}

package/dist/transport/editor.js

@@ -1,4 +1,4 @@
-import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_DIRECT_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_VALUE, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_OFF_QUERY_VALUE, NUDGE_UI_ON_QUERY_VALUE, isReservedNudgeUiRoute, } from "./routes.js";
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_ARTIFACTS_PATH, NUDGE_UI_DIRECT_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_VALUE, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_OFF_QUERY_VALUE, NUDGE_UI_ON_QUERY_VALUE, isReservedNudgeUiRoute, } from "./routes.js";
 const TARGET_QUERY_PARAM = "url";
 const DIRECT_TAB_SESSION_KEY = "nudge-ui:direct-tab";
 const FORCED_TAB_SESSION_KEY = "nudge-ui:forced-tab";
@@ -123,6 +123,8 @@ function readTabFlag(key) {
 export function resolveNudgeUiClientEntry(href, context) {
     if (context.editorDocument || context.canvasRenderer)
         return { kind: "bootstrap" };
+    if (new URL(href).pathname.startsWith(`${NUDGE_UI_ARTIFACTS_PATH}/`))
+        return { kind: "direct" };
     const urlSwitch = readNudgeUiQuerySwitch(href);
     if (urlSwitch === "off")
         return { kind: "direct" };

package/dist/transport/routes.d.ts

@@ -11,6 +11,8 @@ export declare const NUDGE_UI_CLIENT_PATH = "/__nudge_ui__/client.mjs";
 export declare const NUDGE_UI_EDITOR_PATH = "/__nudge_ui__/editor";
 /** Server-sent events announcing settled project changes. */
 export declare const NUDGE_UI_RELOAD_PATH = "/__nudge_ui__/reload";
+/** Project-local HTML iterations created by unlinking a Canvas frame. */
+export declare const NUDGE_UI_ARTIFACTS_PATH = "/__nudge_ui__/artifacts";
 export declare const NUDGE_UI_MOUNT_ID = "nudge-ui-root";
 /** Query marker that presents an application route through the editor shell. */
 export declare const NUDGE_UI_EDITOR_QUERY_PARAM = "nudge-ui";

package/dist/transport/routes.js

@@ -11,6 +11,8 @@ export const NUDGE_UI_CLIENT_PATH = `${NUDGE_UI_ROUTE_PREFIX}client.mjs`;
 export const NUDGE_UI_EDITOR_PATH = `${NUDGE_UI_ROUTE_PREFIX}editor`;
 /** Server-sent events announcing settled project changes. */
 export const NUDGE_UI_RELOAD_PATH = `${NUDGE_UI_ROUTE_PREFIX}reload`;
+/** Project-local HTML iterations created by unlinking a Canvas frame. */
+export const NUDGE_UI_ARTIFACTS_PATH = `${NUDGE_UI_ROUTE_PREFIX}artifacts`;
 export const NUDGE_UI_MOUNT_ID = "nudge-ui-root";
 /** Query marker that presents an application route through the editor shell. */
 export const NUDGE_UI_EDITOR_QUERY_PARAM = "nudge-ui";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nudge-ui",
-  "version": "0.2.2",
-  "description": "Development-only visual UI inspector. One package, one subpath per host.",
+  "version": "0.2.4",
+  "description": "A design panel for your codebase. Development only.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -76,13 +76,14 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.8",
-    "@base-ui/react": "^1.7.0",
+    "@base-ui/react": "^1.8.0",
     "@tabler/icons-react": "^3.46.0",
     "magic-string": "^0.30.21",
     "modern-screenshot": "^4.7.0",
     "parse5": "^7.3.0",
     "perfect-freehand": "^1.2.3",
     "postcss": "^8.5.26",
+    "thinking-orbs": "^0.3.2",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
@@ -110,6 +111,8 @@
     }
   },
   "devDependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@types/hast": "^3.0.5",
     "@types/node": "^22.20.1",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
@@ -118,6 +121,7 @@
     "jsdom": "^25.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
+    "satteri": "^0.10.5",
     "vite": "^8.2.2",
     "vitest": "^2.1.9",
     "@nudge-ui/agent-protocol": "0.2.0"

package/dist/inspector/changes/workspaceChanges.d.ts

@@ -1,47 +0,0 @@
-import type { ChangeRecord } from "./types.js";
-import type { StructuralChange } from "./structuralTypes.js";
-export interface WorkspaceContents {
-    readonly changes: readonly ChangeRecord[];
-    readonly structuralChanges: readonly StructuralChange[];
-}
-export interface WorkspaceChangesSnapshot extends WorkspaceContents {
-    readonly revision: number;
-    readonly canUndo: boolean;
-    readonly canRedo: boolean;
-}
-export type WorkspaceProjector = (snapshot: WorkspaceChangesSnapshot) => void;
-export type CommitResult = "applied" | "unchanged" | "blocked";
-export interface WorkspaceChangeStore {
-    getSnapshot(): WorkspaceChangesSnapshot;
-    subscribe(listener: () => void): () => void;
-    commitChangeRecords(incoming: readonly ChangeRecord[]): CommitResult;
-    revertChangeRecord(change: ChangeRecord): boolean;
-    discardChangeRecords(target: {
-        kind: "selector";
-        selector: string;
-    } | {
-        kind: "instance-override";
-        id: string;
-    }): boolean;
-    commitStructuralChange(change: StructuralChange): boolean;
-    revertStructuralChangeRecord(changeId: string): boolean;
-    reconcileWorkspaceChanges(verifiedKeys: ReadonlySet<string>, verifiedStructuralIds: ReadonlySet<string>): number;
-    undoWorkspaceChange(): boolean;
-    redoWorkspaceChange(): boolean;
-    restoreWorkspaceChanges(next: WorkspaceContents): void;
-    clearWorkspaceChanges(): void;
-}
-/** Groups consecutive synchronous updates from one gesture into one undo step.
- * Updates outside the callback keep their own history entries.
- */
-export declare function createChangeHistoryGroup(): (update: () => void) => void;
-export declare const workspaceChangeStore: WorkspaceChangeStore;
-/** Compatibility accessors retained for callers that have not adopted the store seam. */
-export declare function getWorkspaceChanges(): WorkspaceChangesSnapshot;
-export declare function subscribeWorkspaceChanges(listener: () => void): () => void;
-export declare function commitChangeRecords(incoming: readonly ChangeRecord[], project: WorkspaceProjector): CommitResult;
-export declare function commitStructuralChange(change: StructuralChange, project: WorkspaceProjector): boolean;
-export declare function undoWorkspaceChange(project: WorkspaceProjector): boolean;
-export declare function redoWorkspaceChange(project: WorkspaceProjector): boolean;
-export declare function restoreWorkspaceChanges(next: WorkspaceContents, project: WorkspaceProjector): void;
-export declare function resetWorkspaceChanges(): void;