nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/sketch/persistence.js

@@ -0,0 +1,205 @@
+import { SKETCH_DATABASE_NAME, SKETCH_DATABASE_VERSION, SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE, } from "./model.js";
+export class SketchStorageError extends Error {
+    code = "sketch_storage_error";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SketchStorageError";
+    }
+}
+const memoryProjects = new Map();
+let databasePromise = null;
+function memoryState(projectId) {
+    let state = memoryProjects.get(projectId);
+    if (!state) {
+        state = { documents: new Map(), handoffs: new Map() };
+        memoryProjects.set(projectId, state);
+    }
+    return state;
+}
+function indexedDbFactory() {
+    if (typeof indexedDB === "undefined")
+        return null;
+    return indexedDB;
+}
+function requestResult(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed."));
+    });
+}
+function transactionDone(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed."));
+        transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction was aborted."));
+    });
+}
+async function openDatabase() {
+    const factory = indexedDbFactory();
+    if (!factory)
+        return null;
+    if (!databasePromise) {
+        databasePromise = new Promise((resolve, reject) => {
+            let request;
+            try {
+                request = factory.open(SKETCH_DATABASE_NAME, SKETCH_DATABASE_VERSION);
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            request.onupgradeneeded = () => {
+                const database = request.result;
+                if (!database.objectStoreNames.contains(SKETCH_DOCUMENTS_STORE)) {
+                    const documents = database.createObjectStore(SKETCH_DOCUMENTS_STORE, { keyPath: "id" });
+                    documents.createIndex("projectId", "projectId", { unique: false });
+                }
+                if (!database.objectStoreNames.contains(SKETCH_HANDOFFS_STORE)) {
+                    const handoffs = database.createObjectStore(SKETCH_HANDOFFS_STORE, { keyPath: "id" });
+                    handoffs.createIndex("projectId", "projectId", { unique: false });
+                    handoffs.createIndex("sketchKey", ["sketchId", "sketchRevision"], { unique: false });
+                }
+            };
+            request.onsuccess = () => {
+                const database = request.result;
+                database.onversionchange = () => database.close();
+                resolve(database);
+            };
+            request.onerror = () => reject(request.error ?? new Error("IndexedDB could not be opened."));
+            request.onblocked = () => reject(new Error("IndexedDB upgrade is blocked by another tab."));
+        }).catch((error) => {
+            databasePromise = null;
+            throw new SketchStorageError("Sketch storage is unavailable in this browser.", { cause: error });
+        });
+    }
+    return databasePromise;
+}
+export async function readSketchPersistence(projectId) {
+    const database = await openDatabase();
+    if (!database) {
+        const state = memoryState(projectId);
+        return {
+            documents: [...state.documents.values()],
+            handoffs: [...state.handoffs.values()],
+        };
+    }
+    try {
+        const transaction = database.transaction([SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE], "readonly");
+        const done = transactionDone(transaction);
+        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]);
+        return { documents, handoffs };
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch storage could not be read.", { cause: error });
+    }
+}
+/** Writes a document and its initial/current handoff atomically. */
+export async function writeSketchPersistence(projectId, document, handoff) {
+    const database = await openDatabase();
+    if (!database) {
+        const state = memoryState(projectId);
+        state.documents.set(document.id, document);
+        state.handoffs.set(handoff.id, handoff);
+        return;
+    }
+    try {
+        const transaction = database.transaction([SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE], "readwrite");
+        transaction.objectStore(SKETCH_DOCUMENTS_STORE).put(document);
+        transaction.objectStore(SKETCH_HANDOFFS_STORE).put(handoff);
+        await transactionDone(transaction);
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch could not be saved to browser storage.", { cause: error });
+    }
+}
+export async function writeSketchHandoff(projectId, handoff) {
+    const database = await openDatabase();
+    if (!database) {
+        memoryState(projectId).handoffs.set(handoff.id, handoff);
+        return;
+    }
+    try {
+        const transaction = database.transaction(SKETCH_HANDOFFS_STORE, "readwrite");
+        transaction.objectStore(SKETCH_HANDOFFS_STORE).put(handoff);
+        await transactionDone(transaction);
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch handoff state could not be saved.", { cause: error });
+    }
+}
+export async function writeSketchHandoffs(projectId, handoffs) {
+    if (handoffs.length === 0)
+        return;
+    const database = await openDatabase();
+    if (!database) {
+        const state = memoryState(projectId);
+        handoffs.forEach((handoff) => state.handoffs.set(handoff.id, handoff));
+        return;
+    }
+    try {
+        const transaction = database.transaction(SKETCH_HANDOFFS_STORE, "readwrite");
+        const store = transaction.objectStore(SKETCH_HANDOFFS_STORE);
+        handoffs.forEach((handoff) => store.put(handoff));
+        await transactionDone(transaction);
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch handoff state could not be saved.", { cause: error });
+    }
+}
+export async function deleteSketchPersistence(projectId, sketchId) {
+    const existing = await readSketchPersistence(projectId);
+    const handoffIds = existing.handoffs
+        .filter((handoff) => handoff.sketchId === sketchId)
+        .map((handoff) => handoff.id);
+    const database = await openDatabase();
+    if (!database) {
+        const state = memoryState(projectId);
+        state.documents.delete(sketchId);
+        handoffIds.forEach((id) => state.handoffs.delete(id));
+        return;
+    }
+    try {
+        const transaction = database.transaction([SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE], "readwrite");
+        transaction.objectStore(SKETCH_DOCUMENTS_STORE).delete(sketchId);
+        const handoffs = transaction.objectStore(SKETCH_HANDOFFS_STORE);
+        handoffIds.forEach((id) => handoffs.delete(id));
+        await transactionDone(transaction);
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch could not be removed from browser storage.", { cause: error });
+    }
+}
+export async function clearSketchPersistence(projectId) {
+    const existing = await readSketchPersistence(projectId);
+    const database = await openDatabase();
+    if (!database) {
+        const state = memoryState(projectId);
+        state.documents.clear();
+        state.handoffs.clear();
+        return;
+    }
+    try {
+        const transaction = database.transaction([SKETCH_DOCUMENTS_STORE, SKETCH_HANDOFFS_STORE], "readwrite");
+        const documents = transaction.objectStore(SKETCH_DOCUMENTS_STORE);
+        const handoffs = transaction.objectStore(SKETCH_HANDOFFS_STORE);
+        existing.documents.forEach((document) => documents.delete(document.id));
+        existing.handoffs.forEach((handoff) => handoffs.delete(handoff.id));
+        await transactionDone(transaction);
+    }
+    catch (error) {
+        throw new SketchStorageError("Sketch storage could not be cleared.", { cause: error });
+    }
+}
+export async function closeSketchDatabase() {
+    if (!databasePromise)
+        return;
+    const database = await databasePromise.catch(() => null);
+    database?.close();
+    databasePromise = null;
+}
+/** Test seam for the no-IndexedDB fallback; it does not delete browser data. */
+export function resetSketchMemory() {
+    memoryProjects.clear();
+}

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

