@bendyline/squisq-editor-react 1.4.0 → 1.5.1

package/src/imageEditor/layers/EditorTextLayer.tsx

@@ -0,0 +1,45 @@
+/**
+ * SVG renderer for an `ImageEditLayer` of kind `text` inside the editor.
+ *
+ * Multi-line text is laid out as a `<text>` element with one `<tspan>`
+ * per line. The first line sits at `y + fontSize` so the visible top
+ * of the glyph block aligns with the layer's `y` coordinate (matches
+ * what users expect from a top-anchored bounding box).
+ */
+
+import type { ImageEditCanvas, ImageEditLayer } from '@bendyline/squisq/schemas';
+
+interface Props {
+  layer: ImageEditLayer & { type: 'text' };
+  canvas: ImageEditCanvas;
+}
+
+export function EditorTextLayer({ layer, canvas: _canvas }: Props) {
+  const p = layer.position;
+  const x = typeof p.x === 'number' ? p.x : 0;
+  const y = typeof p.y === 'number' ? p.y : 0;
+  const { text, style } = layer.content;
+  const lineHeight = style.lineHeight ?? 1.4;
+  const lineHeightPx = style.fontSize * lineHeight;
+  const lines = (text ?? '').split('\n');
+  const textAnchor =
+    style.textAlign === 'center' ? 'middle' : style.textAlign === 'right' ? 'end' : 'start';
+
+  return (
+    <text
+      x={x}
+      y={y + style.fontSize}
+      fontFamily={style.fontFamily ?? 'sans-serif'}
+      fontSize={style.fontSize}
+      fontWeight={style.fontWeight ?? 'normal'}
+      fill={style.color}
+      textAnchor={textAnchor}
+    >
+      {lines.map((line, i) => (
+        <tspan key={i} x={x} dy={i === 0 ? 0 : lineHeightPx}>
+          {line || '\u00A0'}
+        </tspan>
+      ))}
+    </text>
+  );
+}

package/src/imageEditor/layers/SelectionHandles.tsx

@@ -0,0 +1,86 @@
+/**
+ * SelectionHandles
+ *
+ * Renders the dashed selection rectangle plus eight resize handles around
+ * the currently-selected layer's bounding box. Pointer events on each
+ * handle bubble back through `onHandlePointerDown` so the surrounding
+ * `<CanvasSurface>` can run its drag loop with the right resize semantics.
+ */
+
+import type { CanvasRect } from '../state.js';
+
+export type Handle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+
+const HANDLE_SIZE = 10; // canvas-pixel size of each square handle
+
+interface Props {
+  box: CanvasRect;
+  onHandlePointerDown: (e: React.PointerEvent<SVGRectElement>, handle: Handle) => void;
+}
+
+export function SelectionHandles({ box, onHandlePointerDown }: Props) {
+  const half = HANDLE_SIZE / 2;
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+
+  const handles: Array<{ id: Handle; x: number; y: number; cursor: string }> = [
+    { id: 'nw', x: box.x, y: box.y, cursor: 'nwse-resize' },
+    { id: 'n', x: cx, y: box.y, cursor: 'ns-resize' },
+    { id: 'ne', x: box.x + box.width, y: box.y, cursor: 'nesw-resize' },
+    { id: 'e', x: box.x + box.width, y: cy, cursor: 'ew-resize' },
+    { id: 'se', x: box.x + box.width, y: box.y + box.height, cursor: 'nwse-resize' },
+    { id: 's', x: cx, y: box.y + box.height, cursor: 'ns-resize' },
+    { id: 'sw', x: box.x, y: box.y + box.height, cursor: 'nesw-resize' },
+    { id: 'w', x: box.x, y: cy, cursor: 'ew-resize' },
+  ];
+
+  return (
+    <g pointerEvents="none">
+      {/*
+       * Outline: rendered as two stacked rectangles so the selection
+       * stays visible over both light and dark imagery. The white
+       * "halo" goes underneath; the blue dashed line on top. Both use
+       * `vector-effect: non-scaling-stroke` so the stroke width stays
+       * crisp at any zoom level (the SVG viewBox is the canvas size,
+       * which can be much larger than the rendered element).
+       */}
+      <rect
+        x={box.x}
+        y={box.y}
+        width={box.width}
+        height={box.height}
+        fill="none"
+        stroke="#ffffff"
+        strokeOpacity={0.9}
+        strokeWidth={4}
+        vectorEffect="non-scaling-stroke"
+      />
+      <rect
+        x={box.x}
+        y={box.y}
+        width={box.width}
+        height={box.height}
+        fill="none"
+        stroke="#39f"
+        strokeWidth={2}
+        strokeDasharray="6 4"
+        vectorEffect="non-scaling-stroke"
+      />
+      {handles.map((h) => (
+        <rect
+          key={h.id}
+          x={h.x - half}
+          y={h.y - half}
+          width={HANDLE_SIZE}
+          height={HANDLE_SIZE}
+          fill="#fff"
+          stroke="#39f"
+          strokeWidth={2}
+          vectorEffect="non-scaling-stroke"
+          style={{ cursor: h.cursor, pointerEvents: 'all' }}
+          onPointerDown={(e) => onHandlePointerDown(e, h.id)}
+        />
+      ))}
+    </g>
+  );
+}

