refactor(ui): rewrite hooks around the new scene snapshot + selection store

ui/hooks/useBlobData.ts

@@ -2,14 +2,14 @@
 
 import { keepPreviousData, useQuery } from '@tanstack/react-query'
 
-import { getBlob } from '@/lib/api/blobs/blobs'
-import { convertToBlob } from '@/lib/util'
+import { getBlob } from '@/lib/api/default/default'
+import { convertToBlob } from '@/lib/io/blobConvert'
 
 const blobQueryOptions = (hash: string) => ({
   queryKey: ['blob', hash] as const,
   queryFn: async () => {
     const blob = await getBlob(hash)
-    const buf = await blob.arrayBuffer()
+    const buf = await (blob as Blob).arrayBuffer()
     return new Uint8Array(buf)
   },
   staleTime: Infinity,
@@ -31,11 +31,10 @@ const blobImageQueryOptions = (hash: string) => ({
   queryKey: ['blobImage', hash] as const,
   queryFn: async () => {
     const response = await getBlob(hash)
-    const buf = await response.arrayBuffer()
+    const buf = await (response as Blob).arrayBuffer()
     const bytes = new Uint8Array(buf)
     const blob = await convertToBlob(bytes)
     const url = URL.createObjectURL(blob)
-    // Preload: wait until the browser has fully decoded the image.
     await new Promise<void>((resolve, reject) => {
       const img = new Image()
       img.onload = () => resolve()
@@ -51,8 +50,7 @@ const blobImageQueryOptions = (hash: string) => ({
 
 /**
  * Fetch blob, convert to displayable format, and preload — returns a
- * ready-to-paint object URL. Keeps the previous URL while a new one loads,
- * with `isPlaceholderData` indicating whether it's stale.
+ * ready-to-paint object URL. Keeps the previous URL while a new one loads.
  */
 export function useBlobImage(hash: string | undefined) {
   return useQuery({
@@ -61,12 +59,3 @@ export function useBlobImage(hash: string | undefined) {
     placeholderData: keepPreviousData,
   })
 }
-
-/** Fetch a document layer's raw bytes by its blob hash. */
-export function useDocumentLayer(
-  _documentId: string | undefined,
-  _layer: string,
-  hash: string | undefined,
-): Uint8Array | undefined {
-  return useBlobData(hash)
-}

ui/hooks/useBlockContextMenu.ts

@@ -3,62 +3,66 @@
 import { useState } from 'react'
 import type React from 'react'
 
+import { isTextNode } from '@/hooks/useCurrentPage'
 import type { PointerToDocumentFn } from '@/hooks/usePointerToDocument'
-import type { MappedDocument } from '@/hooks/useTextBlocks'
+import type { Page } from '@/lib/api/schemas'
 
 type BlockContextMenuOptions = {
-  currentDocument: MappedDocument | null
+  page: Page | null
   pointerToDocument: PointerToDocumentFn
-  selectBlock: (index?: number) => void
-  removeBlock: (index: number) => void
+  onSelect: (nodeId: string | null) => void
+  onRemove: (nodeId: string) => void
 }
 
+/**
+ * Right-click on a text node pops the context menu. `onSelect(null)` / clear
+ * on empty-space right-click. `onRemove(id)` triggered by menu's delete item.
+ */
 export function useBlockContextMenu({
-  currentDocument,
+  page,
   pointerToDocument,
-  selectBlock,
-  removeBlock,
+  onSelect,
+  onRemove,
 }: BlockContextMenuOptions) {
-  const [contextMenuBlockIndex, setContextMenuBlockIndex] = useState<number | undefined>(undefined)
+  const [contextMenuNodeId, setContextMenuNodeId] = useState<string | null>(null)
 
   const handleContextMenu = (event: React.MouseEvent<HTMLElement>) => {
-    if (!currentDocument) return
+    if (!page) return
     const point = pointerToDocument(event)
     if (!point) {
       event.preventDefault()
-      setContextMenuBlockIndex(undefined)
-      selectBlock(undefined)
+      setContextMenuNodeId(null)
+      onSelect(null)
       return
     }
-    const blockIndex = currentDocument.textBlocks.findIndex(
-      (block) =>
-        point.x >= block.x &&
-        point.x <= block.x + block.width &&
-        point.y >= block.y &&
-        point.y <= block.y + block.height,
-    )
-    if (blockIndex >= 0) {
-      selectBlock(blockIndex)
-      setContextMenuBlockIndex(blockIndex)
+    const hitId = Object.entries(page.nodes).find(([, n]) => {
+      if (!isTextNode(n)) return false
+      const t = n.transform
+      if (!t) return false
+      return (
+        point.x >= t.x && point.x <= t.x + t.width && point.y >= t.y && point.y <= t.y + t.height
+      )
+    })?.[0]
+    if (hitId) {
+      onSelect(hitId)
+      setContextMenuNodeId(hitId)
     } else {
       event.preventDefault()
-      setContextMenuBlockIndex(undefined)
-      selectBlock(undefined)
+      setContextMenuNodeId(null)
+      onSelect(null)
     }
   }
 
   const handleDeleteBlock = () => {
-    if (contextMenuBlockIndex === undefined) return
-    removeBlock(contextMenuBlockIndex)
-    setContextMenuBlockIndex(undefined)
+    if (!contextMenuNodeId) return
+    onRemove(contextMenuNodeId)
+    setContextMenuNodeId(null)
   }
 
-  const clearContextMenu = () => {
-    setContextMenuBlockIndex(undefined)
-  }
+  const clearContextMenu = () => setContextMenuNodeId(null)
 
   return {
-    contextMenuBlockIndex,
+    contextMenuNodeId,
     handleContextMenu,
     handleDeleteBlock,
     clearContextMenu,

ui/hooks/useBlockDrafting.ts

@@ -3,82 +3,79 @@
 import { useDrag } from '@use-gesture/react'
 import { useRef, useState } from 'react'
 
-import type { PointerToDocumentFn, DocumentPointer } from '@/hooks/usePointerToDocument'
-import type { MappedDocument } from '@/hooks/useTextBlocks'
-import { TextBlock, ToolMode } from '@/types'
+import type { DocumentPointer, PointerToDocumentFn } from '@/hooks/usePointerToDocument'
+import type { Page } from '@/lib/api/schemas'
+import type { ToolMode } from '@/lib/types'
+
+/**
+ * Rectangle a user is drawing while `mode === 'block'`. Committed on stroke
+ * end via `onCreateBlock` (which dispatches `Op::AddNode` with a text node).
+ */
+export type BlockDraft = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
 
 type BlockDraftingOptions = {
   mode: ToolMode
-  currentDocument: MappedDocument | null
+  page: Page | null
   pointerToDocument: PointerToDocumentFn
   clearSelection: () => void
-  onCreateBlock: (block: TextBlock) => void
+  onCreateBlock: (draft: BlockDraft) => void
 }
 
 export function useBlockDrafting({
   mode,
-  currentDocument,
+  page,
   pointerToDocument,
   clearSelection,
   onCreateBlock,
 }: BlockDraftingOptions) {
   const dragStartRef = useRef<DocumentPointer | null>(null)
-  const draftBlockRef = useRef<TextBlock | null>(null)
-  const [draftBlock, setDraftBlock] = useState<TextBlock | null>(null)
+  const draftRef = useRef<BlockDraft | null>(null)
+  const [draft, setDraft] = useState<BlockDraft | null>(null)
 
-  const resetDraft = () => {
+  const reset = () => {
     dragStartRef.current = null
-    draftBlockRef.current = null
-    setDraftBlock(null)
+    draftRef.current = null
+    setDraft(null)
   }
 
-  const finalizeDraft = () => {
+  const finalize = () => {
     if (mode !== 'block') {
-      resetDraft()
+      reset()
       return
     }
-    const block = draftBlockRef.current
-    dragStartRef.current = null
-    draftBlockRef.current = null
-    setDraftBlock(null)
-    if (!block || !currentDocument) return
-    const minSize = 4
-    if (block.width < minSize || block.height < minSize) return
-    const normalized: TextBlock = {
-      x: Math.round(block.x),
-      y: Math.round(block.y),
-      width: Math.round(block.width),
-      height: Math.round(block.height),
-      confidence: block.confidence ?? 1,
-      text: block.text,
-      translation: block.translation,
-    }
-    onCreateBlock(normalized)
+    const d = draftRef.current
+    reset()
+    if (!d || !page) return
+    const MIN = 4
+    if (d.width < MIN || d.height < MIN) return
+    onCreateBlock({
+      x: Math.round(d.x),
+      y: Math.round(d.y),
+      width: Math.round(d.width),
+      height: Math.round(d.height),
+    })
   }
 
   const bind = useDrag(
     ({ first, last, event, active }) => {
-      if (!currentDocument || mode !== 'block') return
+      if (!page || mode !== 'block') return
       const sourceEvent = event as MouseEvent
       const point = pointerToDocument(sourceEvent)
       if (!point) {
-        if ((last || !active) && draftBlockRef.current) {
-          finalizeDraft()
-        }
+        if ((last || !active) && draftRef.current) finalize()
         return
       }
 
       if (first) {
         dragStartRef.current = point
-        const nextDraft: TextBlock = {
-          x: point.x,
-          y: point.y,
-          width: 0,
-          height: 0,
-          confidence: 1,
-        }
-        draftBlockRef.current = nextDraft
-        setDraftBlock(nextDraft)
+        const next: BlockDraft = { x: point.x, y: point.y, width: 0, height: 0 }
+        draftRef.current = next
+        setDraft(next)
         clearSelection()
         return
       }
@@ -89,19 +86,11 @@ export function useBlockDrafting({
       const y = Math.min(start.y, point.y)
       const width = Math.abs(point.x - start.x)
       const height = Math.abs(point.y - start.y)
-      const nextDraft: TextBlock = {
-        x,
-        y,
-        width,
-        height,
-        confidence: 1,
-      }
-      draftBlockRef.current = nextDraft
-      setDraftBlock(nextDraft)
+      const next: BlockDraft = { x, y, width, height }
+      draftRef.current = next
+      setDraft(next)
 
-      if (last || !active) {
-        finalizeDraft()
-      }
+      if (last || !active) finalize()
     },
     {
       pointer: { buttons: 1, touch: true },
@@ -111,9 +100,5 @@ export function useBlockDrafting({
     },
   )
 
-  return {
-    draftBlock,
-    bind,
-    resetDraft,
-  }
+  return { draftBlock: draft, bind, resetDraft: reset }
 }

ui/hooks/useBrushCursor.ts

@@ -8,7 +8,7 @@ import { usePreferencesStore } from '@/lib/stores/preferencesStore'
 export function useBrushCursor(
   canvasRef: React.RefObject<HTMLDivElement | null>,
   mode: string,
-  currentDocumentId?: string,
+  pageKey?: string,
 ) {
   const brushCursorRef = useRef<HTMLDivElement>(null)
   const cachedRectRef = useRef<DOMRect | null>(null)
@@ -88,7 +88,8 @@ export function useBrushCursor(
       window.removeEventListener('scroll', refresh, true)
       window.removeEventListener('resize', refresh)
     }
-  }, [canvasRef, currentDocumentId])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [canvasRef, pageKey])
 
   // Separate effect for visibility to avoid re-attaching listeners
   useEffect(() => {

ui/hooks/useBrushLayerDisplay.ts

@@ -2,20 +2,20 @@
 
 import { useEffect, useRef } from 'react'
 
-import type { MappedDocument } from '@/hooks/useTextBlocks'
-import { convertToImageBitmap } from '@/lib/util'
+import type { Page } from '@/lib/api/schemas'
+
+async function bytesToBitmap(bytes: Uint8Array): Promise<ImageBitmap> {
+  const blob = new Blob([bytes as unknown as BlobPart])
+  return createImageBitmap(blob)
+}
 
 type BrushLayerDisplayOptions = {
-  currentDocument: MappedDocument | null
+  page: Page | null
   brushLayerData?: Uint8Array
   visible: boolean
 }
 
-export function useBrushLayerDisplay({
-  currentDocument,
-  brushLayerData,
-  visible,
-}: BrushLayerDisplayOptions) {
+export function useBrushLayerDisplay({ page, brushLayerData, visible }: BrushLayerDisplayOptions) {
   const canvasRef = useRef<HTMLCanvasElement | null>(null)
   const ctxRef = useRef<CanvasRenderingContext2D | null>(null)
 
@@ -25,34 +25,31 @@ export function useBrushLayerDisplay({
     const ctx = canvas.getContext('2d')
     ctxRef.current = ctx
 
-    if (!currentDocument) {
+    if (!page) {
       canvas.width = 0
       canvas.height = 0
       ctx?.clearRect(0, 0, canvas.width, canvas.height)
       return
     }
 
-    const needsResize =
-      canvas.width !== currentDocument.width || canvas.height !== currentDocument.height
-
+    const needsResize = canvas.width !== page.width || canvas.height !== page.height
     if (needsResize) {
-      canvas.width = currentDocument.width
-      canvas.height = currentDocument.height
+      canvas.width = page.width
+      canvas.height = page.height
     }
 
     let cancelled = false
-
     if (visible && brushLayerData) {
       void (async () => {
         try {
-          const bitmap = await convertToImageBitmap(brushLayerData)
+          const bitmap = await bytesToBitmap(brushLayerData)
           if (cancelled) {
             bitmap.close()
             return
           }
           ctx?.save()
           ctx?.clearRect(0, 0, canvas.width, canvas.height)
-          ctx?.drawImage(bitmap, 0, 0, currentDocument.width, currentDocument.height)
+          ctx?.drawImage(bitmap, 0, 0, page.width, page.height)
           ctx?.restore()
           bitmap.close()
         } catch (error) {
@@ -66,16 +63,7 @@ export function useBrushLayerDisplay({
     return () => {
       cancelled = true
     }
-  }, [
-    currentDocument?.id,
-    currentDocument?.width,
-    currentDocument?.height,
-    brushLayerData,
-    visible,
-  ])
+  }, [page?.id, page?.width, page?.height, brushLayerData, visible])
 
-  return {
-    canvasRef,
-    visible,
-  }
+  return { canvasRef, visible }
 }

ui/hooks/useCanvasDrawing.ts

@@ -3,47 +3,43 @@
 import { useDrag } from '@use-gesture/react'
 import { useEffect, useRef, type RefObject } from 'react'
 
-import { type PointerToDocumentFn, type DocumentPointer } from '@/hooks/usePointerToDocument'
-import type { MappedDocument } from '@/hooks/useTextBlocks'
-import { blobToUint8Array } from '@/lib/util'
-import type { InpaintRegion } from '@/types'
+import { type DocumentPointer, type PointerToDocumentFn } from '@/hooks/usePointerToDocument'
+import type { Region } from '@/lib/api/schemas'
+
+/** Minimum canvas context needed by the drawing loop. */
+export type CanvasDims = { width: number; height: number; key?: string }
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-type Bounds = {
-  minX: number
-  minY: number
-  maxX: number
-  maxY: number
-}
+type Bounds = { minX: number; minY: number; maxX: number; maxY: number }
 
 export type CanvasDrawingConfig = {
   getColor: () => string
   blendMode: GlobalCompositeOperation
   getBrushSize: () => number
-  onFinalize: (patch: Uint8Array, region: InpaintRegion) => Promise<void>
+  onFinalize: (patch: Uint8Array, region: Region) => Promise<void>
   /** Called after finalize with the full-canvas PNG and the patch region. */
-  onFinalizeFullCanvas?: (fullPng: Uint8Array, patchRegion: InpaintRegion) => Promise<void>
+  onFinalizeFullCanvas?: (fullPng: Uint8Array, patchRegion: Region) => Promise<void>
   enabled: boolean
   /** Optional second canvas to mirror strokes to. */
   targetCanvasRef?: RefObject<HTMLCanvasElement | null>
   /** When true, clear the drawing canvas after each stroke finalize. */
   clearAfterStroke?: boolean
-  /** Called to set up the canvas content when the document changes (e.g. draw existing mask). */
-  onCanvasInit?: (ctx: CanvasRenderingContext2D, doc: MappedDocument) => void | Promise<void>
+  /** Seed canvas content on dims change (e.g. draw an existing mask). */
+  onCanvasInit?: (ctx: CanvasRenderingContext2D, dims: CanvasDims) => void | Promise<void>
 }
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-const clampToDocument = (point: DocumentPointer, doc?: MappedDocument): DocumentPointer => {
-  if (!doc) return point
+const clampToDims = (point: DocumentPointer, dims?: CanvasDims): DocumentPointer => {
+  if (!dims) return point
   return {
-    x: Math.max(0, Math.min(doc.width, point.x)),
-    y: Math.max(0, Math.min(doc.height, point.y)),
+    x: Math.max(0, Math.min(dims.width, point.x)),
+    y: Math.max(0, Math.min(dims.height, point.y)),
   }
 }
 
@@ -54,11 +50,11 @@ const expandBounds = (bounds: Bounds, point: DocumentPointer, radius: number): B
   maxY: Math.max(bounds.maxY, point.y + radius),
 })
 
-const boundsToRegion = (bounds: Bounds, doc: MappedDocument): InpaintRegion => {
+const boundsToRegion = (bounds: Bounds, dims: CanvasDims): Region => {
   const x0 = Math.max(0, Math.floor(bounds.minX))
   const y0 = Math.max(0, Math.floor(bounds.minY))
-  const x1 = Math.min(doc.width, Math.ceil(bounds.maxX))
-  const y1 = Math.min(doc.height, Math.ceil(bounds.maxY))
+  const x1 = Math.min(dims.width, Math.ceil(bounds.maxX))
+  const y1 = Math.min(dims.height, Math.ceil(bounds.maxY))
   return {
     x: x0,
     y: y0,
@@ -67,9 +63,13 @@ const boundsToRegion = (bounds: Bounds, doc: MappedDocument): InpaintRegion => {
   }
 }
 
+async function blobToUint8(blob: Blob): Promise<Uint8Array> {
+  return new Uint8Array(await blob.arrayBuffer())
+}
+
 const exportCanvasRegion = async (
   canvas: HTMLCanvasElement,
-  region: InpaintRegion,
+  region: Region,
 ): Promise<Uint8Array | null> => {
   if (region.width <= 0 || region.height <= 0) return null
   const tmp = document.createElement('canvas')
@@ -89,12 +89,12 @@ const exportCanvasRegion = async (
     region.height,
   )
   const blob = await new Promise<Blob | null>((r) => tmp.toBlob(r, 'image/png'))
-  return blob ? blobToUint8Array(blob) : null
+  return blob ? blobToUint8(blob) : null
 }
 
 const exportFullCanvas = async (canvas: HTMLCanvasElement): Promise<Uint8Array | null> => {
   const blob = await new Promise<Blob | null>((r) => canvas.toBlob(r, 'image/png'))
-  return blob ? blobToUint8Array(blob) : null
+  return blob ? blobToUint8(blob) : null
 }
 
 const initBounds = (point: DocumentPointer, radius: number): Bounds => ({
@@ -109,7 +109,7 @@ const initBounds = (point: DocumentPointer, radius: number): Bounds => ({
 // ---------------------------------------------------------------------------
 
 export function useCanvasDrawing(
-  currentDocument: MappedDocument | null,
+  dims: CanvasDims | null,
   pointerToDocument: PointerToDocumentFn,
   config: CanvasDrawingConfig,
 ) {
@@ -119,7 +119,6 @@ export function useCanvasDrawing(
   const lastPointRef = useRef<DocumentPointer | null>(null)
   const boundsRef = useRef<Bounds | null>(null)
 
-  // Reset drawing state when disabled
   useEffect(() => {
     if (config.enabled) return
     drawingRef.current = false
@@ -127,14 +126,13 @@ export function useCanvasDrawing(
     boundsRef.current = null
   }, [config.enabled])
 
-  // Canvas setup and resize
   useEffect(() => {
     const canvas = canvasRef.current
     if (!canvas) return
     const ctx = canvas.getContext('2d')
     ctxRef.current = ctx
 
-    if (!currentDocument || !config.enabled) {
+    if (!dims || !config.enabled) {
       canvas.width = 0
       canvas.height = 0
       ctx?.clearRect(0, 0, canvas.width, canvas.height)
@@ -145,18 +143,16 @@ export function useCanvasDrawing(
       }
     }
 
-    const needsResize =
-      canvas.width !== currentDocument.width || canvas.height !== currentDocument.height
-
+    const needsResize = canvas.width !== dims.width || canvas.height !== dims.height
     if (needsResize) {
-      canvas.width = currentDocument.width
-      canvas.height = currentDocument.height
+      canvas.width = dims.width
+      canvas.height = dims.height
     }
     ctx?.clearRect(0, 0, canvas.width, canvas.height)
 
     if (config.onCanvasInit && ctx) {
-      const result = config.onCanvasInit(ctx, currentDocument)
-      if (result && typeof (result as any).then === 'function') {
+      const result = config.onCanvasInit(ctx, dims)
+      if (result && typeof (result as Promise<void>).then === 'function') {
         void (result as Promise<void>).catch(console.error)
       }
     }
@@ -166,7 +162,8 @@ export function useCanvasDrawing(
       lastPointRef.current = null
       boundsRef.current = null
     }
-  }, [currentDocument?.id, currentDocument?.width, currentDocument?.height, config.enabled])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dims?.key, dims?.width, dims?.height, config.enabled])
 
   const drawStroke = (from: DocumentPointer, to: DocumentPointer) => {
     const color = config.getColor()
@@ -189,7 +186,6 @@ export function useCanvasDrawing(
 
     const ctx = ctxRef.current
     if (ctx) stroke(ctx)
-
     const targetCtx = config.targetCanvasRef?.current?.getContext('2d')
     if (targetCtx) stroke(targetCtx)
   }
@@ -197,8 +193,8 @@ export function useCanvasDrawing(
   const finalizeStroke = () => {
     if (!config.enabled) return
     const strokeBounds = boundsRef.current
-    if (!currentDocument || !strokeBounds) return
-    const patchRegion = boundsToRegion(strokeBounds, currentDocument)
+    if (!dims || !strokeBounds) return
+    const patchRegion = boundsToRegion(strokeBounds, dims)
     boundsRef.current = null
     drawingRef.current = false
     lastPointRef.current = null
@@ -237,14 +233,14 @@ export function useCanvasDrawing(
 
   const bind = useDrag(
     ({ first, last, event, active }) => {
-      if (!config.enabled || !currentDocument) return
+      if (!config.enabled || !dims) return
       const sourceEvent = event as MouseEvent
       const point = pointerToDocument(sourceEvent)
       if (!point) {
         if ((last || !active) && drawingRef.current) finalizeStroke()
         return
       }
-      const clamped = clampToDocument(point, currentDocument)
+      const clamped = clampToDims(point, dims)
       const brushSize = config.getBrushSize()
       const radius = brushSize / 2
 
@@ -255,7 +251,6 @@ export function useCanvasDrawing(
         drawStroke(clamped, clamped)
         return
       }
-
       if (!drawingRef.current) return
       const lastPoint = lastPointRef.current ?? clamped
       drawStroke(lastPoint, clamped)
@@ -263,7 +258,6 @@ export function useCanvasDrawing(
       boundsRef.current = boundsRef.current
         ? expandBounds(boundsRef.current, clamped, radius)
         : initBounds(clamped, radius)
-
       if (last || !active) finalizeStroke()
     },
     {

ui/hooks/useCanvasZoom.ts

@@ -1,27 +1,19 @@
 'use client'
 
-import { useGetDocument } from '@/lib/api/documents/documents'
+import { useCurrentPage } from '@/hooks/useCurrentPage'
 import { useEditorUiStore } from '@/lib/stores/editorUiStore'
 
 export function useCanvasZoom() {
-  const scale = useEditorUiStore((state) => state.scale)
-  const setScaleRaw = useEditorUiStore((state) => state.setScale)
-  const setAutoFitEnabled = useEditorUiStore((state) => state.setAutoFitEnabled)
-  const documentId = useEditorUiStore((s) => s.currentDocumentId)
-  const { data: document } = useGetDocument(documentId ?? '', {
-    query: { enabled: !!documentId },
-  })
-
-  const summary = document ? `${document.width} x ${document.height}` : '--'
+  const scale = useEditorUiStore((s) => s.scale)
+  const setScaleRaw = useEditorUiStore((s) => s.setScale)
+  const setAutoFitEnabled = useEditorUiStore((s) => s.setAutoFitEnabled)
+  const page = useCurrentPage()
+  const summary = page ? `${page.width} x ${page.height}` : '--'
 
   const applyScale = (value: number) => {
     setAutoFitEnabled(false)
     setScaleRaw(value)
   }
 
-  return {
-    scale,
-    setScale: applyScale,
-    summary,
-  }
+  return { scale, setScale: applyScale, summary }
 }

ui/hooks/useCurrentPage.ts

@@ -0,0 +1,127 @@
+'use client'
+
+import { useMemo } from 'react'
+
+import type { ImageRole, MaskRole, Node, Page, TextData, Transform } from '@/lib/api/schemas'
+import { useSelectionStore } from '@/lib/stores/selectionStore'
+
+import { useScene } from './useScene'
+
+// ---------------------------------------------------------------------------
+// Node kind guards
+// ---------------------------------------------------------------------------
+
+export function isImageNode(
+  n: Node,
+): n is Node & { kind: { image: import('@/lib/api/schemas').ImageData } } {
+  return 'image' in n.kind
+}
+
+export function isMaskNode(
+  n: Node,
+): n is Node & { kind: { mask: import('@/lib/api/schemas').MaskData } } {
+  return 'mask' in n.kind
+}
+
+export function isTextNode(n: Node): n is Node & { kind: { text: TextData } } {
+  return 'text' in n.kind
+}
+
+// ---------------------------------------------------------------------------
+// Accessors — page-level, role-keyed
+// ---------------------------------------------------------------------------
+
+/** Return the blob hash of the `Image { role }` node on `page`, if any. */
+export function findImageBlob(page: Page, role: ImageRole): string | null {
+  for (const node of Object.values(page.nodes)) {
+    if (isImageNode(node) && node.kind.image.role === role) {
+      return node.kind.image.blob
+    }
+  }
+  return null
+}
+
+export function findImageNodeId(page: Page, role: ImageRole): string | null {
+  for (const [id, node] of Object.entries(page.nodes)) {
+    if (isImageNode(node) && node.kind.image.role === role) return id
+  }
+  return null
+}
+
+export function findMaskBlob(page: Page, role: MaskRole): string | null {
+  for (const node of Object.values(page.nodes)) {
+    if (isMaskNode(node) && node.kind.mask.role === role) {
+      return node.kind.mask.blob
+    }
+  }
+  return null
+}
+
+export function findMaskNodeId(page: Page, role: MaskRole): string | null {
+  for (const [id, node] of Object.entries(page.nodes)) {
+    if (isMaskNode(node) && node.kind.mask.role === role) return id
+  }
+  return null
+}
+
+export type TextNodeEntry = {
+  id: string
+  transform: Transform
+  data: TextData
+}
+
+export function textNodesOf(page: Page): TextNodeEntry[] {
+  const out: TextNodeEntry[] = []
+  for (const [id, node] of Object.entries(page.nodes)) {
+    if (!isTextNode(node)) continue
+    out.push({
+      id,
+      transform: node.transform ?? { x: 0, y: 0, width: 0, height: 0 },
+      data: node.kind.text,
+    })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// React hooks
+// ---------------------------------------------------------------------------
+
+/** The active page, or `null` if none selected / no project open. */
+export function useCurrentPage(): Page | null {
+  const pageId = useSelectionStore((s) => s.pageId)
+  const { scene } = useScene()
+  if (!pageId) return null
+  return scene?.pages?.[pageId] ?? null
+}
+
+/** Text nodes on the active page, in stacking order. */
+export function useTextNodes(): TextNodeEntry[] {
+  const page = useCurrentPage()
+  const { epoch } = useScene()
+  return useMemo(() => (page ? textNodesOf(page) : []), [page, epoch])
+}
+
+/**
+ * Selected text node entry, derived from `selectionStore.nodeIds`. Returns
+ * the first selected text node (V1 had a single-select block concept).
+ */
+export function useSelectedTextNode(): TextNodeEntry | null {
+  const page = useCurrentPage()
+  const nodeIds = useSelectionStore((s) => s.nodeIds)
+  const { epoch } = useScene()
+  return useMemo(() => {
+    if (!page) return null
+    for (const id of nodeIds) {
+      const node = page.nodes[id]
+      if (node && isTextNode(node)) {
+        return {
+          id,
+          transform: node.transform ?? { x: 0, y: 0, width: 0, height: 0 },
+          data: node.kind.text,
+        }
+      }
+    }
+    return null
+  }, [page, nodeIds, epoch])
+}

ui/hooks/useKeyboardShortcuts.ts

@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo } from 'react'
 
+import { redoOp, undoOp } from '@/lib/io/scene'
 import { getPlatform, formatShortcut, isModifierKey } from '@/lib/shortcutUtils'
 import { useEditorUiStore } from '@/lib/stores/editorUiStore'
 import { usePreferencesStore } from '@/lib/stores/preferencesStore'
@@ -13,12 +14,29 @@ export function useKeyboardShortcuts() {
 
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
-      // Skip if user is typing in an input
       const target = event.target as HTMLElement
-      if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable) {
+      const inTextField =
+        target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable
+
+      // Undo / Redo — work globally, including from within text fields (the
+      // browser's native `z` on an input would only undo keystrokes, not
+      // scene ops). Cmd on macOS, Ctrl elsewhere.
+      const mod = isMac ? event.metaKey : event.ctrlKey
+      if (mod && (event.key === 'z' || event.key === 'Z')) {
+        event.preventDefault()
+        if (event.shiftKey) void redoOp()
+        else void undoOp()
+        return
+      }
+      if (mod && (event.key === 'y' || event.key === 'Y')) {
+        event.preventDefault()
+        void redoOp()
         return
       }
 
+      // Every other shortcut is tool-level and should not fire while typing.
+      if (inTextField) return
+
       // Early exit for modifier-only events
       if (isModifierKey(event.key)) {
         return
@@ -55,5 +73,6 @@ export function useKeyboardShortcuts() {
 
     window.addEventListener('keydown', handleKeyDown)
     return () => window.removeEventListener('keydown', handleKeyDown)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isMac, setMode])
 }

ui/hooks/useMaskDrawing.ts

@@ -1,72 +1,67 @@
 'use client'
 
-import { useQueryClient } from '@tanstack/react-query'
-import { useCallback, useRef } from 'react'
+import { useRef } from 'react'
 
-import { useCanvasDrawing } from '@/hooks/useCanvasDrawing'
+import { useCanvasDrawing, type CanvasDims } from '@/hooks/useCanvasDrawing'
 import type { PointerToDocumentFn } from '@/hooks/usePointerToDocument'
-import type { MappedDocument } from '@/hooks/useTextBlocks'
-import { getGetDocumentQueryKey, getListDocumentsQueryKey } from '@/lib/api/documents/documents'
-import {
-  updateMask as updateMaskApi,
-  inpaintRegion as inpaintRegionApi,
-} from '@/lib/api/regions/regions'
-import { normalizeErrorMessage } from '@/lib/errors'
+import { getConfig, startPipeline } from '@/lib/api/default/default'
+import type { Page } from '@/lib/api/schemas'
 import { useEditorUiStore } from '@/lib/stores/editorUiStore'
 import { usePreferencesStore } from '@/lib/stores/preferencesStore'
-import { convertToImageBitmap } from '@/lib/util'
-import type { ToolMode } from '@/types'
+import type { ToolMode } from '@/lib/types'
+
+async function convertBytesToBitmap(bytes: Uint8Array): Promise<ImageBitmap> {
+  const blob = new Blob([bytes as unknown as BlobPart])
+  return createImageBitmap(blob)
+}
 
 type MaskDrawingOptions = {
   mode: ToolMode
-  currentDocument: MappedDocument | null
+  page: Page | null
   segmentData?: Uint8Array
   pointerToDocument: PointerToDocumentFn
   showMask: boolean
   enabled: boolean
 }
 
+/**
+ * Repair-brush canvas that edits the `Mask { role: segment }` node. On stroke
+ * end:
+ *   1. PUT the updated mask to `/api/v1/pages/{id}/masks/segment` (raw PNG).
+ *   2. Kick a region-scoped inpainter via `POST /pipelines` so the inpainted
+ *      layer refreshes just over the touched area.
+ */
 export function useMaskDrawing({
   mode,
-  currentDocument,
+  page,
   segmentData,
   pointerToDocument,
   showMask,
   enabled,
 }: MaskDrawingOptions) {
-  const queryClient = useQueryClient()
   const inpaintQueueRef = useRef<Promise<void>>(Promise.resolve())
   const isEraseMode = mode === 'eraser'
   const isActive = enabled && (mode === 'repairBrush' || isEraseMode)
 
-  const invalidateDocument = useCallback(
-    async (documentId: string) => {
-      await queryClient.invalidateQueries({
-        queryKey: getGetDocumentQueryKey(documentId),
-      })
-      await queryClient.invalidateQueries({
-        queryKey: getListDocumentsQueryKey(),
-      })
-    },
-    [queryClient],
-  )
+  const dims: CanvasDims | null = page
+    ? { width: page.width, height: page.height, key: page.id }
+    : null
 
-  const { canvasRef, bind: rawBind } = useCanvasDrawing(currentDocument, pointerToDocument, {
+  const { canvasRef, bind: rawBind } = useCanvasDrawing(dims, pointerToDocument, {
     getColor: () => (isEraseMode ? '#000000' : '#ffffff'),
     blendMode: 'source-over',
     getBrushSize: () => usePreferencesStore.getState().brushConfig.size,
     enabled: showMask,
-    onCanvasInit: (ctx, doc) => {
-      // Fill black then draw existing segment mask on top
+    onCanvasInit: (ctx, d) => {
       ctx.fillStyle = '#000'
-      ctx.fillRect(0, 0, doc.width, doc.height)
+      ctx.fillRect(0, 0, d.width, d.height)
       if (segmentData) {
         void (async () => {
           try {
-            const bitmap = await convertToImageBitmap(segmentData)
+            const bitmap = await convertBytesToBitmap(segmentData)
             ctx.save()
-            ctx.clearRect(0, 0, doc.width, doc.height)
-            ctx.drawImage(bitmap, 0, 0, doc.width, doc.height)
+            ctx.clearRect(0, 0, d.width, d.height)
+            ctx.drawImage(bitmap, 0, 0, d.width, d.height)
             ctx.restore()
             bitmap.close()
           } catch (e) {
@@ -76,28 +71,27 @@ export function useMaskDrawing({
       }
     },
     onFinalizeFullCanvas: async (fullPng) => {
-      const documentId = useEditorUiStore.getState().currentDocumentId
-      if (!documentId) return
+      if (!page) return
       try {
-        await updateMaskApi(documentId, {
-          data: Array.from(fullPng),
+        const res = await fetch(`/api/v1/pages/${page.id}/masks/segment`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'image/png' },
+          body: fullPng as unknown as BodyInit,
         })
+        if (!res.ok) throw new Error(`mask PUT failed: ${res.status}`)
       } catch (e) {
-        useEditorUiStore.getState().showError(normalizeErrorMessage(e))
+        useEditorUiStore.getState().showError(String(e))
       }
     },
     onFinalize: async (_patch, region) => {
-      const documentId = useEditorUiStore.getState().currentDocumentId
-      if (!documentId) return
-      // Compute the inpaint region with margin
+      if (!page) return
       const brushSize = usePreferencesStore.getState().brushConfig.size
       const width = Math.max(brushSize, region.width)
       const margin = Math.min(width * 0.2, 32)
-      const doc = currentDocument!
       const x0 = Math.max(0, Math.floor(region.x - margin))
       const y0 = Math.max(0, Math.floor(region.y - margin))
-      const x1 = Math.min(doc.width, Math.ceil(region.x + region.width + margin))
-      const y1 = Math.min(doc.height, Math.ceil(region.y + region.height + margin))
+      const x1 = Math.min(page.width, Math.ceil(region.x + region.width + margin))
+      const y1 = Math.min(page.height, Math.ceil(region.y + region.height + margin))
       const inpaintRegion = {
         x: x0,
         y: y0,
@@ -108,18 +102,21 @@ export function useMaskDrawing({
         .catch(() => {})
         .then(async () => {
           try {
-            await inpaintRegionApi(documentId, { region: inpaintRegion })
-            await invalidateDocument(documentId)
+            const cfg = await getConfig()
+            const inpainter = cfg.pipeline?.inpainter || 'lama-manga'
+            await startPipeline({
+              steps: [inpainter],
+              pages: [page.id],
+              region: inpaintRegion,
+            })
             useEditorUiStore.getState().setShowInpaintedImage(true)
           } catch (e) {
-            useEditorUiStore.getState().showError(normalizeErrorMessage(e))
+            useEditorUiStore.getState().showError(String(e))
           }
         })
     },
   })
 
-  // Only allow drawing on the mask if the specific tools are active
   const bind = isActive ? rawBind : () => ({})
-
   return { canvasRef, visible: showMask, bind }
 }

ui/hooks/useRenderBrushDrawing.ts

@@ -1,57 +1,60 @@
 'use client'
 
-import { useQueryClient } from '@tanstack/react-query'
 import type { RefObject } from 'react'
 
-import { useCanvasDrawing } from '@/hooks/useCanvasDrawing'
+import { useCanvasDrawing, type CanvasDims } from '@/hooks/useCanvasDrawing'
 import type { PointerToDocumentFn } from '@/hooks/usePointerToDocument'
-import type { MappedDocument } from '@/hooks/useTextBlocks'
-import { getGetDocumentQueryKey, getListDocumentsQueryKey } from '@/lib/api/documents/documents'
-import { updateBrushLayer } from '@/lib/api/regions/regions'
+import type { Page } from '@/lib/api/schemas'
 import { useEditorUiStore } from '@/lib/stores/editorUiStore'
 import { usePreferencesStore } from '@/lib/stores/preferencesStore'
-import type { ToolMode } from '@/types'
+import type { ToolMode } from '@/lib/types'
 
 type RenderBrushOptions = {
   mode: ToolMode
-  currentDocument: MappedDocument | null
+  page: Page | null
   pointerToDocument: PointerToDocumentFn
   enabled: boolean
   action: 'paint' | 'erase'
   targetCanvasRef?: RefObject<HTMLCanvasElement | null>
 }
 
+/**
+ * Color-brush over the `Mask { role: brushInpaint }` node. Stroke finalize
+ * PUTs the updated mask to `/api/v1/pages/{id}/masks/brushInpaint`.
+ */
 export function useRenderBrushDrawing({
-  currentDocument,
+  page,
   pointerToDocument,
   enabled,
   action,
   targetCanvasRef,
 }: RenderBrushOptions) {
-  const queryClient = useQueryClient()
   const isErasing = action === 'erase'
+  const dims: CanvasDims | null = page
+    ? { width: page.width, height: page.height, key: page.id }
+    : null
 
-  return useCanvasDrawing(currentDocument, pointerToDocument, {
+  return useCanvasDrawing(dims, pointerToDocument, {
     getColor: () => (isErasing ? '#000000' : usePreferencesStore.getState().brushConfig.color),
     blendMode: isErasing ? 'destination-out' : 'source-over',
     getBrushSize: () => usePreferencesStore.getState().brushConfig.size,
     enabled,
     targetCanvasRef,
     clearAfterStroke: true,
-    onFinalize: async (patch, region) => {
-      const documentId = useEditorUiStore.getState().currentDocumentId
-      if (!documentId) return
-      await updateBrushLayer(documentId, {
-        data: Array.from(patch),
-        region,
-      })
-      await queryClient.invalidateQueries({
-        queryKey: getGetDocumentQueryKey(documentId),
-      })
-      await queryClient.invalidateQueries({
-        queryKey: getListDocumentsQueryKey(),
-      })
-      useEditorUiStore.getState().setShowBrushLayer(true)
+    onFinalize: async () => {},
+    onFinalizeFullCanvas: async (fullPng) => {
+      if (!page) return
+      try {
+        const res = await fetch(`/api/v1/pages/${page.id}/masks/brushInpaint`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'image/png' },
+          body: fullPng as unknown as BodyInit,
+        })
+        if (!res.ok) throw new Error(`brush PUT failed: ${res.status}`)
+        useEditorUiStore.getState().setShowBrushLayer(true)
+      } catch (e) {
+        useEditorUiStore.getState().showError(String(e))
+      }
     },
   })
 }

ui/hooks/useScene.ts

@@ -0,0 +1,32 @@
+'use client'
+
+import { useGetSceneJson } from '@/lib/api/default/default'
+import type { Scene } from '@/lib/api/schemas'
+
+/**
+ * Backend is the source of truth for the scene. Components read it through
+ * this hook — which is just a thin wrapper around the orval-generated
+ * `useGetSceneJson` query. Mutations must invalidate `getGetSceneJsonQueryKey`
+ * for the UI to pick up changes (see `lib/io/scene.ts`).
+ *
+ * When no project is open, `GET /scene.json` returns 400; React Query stores
+ * that as an error and `scene` is `null`.
+ */
+export function useScene(): { scene: Scene | null; epoch: number } {
+  const { data, isError } = useGetSceneJson({
+    query: {
+      retry: false,
+      staleTime: Infinity,
+      gcTime: Infinity,
+    },
+  })
+  // React Query preserves `data` across a failed refetch, so closing a
+  // project would leave the stale scene visible until the cache is
+  // manually cleared. Treat an error response (e.g. 400 "no project open")
+  // as an explicit "no scene".
+  if (isError) return { scene: null, epoch: 0 }
+  return {
+    scene: data?.scene ?? null,
+    epoch: data?.epoch ?? 0,
+  }
+}

ui/hooks/useTextBlocks.ts

@@ -1,183 +0,0 @@
-'use client'
-
-import { useQueryClient } from '@tanstack/react-query'
-import { useCallback } from 'react'
-
-import {
-  useGetDocument,
-  getGetDocumentQueryKey,
-  getListDocumentsQueryKey,
-} from '@/lib/api/documents/documents'
-export { useBlobData, useDocumentLayer } from '@/hooks/useBlobData'
-import type { DocumentDetail, TextBlockInput } from '@/lib/api/schemas'
-import { createTextBlock, patchTextBlock, putTextBlocks } from '@/lib/api/text-blocks/text-blocks'
-import { useEditorUiStore } from '@/lib/stores/editorUiStore'
-import { TextBlock } from '@/types'
-
-const hasGeometryChange = (updates: Partial<TextBlock>) =>
-  Object.prototype.hasOwnProperty.call(updates, 'x') ||
-  Object.prototype.hasOwnProperty.call(updates, 'y') ||
-  Object.prototype.hasOwnProperty.call(updates, 'width') ||
-  Object.prototype.hasOwnProperty.call(updates, 'height')
-
-const mapTextBlock = (block: DocumentDetail['textBlocks'][number]): TextBlock => ({
-  id: block.id,
-  x: block.x,
-  y: block.y,
-  width: block.width,
-  height: block.height,
-  confidence: block.confidence,
-  linePolygons: block.linePolygons as TextBlock['linePolygons'],
-  sourceDirection: block.sourceDirection ?? undefined,
-  renderedDirection: block.renderedDirection ?? undefined,
-  sourceLanguage: block.sourceLanguage ?? undefined,
-  rotationDeg: block.rotationDeg ?? undefined,
-  detectedFontSizePx: block.detectedFontSizePx ?? undefined,
-  detector: block.detector ?? undefined,
-  text: block.text ?? undefined,
-  translation: block.translation ?? undefined,
-  style: block.style as TextBlock['style'],
-  fontPrediction: block.fontPrediction as TextBlock['fontPrediction'],
-  rendered: block.rendered ?? undefined,
-  renderX: block.renderX ?? undefined,
-  renderY: block.renderY ?? undefined,
-  renderWidth: block.renderWidth ?? undefined,
-  renderHeight: block.renderHeight ?? undefined,
-})
-
-export type MappedDocument = {
-  id: string
-  name: string
-  width: number
-  height: number
-  textBlocks: TextBlock[]
-  /** Blob hashes for each layer — fetch bytes via useDocumentLayer(). */
-  image: string
-  segment?: string
-  inpainted?: string
-  brushLayer?: string
-  rendered?: string
-  style?: { defaultFont?: string | null }
-}
-
-const mapDocumentDetail = (detail: DocumentDetail): MappedDocument => ({
-  id: detail.id,
-  name: detail.name,
-  width: detail.width,
-  height: detail.height,
-  textBlocks: detail.textBlocks.map(mapTextBlock),
-  image: detail.image,
-  segment: detail.segment ?? undefined,
-  inpainted: detail.inpainted ?? undefined,
-  brushLayer: detail.brushLayer ?? undefined,
-  rendered: detail.rendered ?? undefined,
-  style: detail.style ?? undefined,
-})
-
-const toTextBlockInput = (block: TextBlock): TextBlockInput => ({
-  id: block.id ?? null,
-  x: block.x,
-  y: block.y,
-  width: block.width,
-  height: block.height,
-  text: block.text ?? null,
-  translation: block.translation ?? null,
-  style: (block.style as any) ?? null,
-})
-
-export function useCurrentDocument(): MappedDocument | null {
-  const documentId = useEditorUiStore((s) => s.currentDocumentId)
-  const { data: detail } = useGetDocument(documentId ?? '', {
-    query: { enabled: !!documentId },
-  })
-  if (!detail) return null
-  return mapDocumentDetail(detail)
-}
-
-export function useTextBlocks() {
-  const queryClient = useQueryClient()
-  const document = useCurrentDocument()
-  const textBlocks = document?.textBlocks ?? []
-  const selectedBlockIndex = useEditorUiStore((state) => state.selectedBlockIndex)
-  const setSelectedBlockIndex = useEditorUiStore((state) => state.setSelectedBlockIndex)
-
-  const invalidateDocument = useCallback(
-    async (docId: string) => {
-      await queryClient.invalidateQueries({
-        queryKey: getGetDocumentQueryKey(docId),
-      })
-      await queryClient.invalidateQueries({
-        queryKey: getListDocumentsQueryKey(),
-      })
-    },
-    [queryClient],
-  )
-
-  const updateTextBlocks = useCallback(
-    async (blocks: TextBlock[]) => {
-      const docId = useEditorUiStore.getState().currentDocumentId
-      if (!docId) return
-      await putTextBlocks(docId, blocks.map(toTextBlockInput))
-      await invalidateDocument(docId)
-    },
-    [invalidateDocument],
-  )
-
-  const replaceBlock = async (index: number, updates: Partial<TextBlock>) => {
-    const docId = useEditorUiStore.getState().currentDocumentId
-    if (!docId) return
-    const block = document?.textBlocks?.[index]
-    if (!block?.id) return
-
-    const patch: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(updates)) {
-      patch[key] = value
-    }
-
-    if (hasGeometryChange(updates)) {
-      const ui = useEditorUiStore.getState()
-      ui.setShowRenderedImage(false)
-      ui.setShowTextBlocksOverlay(true)
-    }
-
-    await patchTextBlock(docId, block.id, patch)
-    await invalidateDocument(docId)
-  }
-
-  const appendBlock = async (block: TextBlock) => {
-    const docId = useEditorUiStore.getState().currentDocumentId
-    if (!docId) return
-    await createTextBlock(docId, {
-      x: block.x,
-      y: block.y,
-      width: block.width,
-      height: block.height,
-    })
-    await invalidateDocument(docId)
-    const currentBlocks = document?.textBlocks ?? []
-    setSelectedBlockIndex(currentBlocks.length)
-  }
-
-  const removeBlock = async (index: number) => {
-    const currentBlocks = document?.textBlocks ?? []
-    const nextBlocks = currentBlocks.filter((_, idx) => idx !== index)
-    await updateTextBlocks(nextBlocks)
-    setSelectedBlockIndex(undefined)
-  }
-
-  const clearSelection = () => {
-    setSelectedBlockIndex(undefined)
-  }
-
-  return {
-    document,
-    textBlocks,
-    selectedBlockIndex,
-    setSelectedBlockIndex,
-    clearSelection,
-    replaceBlock,
-    appendBlock,
-    removeBlock,
-    updateTextBlocks,
-  }
-}