nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/workspace/handoff.d.ts

@@ -33,10 +33,6 @@ export declare function prepareHandoff(request: HandoffRequest): Promise<Prepare
 export declare function prepareIterationImplementationPrompt(request: HandoffRequest): Promise<string>;
 /** Copies a prompt and records the checkpoint that later clipboard verification reconciles. */
 export declare function copyHandoff(handoff: PreparedHandoff): Promise<void>;
-/**
- * Sends the prompt to a connected agent, or copies it when no agent is given.
- * A failed send without sketches falls back to the clipboard; a failed sketch
- * send is returned so the user can choose to copy without the images.
- */
+/** Falls back to the clipboard; a failed sketch send returns so the caller can copy without the images. */
 export declare function deliverHandoff(handoff: PreparedHandoff, projectId: string, agent: PromptDispatcher | null): Promise<HandoffOutcome>;
 export {};

package/dist/inspector/workspace/handoff.js

@@ -62,11 +62,7 @@ export async function copyHandoff(handoff) {
         recordClipboardHandoff(changes, structuralChanges, owner);
     }
 }
-/**
- * Sends the prompt to a connected agent, or copies it when no agent is given.
- * A failed send without sketches falls back to the clipboard; a failed sketch
- * send is returned so the user can choose to copy without the images.
- */
+/** Falls back to the clipboard; a failed sketch send returns so the caller can copy without the images. */
 export async function deliverHandoff(handoff, projectId, agent) {
     if (agent) {
         const outcome = await dispatchHandoff(handoff, projectId, agent);

package/dist/inspector/workspace/timeline.d.ts

@@ -5,7 +5,11 @@ export interface EditHistoryEntry {
     readonly group?: symbol;
     readonly before: DraftContents;
     readonly after: DraftContents;
-    readonly activate?: () => void;
+    /** Where replay should take the user: the draft's owning frame, when one was known. */
+    readonly focus?: {
+        readonly draftId: string;
+        readonly cardId?: string;
+    };
 }
 export interface CanvasHistoryEntry {
     readonly kind: "canvas";
@@ -33,7 +37,6 @@ export interface Timeline {
     createGroup(): (update: () => void) => void;
 }
 export declare function createTimeline(): Timeline;
-/** The Workspace's session timeline. */
 export declare const sessionTimeline: Timeline;
 export declare function recordCanvasChange(entry: Omit<CanvasHistoryEntry, "kind">): void;
 export declare function discardCanvasHistory(cardId: string): void;

package/dist/inspector/workspace/timeline.js

@@ -108,7 +108,6 @@ export function createTimeline() {
         },
     };
 }
-/** The Workspace's session timeline. */
 export const sessionTimeline = createTimeline();
 export function recordCanvasChange(entry) {
     sessionTimeline.recordCanvasChange(entry);

package/dist/internal/agent-protocol.d.ts

@@ -1,11 +1,4 @@
-/**
- * Public, host-neutral contracts shared by the Nudge browser inspector and
- * its local MCP companion.
- *
- * This module deliberately has no Node, browser, MCP SDK, or framework
- * imports. Hosts can use the same validation and message shapes without
- * pulling the companion into a browser bundle.
- */
+/** Host-neutral contracts shared by the browser inspector and the local MCP companion; no Node, browser, MCP SDK, or framework imports. */
 export declare const AGENT_PROTOCOL_VERSION: 3;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
@@ -38,6 +31,18 @@ export declare const AGENT_PROTOCOL_LIMITS: {
     readonly agentClientName: 120;
 };
 export type AgentProtocolVersion = typeof AGENT_PROTOCOL_VERSION;
+/** Stable loopback endpoint names shared by the browser client and the MCP bridge. */
+export declare const BRIDGE_ENDPOINTS: {
+    readonly health: "/health";
+    readonly pair: "/pair";
+    readonly takeover: "/takeover";
+    readonly events: "/events";
+    readonly prompt: "/prompt";
+    readonly status: "/status";
+    readonly canvasAcknowledgement: "/canvas/ack";
+    readonly disconnect: "/disconnect";
+};
+export type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
 /** A project identity is the pairing boundary for one companion process. */
 export interface AgentProjectIdentity {
     readonly projectId: string;
@@ -54,14 +59,12 @@ export interface AgentRoute {
 }
 /** The owner marker lets the browser remove only groups created by the agent. */
 export type CanvasGroupOwner = "agent" | "user";
-/** A browser-reported comparison group. */
 export interface CanvasGroup {
     readonly id: string;
     readonly label: string;
     readonly owner: CanvasGroupOwner;
     readonly routes: readonly AgentRoute[];
 }
-/** A compact, serialisable Canvas snapshot returned by the browser. */
 export interface CanvasState {
     readonly mode: "inspect" | "canvas";
     readonly groups: readonly CanvasGroup[];
@@ -287,32 +290,16 @@ export interface ProjectBridgeHandle {
     };
     close(): Promise<void>;
 }
-/**
- * The `startProjectBridge` export of `@nudge-ui/mcp/project`. Hosts load it
- * dynamically from the application's own dependencies, so this type is the
- * only compile-time link between the two packages.
- */
+/** The `@nudge-ui/mcp/project` export; hosts load it dynamically, so this is the only compile-time link between the packages. */
 export type StartProjectBridge = (options: ProjectBridgeStartOptions) => Promise<ProjectBridgeHandle>;
-/**
- * Returns a canonical origin or null. Credentials, paths, and fragments are
- * rejected so the browser cannot broaden the pairing boundary accidentally.
- */
+/** Canonical origin or null; credentials, paths, and fragments are rejected so pairing cannot broaden accidentally. */
 export declare function canonicalOrigin(value: unknown): string | null;
-/** Returns true only for exact, canonical HTTP(S) origins. */
 export declare function isCanonicalOrigin(value: unknown): value is string;
-/**
- * Checks an origin against an explicit allow-list. An empty allow-list does
- * not mean wildcard access; callers must choose an origin before pairing.
- */
+/** An empty allow-list is not wildcard access; callers must choose an origin before pairing. */
 export declare function isAllowedOrigin(value: unknown, allowedOrigins: readonly string[]): value is string;
-/**
- * Validates an agent route and ensures it belongs to the paired origin.
- * Fragments are retained because they are useful initial Canvas locations.
- */
+/** Fragments are retained because they are useful initial Canvas locations. */
 export declare function isSameOriginRoute(value: unknown, origin: string): value is AgentRoute;
-/** Validates and normalises route values for a presentation command. */
 export declare function validateRoutes(value: unknown, origin: string): AgentRoute[];
-/** Validates the fields shared by every companion message. */
 export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
 export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
 export declare function isAgentSketchCaptureMetadata(value: unknown): value is AgentSketchCaptureMetadata;
@@ -326,21 +313,12 @@ export declare function isCanvasState(value: unknown): value is CanvasState;
 export declare function isCanvasGroup(value: unknown): value is CanvasGroup;
 export declare function isCanvasCommand(value: unknown): value is CanvasCommand;
 export declare function isAgentDeliveredPrompt(value: unknown): value is AgentDeliveredPrompt;
-/** A Canvas acknowledgement or result; a successful one never carries an error. */
+/** A successful result never carries an error. */
 export declare function isCanvasCommandResult(value: unknown): value is CanvasCommandResult;
-/** The connection state shown for a pairing, a listener, and the current request. */
 export declare function deriveConnectionState(status: Pick<AgentStatusSnapshot, "listenerActive" | "paired" | "request">): AgentConnectionState;
-/**
- * Decodes a status snapshot from any peer. Unknown fields are dropped and the
- * connection state is recomputed, so a snapshot can never claim a state its
- * own fields contradict.
- */
+/** Unknown fields are dropped and the connection state is recomputed, so a snapshot cannot claim a state its own fields contradict. */
 export declare function decodeAgentStatusSnapshot(value: unknown): AgentStatusSnapshot | null;
-/**
- * Decodes the event inside a bridge envelope. A Canvas command is passed
- * through as received: the Canvas controller validates it so a malformed
- * command still receives an error acknowledgement instead of a timeout.
- */
+/** A Canvas command is passed through as received: the Canvas controller validates it so a malformed command still receives an error acknowledgement. */
 export declare function decodeBridgeEvent(value: unknown): BridgeEvent | null;
 /** Decodes a pairing or takeover response for the exact project and origin requested. */
 export declare function decodePairingResponse(value: unknown, expected: Pick<PairingRequest, "projectId" | "origin">): PairingResponse | null;

package/dist/internal/agent-protocol.js

@@ -1,11 +1,4 @@
-/**
- * Public, host-neutral contracts shared by the Nudge browser inspector and
- * its local MCP companion.
- *
- * This module deliberately has no Node, browser, MCP SDK, or framework
- * imports. Hosts can use the same validation and message shapes without
- * pulling the companion into a browser bundle.
- */
+/** Host-neutral contracts shared by the browser inspector and the local MCP companion; no Node, browser, MCP SDK, or framework imports. */
 export const AGENT_PROTOCOL_VERSION = 3;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
@@ -37,6 +30,17 @@ export const AGENT_PROTOCOL_LIMITS = {
     canvasCardCount: 128,
     agentClientName: 120,
 };
+/** Stable loopback endpoint names shared by the browser client and the MCP bridge. */
+export const BRIDGE_ENDPOINTS = {
+    health: "/health",
+    pair: "/pair",
+    takeover: "/takeover",
+    events: "/events",
+    prompt: "/prompt",
+    status: "/status",
+    canvasAcknowledgement: "/canvas/ack",
+    disconnect: "/disconnect",
+};
 export const CANVAS_COMMAND_TYPES = [
     "read-state",
     "present-routes",
@@ -93,10 +97,7 @@ function encodedByteLength(value) {
     const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
     return Math.max(0, Math.floor(value.length * 3 / 4) - padding);
 }
-/**
- * Returns a canonical origin or null. Credentials, paths, and fragments are
- * rejected so the browser cannot broaden the pairing boundary accidentally.
- */
+/** Canonical origin or null; credentials, paths, and fragments are rejected so pairing cannot broaden accidentally. */
 export function canonicalOrigin(value) {
     if (!nonEmptyString(value, AGENT_PROTOCOL_LIMITS.origin))
         return null;
@@ -113,24 +114,17 @@ export function canonicalOrigin(value) {
         return null;
     return parsed.origin;
 }
-/** Returns true only for exact, canonical HTTP(S) origins. */
 export function isCanonicalOrigin(value) {
     return canonicalOrigin(value) === value;
 }
-/**
- * Checks an origin against an explicit allow-list. An empty allow-list does
- * not mean wildcard access; callers must choose an origin before pairing.
- */
+/** An empty allow-list is not wildcard access; callers must choose an origin before pairing. */
 export function isAllowedOrigin(value, allowedOrigins) {
     const origin = canonicalOrigin(value);
     if (!origin || allowedOrigins.length === 0)
         return false;
     return allowedOrigins.some((candidate) => canonicalOrigin(candidate) === origin);
 }
-/**
- * Validates an agent route and ensures it belongs to the paired origin.
- * Fragments are retained because they are useful initial Canvas locations.
- */
+/** Fragments are retained because they are useful initial Canvas locations. */
 export function isSameOriginRoute(value, origin) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["url", "title", "label"]))
         return false;
@@ -154,7 +148,6 @@ export function isSameOriginRoute(value, origin) {
         return false;
     return true;
 }
-/** Validates and normalises route values for a presentation command. */
 export function validateRoutes(value, origin) {
     if (!Array.isArray(value) || value.length === 0 || value.length > AGENT_PROTOCOL_LIMITS.routeCount) {
         throw new TypeError(`routes must contain between 1 and ${AGENT_PROTOCOL_LIMITS.routeCount} items`);
@@ -175,7 +168,6 @@ export function validateRoutes(value, origin) {
         };
     });
 }
-/** Validates the fields shared by every companion message. */
 export function isProtocolVersion(value) {
     return value === AGENT_PROTOCOL_VERSION;
 }
@@ -418,7 +410,7 @@ function isCanvasCommandError(value) {
         && nonEmptyString(value.code, 128)
         && typeof value.message === "string" && value.message.length <= AGENT_PROTOCOL_LIMITS.prompt;
 }
-/** A Canvas acknowledgement or result; a successful one never carries an error. */
+/** A successful result never carries an error. */
 export function isCanvasCommandResult(value) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["commandId", "ok", "state", "group", "error"]))
         return false;