@@ -0,0 +1,22 @@
+import { type SketchAnnotation, type SketchStroke } from "./model.js";
+export interface PngDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+export declare function readPngDimensions(bytes: Uint8Array): PngDimensions | null;
+export declare function getPngDimensions(blob: Blob): Promise<PngDimensions | null>;
+export declare function validatePngBlob(blob: Blob, expected?: PngDimensions): Promise<PngDimensions>;
+export declare function drawSketchStroke(ctx: CanvasRenderingContext2D, stroke: Pick<SketchStroke, "points" | "width"> & Partial<Pick<SketchStroke, "kind" | "color">>, scaleX?: number, scaleY?: number): void;
+export declare function drawSketchStrokes(ctx: CanvasRenderingContext2D, strokes: readonly SketchStroke[], scaleX?: number, scaleY?: number): void;
+export declare function drawSketchAnnotation(ctx: CanvasRenderingContext2D, annotation: Pick<SketchAnnotation, "number" | "point">, scaleX?: number, scaleY?: number): void;
+export declare function drawSketchAnnotations(ctx: CanvasRenderingContext2D, annotations: readonly SketchAnnotation[], scaleX?: number, scaleY?: number): void;
+/** Renders the immutable screenshot and committed strokes into one PNG. */
+export declare function renderAnnotatedPng(originalImage: Blob, imageWidth: number, imageHeight: number, strokes: readonly SketchStroke[], annotations?: readonly SketchAnnotation[]): Promise<{
+    readonly blob: Blob;
+    readonly width: number;
+    readonly height: number;
+}>;
+export declare function blobToBase64(blob: Blob): Promise<string>;
+export declare function copyImageToClipboard(blob: 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

@@ -0,0 +1,203 @@
+import { SKETCH_ANNOTATION_RADIUS, SKETCH_LIMITS, SKETCH_STROKE_COLOR, } from "./model.js";
+import { sketchStrokeOutline } from "./freehand.js";
+const PNG_SIGNATURE = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+export function readPngDimensions(bytes) {
+    if (bytes.length < 24)
+        return null;
+    for (let index = 0; index < PNG_SIGNATURE.length; index += 1) {
+        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.
+    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);
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    if (!width || !height)
+        return null;
+    return { width, height };
+}
+export async function getPngDimensions(blob) {
+    return readPngDimensions(new Uint8Array(await blob.slice(0, 24).arrayBuffer()));
+}
+export async function validatePngBlob(blob, expected) {
+    if (blob.type !== "image/png" || blob.size <= 0 || blob.size > SKETCH_LIMITS.imageBytes) {
+        throw new Error("Sketch images must be PNG files smaller than 2 MiB.");
+    }
+    const dimensions = await getPngDimensions(blob);
+    if (!dimensions
+        || dimensions.width > SKETCH_LIMITS.imageEdge
+        || dimensions.height > SKETCH_LIMITS.imageEdge) {
+        throw new Error("Sketch images must be valid PNGs no larger than 2048 pixels on an edge.");
+    }
+    if (expected && (expected.width !== dimensions.width || expected.height !== dimensions.height)) {
+        throw new Error("The sketch image dimensions do not match its capture metadata.");
+    }
+    return dimensions;
+}
+function drawPointPath(ctx, points, scaleX, scaleY) {
+    const first = points[0];
+    if (!first)
+        return;
+    ctx.beginPath();
+    ctx.moveTo(first.x * scaleX, first.y * scaleY);
+    for (let index = 1; index < points.length; index += 1) {
+        const point = points[index];
+        ctx.lineTo(point.x * scaleX, point.y * scaleY);
+    }
+    if (points.length === 1) {
+        ctx.lineTo(first.x * scaleX + 0.01, first.y * scaleY + 0.01);
+    }
+}
+export function drawSketchStroke(ctx, stroke, scaleX = 1, scaleY = scaleX) {
+    if (stroke.points.length === 0)
+        return;
+    ctx.save();
+    if (stroke.kind === "rectangle") {
+        ctx.lineCap = "round";
+        ctx.lineJoin = "round";
+        ctx.strokeStyle = stroke.color || SKETCH_STROKE_COLOR;
+        ctx.lineWidth = stroke.width * Math.max(scaleX, scaleY);
+        drawPointPath(ctx, stroke.points, scaleX, scaleY);
+        ctx.stroke();
+    }
+    else {
+        const outline = sketchStrokeOutline(stroke, scaleX, scaleY);
+        const first = outline[0];
+        if (first) {
+            ctx.beginPath();
+            ctx.moveTo(first[0], first[1]);
+            for (const point of outline.slice(1))
+                ctx.lineTo(point[0], point[1]);
+            ctx.closePath();
+            ctx.fillStyle = stroke.color || SKETCH_STROKE_COLOR;
+            ctx.fill();
+        }
+    }
+    ctx.restore();
+}
+export function drawSketchStrokes(ctx, strokes, scaleX = 1, scaleY = scaleX) {
+    for (const stroke of strokes)
+        drawSketchStroke(ctx, stroke, scaleX, scaleY);
+}
+export function drawSketchAnnotation(ctx, annotation, scaleX = 1, scaleY = scaleX) {
+    const scale = Math.max(scaleX, scaleY);
+    const x = annotation.point.x * scaleX;
+    const y = annotation.point.y * scaleY;
+    const radius = SKETCH_ANNOTATION_RADIUS * scale;
+    ctx.save();
+    ctx.fillStyle = SKETCH_STROKE_COLOR;
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = "#ffffff";
+    ctx.font = `600 ${12 * scale}px system-ui, sans-serif`;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(String(annotation.number), x, y);
+    ctx.restore();
+}
+export function drawSketchAnnotations(ctx, annotations, scaleX = 1, scaleY = scaleX) {
+    for (const annotation of annotations) {
+        drawSketchAnnotation(ctx, annotation, scaleX, scaleY);
+    }
+}
+async function loadImage(blob) {
+    if (typeof createImageBitmap === "function") {
+        const bitmap = await createImageBitmap(blob);
+        return { source: bitmap, close: () => bitmap.close() };
+    }
+    if (typeof Image === "undefined" || typeof URL === "undefined") {
+        throw new Error("This browser cannot decode sketch images.");
+    }
+    const url = URL.createObjectURL(blob);
+    try {
+        const image = await new Promise((resolve, reject) => {
+            const element = new Image();
+            element.onload = () => resolve(element);
+            element.onerror = () => reject(new Error("The sketch screenshot could not be decoded."));
+            element.src = url;
+        });
+        return { source: image, close: () => URL.revokeObjectURL(url) };
+    }
+    catch (error) {
+        URL.revokeObjectURL(url);
+        throw error;
+    }
+}
+function canvasPng(canvas) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (blob)
+                resolve(blob);
+            else
+                reject(new Error("The browser could not encode the sketch as PNG."));
+        }, "image/png");
+    });
+}
+/** Renders the immutable screenshot and committed strokes into one PNG. */
+export async function renderAnnotatedPng(originalImage, imageWidth, imageHeight, strokes, annotations = []) {
+    await validatePngBlob(originalImage, { width: imageWidth, height: imageHeight });
+    if (typeof document === "undefined")
+        throw new Error("Sketch rendering requires a browser document.");
+    const image = await loadImage(originalImage);
+    try {
+        const canvas = document.createElement("canvas");
+        canvas.width = imageWidth;
+        canvas.height = imageHeight;
+        const context = canvas.getContext("2d");
+        if (!context)
+            throw new Error("The browser could not create a sketch canvas.");
+        context.drawImage(image.source, 0, 0, imageWidth, imageHeight);
+        drawSketchStrokes(context, strokes);
+        drawSketchAnnotations(context, annotations);
+        const result = await canvasPng(canvas);
+        if (result.size > SKETCH_LIMITS.imageBytes) {
+            throw new Error("This sketch is too detailed to save within the 2 MiB image limit.");
+        }
+        return { blob: result, width: imageWidth, height: imageHeight };
+    }
+    finally {
+        image.close();
+    }
+}
+export async function blobToBase64(blob) {
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(offset, Math.min(offset + chunkSize, bytes.length)));
+    }
+    if (typeof btoa !== "function")
+        throw new Error("This browser cannot prepare sketch attachments.");
+    return btoa(binary);
+}
+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.");
+    }
+    await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })]);
+}
+export async function copyImageAndTextToClipboard(blob, text) {
+    if (typeof navigator === "undefined" || !navigator.clipboard?.write || typeof ClipboardItem === "undefined") {
+        throw new Error("Combined image and text clipboard access is unavailable. Copy the prompt and image separately.");
+    }
+    await navigator.clipboard.write([
+        new ClipboardItem({
+            "image/png": blob,
+            "text/plain": new Blob([text], { type: "text/plain" }),
+        }),
+    ]);
+}
+export function downloadImage(blob, filename) {
+    if (typeof document === "undefined" || typeof URL === "undefined")
+        return;
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}

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

