nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/sketch/SketchWorkspace.js

@@ -16,7 +16,6 @@ import { SketchEditor } from "./SketchEditor.js";
 import { SketchOverlay } from "./SketchOverlay.js";
 import { closeSketchNote, useSketchNote } from "./sketchNote.js";
 import { SketchPromptPanel } from "./SketchPromptPanel.js";
-/** Makes saving a new sketch one step in the session undo history. */
 function recordSketchCreation(document, owner) {
     let snapshot = document;
     recordCanvasChange({
@@ -66,9 +65,8 @@ export function SketchWorkspace({ hostElement, projectId }) {
     const editingDocument = interaction.editingId
         ? store.items.find((item) => item.document.id === interaction.editingId)?.document ?? null
         : null;
-    // IndexedDB hydration is deliberately independent from the localStorage
-    // session schema. A failed hydration leaves the inspector usable and gives
-    // the Changes log a recovery message.
+    // Deliberately independent of the localStorage session schema; a failed
+    // hydration leaves the inspector usable.
     useEffect(() => {
         clearSketchClipboardHandoff();
         closeSketchNote();

package/dist/inspector/sketch/capture.d.ts

@@ -1,3 +1,5 @@
+import { type Options } from "modern-screenshot";
+import { getPngDimensions } from "./raster.js";
 export type SketchCaptureErrorCode = "unsupported" | "cancelled" | "capture-failed" | "processing-timeout";
 export declare class SketchCaptureError extends Error {
     readonly code: SketchCaptureErrorCode;
@@ -29,6 +31,13 @@ export interface SketchCaptureOptions {
     readonly signal?: AbortSignal;
     readonly processingTimeoutMs?: number;
 }
+/** The `domToBlob` call shape this module uses: a node plus render options. */
+export type DomCaptureToBlob = (node: Node, options?: Options) => Promise<Blob>;
+/** Replaces the DOM renderer and PNG reader for callers that cannot rasterize, such as jsdom tests. */
+export interface SketchCaptureResources {
+    readonly toBlob?: DomCaptureToBlob;
+    readonly pngDimensions?: typeof getPngDimensions;
+}
 export interface SketchViewport {
     readonly width: number;
     readonly height: number;
@@ -44,11 +53,11 @@ export interface SketchScrollPosition {
     readonly x: number;
     readonly y: number;
 }
-/** Reads root scrolling from both window and document APIs. */
+/** Browsers expose root scrolling through different APIs. */
 export declare function getSketchScrollPosition(targetWindow: Window): SketchScrollPosition;
 export declare function getSketchViewport(hostElement: HTMLElement): SketchViewport;
-/** Renders the current viewport from its DOM without invoking screen capture permissions. */
-export declare function captureViewport(options: SketchCaptureOptions): Promise<CapturedSketch>;
+/** DOM-rendered, so no screen-capture permission is required. */
+export declare function captureViewport(options: SketchCaptureOptions, resources?: SketchCaptureResources): Promise<CapturedSketch>;
 export declare function createSketchCaptureOperation(options: SketchCaptureOptions): {
     readonly promise: Promise<CapturedSketch>;
     readonly cancel: () => void;

package/dist/inspector/sketch/capture.js

@@ -74,7 +74,7 @@ async function waitForLayout(signal, targetDocument) {
         }
     }
     catch {
-        // Font readiness is best effort; the animation-frame settle still runs.
+        // Font readiness is best effort.
     }
     await waitForAnimationFrame(signal);
     await waitForAnimationFrame(signal);
@@ -89,7 +89,7 @@ function domContentWidth(hostElement) {
 function nonNegativeOffset(...values) {
     return Math.max(0, ...values.filter((value) => Number.isFinite(value)));
 }
-/** Reads root scrolling from both window and document APIs. */
+/** Browsers expose root scrolling through different APIs. */
 export function getSketchScrollPosition(targetWindow) {
     const targetDocument = targetWindow.document;
     const scrollingElement = targetDocument.scrollingElement;
@@ -253,7 +253,9 @@ async function runWithProcessingTimeout(operation, timeoutMs, parentSignal) {
         controller.abort();
     }
 }
-async function captureDomFrame(options, signal) {
+async function captureDomFrame(options, resources, signal) {
+    const toBlob = resources.toBlob ?? domToBlob;
+    const readPngDimensions = resources.pngDimensions ?? getPngDimensions;
     const surface = getSketchSurface(options.hostElement);
     const viewport = domViewportDimensions(options.hostElement);
     let scale = viewport.scale;
@@ -272,7 +274,7 @@ async function captureDomFrame(options, signal) {
         signal?.addEventListener("abort", restore, { once: true });
         let blob;
         try {
-            blob = await domToBlob(surface.document.documentElement, {
+            blob = await toBlob(surface.document.documentElement, {
                 type: "image/png",
                 width: viewport.width,
                 height: viewport.height,
@@ -286,9 +288,8 @@ async function captureDomFrame(options, signal) {
                 filter: (node) => node !== options.hostElement && !isGoogleFontStylesheet(node) && videoFrames.filter(node),
                 features: { restoreScrollPosition: true },
                 timeout: MEDIA_LOAD_TIMEOUT_MS,
-                // Cross-origin Google CSS cannot be read by modern-screenshot. Skipping
-                // its font embedding avoids waiting on a stylesheet that the renderer
-                // cannot serialize anyway; computed font styles still remain inline.
+                // modern-screenshot cannot serialize cross-origin Google CSS; computed
+                // font styles still remain inline.
                 font: hasGoogleFontStylesheet(surface.document) ? false : undefined,
                 onCloneEachNode: (node) => {
                     prepareDomClone(node);
@@ -302,7 +303,7 @@ async function captureDomFrame(options, signal) {
             restore();
         }
         assertNotAborted(signal);
-        const dimensions = await getPngDimensions(blob);
+        const dimensions = await readPngDimensions(blob);
         if (!dimensions
             || dimensions.width > SKETCH_LIMITS.imageEdge
             || dimensions.height > SKETCH_LIMITS.imageEdge) {
@@ -315,8 +316,8 @@ async function captureDomFrame(options, signal) {
     }
     throw new SketchCaptureError("capture-failed", "This viewport is too detailed to save within the 2 MiB image limit.");
 }
-/** Renders the current viewport from its DOM without invoking screen capture permissions. */
-export async function captureViewport(options) {
+/** DOM-rendered, so no screen-capture permission is required. */
+export async function captureViewport(options, resources = {}) {
     if (typeof document === "undefined" || typeof window === "undefined") {
         throw new SketchCaptureError("unsupported", "Viewport capture is only available in a browser.");
     }
@@ -325,7 +326,7 @@ export async function captureViewport(options) {
         const surface = getSketchSurface(options.hostElement);
         const frame = await runWithProcessingTimeout(async (processingSignal) => {
             await waitForLayout(processingSignal, surface.document);
-            return captureDomFrame(options, processingSignal);
+            return captureDomFrame(options, resources, processingSignal);
         }, options.processingTimeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS, options.signal);
         assertNotAborted(options.signal);
         const runtime = getNudgeUiRuntimeConfig();

package/dist/inspector/sketch/copySketch.d.ts

@@ -1,10 +1,4 @@
-/** Copies a saved sketch image automatically after an edit and reports the outcome as a toast. */
 export declare function copySketchImage(image: Blob): Promise<void>;
-/** Copies a sketch image the user asked for; only a failure needs a toast. */
 export declare function copySketchImageOnRequest(image: Blob): Promise<void>;
-/**
- * Starts the clipboard write synchronously (inside the "Done" gesture) and
- * fills it with the image that `save` renders. A failed save skips the toast
- * and rethrows so the caller can show its own error.
- */
+/** A failed save skips the toast and rethrows so the caller can show its own error; the clipboard write starts before `save` resolves. */
 export declare function saveAndCopySketch(save: () => Promise<Blob>): Promise<void>;

package/dist/inspector/sketch/copySketch.js

@@ -7,30 +7,21 @@ function reportCopyFailure(title, error) {
         description: error instanceof Error ? error.message : "The sketch image could not be copied.",
     });
 }
-/**
- * Reports a copy made automatically on save. The toast is the only sign the
- * clipboard changed, so success is announced as well as failure.
- */
+/** The toast is the only sign the clipboard changed, so success is announced too. */
 function reportAutoCopy(copied) {
     void copied.then(() => showToast({ title: "Copied to clipboard" }), (error) => reportCopyFailure("Sketch saved, but not copied", error));
 }
-/** Copies a saved sketch image automatically after an edit and reports the outcome as a toast. */
 export function copySketchImage(image) {
     const copied = copyImageToClipboard(image);
     reportAutoCopy(copied);
     return copied.catch(() => undefined);
 }
-/** Copies a sketch image the user asked for; only a failure needs a toast. */
 export function copySketchImageOnRequest(image) {
     const copied = copyImageToClipboard(image);
     void copied.catch((error) => reportCopyFailure("Sketch not copied", error));
     return copied.catch(() => undefined);
 }
-/**
- * Starts the clipboard write synchronously (inside the "Done" gesture) and
- * fills it with the image that `save` renders. A failed save skips the toast
- * and rethrows so the caller can show its own error.
- */
+/** A failed save skips the toast and rethrows so the caller can show its own error; the clipboard write starts before `save` resolves. */
 export async function saveAndCopySketch(save) {
     let resolveImage = () => undefined;
     let rejectImage = () => undefined;

package/dist/inspector/sketch/drawingTools.d.ts

@@ -1,5 +1,4 @@
 import { type SketchPenColor } from "./model.js";
-/** Drawing mode chosen from the canvas toolbar while the sketch tool is active. */
 export type SketchDrawingTool = "pen" | "eraser" | "rectangle";
 export interface SketchDrawingToolsSnapshot {
     readonly tool: SketchDrawingTool;
@@ -11,7 +10,6 @@ export declare function useSketchDrawingTools(): SketchDrawingToolsSnapshot;
 export declare function setSketchDrawingTool(tool: SketchDrawingTool): void;
 /** Choosing a color implies drawing with it, so the eraser hands back to the pen. */
 export declare function setSketchStrokeColor(color: SketchPenColor): void;
-/** Every sketch session starts with the pen; the chosen color is kept. */
+/** Resets the tool only; the chosen color is kept. */
 export declare function resetSketchDrawingTool(): void;
-/** Restores the default tool and color. */
 export declare function restoreDefaultSketchDrawingTools(): void;

package/dist/inspector/sketch/drawingTools.js

@@ -37,11 +37,10 @@ export function setSketchDrawingTool(tool) {
 export function setSketchStrokeColor(color) {
     publish({ tool: snapshot.tool === "eraser" ? "pen" : snapshot.tool, color });
 }
-/** Every sketch session starts with the pen; the chosen color is kept. */
+/** Resets the tool only; the chosen color is kept. */
 export function resetSketchDrawingTool() {
     setSketchDrawingTool("pen");
 }
-/** Restores the default tool and color. */
 export function restoreDefaultSketchDrawingTools() {
     snapshot = DEFAULT_SNAPSHOT;
 }

package/dist/inspector/sketch/frameHeading.d.ts

@@ -1,9 +1,3 @@
 import { type CanvasCard } from "../canvas/canvasStore.js";
-/**
- * Names the frame an annotated sketch targets, so the PNG stays actionable when
- * a user copies it to an agent without the handoff prompt. Iterations also name
- * their artifact file: the folder ID is the only stable identity an agent can
- * use to find the right iteration, since canvas iteration numbers are live
- * labels that nothing persists.
- */
+/** Iterations also name their artifact folder: iteration numbers are live labels that nothing persists. */
 export declare function sketchFrameHeading(captureUrl: string, frameCards?: readonly CanvasCard[]): string;

package/dist/inspector/sketch/frameHeading.js

@@ -1,7 +1,6 @@
 import { getCanvasCards } from "../canvas/canvasStore.js";
 import { contentSourceUrl } from "../canvas/frameContent.js";
 import { artifactIdFromUrl, htmlTarget } from "../drafts/model.js";
-/** The page path shown in sketch headings; origin, query, and hash stay out. */
 function routePath(url) {
     try {
         return new URL(url).pathname || "/";
@@ -10,13 +9,7 @@ function routePath(url) {
         return url;
     }
 }
-/**
- * Names the frame an annotated sketch targets, so the PNG stays actionable when
- * a user copies it to an agent without the handoff prompt. Iterations also name
- * their artifact file: the folder ID is the only stable identity an agent can
- * use to find the right iteration, since canvas iteration numbers are live
- * labels that nothing persists.
- */
+/** Iterations also name their artifact folder: iteration numbers are live labels that nothing persists. */
 export function sketchFrameHeading(captureUrl, frameCards = getCanvasCards()) {
     const artifactId = artifactIdFromUrl(captureUrl);
     if (!artifactId)

package/dist/inspector/sketch/freehand.d.ts

@@ -9,5 +9,4 @@ export interface SketchSvgLayerProps {
     readonly annotations?: readonly SketchAnnotation[];
     readonly annotationScale?: number;
 }
-/** Renders sketch geometry as DOM-native SVG shapes. */
 export declare function SketchSvgLayer({ strokes, annotations, annotationScale, }: SketchSvgLayerProps): ReactElement;

package/dist/inspector/sketch/freehand.js

@@ -49,7 +49,6 @@ export function sketchStrokePath(stroke, scaleX = 1, scaleY = scaleX) {
         return linePath(stroke.points, scaleX, scaleY);
     return getSvgPathFromStroke(sketchStrokeOutline(stroke, scaleX, scaleY));
 }
-/** Renders sketch geometry as DOM-native SVG shapes. */
 export function SketchSvgLayer({ strokes, annotations = [], annotationScale = 1, }) {
     return (_jsxs("g", { "data-test": "sketch-svg-layer", children: [strokes.map((stroke) => {
                 const path = sketchStrokePath(stroke);

package/dist/inspector/sketch/geometry.d.ts

@@ -11,13 +11,8 @@ export type SketchElementReference = {
     readonly id: string;
 };
 export declare function distanceToSegment(point: SketchPoint, start: SketchPoint, end: SketchPoint): number;
-/** Returns the topmost drawable object under a point in canvas coordinates. */
 export declare function findSketchElementAt(point: SketchPoint, strokes: readonly SketchStroke[], annotations: readonly SketchAnnotation[]): SketchElementReference | null;
 export declare function translateSketchStroke(stroke: SketchStroke, delta: SketchPoint, bounds: SketchBounds): SketchStroke;
 export declare function translateSketchAnnotation(annotation: SketchAnnotation, delta: SketchPoint, bounds: SketchBounds): SketchAnnotation;
-/**
- * Returns the ids of strokes whose drawn line passes within `radius` of the
- * eraser path from `start` to `end`. Rectangles are hit on their outline only,
- * so erasing across the inside of a box leaves it in place.
- */
+/** Rectangles are hit on their outline only, so erasing inside a box leaves it in place. */
 export declare function findErasedSketchStrokeIds(start: SketchPoint, end: SketchPoint, strokes: readonly SketchStroke[], radius: number): string[];

package/dist/inspector/sketch/geometry.js

@@ -37,7 +37,6 @@ function pointBounds(points) {
     }
     return { minX, maxX, minY, maxY };
 }
-/** Returns the topmost drawable object under a point in canvas coordinates. */
 export function findSketchElementAt(point, strokes, annotations) {
     for (let index = annotations.length - 1; index >= 0; index -= 1) {
         const annotation = annotations[index];
@@ -96,11 +95,7 @@ export function translateSketchAnnotation(annotation, delta, bounds) {
         },
     };
 }
-/**
- * Returns the ids of strokes whose drawn line passes within `radius` of the
- * eraser path from `start` to `end`. Rectangles are hit on their outline only,
- * so erasing across the inside of a box leaves it in place.
- */
+/** Rectangles are hit on their outline only, so erasing inside a box leaves it in place. */
 export function findErasedSketchStrokeIds(start, end, strokes, radius) {
     const steps = Math.max(1, Math.ceil(distance(start, end) / Math.max(1, radius / 2)));
     const samples = [];

package/dist/inspector/sketch/handoff.js

@@ -20,7 +20,6 @@ function randomId() {
             return crypto.randomUUID();
     }
     catch {
-        // Use the fallback below.
     }
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }

package/dist/inspector/sketch/history.d.ts

@@ -12,7 +12,6 @@ type SketchHistoryEntry = {
     readonly gesture: number;
     readonly erased: readonly ErasedStroke[];
 };
-/** Strokes plus the undo and redo stacks of the edits that produced them. */
 export interface SketchHistory {
     readonly strokes: readonly SketchStroke[];
     readonly undo: readonly SketchHistoryEntry[];
@@ -20,10 +19,7 @@ export interface SketchHistory {
 }
 export declare const EMPTY_SKETCH_HISTORY: SketchHistory;
 export declare function addSketchStroke(history: SketchHistory, stroke: SketchStroke): SketchHistory;
-/**
- * Erases strokes as one undoable edit. Strokes erased by the same `gesture`
- * share an entry, so one eraser drag undoes in a single step.
- */
+/** Strokes erased by the same `gesture` share one undo entry, so an eraser drag undoes in one step. */
 export declare function eraseSketchStrokes(history: SketchHistory, ids: readonly string[], gesture: number): SketchHistory;
 export declare function undoSketchEdit(history: SketchHistory): SketchHistory;
 export declare function redoSketchEdit(history: SketchHistory): SketchHistory;

package/dist/inspector/sketch/history.js

@@ -17,10 +17,7 @@ function removeStrokes(strokes, ids) {
     });
     return { strokes: remaining, erased };
 }
-/**
- * Erases strokes as one undoable edit. Strokes erased by the same `gesture`
- * share an entry, so one eraser drag undoes in a single step.
- */
+/** Strokes erased by the same `gesture` share one undo entry, so an eraser drag undoes in one step. */
 export function eraseSketchStrokes(history, ids, gesture) {
     const { strokes, erased } = removeStrokes(history.strokes, new Set(ids));
     if (erased.length === 0)

package/dist/inspector/sketch/interaction.d.ts

@@ -1,4 +1,4 @@
-import { type CapturedSketch } from "./capture.js";
+import { captureViewport, type CapturedSketch } from "./capture.js";
 export type SketchCaptureState = "idle" | "sketching" | "capturing" | "ready" | "error";
 export interface SketchInteractionSnapshot {
     readonly captureState: SketchCaptureState;
@@ -13,7 +13,7 @@ export declare function useSketchInteraction(): SketchInteractionSnapshot;
 export declare function isSketchInteractionActive(): boolean;
 export declare function useSketchInteractionActive(): boolean;
 export declare function beginSketchCapture(): void;
-export declare function completeSketchCapture(hostElement: HTMLElement): Promise<CapturedSketch>;
+export declare function completeSketchCapture(hostElement: HTMLElement, capture?: typeof captureViewport): Promise<CapturedSketch>;
 export declare function cancelSketchInteraction(): void;
 export declare function openSketchEditor(sketchId: string): void;
 export declare function closeSketchEditor(): void;

package/dist/inspector/sketch/interaction.js

@@ -44,14 +44,14 @@ export function beginSketchCapture() {
     captureController = null;
     publish({ captureState: "sketching", captured: null, editingId: null, error: null, draftId: getActiveDraftChanges().draftId });
 }
-export function completeSketchCapture(hostElement) {
+export function completeSketchCapture(hostElement, capture = captureViewport) {
     captureController?.abort();
     const controller = new AbortController();
     captureController = controller;
     const draftId = snapshot.draftId;
     publish({ captureState: "capturing", captured: null, editingId: null, error: null, draftId });
     const options = { hostElement, signal: controller.signal };
-    return captureViewport(options)
+    return capture(options)
         .then((captured) => {
         if (captureController !== controller)
             return captured;

package/dist/inspector/sketch/model.d.ts

@@ -17,16 +17,13 @@ export declare const SKETCH_LIMITS: {
     readonly title: 512;
 };
 export declare const SKETCH_STROKE_WIDTH = 6;
-/** Drawn rectangles use a lighter outline than the freehand pen. */
 export declare const SKETCH_RECTANGLE_STROKE_WIDTH = 4;
-/** Opacity of the tint inside a drawn rectangle, in the rectangle's own color. */
 export declare const SKETCH_RECTANGLE_FILL_OPACITY = 0.1;
-/** Default pen color, and the fallback for strokes saved without one. */
 export declare const SKETCH_STROKE_COLOR = "#0096ff";
 /** Annotation markers and the notes panel; independent of the chosen pen color. */
 export declare const SKETCH_ACCENT_COLOR = "#0096ff";
 export declare const SKETCH_STROKE_OUTLINE = "";
-/** Pen palette offered by the canvas toolbar, in clockwise order around its swatch picker. */
+/** Ordered clockwise around the toolbar's swatch picker. */
 export declare const SKETCH_PEN_COLORS: readonly [{
     readonly id: "red";
     readonly name: "Red";
@@ -97,11 +94,7 @@ export interface SketchDocument {
     readonly strokes: readonly SketchStroke[];
     /** Optional for compatibility with sketches saved before annotations existed. */
     readonly annotations?: readonly SketchAnnotation[];
-    /**
-     * Size of `annotatedImage`, which can be taller than the capture when a
-     * notes panel is appended. `capture.imageWidth`/`imageHeight` size the
-     * original screenshot and the stroke coordinate space.
-     */
+    /** Size of `annotatedImage` (grows with a notes panel); `capture.imageWidth`/`imageHeight` size the stroke coordinate space. */
     readonly imageWidth: number;
     readonly imageHeight: number;
     readonly originalByteSize: number;

package/dist/inspector/sketch/model.js

@@ -16,16 +16,13 @@ export const SKETCH_LIMITS = {
     title: 512,
 };
 export const SKETCH_STROKE_WIDTH = 6;
-/** Drawn rectangles use a lighter outline than the freehand pen. */
 export const SKETCH_RECTANGLE_STROKE_WIDTH = 4;
-/** Opacity of the tint inside a drawn rectangle, in the rectangle's own color. */
 export const SKETCH_RECTANGLE_FILL_OPACITY = 0.1;
-/** Default pen color, and the fallback for strokes saved without one. */
 export const SKETCH_STROKE_COLOR = "#0096ff";
 /** Annotation markers and the notes panel; independent of the chosen pen color. */
 export const SKETCH_ACCENT_COLOR = "#0096ff";
 export const SKETCH_STROKE_OUTLINE = "";
-/** Pen palette offered by the canvas toolbar, in clockwise order around its swatch picker. */
+/** Ordered clockwise around the toolbar's swatch picker. */
 export const SKETCH_PEN_COLORS = [
     { id: "red", name: "Red", value: "#f03e1e" },
     { id: "orange", name: "Orange", value: "#ff8a00" },
@@ -35,8 +32,7 @@ export const SKETCH_PEN_COLORS = [
     { id: "green", name: "Green", value: "#1fc85a" },
 ];
 export const SKETCH_ANNOTATION_RADIUS = 16;
-// Keep accepting sketches saved before the annotation color update. Existing
-// PNGs remain unchanged until a user edits and saves them again.
+// Keep accepting sketches saved before the annotation color update.
 const LEGACY_SKETCH_STROKE_COLOR = "#ef4444";
 const LEGACY_SKETCH_STROKE_OUTLINE = "#111827";
 export function createSketchFilename(id, revision) {
@@ -49,19 +45,16 @@ value) {
     return typeof value === "number" && Number.isFinite(value);
 }
 function safeIntegerInRange(
-// Stored sketch fields are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value, minimum, maximum = Number.MAX_SAFE_INTEGER) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum && value <= maximum;
 }
 function boundedString(
-// Stored sketch fields are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value, maximum, allowEmpty = false) {
     return typeof value === "string" && value.length <= maximum && (allowEmpty || value.length > 0);
 }
 function isBlob(
-// Stored sketch images are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value, mimeType) {
     return typeof Blob !== "undefined"
@@ -69,7 +62,6 @@ value, mimeType) {
         && (mimeType === undefined || value.type === mimeType);
 }
 function validHttpUrl(
-// Stored sketch fields are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value, maximum) {
     if (!boundedString(value, maximum))
@@ -83,13 +75,11 @@ value, maximum) {
     }
 }
 function isPlainObject(
-// Stored sketch records are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export function isSketchCaptureMetadata(
-// Capture metadata is read back from storage and parsed here.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))
@@ -130,7 +120,6 @@ value) {
         && safeIntegerInRange(capture.imageHeight, 1, SKETCH_LIMITS.imageEdge);
 }
 export function isSketchPoint(
-// Stored points are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))
@@ -146,7 +135,6 @@ value) {
         && point.y <= SKETCH_LIMITS.imageEdge;
 }
 export function isSketchAnnotation(
-// Stored annotations are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))
@@ -160,7 +148,6 @@ value) {
         && boundedString(annotation.description, SKETCH_LIMITS.description);
 }
 export function isSketchStroke(
-// Stored strokes are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))
@@ -182,7 +169,6 @@ value) {
         && stroke.points.every(isSketchPoint);
 }
 function isSketchStrokeList(
-// Stored stroke lists are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     return Array.isArray(value)
@@ -190,7 +176,6 @@ value) {
         && value.every(isSketchStroke);
 }
 function isSketchAnnotationList(
-// Stored annotation lists are untrusted until this check narrows them.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     return Array.isArray(value)
@@ -198,7 +183,6 @@ value) {
         && value.every(isSketchAnnotation);
 }
 export function isSketchDocument(
-// Sketch documents are read back from storage and parsed here.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))
@@ -248,7 +232,6 @@ value) {
         && document.annotatedImage.size === document.annotatedByteSize;
 }
 export function isSketchHandoffRecord(
-// Handoff records are read back from storage and parsed here.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 value) {
     if (!isPlainObject(value))

package/dist/inspector/sketch/persistence.d.ts

@@ -24,7 +24,6 @@ export interface SketchStorage {
 }
 export declare function configureSketchStorage(storage: SketchStorage | null): void;
 export declare function readSketchPersistence(projectId: string): Promise<SketchPersistenceSnapshot>;
-/** Writes a document and its initial/current handoff atomically. */
 export declare function writeSketchPersistence(projectId: string, document: SketchDocument, handoff: SketchHandoffRecord): Promise<void>;
 export declare function writeSketchHandoff(projectId: string, handoff: SketchHandoffRecord): Promise<void>;
 export declare function writeSketchHandoffs(projectId: string, handoffs: readonly SketchHandoffRecord[]): Promise<void>;

package/dist/inspector/sketch/persistence.js

@@ -62,7 +62,7 @@ async function openDatabase() {
     if (!factory)
         return null;
     // Demo runtimes (the landing page) are session-only: sketches live in the
-    // in-memory fallback and never touch IndexedDB, so every visit starts clean.
+    // in-memory fallback and never touch IndexedDB.
     if (isDemoRuntime())
         return null;
     if (!databasePromise) {
@@ -121,6 +121,7 @@ export async function readSketchPersistence(projectId) {
     try {
         const transaction = database.transaction([SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE], "readonly");
         const done = transactionDone(transaction);
+        // Records come back as stored; the store drops anything that fails validation during hydration.
         const documentsPromise = requestResult(transaction.objectStore(SKETCH_DOCUMENTS_STORE).index("projectId").getAll(projectId));
         const handoffsPromise = requestResult(transaction.objectStore(SKETCH_HANDOFFS_STORE).index("projectId").getAll(projectId));
         const [documents, handoffs] = await Promise.all([documentsPromise, handoffsPromise, done]);
@@ -130,7 +131,6 @@ export async function readSketchPersistence(projectId) {
         throw storageError("Sketch storage could not be read.", error);
     }
 }
-/** Writes a document and its initial/current handoff atomically. */
 export async function writeSketchPersistence(projectId, document, handoff) {
     if (configuredStorage) {
         const change = { documents: [document], handoffs: [handoff] };

package/dist/inspector/sketch/raster.d.ts

@@ -16,10 +16,7 @@ export declare function renderAnnotatedPng(originalImage: Blob, imageWidth: numb
     readonly height: number;
 }>;
 export declare function blobToBase64(blob: Blob): Promise<string>;
-/**
- * Accepts a pending blob so callers can start the write inside the user gesture
- * (required by Safari) and resolve the image once rendering finishes.
- */
+/** The promise form lets callers start the write inside the user gesture (required by Safari). */
 export declare function copyImageToClipboard(blob: Blob | Promise<Blob>): Promise<void>;
 export declare function copyImageAndTextToClipboard(blob: Blob, text: string): Promise<void>;
 export declare function downloadImage(blob: Blob, filename: string): void;

package/dist/inspector/sketch/raster.js

@@ -14,8 +14,7 @@ export function readPngDimensions(bytes) {
         if (bytes[index] !== PNG_SIGNATURE[index])
             return null;
     }
-    // IHDR is the first chunk in every PNG. The dimensions are big-endian at
-    // byte offsets 16 and 20 in the complete file.
+    // IHDR is the first chunk; dimensions are big-endian at byte offsets 16 and 20.
     if (bytes[12] !== 73 || bytes[13] !== 72 || bytes[14] !== 68 || bytes[15] !== 82)
         return null;
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -166,7 +165,6 @@ function wrapText(ctx, text, maxWidth) {
         lines.push(line);
     return lines;
 }
-/** Wraps the frame heading that names the sketch target to the panel width. */
 function wrapSketchHeading(ctx, width, heading) {
     const text = heading.trim();
     if (!text)
@@ -174,7 +172,6 @@ function wrapSketchHeading(ctx, width, heading) {
     ctx.font = SKETCH_NOTE_TITLE_FONT;
     return wrapText(ctx, text, Math.max(1, width - SKETCH_NOTE_PADDING * 2));
 }
-/** Wraps the description and numbered annotation notes to the panel width. */
 function wrapSketchNotes(ctx, width, description, annotations) {
     const notes = [
         description.trim(),
@@ -260,10 +257,7 @@ export async function blobToBase64(blob) {
         throw new Error("This browser cannot prepare sketch attachments.");
     return btoa(binary);
 }
-/**
- * Accepts a pending blob so callers can start the write inside the user gesture
- * (required by Safari) and resolve the image once rendering finishes.
- */
+/** The promise form lets callers start the write inside the user gesture (required by Safari). */
 export async function copyImageToClipboard(blob) {
     if (typeof navigator === "undefined" || !navigator.clipboard?.write || typeof ClipboardItem === "undefined") {
         throw new Error("Image clipboard access is unavailable. Use Download image instead.");

package/dist/inspector/sketch/store.js

@@ -74,7 +74,6 @@ function randomId(prefix) {
         }
     }
     catch {
-        // Fall through to the deterministic-enough browser fallback.
     }
     return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
@@ -300,8 +299,8 @@ export function settleSketchDispatch(batchRevision, state, agentRequestId, local
         if (hydration)
             await hydration;
         assertWritable(projectId, expectedGeneration);
-        // Resolve the current revisions inside the write queue so a pending save
-        // or requeue cannot be removed by an older completion event.
+        // Resolved inside the write queue so an older completion event cannot
+        // remove a pending save or requeue.
         const changes = snapshot.items.flatMap(({ document, handoff }) => {
             if (!handoff || handoff.sketchRevision !== document.revision
                 || handoff.transport !== "direct" || handoff.batchRevision !== batchRevision)