nudge-ui 0.2.4 → 0.2.6

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

@@ -1,12 +1,10 @@
-import { type CapturedSketch } from "./capture.js";
+import { captureViewport, type CapturedSketch } from "./capture.js";
 export type SketchCaptureState = "idle" | "sketching" | "capturing" | "ready" | "error";
-export type SketchEntryTool = "pen" | "annotate";
 export interface SketchInteractionSnapshot {
     readonly captureState: SketchCaptureState;
     readonly captured: CapturedSketch | null;
     readonly editingId: string | null;
     readonly error: string | null;
-    readonly initialTool: SketchEntryTool;
     readonly draftId: string | null;
 }
 export declare function getSketchInteractionSnapshot(): SketchInteractionSnapshot;
@@ -14,8 +12,8 @@ export declare function subscribeSketchInteraction(listener: () => void): () =>
 export declare function useSketchInteraction(): SketchInteractionSnapshot;
 export declare function isSketchInteractionActive(): boolean;
 export declare function useSketchInteractionActive(): boolean;
-export declare function beginSketchCapture(initialTool?: SketchEntryTool): void;
-export declare function completeSketchCapture(hostElement: HTMLElement): Promise<CapturedSketch>;
+export declare function beginSketchCapture(): void;
+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

@@ -1,4 +1,4 @@
-import { getActiveDraftChanges } from "../changes/draftChanges.js";
+import { getActiveDraftChanges } from "../drafts/store.js";
 import { useSyncExternalStore } from "react";
 import { captureViewport, } from "./capture.js";
 const EMPTY_SNAPSHOT = {
@@ -6,7 +6,6 @@ const EMPTY_SNAPSHOT = {
     captured: null,
     editingId: null,
     error: null,
-    initialTool: "pen",
     draftId: null,
 };
 let snapshot = EMPTY_SNAPSHOT;
@@ -40,25 +39,24 @@ export function useSketchInteractionActive() {
     const current = useSketchInteraction();
     return current.captureState !== "idle" || current.captured !== null || current.editingId !== null;
 }
-export function beginSketchCapture(initialTool = "pen") {
+export function beginSketchCapture() {
     captureController?.abort();
     captureController = null;
-    publish({ captureState: "sketching", captured: null, editingId: null, error: null, initialTool, draftId: getActiveDraftChanges().draftId });
+    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 initialTool = snapshot.initialTool;
     const draftId = snapshot.draftId;
-    publish({ captureState: "capturing", captured: null, editingId: null, error: null, initialTool, 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;
         captureController = null;
-        publish({ captureState: "ready", captured, editingId: null, error: null, initialTool, draftId });
+        publish({ captureState: "ready", captured, editingId: null, error: null, draftId });
         return captured;
     })
         .catch((error) => {
@@ -74,7 +72,6 @@ export function completeSketchCapture(hostElement) {
             captured: null,
             editingId: null,
             error: error instanceof Error ? error.message : "The viewport could not be captured.",
-            initialTool,
             draftId,
         });
         throw error;
@@ -88,7 +85,7 @@ export function cancelSketchInteraction() {
 export function openSketchEditor(sketchId) {
     captureController?.abort();
     captureController = null;
-    publish({ captureState: "idle", captured: null, editingId: sketchId, error: null, initialTool: "pen", draftId: null });
+    publish({ captureState: "idle", captured: null, editingId: sketchId, error: null, draftId: null });
 }
 export function closeSketchEditor() {
     if (snapshot.captureState !== "ready" && snapshot.editingId === null)

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

@@ -17,8 +17,39 @@ export declare const SKETCH_LIMITS: {
     readonly title: 512;
 };
 export declare const SKETCH_STROKE_WIDTH = 6;
+export declare const SKETCH_RECTANGLE_STROKE_WIDTH = 4;
+export declare const SKETCH_RECTANGLE_FILL_OPACITY = 0.1;
 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 = "";
+/** Ordered clockwise around the toolbar's swatch picker. */
+export declare const SKETCH_PEN_COLORS: readonly [{
+    readonly id: "red";
+    readonly name: "Red";
+    readonly value: "#f03e1e";
+}, {
+    readonly id: "orange";
+    readonly name: "Orange";
+    readonly value: "#ff8a00";
+}, {
+    readonly id: "blue";
+    readonly name: "Blue";
+    readonly value: "#0096ff";
+}, {
+    readonly id: "black";
+    readonly name: "Black";
+    readonly value: "#242424";
+}, {
+    readonly id: "yellow";
+    readonly name: "Yellow";
+    readonly value: "#ffc800";
+}, {
+    readonly id: "green";
+    readonly name: "Green";
+    readonly value: "#1fc85a";
+}];
+export type SketchPenColor = (typeof SKETCH_PEN_COLORS)[number];
 export declare const SKETCH_ANNOTATION_RADIUS = 16;
 declare const LEGACY_SKETCH_STROKE_COLOR = "#ef4444";
 declare const LEGACY_SKETCH_STROKE_OUTLINE = "#111827";
@@ -29,7 +60,7 @@ export interface SketchPoint {
     readonly x: number;
     readonly y: number;
 }
-type SketchStrokeColor = typeof SKETCH_STROKE_COLOR | typeof LEGACY_SKETCH_STROKE_COLOR;
+export type SketchStrokeColor = SketchPenColor["value"] | typeof LEGACY_SKETCH_STROKE_COLOR;
 type SketchStrokeOutline = typeof SKETCH_STROKE_OUTLINE | typeof LEGACY_SKETCH_STROKE_OUTLINE;
 export type SketchStrokeKind = "freehand" | "rectangle";
 export interface SketchStroke {
@@ -63,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,28 +16,54 @@ export const SKETCH_LIMITS = {
     title: 512,
 };
 export const SKETCH_STROKE_WIDTH = 6;
+export const SKETCH_RECTANGLE_STROKE_WIDTH = 4;
+export const SKETCH_RECTANGLE_FILL_OPACITY = 0.1;
 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 = "";
+/** 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" },
+    { id: "blue", name: "Blue", value: SKETCH_STROKE_COLOR },
+    { id: "black", name: "Black", value: "#242424" },
+    { id: "yellow", name: "Yellow", value: "#ffc800" },
+    { 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) {
     return `sketch-${id}-r${revision}.png`;
 }
-export function isFiniteNumber(value) {
+export function isFiniteNumber(
+// Stored sketch fields are untrusted until this check narrows them.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
     return typeof value === "number" && Number.isFinite(value);
 }
-function boundedString(value, maximum, allowEmpty = false) {
+function safeIntegerInRange(
+// 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(
+// 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(value, mimeType) {
+function isBlob(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value, mimeType) {
     return typeof Blob !== "undefined"
         && value instanceof Blob
         && (mimeType === undefined || value.type === mimeType);
 }
-function validHttpUrl(value, maximum) {
+function validHttpUrl(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value, maximum) {
     if (!boundedString(value, maximum))
         return false;
     try {
@@ -48,9 +74,17 @@ function validHttpUrl(value, maximum) {
         return false;
     }
 }
-export function isSketchCaptureMetadata(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+function isPlainObject(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isSketchCaptureMetadata(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     const capture = value;
     const keys = [
         "url",
@@ -70,14 +104,9 @@ export function isSketchCaptureMetadata(value) {
         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
+        && safeIntegerInRange(capture.timestamp, 1)
+        && safeIntegerInRange(capture.viewportWidth, 1, 100_000)
+        && safeIntegerInRange(capture.viewportHeight, 1, 100_000)
         && isFiniteNumber(capture.scrollX)
         && capture.scrollX >= 0
         && isFiniteNumber(capture.scrollY)
@@ -87,16 +116,15 @@ export function isSketchCaptureMetadata(value) {
         && 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;
+        && safeIntegerInRange(capture.imageWidth, 1, SKETCH_LIMITS.imageEdge)
+        && safeIntegerInRange(capture.imageHeight, 1, SKETCH_LIMITS.imageEdge);
 }
-export function isSketchPoint(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+export function isSketchPoint(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     const point = value;
     return Object.keys(point).every((key) => key === "x" || key === "y")
         && isFiniteNumber(point.x)
@@ -106,21 +134,25 @@ export function isSketchPoint(value) {
         && point.y >= 0
         && point.y <= SKETCH_LIMITS.imageEdge;
 }
-export function isSketchAnnotation(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+export function isSketchAnnotation(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     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
+        && safeIntegerInRange(annotation.number, 1, SKETCH_LIMITS.annotations)
         && isSketchPoint(annotation.point)
         && boundedString(annotation.description, SKETCH_LIMITS.description);
 }
-export function isSketchStroke(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+export function isSketchStroke(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     const stroke = value;
     return Object.keys(stroke).every((key) => ["id", "kind", "width", "color", "outlineColor", "points"].includes(key))
         && boundedString(stroke.id, 256)
@@ -128,16 +160,34 @@ export function isSketchStroke(value) {
         && isFiniteNumber(stroke.width)
         && stroke.width > 0
         && stroke.width <= 128
-        && (stroke.color === SKETCH_STROKE_COLOR || stroke.color === LEGACY_SKETCH_STROKE_COLOR)
+        && (SKETCH_PEN_COLORS.some((color) => color.value === 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))
+function isSketchStrokeList(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    return Array.isArray(value)
+        && value.length <= SKETCH_LIMITS.strokes
+        && value.every(isSketchStroke);
+}
+function isSketchAnnotationList(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    return Array.isArray(value)
+        && value.length <= SKETCH_LIMITS.annotations
+        && value.every(isSketchAnnotation);
+}
+export function isSketchDocument(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     const document = value;
     return Object.keys(document).every((key) => [
         "schemaVersion",
@@ -161,42 +211,32 @@ export function isSketchDocument(value) {
         && 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)
+        && safeIntegerInRange(document.revision, 1)
+        && safeIntegerInRange(document.createdAt, Number.MIN_SAFE_INTEGER)
+        && safeIntegerInRange(document.updatedAt, Number.MIN_SAFE_INTEGER)
         && isSketchCaptureMetadata(document.capture)
         && boundedString(document.description, SKETCH_LIMITS.description, true)
-        && Array.isArray(document.strokes)
-        && document.strokes.length <= SKETCH_LIMITS.strokes
-        && document.strokes.every(isSketchStroke)
+        && isSketchStrokeList(document.strokes)
         && 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)
+            || (isSketchAnnotationList(document.annotations)
                 && new Set(document.annotations.map((annotation) => annotation.number)).size === document.annotations.length))
-        && Number.isSafeInteger(document.imageWidth)
-        && document.imageWidth > 0
-        && document.imageWidth <= SKETCH_LIMITS.imageEdge
-        && Number.isSafeInteger(document.imageHeight)
-        && document.imageHeight > 0
-        && document.imageHeight <= SKETCH_LIMITS.imageEdge
-        && Number.isSafeInteger(document.originalByteSize)
-        && document.originalByteSize > 0
-        && document.originalByteSize <= SKETCH_LIMITS.imageBytes
-        && Number.isSafeInteger(document.annotatedByteSize)
-        && document.annotatedByteSize > 0
-        && document.annotatedByteSize <= SKETCH_LIMITS.imageBytes
+        && safeIntegerInRange(document.imageWidth, 1, SKETCH_LIMITS.imageEdge)
+        && safeIntegerInRange(document.imageHeight, 1, SKETCH_LIMITS.imageEdge)
+        && safeIntegerInRange(document.originalByteSize, 1, SKETCH_LIMITS.imageBytes)
+        && safeIntegerInRange(document.annotatedByteSize, 1, 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))
+export function isSketchHandoffRecord(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isPlainObject(value))
         return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
     const handoff = value;
     return Object.keys(handoff).every((key) => [
         "id",
@@ -213,14 +253,12 @@ export function isSketchHandoffRecord(value) {
         && boundedString(handoff.id, 256)
         && boundedString(handoff.projectId, 256)
         && boundedString(handoff.sketchId, 256)
-        && Number.isSafeInteger(handoff.sketchRevision)
-        && handoff.sketchRevision > 0
+        && safeIntegerInRange(handoff.sketchRevision, 1)
         && boundedString(handoff.localBatchId, 256)
-        && (handoff.batchRevision === undefined
-            || (Number.isSafeInteger(handoff.batchRevision) && handoff.batchRevision >= 0))
+        && (handoff.batchRevision === undefined || safeIntegerInRange(handoff.batchRevision, 0))
         && (handoff.transport === "local" || handoff.transport === "clipboard" || handoff.transport === "direct")
         && (handoff.agentRequestId === undefined || boundedString(handoff.agentRequestId, 256))
-        && Number.isSafeInteger(handoff.timestamp)
+        && safeIntegerInRange(handoff.timestamp, Number.MIN_SAFE_INTEGER)
         && (handoff.state === "pending"
             || handoff.state === "dispatching"
             || handoff.state === "handing-off"

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

@@ -5,12 +5,25 @@ export declare class SketchStorageError extends Error {
         cause?: unknown;
     });
 }
+export declare const SKETCH_STORAGE_FULL_MESSAGE = "Browser storage is full. Remove saved sketches you no longer need, then try again.";
 export interface SketchPersistenceSnapshot {
     readonly documents: SketchDocument[];
     readonly handoffs: SketchHandoffRecord[];
 }
+/** One atomic set of puts and deletes against a project's sketch records. */
+export interface SketchStorageChange {
+    readonly documents?: readonly SketchDocument[];
+    readonly handoffs?: readonly SketchHandoffRecord[];
+    readonly deleteDocumentIds?: readonly string[];
+    readonly deleteHandoffIds?: readonly string[];
+}
+/** Replaces the page origin's IndexedDB for sketches, for example with extension storage. */
+export interface SketchStorage {
+    read(projectId: string): Promise<SketchPersistenceSnapshot>;
+    update(projectId: string, change: SketchStorageChange): Promise<void>;
+}
+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

@@ -1,3 +1,4 @@
+import { isDemoRuntime } from "../runtime/runtimeConfig.js";
 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";
@@ -6,8 +7,30 @@ export class SketchStorageError extends Error {
         this.name = "SketchStorageError";
     }
 }
+export const SKETCH_STORAGE_FULL_MESSAGE = "Browser storage is full. Remove saved sketches you no longer need, then try again.";
+// IndexedDB rejects with a QuotaExceededError; `chrome.storage` with a "quota exceeded" message.
+function isQuotaError(error) {
+    if (error instanceof DOMException && error.name === "QuotaExceededError")
+        return true;
+    return error instanceof Error && /quota/i.test(error.message);
+}
+function storageError(message, error) {
+    return new SketchStorageError(isQuotaError(error) ? SKETCH_STORAGE_FULL_MESSAGE : message, { cause: error });
+}
 const memoryProjects = new Map();
 let databasePromise = null;
+let configuredStorage = null;
+export function configureSketchStorage(storage) {
+    configuredStorage = storage;
+}
+async function updateConfigured(storage, projectId, change, message) {
+    try {
+        await storage.update(projectId, change);
+    }
+    catch (error) {
+        throw storageError(message, error);
+    }
+}
 function memoryState(projectId) {
     let state = memoryProjects.get(projectId);
     if (!state) {
@@ -38,6 +61,10 @@ async function openDatabase() {
     const factory = indexedDbFactory();
     if (!factory)
         return null;
+    // Demo runtimes (the landing page) are session-only: sketches live in the
+    // in-memory fallback and never touch IndexedDB.
+    if (isDemoRuntime())
+        return null;
     if (!databasePromise) {
         databasePromise = new Promise((resolve, reject) => {
             let request;
@@ -69,12 +96,20 @@ async function openDatabase() {
             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 });
+            throw storageError("Sketch storage is unavailable in this browser.", error);
         });
     }
     return databasePromise;
 }
 export async function readSketchPersistence(projectId) {
+    if (configuredStorage) {
+        try {
+            return await configuredStorage.read(projectId);
+        }
+        catch (error) {
+            throw storageError("Sketch storage could not be read.", error);
+        }
+    }
     const database = await openDatabase();
     if (!database) {
         const state = memoryState(projectId);
@@ -86,17 +121,21 @@ 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]);
         return { documents, handoffs };
     }
     catch (error) {
-        throw new SketchStorageError("Sketch storage could not be read.", { cause: error });
+        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] };
+        return updateConfigured(configuredStorage, projectId, change, "Sketch could not be saved to browser storage.");
+    }
     const database = await openDatabase();
     if (!database) {
         const state = memoryState(projectId);
@@ -111,10 +150,13 @@ export async function writeSketchPersistence(projectId, document, handoff) {
         await transactionDone(transaction);
     }
     catch (error) {
-        throw new SketchStorageError("Sketch could not be saved to browser storage.", { cause: error });
+        throw storageError("Sketch could not be saved to browser storage.", error);
     }
 }
 export async function writeSketchHandoff(projectId, handoff) {
+    if (configuredStorage) {
+        return updateConfigured(configuredStorage, projectId, { handoffs: [handoff] }, "Sketch handoff state could not be saved.");
+    }
     const database = await openDatabase();
     if (!database) {
         memoryState(projectId).handoffs.set(handoff.id, handoff);
@@ -126,12 +168,15 @@ export async function writeSketchHandoff(projectId, handoff) {
         await transactionDone(transaction);
     }
     catch (error) {
-        throw new SketchStorageError("Sketch handoff state could not be saved.", { cause: error });
+        throw storageError("Sketch handoff state could not be saved.", error);
     }
 }
 export async function writeSketchHandoffs(projectId, handoffs) {
     if (handoffs.length === 0)
         return;
+    if (configuredStorage) {
+        return updateConfigured(configuredStorage, projectId, { handoffs }, "Sketch handoff state could not be saved.");
+    }
     const database = await openDatabase();
     if (!database) {
         const state = memoryState(projectId);
@@ -145,7 +190,7 @@ export async function writeSketchHandoffs(projectId, handoffs) {
         await transactionDone(transaction);
     }
     catch (error) {
-        throw new SketchStorageError("Sketch handoff state could not be saved.", { cause: error });
+        throw storageError("Sketch handoff state could not be saved.", error);
     }
 }
 export async function deleteSketchPersistence(projectId, sketchId) {
@@ -153,6 +198,10 @@ export async function deleteSketchPersistence(projectId, sketchId) {
     const handoffIds = existing.handoffs
         .filter((handoff) => handoff.sketchId === sketchId)
         .map((handoff) => handoff.id);
+    if (configuredStorage) {
+        const change = { deleteDocumentIds: [sketchId], deleteHandoffIds: handoffIds };
+        return updateConfigured(configuredStorage, projectId, change, "Sketch could not be removed from browser storage.");
+    }
     const database = await openDatabase();
     if (!database) {
         const state = memoryState(projectId);
@@ -168,11 +217,18 @@ export async function deleteSketchPersistence(projectId, sketchId) {
         await transactionDone(transaction);
     }
     catch (error) {
-        throw new SketchStorageError("Sketch could not be removed from browser storage.", { cause: error });
+        throw storageError("Sketch could not be removed from browser storage.", error);
     }
 }
 export async function clearSketchPersistence(projectId) {
     const existing = await readSketchPersistence(projectId);
+    if (configuredStorage) {
+        const change = {
+            deleteDocumentIds: existing.documents.map((document) => document.id),
+            deleteHandoffIds: existing.handoffs.map((handoff) => handoff.id),
+        };
+        return updateConfigured(configuredStorage, projectId, change, "Sketch storage could not be cleared.");
+    }
     const database = await openDatabase();
     if (!database) {
         const state = memoryState(projectId);
@@ -189,7 +245,7 @@ export async function clearSketchPersistence(projectId) {
         await transactionDone(transaction);
     }
     catch (error) {
-        throw new SketchStorageError("Sketch storage could not be cleared.", { cause: error });
+        throw storageError("Sketch storage could not be cleared.", error);
     }
 }
 export async function closeSketchDatabase() {

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

@@ -10,12 +10,13 @@ export declare function drawSketchStroke(ctx: CanvasRenderingContext2D, stroke:
 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;
-export declare function renderAnnotatedPng(originalImage: Blob, imageWidth: number, imageHeight: number, strokes: readonly SketchStroke[], annotations?: readonly SketchAnnotation[], description?: string): Promise<{
+export declare function renderAnnotatedPng(originalImage: Blob, imageWidth: number, imageHeight: number, strokes: readonly SketchStroke[], annotations?: readonly SketchAnnotation[], description?: string, heading?: string): 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>;
+/** 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;