@bendyline/squisq-editor-react 1.6.2 → 2.0.0

package/src/editorScrollSync.ts

@@ -0,0 +1,73 @@
+/**
+ * Scroll-position handoff between the WYSIWYG and source editors.
+ *
+ * The two surfaces render the same document at very different heights, so a
+ * normalized position is a better shared currency than raw pixels. Keeping
+ * these adapters separate from EditorContext also makes the DOM/Monaco math
+ * independently testable.
+ */
+
+interface MonacoScrollEditor {
+  getScrollTop(): number;
+  getScrollHeight(): number;
+  getLayoutInfo(): { height: number };
+  setScrollTop(scrollTop: number): void;
+}
+
+interface WysiwygScrollEditor {
+  view: { dom: Element };
+}
+
+function clampRatio(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+export function scrollRatio(
+  scrollTop: number,
+  scrollHeight: number,
+  viewportHeight: number,
+): number {
+  const availableScroll = scrollHeight - viewportHeight;
+  if (availableScroll <= 0) return 0;
+  return clampRatio(scrollTop / availableScroll);
+}
+
+export function scrollTopForRatio(
+  ratio: number,
+  scrollHeight: number,
+  viewportHeight: number,
+): number {
+  return clampRatio(ratio) * Math.max(0, scrollHeight - viewportHeight);
+}
+
+export function readMonacoScrollRatio(editor: MonacoScrollEditor): number {
+  return scrollRatio(
+    editor.getScrollTop(),
+    editor.getScrollHeight(),
+    editor.getLayoutInfo().height,
+  );
+}
+
+export function restoreMonacoScrollRatio(editor: MonacoScrollEditor, ratio: number): void {
+  editor.setScrollTop(
+    scrollTopForRatio(ratio, editor.getScrollHeight(), editor.getLayoutInfo().height),
+  );
+}
+
+function findWysiwygScrollElement(editor: WysiwygScrollEditor): HTMLElement | null {
+  return editor.view.dom.closest<HTMLElement>('.squisq-wysiwyg-container');
+}
+
+export function readWysiwygScrollRatio(editor: WysiwygScrollEditor): number | null {
+  const element = findWysiwygScrollElement(editor);
+  if (!element) return null;
+  return scrollRatio(element.scrollTop, element.scrollHeight, element.clientHeight);
+}
+
+export function restoreWysiwygScrollRatio(editor: WysiwygScrollEditor, ratio: number): boolean {
+  const element = findWysiwygScrollElement(editor);
+  if (!element) return false;
+  element.scrollTop = scrollTopForRatio(ratio, element.scrollHeight, element.clientHeight);
+  return true;
+}

package/src/emojiData.ts

@@ -13,7 +13,7 @@
  * lookup; the user can paste anything we don't have.
  */
 
-export interface EmojiEntry {
+interface EmojiEntry {
   /** The actual emoji glyph (may be multi-codepoint, e.g. ZWJ sequences). */
   char: string;
   /** Display name shown in the tooltip. */
@@ -22,7 +22,7 @@ export interface EmojiEntry {
   keywords: string;
 }
 
-export interface EmojiCategory {
+interface EmojiCategory {
   id: string;
   label: string;
   /** Single-glyph icon shown on the tab. */
@@ -34,7 +34,7 @@ function e(char: string, name: string, ...kw: string[]): EmojiEntry {
   return { char, name, keywords: [name, ...kw].join(' ').toLowerCase() };
 }
 
-export const EMOJI_CATEGORIES: EmojiCategory[] = [
+const EMOJI_CATEGORIES: EmojiCategory[] = [
   {
     id: 'smileys',
     label: 'Smileys',
@@ -1216,26 +1216,6 @@ export const EMOJI_CATEGORIES: EmojiCategory[] = [
   },
 ];
 
-/**
- * Flat list of every emoji across all categories — used as the search
- * corpus and to expose a `getEmojiByChar` lookup.
- */
-export const ALL_EMOJIS: EmojiEntry[] = EMOJI_CATEGORIES.flatMap((c) => c.emojis);
-
-/** Search for emoji whose name or keywords contain the query (case-insensitive). */
-export function searchEmojis(query: string, limit = 80): EmojiEntry[] {
-  const q = query.trim().toLowerCase();
-  if (!q) return [];
-  const out: EmojiEntry[] = [];
-  for (const entry of ALL_EMOJIS) {
-    if (entry.keywords.includes(q)) {
-      out.push(entry);
-      if (out.length >= limit) break;
-    }
-  }
-  return out;
-}
-
 // ── Unified picker entries (emoji + FontAwesome icons) ─────────────
 
 import { ICONS } from '@bendyline/squisq/icons';

package/src/headingTransition.ts

@@ -276,21 +276,6 @@ export function setHeadingAttrsTransition(
   };
 }
 
-/**
- * Legacy single-channel writer for callers that only own `dataBlockAttrs`.
- * Internal editor surfaces should use {@link setHeadingAttrsTransition} so new
- * transition edits land in the squisq-native `{[…]}` params.
- */
-export function setBlockAttrsTransition(
-  blockAttrsInner: string | null | undefined,
-  next: TransitionFields,
-): string | null {
-  const attrs: HeadingAttributes = blockAttrsInner ? parsePandocAttrTokens(blockAttrsInner) : {};
-  attrs.params = applyFieldsToParams(attrs.params ?? {}, next);
-  const pandoc = pandocBlockOrNull(attrs);
-  return pandoc ? pandoc.slice(1, -1) : null;
-}
-
 // ============================================
 // shared
 // ============================================

package/src/imageEditor/CanvasSurface.tsx

@@ -15,7 +15,7 @@
  * the canvas is the viewport and `blockTime` is 0 (no animation).
  */
 
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
 import { PathLayer } from '@bendyline/squisq-react';
 import type { ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
 import type { CanvasRect, ImageEditorAction, ImageEditorTool } from './state.js';
@@ -97,6 +97,7 @@ export function CanvasSurface({
   surfaceRef,
   requestEditLayerId,
 }: CanvasSurfaceProps) {
+  const checkerId = `squisq-image-editor-checker-${useId().replace(/:/g, '')}`;
   const svgRef = useRef<SVGSVGElement | null>(null);
   const dragRef = useRef<DragState | null>(null);
   const [, forceRender] = useState(0);
@@ -402,16 +403,11 @@ export function CanvasSurface({
             fill={
               doc.canvas.background && doc.canvas.background !== 'transparent'
                 ? doc.canvas.background
-                : 'url(#squisq-image-editor-checker)'
+                : `url(#${checkerId})`
             }
           />
           <defs>
-            <pattern
-              id="squisq-image-editor-checker"
-              width="16"
-              height="16"
-              patternUnits="userSpaceOnUse"
-            >
+            <pattern id={checkerId} width="16" height="16" patternUnits="userSpaceOnUse">
               <rect width="16" height="16" fill="#f0f0f0" />
               <rect width="8" height="8" fill="#d0d0d0" />
               <rect x="8" y="8" width="8" height="8" fill="#d0d0d0" />
@@ -461,9 +457,16 @@ export function CanvasSurface({
           })}
 
           {/* Selection handles */}
-          {selectedLayer && paddedSelectionBox && tool === 'select' && !selectedLayer.locked && (
-            <SelectionHandles box={paddedSelectionBox} onHandlePointerDown={onPointerDownHandle} />
-          )}
+          {selectedLayer &&
+            paddedSelectionBox &&
+            tool === 'select' &&
+            !selectedLayer.locked &&
+            editingLayerId !== selectedLayer.id && (
+              <SelectionHandles
+                box={paddedSelectionBox}
+                onHandlePointerDown={onPointerDownHandle}
+              />
+            )}
 
           {/* Inline text editor — foreignObject overlays the hidden text layer */}
           {editingLayerId &&
@@ -471,16 +474,16 @@ export function CanvasSurface({
               const editLayer = doc.layers.find((l) => l.id === editingLayerId);
               if (!editLayer || editLayer.type !== 'text') return null;
               const pos = layerBox(editLayer, doc);
-              const s = (editLayer as ImageEditLayer & { type: 'text' }).content;
-              // Give generous height so text can grow without being clipped.
-              const foHeight = Math.max(pos.height * 4, 200);
+              const textLayer = editLayer as ImageEditLayer & { type: 'text' };
+              const s = textLayer.content;
+              const editBox = measureTextLayerBox(textLayer, pos);
               return (
                 <foreignObject
                   key={`inline-edit-${editingLayerId}`}
-                  x={pos.x}
-                  y={pos.y}
-                  width={pos.width}
-                  height={foHeight}
+                  x={editBox.x}
+                  y={editBox.y}
+                  width={editBox.width}
+                  height={editBox.height}
                   style={{ overflow: 'visible' }}
                 >
                   <textarea
@@ -503,9 +506,11 @@ export function CanvasSurface({
                     }}
                     onPointerDown={(e) => e.stopPropagation()}
                     onClick={(e) => e.stopPropagation()}
+                    wrap="off"
                     style={{
                       display: 'block',
                       width: '100%',
+                      height: '100%',
                       padding: 0,
                       margin: 0,
                       border: 'none',
@@ -514,9 +519,9 @@ export function CanvasSurface({
                       resize: 'none',
                       background: 'transparent',
                       fontFamily: s.style.fontFamily ?? 'sans-serif',
-                      // font-size in CSS pixels must be scaled by zoom because foreignObject
-                      // content renders in screen pixels, not SVG user-space pixels.
-                      fontSize: `${s.style.fontSize * zoom}px`,
+                      // The foreignObject participates in the SVG viewBox transform, so its
+                      // contents use canvas units and inherit zoom from the SVG exactly once.
+                      fontSize: `${s.style.fontSize}px`,
                       fontWeight: s.style.fontWeight ?? 'normal',
                       color: s.style.color,
                       textAlign: (s.style.textAlign ?? 'left') as 'left' | 'center' | 'right',
@@ -677,8 +682,9 @@ function measureTextLayerBox(
   }
   const lineHeight = style.lineHeight ?? 1.4;
   const lineHeightPx = fontSize * lineHeight;
-  // First line spans fontSize tall; subsequent lines add lineHeightPx each.
-  const totalHeight = fontSize + Math.max(0, lines.length - 1) * lineHeightPx;
+  // Use full line boxes so the SVG selection and textarea editor share
+  // identical bounds without clipping the caret or the final line.
+  const totalHeight = Math.max(1, lines.length) * lineHeightPx;
   // Mirror the textAnchor logic in EditorTextLayer.
   const anchor =
     style.textAlign === 'center' ? 'middle' : style.textAlign === 'right' ? 'end' : 'start';

package/src/imageEditor/LayersPanel.tsx

@@ -4,6 +4,7 @@
  * panel shows the array reversed so "top" appears at the top of the list.
  */
 
+import { useEffect, useRef, useState } from 'react';
 import type { ImageEditDoc } from '@bendyline/squisq/schemas';
 import type { ImageEditorAction } from './state.js';
 import {
@@ -12,23 +13,95 @@ import {
   CloseIcon,
   EyeIcon,
   EyeOffIcon,
+  ImageIcon,
   LockIcon,
+  PlusIcon,
+  ShapeIcon,
+  TextIcon,
   UnlockIcon,
 } from './icons.js';
 
+export type AddableLayerKind = 'text' | 'shape' | 'image';
+
 export interface LayersPanelProps {
   doc: ImageEditDoc;
   selectedLayerId: string | null;
   dispatch: (action: ImageEditorAction) => void;
+  onAddLayer: (kind: AddableLayerKind) => void;
 }
 
-export function LayersPanel({ doc, selectedLayerId, dispatch }: LayersPanelProps) {
+const ADD_LAYER_OPTIONS: ReadonlyArray<{
+  kind: AddableLayerKind;
+  label: string;
+  icon: React.ReactNode;
+}> = [
+  { kind: 'text', label: 'Text layer', icon: <TextIcon /> },
+  { kind: 'shape', label: 'Shape layer', icon: <ShapeIcon /> },
+  { kind: 'image', label: 'Image layer…', icon: <ImageIcon /> },
+];
+
+export function LayersPanel({ doc, selectedLayerId, dispatch, onAddLayer }: LayersPanelProps) {
+  const [addMenuOpen, setAddMenuOpen] = useState(false);
+  const addMenuRef = useRef<HTMLSpanElement | null>(null);
+
+  useEffect(() => {
+    if (!addMenuOpen) return;
+
+    const closeOnOutsideClick = (event: MouseEvent) => {
+      if (!addMenuRef.current?.contains(event.target as Node)) setAddMenuOpen(false);
+    };
+    const closeOnEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setAddMenuOpen(false);
+    };
+
+    document.addEventListener('mousedown', closeOnOutsideClick);
+    document.addEventListener('keydown', closeOnEscape);
+    return () => {
+      document.removeEventListener('mousedown', closeOnOutsideClick);
+      document.removeEventListener('keydown', closeOnEscape);
+    };
+  }, [addMenuOpen]);
+
   // Visual order: top of stack first.
   const ordered = doc.layers.slice().reverse();
 
   return (
     <div className="squisq-image-editor-layers" data-testid="image-editor-layers">
-      <div className="squisq-image-editor-panel-header">Layers</div>
+      <div className="squisq-image-editor-panel-header squisq-image-editor-layers-header">
+        <span>Layers</span>
+        <span ref={addMenuRef} className="squisq-image-editor-layer-add">
+          <button
+            type="button"
+            className="squisq-image-editor-layer-add-button"
+            onClick={() => setAddMenuOpen((open) => !open)}
+            aria-label="Add layer"
+            title="Add layer"
+            aria-haspopup="menu"
+            aria-expanded={addMenuOpen}
+          >
+            <PlusIcon />
+          </button>
+          {addMenuOpen && (
+            <div className="squisq-image-editor-layer-add-menu" role="menu">
+              {ADD_LAYER_OPTIONS.map(({ kind, label, icon }) => (
+                <button
+                  key={kind}
+                  type="button"
+                  className="squisq-image-editor-layer-add-menu-item"
+                  role="menuitem"
+                  onClick={() => {
+                    setAddMenuOpen(false);
+                    onAddLayer(kind);
+                  }}
+                >
+                  {icon}
+                  <span>{label}</span>
+                </button>
+              ))}
+            </div>
+          )}
+        </span>
+      </div>
       <ul className="squisq-image-editor-layer-list">
         {ordered.length === 0 && <li className="squisq-image-editor-layer-empty">No layers yet</li>}
         {ordered.map((layer) => {
@@ -38,6 +111,7 @@ export function LayersPanel({ doc, selectedLayerId, dispatch }: LayersPanelProps
           const canMoveUp = stackIndex < doc.layers.length - 1;
           const canMoveDown = stackIndex > 0;
           const isSelected = selectedLayerId === layer.id;
+          const layerName = layer.name ?? defaultLayerName(layer);
 
           return (
             <li
@@ -84,8 +158,9 @@ export function LayersPanel({ doc, selectedLayerId, dispatch }: LayersPanelProps
                 type="button"
                 className="squisq-image-editor-layer-name"
                 onClick={() => dispatch({ type: 'select', layerId: layer.id })}
+                title={layerName}
               >
-                {layer.name ?? defaultLayerName(layer)}
+                <span className="squisq-image-editor-layer-name-text">{layerName}</span>
                 <span className="squisq-image-editor-layer-kind">{layer.type}</span>
               </button>
               <button

package/src/imageEditor/Toolbar.tsx

@@ -18,6 +18,8 @@ export interface ToolbarProps {
   dispatch: (a: ImageEditorAction) => void;
   /** Upload an image asset and return its sidecar-relative path. */
   uploadAsset: (file: Blob, suggestedName?: string) => Promise<string>;
+  /** Shared image picker ref used by the toolbar and Layers panel. */
+  imageInputRef?: React.RefObject<HTMLInputElement>;
   /** Trigger an export (PNG/JPEG/WebP) of the flattened canvas. */
   onExport: (format: 'png' | 'jpeg' | 'webp') => void;
   /** Force-flush the state.json (host's "save" button). */
@@ -142,6 +144,7 @@ export function Toolbar({
   shapeKind,
   dispatch,
   uploadAsset,
+  imageInputRef,
   onExport,
   onSave,
   saveLabel = 'Save',
@@ -154,7 +157,8 @@ export function Toolbar({
   onZoomFit,
   onZoom1to1,
 }: ToolbarProps) {
-  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const internalImageInputRef = useRef<HTMLInputElement>(null);
+  const fileInputRef = imageInputRef ?? internalImageInputRef;
   const [shapePaletteOpen, setShapePaletteOpen] = useState(false);
 
   const onFilePicked = async (file: File) => {

package/src/imageEditor/icons.tsx

@@ -58,6 +58,10 @@ export function PlusIcon(props: Props) {
   return <Icon icon="fa-solid fa-plus" {...props} />;
 }
 
+export function ImageIcon(props: Props) {
+  return <Icon icon="fa-solid fa-image" {...props} />;
+}
+
 export function NoneIcon(props: Props) {
   // "No fill / transparent" affordance.
   return <Icon icon="fa-solid fa-ban" {...props} />;

package/src/imageEditor/image-editor.css

@@ -193,6 +193,73 @@
 .squisq-image-editor-layers {
   border-bottom: 1px solid var(--squisq-image-editor-panel-border);
 }
+.squisq-image-editor-layers-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+}
+.squisq-image-editor-layer-add {
+  position: relative;
+  display: inline-flex;
+}
+.squisq-image-editor-layer-add-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  color: inherit;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 3px;
+  cursor: pointer;
+  font: inherit;
+}
+.squisq-image-editor-layer-add-button:hover,
+.squisq-image-editor-layer-add-button[aria-expanded='true'] {
+  background: var(--squisq-image-editor-control-bg);
+  border-color: var(--squisq-image-editor-control-border);
+}
+.squisq-image-editor-layer-add-menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 20;
+  min-width: 150px;
+  padding: 4px;
+  background: var(--squisq-image-editor-panel-bg);
+  border: 1px solid var(--squisq-image-editor-panel-border);
+  border-radius: 5px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  text-transform: none;
+  letter-spacing: normal;
+}
+.squisq-image-editor-layer-add-menu-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 6px 8px;
+  color: inherit;
+  background: transparent;
+  border: 0;
+  border-radius: 3px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  text-align: left;
+}
+.squisq-image-editor-layer-add-menu-item:hover,
+.squisq-image-editor-layer-add-menu-item:focus-visible {
+  background: var(--squisq-image-editor-control-bg);
+  outline: none;
+}
+.squisq-image-editor-layer-add-menu-item svg {
+  flex: 0 0 auto;
+  width: 14px;
+}
 .squisq-image-editor-layer-list {
   list-style: none;
   margin: 0;
@@ -239,6 +306,7 @@
   cursor: not-allowed;
 }
 .squisq-image-editor-layer-name {
+  min-width: 0;
   flex: 1 1 auto;
   text-align: left;
   background: transparent;
@@ -254,7 +322,14 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.squisq-image-editor-layer-name-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
 .squisq-image-editor-layer-kind {
+  flex: 0 0 auto;
   margin-left: auto;
   font-size: 10px;
   color: var(--squisq-image-editor-text-muted);

package/src/imageEditor/layers/SelectionHandles.tsx

@@ -35,7 +35,7 @@ export function SelectionHandles({ box, onHandlePointerDown }: Props) {
   ];
 
   return (
-    <g pointerEvents="none">
+    <g className="squisq-image-editor-selection-handles" pointerEvents="none">
       {/*
        * Outline: rendered as two stacked rectangles so the selection
        * stays visible over both light and dark imagery. The white

package/src/imageEditor/useImageEditor.ts

@@ -110,6 +110,7 @@ export function useImageEditor(options: UseImageEditorOptions): UseImageEditorRe
         const seeded = await seedFromSource(container, initialSrc);
         if (cancelled) return;
         await writeImageEditDoc(container, seeded, stateFilename);
+        if (cancelled) return;
         dispatch({ type: 'load', doc: seeded });
         setReady(true);
         // Capture an initial snapshot of the freshly-seeded state so the
@@ -131,27 +132,53 @@ export function useImageEditor(options: UseImageEditorOptions): UseImageEditorRe
   // ── Debounced persistence of state.json ────────────────────────────────
   const persistTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const docRef = useRef<ImageEditDoc | null>(null);
-  docRef.current = state?.doc ?? null;
+  const dirtyRef = useRef(false);
+  const revisionRef = useRef(0);
+  const previousDocRef = useRef<ImageEditDoc | null>(null);
+  const nextDoc = state?.doc ?? null;
+  if (nextDoc !== previousDocRef.current) {
+    previousDocRef.current = nextDoc;
+    revisionRef.current += 1;
+  }
+  docRef.current = nextDoc;
+  dirtyRef.current = state?.dirty ?? false;
+  const writeQueueRef = useRef<Promise<void>>(Promise.resolve());
+  const persistTargetRef = useRef({ container, stateFilename });
+  persistTargetRef.current = { container, stateFilename };
+
+  const enqueueWrite = useCallback(
+    (doc: ImageEditDoc, revision: number, markClean: boolean): Promise<void> => {
+      const write = writeQueueRef.current
+        .catch(() => undefined)
+        .then(() => writeImageEditDoc(container, doc, stateFilename));
+      writeQueueRef.current = write.catch(() => undefined);
+      return write.then(() => {
+        if (markClean && revision === revisionRef.current && docRef.current === doc) {
+          dispatch({ type: 'mark-clean' });
+        }
+      });
+    },
+    [container, stateFilename],
+  );
 
   useEffect(() => {
     if (!state?.dirty) return;
     if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
     persistTimerRef.current = setTimeout(() => {
-      const doc = docRef.current;
+      const doc = state.doc;
       if (!doc) return;
-      writeImageEditDoc(container, doc, stateFilename)
-        .then(() => dispatch({ type: 'mark-clean' }))
-        .catch((err: unknown) => {
-          console.warn(
-            '[squisq-editor] image-edit state persist failed:',
-            err instanceof Error ? err.message : err,
-          );
-        });
+      const revision = revisionRef.current;
+      enqueueWrite(doc, revision, true).catch((err: unknown) => {
+        console.warn(
+          '[squisq-editor] image-edit state persist failed:',
+          err instanceof Error ? err.message : err,
+        );
+      });
     }, persistDebounceMs);
     return () => {
       if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
     };
-  }, [state?.dirty, state?.doc, container, stateFilename, persistDebounceMs]);
+  }, [state?.dirty, state?.doc, persistDebounceMs, enqueueWrite]);
 
   const flush = useCallback(async () => {
     const doc = docRef.current;
@@ -160,9 +187,29 @@ export function useImageEditor(options: UseImageEditorOptions): UseImageEditorRe
       clearTimeout(persistTimerRef.current);
       persistTimerRef.current = null;
     }
-    await writeImageEditDoc(container, doc, stateFilename);
-    dispatch({ type: 'mark-clean' });
-  }, [container, stateFilename]);
+    await enqueueWrite(doc, revisionRef.current, true);
+  }, [enqueueWrite]);
+
+  // A quick modal close must not discard the final edit that is still inside
+  // the debounce window. Queue it behind any in-flight write on unmount.
+  useEffect(
+    () => () => {
+      if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
+      const doc = docRef.current;
+      if (!dirtyRef.current || !doc) return;
+      const target = persistTargetRef.current;
+      const write = writeQueueRef.current
+        .catch(() => undefined)
+        .then(() => writeImageEditDoc(target.container, doc, target.stateFilename));
+      writeQueueRef.current = write.catch((err: unknown) => {
+        console.warn(
+          '[squisq-editor] image-edit final persist failed:',
+          err instanceof Error ? err.message : err,
+        );
+      });
+    },
+    [],
+  );
 
   // ── Versioning ─────────────────────────────────────────────────────────
   const versioning = useMemo(
@@ -204,17 +251,26 @@ export function useImageEditor(options: UseImageEditorOptions): UseImageEditorRe
 
   // ── Asset URL cache ────────────────────────────────────────────────────
   const urlCacheRef = useRef<Map<string, string>>(new Map());
+  const urlCacheGenerationRef = useRef(0);
 
   const resolveAssetUrl = useCallback(
     async (path: string): Promise<string> => {
       const cache = urlCacheRef.current;
+      const generation = urlCacheGenerationRef.current;
       const cached = cache.get(path);
       if (cached) return cached;
       const data = await container.readFile(path);
+      if (generation !== urlCacheGenerationRef.current) {
+        throw new Error('useImageEditor: asset resolution cancelled');
+      }
       if (!data) throw new Error(`useImageEditor: missing asset "${path}"`);
       const list = await container.listFiles(path);
       const mime = list.find((e) => e.path === path)?.mimeType ?? 'application/octet-stream';
       const url = URL.createObjectURL(new Blob([data], { type: mime }));
+      if (generation !== urlCacheGenerationRef.current) {
+        URL.revokeObjectURL(url);
+        throw new Error('useImageEditor: asset resolution cancelled');
+      }
       cache.set(path, url);
       return url;
     },
@@ -225,6 +281,7 @@ export function useImageEditor(options: UseImageEditorOptions): UseImageEditorRe
   useEffect(() => {
     const cache = urlCacheRef.current;
     return () => {
+      urlCacheGenerationRef.current += 1;
       for (const url of cache.values()) URL.revokeObjectURL(url);
       cache.clear();
     };