@@ -0,0 +1,10 @@
+interface SketchNoteSnapshot {
+    readonly sketchId: string | null;
+}
+export declare function getSketchNoteSnapshot(): SketchNoteSnapshot;
+export declare function subscribeSketchNote(listener: () => void): () => void;
+export declare function useSketchNote(): SketchNoteSnapshot;
+export declare function openSketchNote(sketchId: string): void;
+export declare function closeSketchNote(): void;
+export declare function resetSketchNote(): void;
+export {};

package/dist/inspector/sketch/sketchNote.js

@@ -0,0 +1,30 @@
+import { useSyncExternalStore } from "react";
+const EMPTY_SNAPSHOT = { sketchId: null };
+let snapshot = EMPTY_SNAPSHOT;
+const listeners = new Set();
+function publish(next) {
+    snapshot = next;
+    for (const listener of listeners)
+        listener();
+}
+export function getSketchNoteSnapshot() {
+    return snapshot;
+}
+export function subscribeSketchNote(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function useSketchNote() {
+    return useSyncExternalStore(subscribeSketchNote, getSketchNoteSnapshot, getSketchNoteSnapshot);
+}
+export function openSketchNote(sketchId) {
+    publish({ sketchId });
+}
+export function closeSketchNote() {
+    if (snapshot.sketchId === null)
+        return;
+    publish(EMPTY_SNAPSHOT);
+}
+export function resetSketchNote() {
+    snapshot = EMPTY_SNAPSHOT;
+}

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

@@ -0,0 +1,47 @@
+import { toAgentSketchMetadata, type SketchCaptureMetadata, type SketchAnnotation, type SketchDocument, type SketchHandoffRecord, type SketchQueueItem, type SketchStroke } from "./model.js";
+export interface SaveSketchInput {
+    readonly id?: string;
+    readonly capture: SketchCaptureMetadata;
+    readonly description: string;
+    readonly strokes: readonly SketchStroke[];
+    readonly annotations?: readonly SketchAnnotation[];
+    readonly imageWidth: number;
+    readonly imageHeight: number;
+    readonly originalImage: Blob;
+    readonly annotatedImage: Blob;
+}
+export interface SketchStoreSnapshot {
+    readonly projectId: string | null;
+    readonly ready: boolean;
+    readonly documents: readonly SketchDocument[];
+    readonly handoffs: readonly SketchHandoffRecord[];
+    readonly items: readonly SketchQueueItem[];
+    readonly error: string | null;
+}
+export declare function getSketchStoreSnapshot(): SketchStoreSnapshot;
+export declare function subscribeSketchStore(listener: () => void): () => void;
+export declare function useSketchStore(): SketchStoreSnapshot;
+export declare function useSketches(): readonly SketchQueueItem[];
+export declare function getSketches(): readonly SketchQueueItem[];
+export declare function getPendingSketches(): readonly SketchQueueItem[];
+export declare function getSketch(sketchId: string): SketchQueueItem | null;
+export declare function initializeSketchStore(projectId?: string): Promise<void>;
+export declare function saveSketch(input: SaveSketchInput): Promise<SketchDocument>;
+export declare function markSketchesDispatching(entries: readonly {
+    readonly id: string;
+    readonly revision: number;
+}[], batchRevision: number, localBatchId: string): Promise<boolean>;
+export declare function markSketchesHandingOff(entries: readonly {
+    readonly id: string;
+    readonly revision: number;
+}[], batchRevision: number, localBatchId: string, agentRequestId?: string): Promise<boolean>;
+export declare function settleSketchDispatch(batchRevision: number | undefined, state: "working" | "completed" | "failed" | "interrupted", agentRequestId?: string, localBatchId?: string): Promise<boolean>;
+export declare function markSketchesHandedOff(entries: readonly {
+    readonly id: string;
+    readonly revision: number;
+}[], localBatchId?: string): Promise<boolean>;
+export declare function requeueSketch(sketchId: string): Promise<boolean>;
+export declare function removeSketch(sketchId: string): Promise<boolean>;
+export declare function clearSketchesForProject(projectId?: string): Promise<void>;
+export declare function sketchMetadataFor(items: readonly SketchQueueItem[]): ReturnType<typeof toAgentSketchMetadata>[];
+export declare function resetSketchStore(): void;