package/src/imageEditor/state.ts

@@ -0,0 +1,153 @@
+/**
+ * Pure state + reducer for the `<ImageEditor>` component.
+ *
+ * Kept React-free so it's easy to unit-test in isolation. The actual
+ * React hook that wires this to a {@link ContentContainer} (and the
+ * version manager) lives in `useImageEditor.ts`.
+ */
+
+import type { ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
+import {
+  addLayer,
+  removeLayer,
+  reorderLayer,
+  setCanvas,
+  updateLayer,
+  touch,
+} from '@bendyline/squisq/imageEdit';
+
+/**
+ * Layer payload accepted by the `add-layer` action — the `id` field is
+ * optional and will be assigned by the underlying `addLayer` helper if
+ * the caller doesn't supply one.
+ */
+export type ImageEditLayerInput = ImageEditLayer | (Omit<ImageEditLayer, 'id'> & { id?: string });
+
+/** The currently active interaction tool. */
+export type ImageEditorTool = 'select' | 'text' | 'shape' | 'image' | 'crop';
+
+/** A pixel-space rectangle in canvas coordinates. */
+export interface CanvasRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ImageEditorState {
+  /** The persisted document. */
+  doc: ImageEditDoc;
+  /** Selected layer id, or `null` when nothing is selected. */
+  selectedLayerId: string | null;
+  /** Active tool. */
+  tool: ImageEditorTool;
+  /**
+   * Dirty flag — true when the in-memory doc has unsaved changes
+   * relative to the last `markClean()` call. The hook uses this to
+   * debounce writes back to `state.json`.
+   */
+  dirty: boolean;
+}
+
+export type ImageEditorAction =
+  | { type: 'load'; doc: ImageEditDoc }
+  | { type: 'mark-clean' }
+  | { type: 'set-tool'; tool: ImageEditorTool }
+  | { type: 'select'; layerId: string | null }
+  | { type: 'set-canvas'; canvas: ImageEditDoc['canvas'] }
+  | { type: 'add-layer'; layer: ImageEditLayerInput; select?: boolean }
+  | { type: 'remove-layer'; layerId: string }
+  | { type: 'update-layer'; layerId: string; patch: Partial<ImageEditLayer> }
+  | { type: 'reorder-layer'; layerId: string; toIndex: number }
+  | { type: 'crop'; rect: CanvasRect };
+
+/** Build the initial state from a freshly-loaded doc. */
+export function initialImageEditorState(doc: ImageEditDoc): ImageEditorState {
+  return {
+    doc,
+    selectedLayerId: null,
+    tool: 'select',
+    dirty: false,
+  };
+}
+
+export function imageEditorReducer(
+  state: ImageEditorState,
+  action: ImageEditorAction,
+): ImageEditorState {
+  switch (action.type) {
+    case 'load':
+      return { doc: action.doc, selectedLayerId: null, tool: 'select', dirty: false };
+
+    case 'mark-clean':
+      return state.dirty ? { ...state, dirty: false } : state;
+
+    case 'set-tool':
+      return state.tool === action.tool ? state : { ...state, tool: action.tool };
+
+    case 'select':
+      return state.selectedLayerId === action.layerId
+        ? state
+        : { ...state, selectedLayerId: action.layerId };
+
+    case 'set-canvas': {
+      const next = setCanvas(state.doc, action.canvas);
+      return next === state.doc ? state : { ...state, doc: next, dirty: true };
+    }
+
+    case 'add-layer': {
+      // `addLayer` from core assigns an id when missing; cast through
+      // `ImageEditLayer` for the existing helper signature.
+      const next = addLayer(state.doc, action.layer as ImageEditLayer);
+      // Pick up the assigned id (last layer)
+      const newId = next.layers[next.layers.length - 1]!.id;
+      return {
+        ...state,
+        doc: next,
+        dirty: true,
+        selectedLayerId: action.select === false ? state.selectedLayerId : newId,
+      };
+    }
+
+    case 'remove-layer': {
+      const next = removeLayer(state.doc, action.layerId);
+      if (next === state.doc) return state;
+      return {
+        ...state,
+        doc: next,
+        dirty: true,
+        selectedLayerId: state.selectedLayerId === action.layerId ? null : state.selectedLayerId,
+      };
+    }
+
+    case 'update-layer': {
+      const next = updateLayer(state.doc, action.layerId, action.patch);
+      return next === state.doc ? state : { ...state, doc: next, dirty: true };
+    }
+
+    case 'reorder-layer': {
+      const next = reorderLayer(state.doc, action.layerId, action.toIndex);
+      return next === state.doc ? state : { ...state, doc: next, dirty: true };
+    }
+
+    case 'crop': {
+      const { rect } = action;
+      const newCanvas = {
+        ...state.doc.canvas,
+        width: Math.max(1, Math.round(rect.width)),
+        height: Math.max(1, Math.round(rect.height)),
+      };
+      // Translate every layer by (-rect.x, -rect.y). Only handles numeric
+      // positions; percentage strings are left alone (rare for image-edit
+      // layers, which the editor produces with numeric coords).
+      const translated: ImageEditLayer[] = state.doc.layers.map((layer) => {
+        const { position } = layer;
+        const x = typeof position.x === 'number' ? position.x - rect.x : position.x;
+        const y = typeof position.y === 'number' ? position.y - rect.y : position.y;
+        return { ...layer, position: { ...position, x, y } } as ImageEditLayer;
+      });
+      const next = touch({ ...state.doc, canvas: newCanvas, layers: translated });
+      return { ...state, doc: next, dirty: true };
+    }
+  }
+}

package/src/imageEditor/useImageEditor.ts

@@ -0,0 +1,328 @@
+/**
+ * React hook that bundles the image-editor reducer with sidecar
+ * persistence, versioning, and an object-URL cache for asset bytes.
+ *
+ * Hosts pass an already-scoped {@link ContentContainer} (typically built
+ * with `scopeContainer(parent, basename + '_files')`); the hook never
+ * looks above that root.
+ */
+
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
+import {
+  IMAGE_EDIT_ASSETS_PREFIX,
+  IMAGE_EDIT_STATE_FILENAME,
+  ImageEditVersionManager,
+  createEmptyImageEditDoc,
+  readImageEditDoc,
+  writeImageEditDoc,
+} from '@bendyline/squisq/imageEdit';
+import {
+  imageEditorReducer,
+  initialImageEditorState,
+  type ImageEditorAction,
+  type ImageEditorState,
+} from './state.js';
+
+export interface UseImageEditorOptions {
+  /** Sidecar container for the image being edited. */
+  container: ContentContainer;
+  /**
+   * Initial source image URL — used to seed layer 0 when the sidecar has
+   * no `state.json` yet. Bytes are fetched and copied into
+   * `assets/source.<ext>` so the doc is portable.
+   */
+  initialSrc?: string;
+  /** Override the state filename. Defaults to `state.json`. */
+  stateFilename?: string;
+  /** Enable version history. Default: `false`. */
+  allowVersioning?: boolean;
+  /** Auto-save idle delay (ms). `0` disables. Default: `5000`. */
+  versioningAutoSaveIdleMs?: number;
+  /** Debounced write delay for state.json (ms). Default: `500`. */
+  persistDebounceMs?: number;
+}
+
+export interface UseImageEditorReturn {
+  /** Current reducer state (or `null` while still loading the initial doc). */
+  state: ImageEditorState | null;
+  /** Dispatch a reducer action. No-op while loading. */
+  dispatch: (action: ImageEditorAction) => void;
+  /** Manually trigger a synchronous write of `state.json`. */
+  flush: () => Promise<void>;
+  /** Resolve an asset path inside the sidecar to a blob URL (cached). */
+  resolveAssetUrl: (path: string) => Promise<string>;
+  /**
+   * Write a new asset (raster image) into `assets/` and return the
+   * sidecar-relative path. The caller is then expected to push a layer
+   * referencing that path.
+   */
+  uploadAsset: (file: Blob, suggestedName?: string) => Promise<string>;
+  /** Versioning handle. `null` when `allowVersioning` is false or no container. */
+  versioning: ImageEditVersionManager | null;
+  /** True after the initial load completes (either an existing doc or seeded). */
+  ready: boolean;
+  /** Last load / persistence error, if any. */
+  error: Error | null;
+}
+
+export function useImageEditor(options: UseImageEditorOptions): UseImageEditorReturn {
+  const {
+    container,
+    initialSrc,
+    stateFilename = IMAGE_EDIT_STATE_FILENAME,
+    allowVersioning = false,
+    versioningAutoSaveIdleMs = 5000,
+    persistDebounceMs = 500,
+  } = options;
+
+  const [state, dispatch] = useReducer(
+    (s: ImageEditorState | null, a: ImageEditorAction): ImageEditorState | null => {
+      if (s === null) return a.type === 'load' ? initialImageEditorState(a.doc) : null;
+      return imageEditorReducer(s, a);
+    },
+    null,
+  );
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  // Set to true inside the initial-load effect when we just seeded the
+  // sidecar (no prior `state.json`). The versioning effect below reads
+  // this flag to write an "original" snapshot once the manager exists.
+  const seededOnLoadRef = useRef(false);
+
+  // ── Initial load (or seed from initialSrc) ────────────────────────────
+  useEffect(() => {
+    let cancelled = false;
+    setReady(false);
+    setError(null);
+
+    (async () => {
+      try {
+        const existing = await readImageEditDoc(container, stateFilename);
+        if (cancelled) return;
+        if (existing) {
+          dispatch({ type: 'load', doc: existing });
+          setReady(true);
+          return;
+        }
+        // No existing state — seed.
+        const seeded = await seedFromSource(container, initialSrc);
+        if (cancelled) return;
+        await writeImageEditDoc(container, seeded, stateFilename);
+        dispatch({ type: 'load', doc: seeded });
+        setReady(true);
+        // Capture an initial snapshot of the freshly-seeded state so the
+        // version history always has an "original" entry the user can
+        // revert to after their first edit.
+        seededOnLoadRef.current = true;
+      } catch (err: unknown) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setReady(true);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [container, stateFilename, initialSrc]);
+
+  // ── Debounced persistence of state.json ────────────────────────────────
+  const persistTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const docRef = useRef<ImageEditDoc | null>(null);
+  docRef.current = state?.doc ?? null;
+
+  useEffect(() => {
+    if (!state?.dirty) return;
+    if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
+    persistTimerRef.current = setTimeout(() => {
+      const doc = docRef.current;
+      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,
+          );
+        });
+    }, persistDebounceMs);
+    return () => {
+      if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
+    };
+  }, [state?.dirty, state?.doc, container, stateFilename, persistDebounceMs]);
+
+  const flush = useCallback(async () => {
+    const doc = docRef.current;
+    if (!doc) return;
+    if (persistTimerRef.current) {
+      clearTimeout(persistTimerRef.current);
+      persistTimerRef.current = null;
+    }
+    await writeImageEditDoc(container, doc, stateFilename);
+    dispatch({ type: 'mark-clean' });
+  }, [container, stateFilename]);
+
+  // ── Versioning ─────────────────────────────────────────────────────────
+  const versioning = useMemo(
+    () => (allowVersioning ? new ImageEditVersionManager(container, { stateFilename }) : null),
+    [allowVersioning, container, stateFilename],
+  );
+
+  // Drop the "original" snapshot once versioning is wired and we just
+  // seeded a fresh sidecar. Guarded by `seededOnLoadRef` so we never
+  // duplicate-snapshot on subsequent renders. Uses `force: true` so the
+  // initial entry always lands even though no diff has occurred yet.
+  useEffect(() => {
+    if (!versioning) return;
+    if (!ready) return;
+    if (!seededOnLoadRef.current) return;
+    seededOnLoadRef.current = false;
+    versioning.saveVersion({ force: true }).catch((err: unknown) => {
+      console.warn(
+        '[squisq-editor] image-edit initial snapshot failed:',
+        err instanceof Error ? err.message : err,
+      );
+    });
+  }, [versioning, ready]);
+
+  useEffect(() => {
+    if (!versioning) return;
+    if (versioningAutoSaveIdleMs <= 0) return;
+    if (!state?.doc) return;
+    const timer = setTimeout(() => {
+      versioning.saveVersion({ doc: docRef.current ?? undefined }).catch((err: unknown) => {
+        console.warn(
+          '[squisq-editor] image-edit auto-save version failed:',
+          err instanceof Error ? err.message : err,
+        );
+      });
+    }, versioningAutoSaveIdleMs);
+    return () => clearTimeout(timer);
+  }, [versioning, versioningAutoSaveIdleMs, state?.doc]);
+
+  // ── Asset URL cache ────────────────────────────────────────────────────
+  const urlCacheRef = useRef<Map<string, string>>(new Map());
+
+  const resolveAssetUrl = useCallback(
+    async (path: string): Promise<string> => {
+      const cache = urlCacheRef.current;
+      const cached = cache.get(path);
+      if (cached) return cached;
+      const data = await container.readFile(path);
+      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 }));
+      cache.set(path, url);
+      return url;
+    },
+    [container],
+  );
+
+  // Revoke all cached object URLs on unmount / container swap
+  useEffect(() => {
+    const cache = urlCacheRef.current;
+    return () => {
+      for (const url of cache.values()) URL.revokeObjectURL(url);
+      cache.clear();
+    };
+  }, [container]);
+
+  const uploadAsset = useCallback(
+    async (file: Blob, suggestedName?: string): Promise<string> => {
+      const ext = guessExtensionFromMime(file.type) ?? extensionFromName(suggestedName) ?? 'bin';
+      const id = randomId();
+      const path = `${IMAGE_EDIT_ASSETS_PREFIX}${id}.${ext}`;
+      const buf = await file.arrayBuffer();
+      await container.writeFile(path, buf, file.type || undefined);
+      return path;
+    },
+    [container],
+  );
+
+  return {
+    state,
+    dispatch,
+    flush,
+    resolveAssetUrl,
+    uploadAsset,
+    versioning,
+    ready,
+    error,
+  };
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+async function seedFromSource(
+  container: ContentContainer,
+  initialSrc: string | undefined,
+): Promise<ImageEditDoc> {
+  if (!initialSrc) {
+    return createEmptyImageEditDoc(800, 600);
+  }
+  // Fetch the source bytes (works for blob:, data:, http(s):, and same-origin
+  // relative URLs).
+  const resp = await fetch(initialSrc);
+  if (!resp.ok) throw new Error(`useImageEditor: failed to fetch initialSrc (${resp.status})`);
+  const blob = await resp.blob();
+  const ext = guessExtensionFromMime(blob.type) ?? 'png';
+  const assetPath = `${IMAGE_EDIT_ASSETS_PREFIX}source.${ext}`;
+  await container.writeFile(assetPath, await blob.arrayBuffer(), blob.type || undefined);
+
+  // Probe natural dimensions by loading into an Image.
+  const dims = await probeImageDimensions(initialSrc);
+  const w = dims?.width ?? 800;
+  const h = dims?.height ?? 600;
+
+  const layer: ImageEditLayer = {
+    id: 'base',
+    type: 'image',
+    name: 'Background',
+    position: { x: 0, y: 0, width: w, height: h },
+    content: { src: assetPath, alt: '', fit: 'fill' },
+  };
+  return {
+    version: 1,
+    canvas: { width: w, height: h, background: 'transparent' },
+    layers: [layer],
+    meta: {
+      sourcePath: assetPath,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  };
+}
+
+function probeImageDimensions(src: string): Promise<{ width: number; height: number } | null> {
+  return new Promise((resolve) => {
+    const img = new Image();
+    img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+    img.onerror = () => resolve(null);
+    img.src = src;
+  });
+}
+
+function guessExtensionFromMime(mime: string | undefined): string | null {
+  if (!mime) return null;
+  if (mime.includes('png')) return 'png';
+  if (mime.includes('jpeg') || mime.includes('jpg')) return 'jpg';
+  if (mime.includes('webp')) return 'webp';
+  if (mime.includes('gif')) return 'gif';
+  if (mime.includes('svg')) return 'svg';
+  return null;
+}
+
+function extensionFromName(name: string | undefined): string | null {
+  if (!name) return null;
+  const dot = name.lastIndexOf('.');
+  return dot >= 0 ? name.slice(dot + 1).toLowerCase() : null;
+}
+
+function randomId(): string {
+  return Math.random().toString(36).slice(2, 10);
+}

package/src/imageEditor/useImageEditorTokens.ts

@@ -0,0 +1,70 @@
+/**
+ * Derive `--squisq-image-editor-*` CSS custom properties from a Theme +
+ * SurfaceScheme, mirroring `useJsonViewTokens` in squisq-react. Lets the
+ * ImageEditor re-theme consistently with the rest of Squisq (light/dark
+ * surface, theme palette, font family overrides).
+ */
+
+import { useMemo, type CSSProperties } from 'react';
+import {
+  applySurface,
+  resolveFontFamily,
+  type SurfaceScheme,
+  type Theme,
+} from '@bendyline/squisq/schemas';
+import { DEFAULT_THEME } from '@bendyline/squisq/doc';
+import { useAutoSurface } from '@bendyline/squisq-react';
+
+export interface ImageEditorTokens {
+  /** Inline style object to spread onto the root `.squisq-image-editor`. */
+  style: CSSProperties;
+  /** The effective theme (after surface application). */
+  theme: Theme;
+}
+
+export function useImageEditorTokens(
+  theme: Theme | undefined,
+  surface: SurfaceScheme | 'auto' | undefined,
+): ImageEditorTokens {
+  const auto = useAutoSurface(surface === 'auto');
+  const effectiveSurface = surface === 'auto' ? auto : (surface ?? undefined);
+
+  return useMemo(() => {
+    const baseTheme = theme ?? DEFAULT_THEME;
+    const finalTheme = effectiveSurface ? applySurface(baseTheme, effectiveSurface) : baseTheme;
+
+    const bg = finalTheme.colors.background;
+    const text = finalTheme.colors.text;
+    const muted = finalTheme.colors.textMuted;
+    const accent = finalTheme.colors.primary;
+
+    // Panel / control surfaces are derived by mixing toward the opposite
+    // pole (text color), so the same recipe works for both light and dark
+    // surfaces without conditional branches.
+    const panelBg = `color-mix(in srgb, ${bg} 92%, ${text} 8%)`;
+    const panelBorder = `color-mix(in srgb, ${bg} 80%, ${text} 20%)`;
+    const controlBg = `color-mix(in srgb, ${bg} 86%, ${text} 14%)`;
+    const controlBorder = `color-mix(in srgb, ${bg} 72%, ${text} 28%)`;
+    const workspaceBg = `color-mix(in srgb, ${bg} 95%, ${text} 5%)`;
+
+    const bodyFont = resolveFontFamily(
+      finalTheme.typography.bodyFont,
+      'system-ui, -apple-system, sans-serif',
+    );
+
+    const style: CSSProperties = {
+      ['--squisq-image-editor-bg' as string]: bg,
+      ['--squisq-image-editor-panel-bg' as string]: panelBg,
+      ['--squisq-image-editor-panel-border' as string]: panelBorder,
+      ['--squisq-image-editor-text' as string]: text,
+      ['--squisq-image-editor-text-muted' as string]: muted,
+      ['--squisq-image-editor-accent' as string]: accent,
+      ['--squisq-image-editor-control-bg' as string]: controlBg,
+      ['--squisq-image-editor-control-border' as string]: controlBorder,
+      ['--squisq-image-editor-workspace-bg' as string]: workspaceBg,
+      ['--squisq-image-editor-body-font' as string]: bodyFont,
+    };
+
+    return { style, theme: finalTheme };
+  }, [theme, effectiveSurface]);
+}