@@ -428,7 +420,6 @@ export function isCanvasCommandResult(value) {
         && (value.group === undefined || isCanvasGroup(value.group))
         && (value.error === undefined || (!value.ok && isCanvasCommandError(value.error)));
 }
-/** The connection state shown for a pairing, a listener, and the current request. */
 export function deriveConnectionState(status) {
     if (status.request?.status === "delivered")
         return "delivered";
@@ -460,11 +451,7 @@ function decodeStatusRequest(value) {
         ...(error === undefined ? {} : { error }),
     };
 }
-/**
- * Decodes a status snapshot from any peer. Unknown fields are dropped and the
- * connection state is recomputed, so a snapshot can never claim a state its
- * own fields contradict.
- */
+/** Unknown fields are dropped and the connection state is recomputed, so a snapshot cannot claim a state its own fields contradict. */
 export function decodeAgentStatusSnapshot(value) {
     if (!isRecord(value)
         || value.protocolVersion !== AGENT_PROTOCOL_VERSION
@@ -491,11 +478,7 @@ export function decodeAgentStatusSnapshot(value) {
             : {}),
     };
 }
-/**
- * Decodes the event inside a bridge envelope. A Canvas command is passed
- * through as received: the Canvas controller validates it so a malformed
- * command still receives an error acknowledgement instead of a timeout.
- */
+/** A Canvas command is passed through as received: the Canvas controller validates it so a malformed command still receives an error acknowledgement. */
 export function decodeBridgeEvent(value) {
     if (!isRecord(value))
         return null;

package/dist/nudge-ui.mjs

@@ -6199,7 +6199,7 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPnpRuntime() {
-  return typeof process.versions.pnp === "string";
+  return "pnp" in process.versions && typeof process.versions.pnp === "string";
 }
 
 // src/cli/agentCommand.ts
@@ -6262,6 +6262,42 @@ function isReservedNudgeUiRoute(pathname) {
   return pathname === NUDGE_UI_ROUTE_PREFIX.slice(0, -1) || pathname.startsWith(NUDGE_UI_ROUTE_PREFIX);
 }
 
+// src/inspector/runtime/runtimeConfig.ts
+function cloneAndFreeze(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value === null || typeof value !== "object") return value;
+  const source = value;
+  const existing = seen.get(source);
+  if (existing) return existing;
+  if (Object.isFrozen(value)) {
+    seen.set(source, value);
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const copy2 = [];
+    seen.set(source, copy2);
+    for (const item of value) copy2.push(cloneAndFreeze(item, seen));
+    return Object.freeze(copy2);
+  }
+  const copy = {};
+  seen.set(source, copy);
+  for (const [key, child] of Object.entries(value)) {
+    copy[key] = cloneAndFreeze(child, seen);
+  }
+  return Object.freeze(copy);
+}
+var DEFAULT_RUNTIME_CONFIG = cloneAndFreeze({
+  projectId: "/stub/project",
+  host: "vite-react",
+  framework: "React",
+  stylingSystem: "CSS custom properties",
+  capabilities: { canvas: true, componentSemantics: true, domNavigation: false },
+  tokenCatalog: [],
+  tokens: [],
+  tokenDiagnostics: [],
+  tokenGeneration: "",
+  componentContracts: []
+});
+
 // src/transport/editor.ts
 function isNudgeUiEditorDocumentRequest(requestHref, method, headers) {
   const normalizedMethod = (method ?? "GET").toUpperCase();
@@ -6285,7 +6321,7 @@ function createNudgeUiEditorDocument() {
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Nudge UI</title>
+  <title></title>
   <style>html,body,#${NUDGE_UI_MOUNT_ID}{width:100%;height:100%;margin:0}body{overflow:hidden}</style>
 </head>
 <body>
@@ -6298,6 +6334,20 @@ function createNudgeUiEditorDocument() {
 // src/transport/index.ts
 var NUDGE_UI_MANIFEST_VERSION = 1;
 
+// src/inspector/clientManifest.ts
+var NUDGE_UI_CLIENT_MANIFEST_VERSION = NUDGE_UI_MANIFEST_VERSION;
+function createNudgeUiClientManifest(input) {
+  return {
+    version: NUDGE_UI_CLIENT_MANIFEST_VERSION,
+    revision: input.revision ?? 0,
+    runtime: input.runtime,
+    ...input.agentBridge ? { agentBridge: input.agentBridge } : {},
+    ...input.document ? { document: input.document } : {},
+    ...input.reload ? { reload: input.reload } : {},
+    ...input.inspectAutomatedBrowsers ? { inspectAutomatedBrowsers: true } : {}
+  };
+}
+
 // src/hosts/environment.ts
 function readNudgeUiEnvironmentSwitch(env = process.env) {
   const value = env.NUDGE_UI?.trim().toLowerCase();
@@ -6311,17 +6361,14 @@ function automationManifestFields(env = process.env) {
 
 // src/hosts/static/manifest.ts
 function createStandaloneRuntimeManifest(projectId, tokenSnapshot = emptyTokenSnapshot(), revision2 = 0) {
-  return {
-    version: NUDGE_UI_MANIFEST_VERSION,
+  return createNudgeUiClientManifest({
     revision: revision2,
     runtime: {
       projectId,
       host: "static-html",
       framework: "HTML",
       stylingSystem: "CSS custom properties",
-      // Canvas shares the Vite host's controller/renderer runtime (ADR-0012):
-      // every served document carries the bootstrap, so card iframes boot as
-      // renderers without host-specific code.
+      // Canvas shares the Vite host's controller/renderer runtime (ADR-0012).
       capabilities: { canvas: true, componentSemantics: false, domNavigation: true },
       tokenCatalog: tokenSnapshot.tokenCatalog,
       tokens: tokenSnapshot.tokens,
@@ -6339,7 +6386,7 @@ function createStandaloneRuntimeManifest(projectId, tokenSnapshot = emptyTokenSn
       events: ["ready", "reload"]
     },
     ...automationManifestFields()
-  };
+  });
 }
 function emptyTokenSnapshot() {
   return {
@@ -14320,6 +14367,9 @@ async function directory(root2, id) {
   }
   return join2(actual, id);
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function body(request) {
   const chunks = [];
   let size = 0;
@@ -14330,7 +14380,9 @@ async function body(request) {
     chunks.push(data);
   }
   const text = Buffer.concat(chunks).toString("utf8");
-  return text.length === 0 ? {} : JSON.parse(text);
+  if (text.length === 0) return {};
+  const parsed = JSON.parse(text);
+  return isRecord2(parsed) ? parsed : null;
 }
 function respond(response, status, content, type = "text/plain; charset=utf-8") {
   response.writeHead(status, {
@@ -14367,7 +14419,7 @@ async function handleHtmlArtifactRequest(request, response, root2, transformHtml
   try {
     if (request.method === "POST" && parts.length === 0) {
       const input = await body(request);
-      if (!validArtifact(input)) {
+      if (!input || !validArtifact(input)) {
         respond(response, 400, "Invalid artifact");
         return true;
       }
@@ -14423,27 +14475,26 @@ async function handleHtmlArtifactRequest(request, response, root2, transformHtml
       }
       if (request.method === "PUT" && parts[1] === "document" || request.method === "POST" && parts[1] === "commit") {
         const input = await body(request);
-        if (!input || typeof input !== "object") {
+        if (!input) {
           respond(response, 400, "Invalid document");
           return true;
         }
-        const item = input;
-        if (!isHtmlArtifactRevision(item.expected)) {
+        if (!isHtmlArtifactRevision(input.expected)) {
           respond(response, 428, "An expected iteration revision is required");
           return true;
         }
-        if (item.html !== void 0 && typeof item.html !== "string" || request.method === "PUT" && typeof item.html !== "string") {
+        if (input.html !== void 0 && typeof input.html !== "string" || request.method === "PUT" && typeof input.html !== "string") {
           respond(response, 400, "Invalid document");
           return true;
         }
-        const expected = item.expected;
+        const expected = input.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(join2(target, "document.html"), "utf8");
+        const html = typeof input.html === "string" ? input.html : await readFile(join2(target, "document.html"), "utf8");
         const writes = request.method === "POST" ? ["preview.html"] : [];
-        if (typeof item.html === "string") writes.push("document.html");
+        if (typeof input.html === "string") writes.push("document.html");
         const previewBefore = await readFile(join2(target, "preview.html"));
         const temporaryFiles = [];
         try {
@@ -14500,10 +14551,9 @@ async function handleHtmlArtifactRequest(request, response, root2, transformHtml
   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";
+  if (!isRecord2(value)) return false;
+  const viewport = value.viewport;
+  return typeof value.id === "string" && ID.test(value.id) && typeof value.sourceUrl === "string" && value.sourceUrl.length < 4096 && typeof value.title === "string" && value.title.length < 512 && typeof value.html === "string" && value.html.length > 0 && isRecord2(viewport) && typeof viewport.width === "number" && typeof viewport.height === "number";
 }
 
 // src/hosts/static/server.ts
@@ -15858,10 +15908,7 @@ function createStandaloneProjectId(rootDirectory) {
 }
 function contentTypeForPath(filePath) {
   const extension = extname2(filePath).toLowerCase();
-  return MIME_TYPES2[extension] ?? "application/octet-stream";
-}
-function isReservedNudgeUiRoute2(pathname) {
-  return pathname === NUDGE_UI_ROUTE_PREFIX.slice(0, -1) || pathname.startsWith(NUDGE_UI_ROUTE_PREFIX);
+  return MIME_TYPES2.get(extension) ?? "application/octet-stream";
 }
 function canonicalDirectory(directory2) {
   const canonical = canonicalDirectoryOrNull(directory2);
@@ -15944,7 +15991,7 @@ async function handleRequest(input) {
     sendText(response, 400, "Bad Request");
     return;
   }
-  if (isReservedNudgeUiRoute2(decodedPath)) {
+  if (isReservedNudgeUiRoute(decodedPath)) {
     await handleNudgeUiRoute(input, decodedPath);
     return;
   }
@@ -16100,7 +16147,7 @@ function sendBody(response, status, body2, contentType, headers = {}) {
   if (response.req?.method !== "HEAD") response.end(body2);
   else response.end();
 }
-var MIME_TYPES2 = {
+var MIME_TYPES2 = new Map(Object.entries({
   ".avif": "image/avif",
   ".css": "text/css; charset=utf-8",
   ".csv": "text/csv; charset=utf-8",
@@ -16126,7 +16173,7 @@ var MIME_TYPES2 = {
   ".woff": "font/woff",
   ".woff2": "font/woff2",
   ".xml": "application/xml; charset=utf-8"
-};
+}));
 
 // src/hosts/static/cli.ts
 function parseServeArguments(args, currentDirectory = process.cwd()) {

package/dist/project/artifacts.js

@@ -49,6 +49,10 @@ async function directory(root, id) {
     }
     return join(actual, id);
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Both artifact endpoints accept JSON objects only. */
 async function body(request) {
     const chunks = [];
     let size = 0;
@@ -60,7 +64,10 @@ async function body(request) {
         chunks.push(data);
     }
     const text = Buffer.concat(chunks).toString("utf8");
-    return text.length === 0 ? {} : JSON.parse(text);
+    if (text.length === 0)
+        return {};
+    const parsed = JSON.parse(text);
+    return isRecord(parsed) ? parsed : null;
 }
 function respond(response, status, content, type = "text/plain; charset=utf-8") {
     response.writeHead(status, {
@@ -100,7 +107,7 @@ export async function handleHtmlArtifactRequest(request, response, root, transfo
     try {
         if (request.method === "POST" && parts.length === 0) {
             const input = await body(request);
-            if (!validArtifact(input)) {
+            if (!input || !validArtifact(input)) {
                 respond(response, 400, "Invalid artifact");
                 return true;
             }
@@ -159,28 +166,27 @@ export async function handleHtmlArtifactRequest(request, response, root, transfo
             if ((request.method === "PUT" && parts[1] === "document")
                 || (request.method === "POST" && parts[1] === "commit")) {
                 const input = await body(request);
-                if (!input || typeof input !== "object") {
+                if (!input) {
                     respond(response, 400, "Invalid document");
                     return true;
                 }
-                const item = input;
-                if (!isHtmlArtifactRevision(item.expected)) {
+                if (!isHtmlArtifactRevision(input.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")) {
+                if ((input.html !== undefined && typeof input.html !== "string")
+                    || (request.method === "PUT" && typeof input.html !== "string")) {
                     respond(response, 400, "Invalid document");
                     return true;
                 }
-                const expected = item.expected;
+                const expected = input.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 html = typeof input.html === "string" ? input.html : await readFile(join(target, "document.html"), "utf8");
                 const writes = request.method === "POST" ? ["preview.html"] : [];
-                if (typeof item.html === "string")
+                if (typeof input.html === "string")
                     writes.push("document.html");
                 const previewBefore = await readFile(join(target, "preview.html"));
                 const temporaryFiles = [];
@@ -190,9 +196,7 @@ export async function handleHtmlArtifactRequest(request, response, root, transfo
                         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.
+                    // External writers do not join this request queue, so the final check and replacements stay in one critical section.
                     const latest = {
                         document: revision(readFileSync(join(target, "document.html"))),
                         preview: revision(readFileSync(join(target, "preview.html"))),
@@ -241,13 +245,12 @@ export async function handleHtmlArtifactRequest(request, response, root, transfo
     return true;
 }
 function validArtifact(value) {
-    if (!value || typeof value !== "object")
+    if (!isRecord(value))
         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";
+    const viewport = value.viewport;
+    return typeof value.id === "string" && ID.test(value.id)
+        && typeof value.sourceUrl === "string" && value.sourceUrl.length < 4096
+        && typeof value.title === "string" && value.title.length < 512
+        && typeof value.html === "string" && value.html.length > 0
+        && isRecord(viewport) && typeof viewport.width === "number" && typeof viewport.height === "number";
 }

package/dist/project/files.d.ts

@@ -15,5 +15,4 @@ export interface ProjectFileWatcher {
     start(): Promise<void>;
     close(): Promise<void>;
 }
-/** Creates a watcher that starts and stops explicitly with the server. */
 export declare function createProjectFileWatcher(options: ProjectFileWatcherOptions): ProjectFileWatcher;

package/dist/project/files.js

@@ -1,16 +1,10 @@
-/**
- * Node's recursive `fs.watch` is not available on every supported platform, so
- * this watches each directory and adds watches for ones created later. The
- * public surface is lifecycle and settled batches; debounce and symlink
- * confinement stay internal.
- */
+/** Node's recursive `fs.watch` is not available on every supported platform, so directories are watched individually. */
 import { watch } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isExcludedDirectoryName, isSensitiveProjectPath } from "./pathPolicy.js";
 export { isExcludedDirectoryName, isSensitiveProjectPath } from "./pathPolicy.js";
-/** Creates a watcher that starts and stops explicitly with the server. */
 export function createProjectFileWatcher(options) {
     const rootDirectory = realpathSync(resolve(options.rootDirectory));
     const debounceMs = Math.max(0, options.debounceMs ?? 60);
@@ -85,8 +79,7 @@ export function createProjectFileWatcher(options) {
             return;
         }
         watches.set(directory, { directory, canonicalDirectory, watcher: directoryWatcher });
-        // Watch before scanning so events during the async walk are not missed. Scans
-        // run serially and re-check `closed` after every await, so none leak past close().
+        // Watch before scanning so events during the async walk are not missed.
         pendingScans += 1;
         scanQueue = scanQueue
             .then(() => scanSubdirectories(directory))