nudge-ui 0.2.0 → 0.2.1

package/dist/inspector/sketch/model.js

@@ -0,0 +1,282 @@
+export const SKETCH_SCHEMA_VERSION = 1;
+export const SKETCH_DATABASE_NAME = "nudge-ui-sketches";
+export const SKETCH_DATABASE_VERSION = 1;
+export const SKETCH_DOCUMENTS_STORE = "documents";
+export const SKETCH_HANDOFFS_STORE = "handoffs";
+export const SKETCH_LIMITS = {
+    completedSketches: 4,
+    imageEdge: 2_048,
+    imageBytes: 2 * 1024 * 1024,
+    projectBytes: 20 * 1024 * 1024,
+    strokes: 500,
+    points: 20_000,
+    annotations: 50,
+    description: 2_000,
+    url: 2_048,
+    title: 512,
+};
+export const SKETCH_STROKE_WIDTH = 6;
+export const SKETCH_STROKE_COLOR = "#0096ff";
+export const SKETCH_STROKE_OUTLINE = "";
+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.
+const LEGACY_SKETCH_STROKE_COLOR = "#ef4444";
+const LEGACY_SKETCH_STROKE_OUTLINE = "#111827";
+export function createSketchFilename(id, revision) {
+    return `sketch-${id}-r${revision}.png`;
+}
+export function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function boundedString(value, maximum, allowEmpty = false) {
+    return typeof value === "string" && value.length <= maximum && (allowEmpty || value.length > 0);
+}
+function isBlob(value, mimeType) {
+    return typeof Blob !== "undefined"
+        && value instanceof Blob
+        && (mimeType === undefined || value.type === mimeType);
+}
+function validHttpUrl(value, maximum) {
+    if (!boundedString(value, maximum))
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export function isSketchCaptureMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const capture = value;
+    const keys = [
+        "url",
+        "title",
+        "timestamp",
+        "viewportWidth",
+        "viewportHeight",
+        "scrollX",
+        "scrollY",
+        "devicePixelRatio",
+        "host",
+        "framework",
+        "imageWidth",
+        "imageHeight",
+    ];
+    if (!Object.keys(capture).every((key) => keys.includes(key)))
+        return false;
+    return validHttpUrl(capture.url, SKETCH_LIMITS.url)
+        && boundedString(capture.title, SKETCH_LIMITS.title, true)
+        && Number.isSafeInteger(capture.timestamp)
+        && capture.timestamp > 0
+        && Number.isSafeInteger(capture.viewportWidth)
+        && capture.viewportWidth > 0
+        && capture.viewportWidth <= 100_000
+        && Number.isSafeInteger(capture.viewportHeight)
+        && capture.viewportHeight > 0
+        && capture.viewportHeight <= 100_000
+        && isFiniteNumber(capture.scrollX)
+        && capture.scrollX >= 0
+        && isFiniteNumber(capture.scrollY)
+        && capture.scrollY >= 0
+        && isFiniteNumber(capture.devicePixelRatio)
+        && capture.devicePixelRatio > 0
+        && capture.devicePixelRatio <= 100
+        && boundedString(capture.host, 128)
+        && boundedString(capture.framework, 128)
+        && Number.isSafeInteger(capture.imageWidth)
+        && capture.imageWidth > 0
+        && capture.imageWidth <= SKETCH_LIMITS.imageEdge
+        && Number.isSafeInteger(capture.imageHeight)
+        && capture.imageHeight > 0
+        && capture.imageHeight <= SKETCH_LIMITS.imageEdge;
+}
+export function isSketchPoint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const point = value;
+    return Object.keys(point).every((key) => key === "x" || key === "y")
+        && isFiniteNumber(point.x)
+        && isFiniteNumber(point.y)
+        && point.x >= 0
+        && point.x <= SKETCH_LIMITS.imageEdge
+        && point.y >= 0
+        && point.y <= SKETCH_LIMITS.imageEdge;
+}
+export function isSketchAnnotation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const annotation = value;
+    return Object.keys(annotation).every((key) => ["id", "number", "point", "description"].includes(key))
+        && boundedString(annotation.id, 256)
+        && Number.isSafeInteger(annotation.number)
+        && annotation.number >= 1
+        && annotation.number <= SKETCH_LIMITS.annotations
+        && isSketchPoint(annotation.point)
+        && boundedString(annotation.description, SKETCH_LIMITS.description);
+}
+export function isSketchStroke(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const stroke = value;
+    return Object.keys(stroke).every((key) => ["id", "kind", "width", "color", "outlineColor", "points"].includes(key))
+        && boundedString(stroke.id, 256)
+        && (stroke.kind === undefined || stroke.kind === "freehand" || stroke.kind === "rectangle")
+        && isFiniteNumber(stroke.width)
+        && stroke.width > 0
+        && stroke.width <= 128
+        && (stroke.color === SKETCH_STROKE_COLOR || stroke.color === LEGACY_SKETCH_STROKE_COLOR)
+        && (stroke.outlineColor === SKETCH_STROKE_OUTLINE || stroke.outlineColor === LEGACY_SKETCH_STROKE_OUTLINE)
+        && Array.isArray(stroke.points)
+        && stroke.points.length > 0
+        && stroke.points.length <= SKETCH_LIMITS.points
+        && stroke.points.every(isSketchPoint);
+}
+export function isSketchDocument(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const document = value;
+    return Object.keys(document).every((key) => [
+        "schemaVersion",
+        "projectId",
+        "id",
+        "revision",
+        "createdAt",
+        "updatedAt",
+        "capture",
+        "description",
+        "strokes",
+        "annotations",
+        "imageWidth",
+        "imageHeight",
+        "originalByteSize",
+        "annotatedByteSize",
+        "filename",
+        "originalImage",
+        "annotatedImage",
+    ].includes(key))
+        && document.schemaVersion === SKETCH_SCHEMA_VERSION
+        && boundedString(document.projectId, 256)
+        && boundedString(document.id, 256)
+        && Number.isSafeInteger(document.revision)
+        && document.revision > 0
+        && Number.isSafeInteger(document.createdAt)
+        && Number.isSafeInteger(document.updatedAt)
+        && isSketchCaptureMetadata(document.capture)
+        && boundedString(document.description, SKETCH_LIMITS.description, true)
+        && Array.isArray(document.strokes)
+        && document.strokes.length <= SKETCH_LIMITS.strokes
+        && document.strokes.every(isSketchStroke)
+        && document.strokes.reduce((total, stroke) => total + stroke.points.length, 0) <= SKETCH_LIMITS.points
+        && (document.annotations === undefined
+            || (Array.isArray(document.annotations)
+                && document.annotations.length <= SKETCH_LIMITS.annotations
+                && document.annotations.every(isSketchAnnotation)
+                && new Set(document.annotations.map((annotation) => annotation.number)).size === document.annotations.length))
+        && document.imageWidth === document.capture.imageWidth
+        && document.imageHeight === document.capture.imageHeight
+        && Number.isSafeInteger(document.originalByteSize)
+        && document.originalByteSize > 0
+        && document.originalByteSize <= SKETCH_LIMITS.imageBytes
+        && Number.isSafeInteger(document.annotatedByteSize)
+        && document.annotatedByteSize > 0
+        && document.annotatedByteSize <= SKETCH_LIMITS.imageBytes
+        && boundedString(document.filename, 256)
+        && isBlob(document.originalImage, "image/png")
+        && isBlob(document.annotatedImage, "image/png")
+        && document.originalImage.size === document.originalByteSize
+        && document.annotatedImage.size === document.annotatedByteSize;
+}
+export function isSketchHandoffRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const handoff = value;
+    return Object.keys(handoff).every((key) => [
+        "id",
+        "projectId",
+        "sketchId",
+        "sketchRevision",
+        "localBatchId",
+        "batchRevision",
+        "transport",
+        "agentRequestId",
+        "timestamp",
+        "state",
+    ].includes(key))
+        && boundedString(handoff.id, 256)
+        && boundedString(handoff.projectId, 256)
+        && boundedString(handoff.sketchId, 256)
+        && Number.isSafeInteger(handoff.sketchRevision)
+        && handoff.sketchRevision > 0
+        && boundedString(handoff.localBatchId, 256)
+        && (handoff.batchRevision === undefined
+            || (Number.isSafeInteger(handoff.batchRevision) && handoff.batchRevision >= 0))
+        && (handoff.transport === "local" || handoff.transport === "clipboard" || handoff.transport === "direct")
+        && (handoff.agentRequestId === undefined || boundedString(handoff.agentRequestId, 256))
+        && Number.isSafeInteger(handoff.timestamp)
+        && (handoff.state === "pending"
+            || handoff.state === "dispatching"
+            || handoff.state === "handing-off"
+            || handoff.state === "needs-review"
+            || handoff.state === "unknown");
+}
+export function cloneSketchDocument(document) {
+    return {
+        ...document,
+        capture: { ...document.capture },
+        strokes: document.strokes.map((stroke) => ({
+            ...stroke,
+            points: stroke.points.map((point) => ({ ...point })),
+        })),
+        ...(document.annotations
+            ? {
+                annotations: document.annotations.map((annotation) => ({
+                    ...annotation,
+                    point: { ...annotation.point },
+                })),
+            }
+            : {}),
+    };
+}
+export function cloneSketchHandoff(handoff) {
+    return { ...handoff };
+}
+export function sketchContentFingerprint(description, strokes, annotations = []) {
+    return JSON.stringify({ description, strokes, annotations });
+}
+export function sameSketchContent(document, description, strokes, annotations = []) {
+    return sketchContentFingerprint(document.description, document.strokes, document.annotations ?? [])
+        === sketchContentFingerprint(description, strokes, annotations);
+}
+export function toAgentSketchMetadata(document) {
+    const annotations = document.annotations?.map((annotation) => ({
+        number: annotation.number,
+        description: annotation.description,
+    }));
+    return {
+        id: document.id,
+        revision: document.revision,
+        filename: document.filename,
+        mimeType: "image/png",
+        width: document.imageWidth,
+        height: document.imageHeight,
+        byteSize: document.annotatedByteSize,
+        capture: {
+            url: document.capture.url,
+            title: document.capture.title,
+            timestamp: document.capture.timestamp,
+            viewportWidth: document.capture.viewportWidth,
+            viewportHeight: document.capture.viewportHeight,
+            scrollX: document.capture.scrollX,
+            scrollY: document.capture.scrollY,
+            devicePixelRatio: document.capture.devicePixelRatio,
+            host: document.capture.host,
+            framework: document.capture.framework,
+        },
+        ...(document.description ? { description: document.description } : {}),
+        ...(annotations?.length ? { annotations } : {}),
+    };
+}

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

@@ -0,0 +1,21 @@
+import { type SketchDocument, type SketchHandoffRecord } from "./model.js";
+export declare class SketchStorageError extends Error {
+    readonly code = "sketch_storage_error";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SketchPersistenceSnapshot {
+    readonly documents: SketchDocument[];
+    readonly handoffs: SketchHandoffRecord[];
+}
+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>;
+export declare function deleteSketchPersistence(projectId: string, sketchId: string): Promise<void>;
+export declare function clearSketchPersistence(projectId: string): Promise<void>;
+export declare function closeSketchDatabase(): Promise<void>;
+/** Test seam for the no-IndexedDB fallback; it does not delete browser data. */
+export declare function resetSketchMemory(): void;

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;