@bendyline/squisq-editor-react 1.6.1 → 2.0.0

package/src/customThemes/CustomThemeDialog.tsx

@@ -24,9 +24,10 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type { Theme, ThemeSeedColors } from '@bendyline/squisq/schemas';
+import type { CustomTemplateDefinition, Theme, ThemeSeedColors } from '@bendyline/squisq/schemas';
 import { resolveTheme } from '@bendyline/squisq/schemas';
 import { ThemePicker } from '../ThemePicker';
+import { ImportThemeSection } from './ImportThemeSection';
 import {
   type Draft,
   type AccentInput,
@@ -49,13 +50,19 @@ import { Section, SeedColorRow, FontPicker, PresetRow, AccentEditor } from './th
 /** Where a saved theme lands — mirrors `DesignerSaveTarget` for templates. */
 export type ThemeSaveTarget = 'doc' | 'library';
 
+/** Extra assets riding along with a theme save (file-import byproducts). */
+export interface ThemeSaveExtras {
+  /** Custom layout templates inferred from an imported PPTX. */
+  templates?: CustomTemplateDefinition[];
+}
+
 export interface CustomThemeDialogProps {
   /** Theme being edited, or null to author a new one. */
   value: Theme | null;
   /** Fired on every edit with the compiled theme (host previews via themeOverride). */
   onChange?: (theme: Theme) => void;
   /** Fired when the user saves, with the chosen target. */
-  onSave: (theme: Theme, target: ThemeSaveTarget) => void;
+  onSave: (theme: Theme, target: ThemeSaveTarget, extras?: ThemeSaveExtras) => void;
   /** Dismiss (Cancel / Esc / close button). */
   onClose: () => void;
 }
@@ -70,6 +77,8 @@ function initialDraft(value: Theme | null): Draft {
 
 export function CustomThemeDialog({ value, onChange, onSave, onClose }: CustomThemeDialogProps) {
   const [draft, setDraft] = useState<Draft>(() => initialDraft(value));
+  // Layout templates inferred from a file import, saved alongside the theme.
+  const [importedLayouts, setImportedLayouts] = useState<CustomTemplateDefinition[] | null>(null);
 
   const nameRef = useRef<HTMLInputElement>(null);
   useEffect(() => {
@@ -117,12 +126,16 @@ export function CustomThemeDialog({ value, onChange, onSave, onClose }: CustomTh
   const handleSave = useCallback(
     (target: ThemeSaveTarget) => {
       try {
-        onSave(compile(draft), target);
+        const extras =
+          importedLayouts && importedLayouts.length > 0
+            ? { templates: importedLayouts }
+            : undefined;
+        onSave(compile(draft), target, extras);
       } catch {
         // A compile failure here means the draft is invalid; leave the dialog open.
       }
     },
-    [draft, onSave, compile],
+    [draft, onSave, compile, importedLayouts],
   );
 
   // Accents show the base's schemes until the user edits them (then the draft's
@@ -175,6 +188,19 @@ export function CustomThemeDialog({ value, onChange, onSave, onClose }: CustomTh
           />
         </Section>
 
+        <Section
+          title="Import from file"
+          hint="Pull colors and fonts from a Word, PowerPoint, or Excel file. PowerPoint slide layouts become custom layouts."
+        >
+          <ImportThemeSection
+            allowLayouts
+            onImported={(patch, result) => {
+              updateDraft(patch);
+              setImportedLayouts(result.layouts ?? null);
+            }}
+          />
+        </Section>
+
         <Section
           title="Colors"
           hint="Primary, secondary, and tertiary (accent). The rest is derived."
@@ -269,7 +295,11 @@ export function CustomThemeDialog({ value, onChange, onSave, onClose }: CustomTh
           type="button"
           className="squisq-doc-settings-btn squisq-doc-settings-btn--secondary"
           onClick={() => handleSave('library')}
-          title="Save to your browser-local library so other docs can use it"
+          title={
+            importedLayouts && importedLayouts.length > 0
+              ? 'Save to your browser-local library so other docs can use it (imported slide layouts only save to the document)'
+              : 'Save to your browser-local library so other docs can use it'
+          }
         >
           Save to library
         </button>

package/src/customThemes/ImportThemeSection.tsx

@@ -0,0 +1,178 @@
+/**
+ * ImportThemeSection
+ *
+ * "Infer theme from a file" affordance shared by the CustomThemeDialog pane
+ * and the ThemeCustomizerPanel popover: a Choose-file button plus a local
+ * dropzone that accepts a Word/PowerPoint/Excel file, runs
+ * `inferThemeFromFile` from `@bendyline/squisq-formats/infer` (loaded
+ * lazily), and hands back a `Partial<Draft>` patch for the host's
+ * `updateDraft` — so the existing live-preview path applies unchanged.
+ *
+ * The dropzone handles its own drag events with `stopPropagation` so a file
+ * dropped here never reaches EditorShell's document-import drop handling.
+ */
+
+import { useCallback, useRef, useState } from 'react';
+import type { DragEvent } from 'react';
+import type { CustomTemplateDefinition, Theme } from '@bendyline/squisq/schemas';
+import { draftPatchFromImportedTheme, type Draft } from './themeDraft';
+
+export interface ImportedThemeResult {
+  theme: Theme;
+  /** PPTX only, when `allowLayouts`: custom templates derived from slide layouts. */
+  layouts?: CustomTemplateDefinition[];
+  warnings: string[];
+  fileName: string;
+}
+
+export interface ImportThemeSectionProps {
+  /** Fired on successful inference with the draft patch + full result. */
+  onImported: (patch: Partial<Draft>, result: ImportedThemeResult) => void;
+  /** Also derive PPTX slide layouts as custom templates. Default false. */
+  allowLayouts?: boolean;
+}
+
+const ACCEPT = '.docx,.pptx,.xlsx';
+const SUPPORTED_RE = /\.(docx|pptx|xlsx)$/i;
+const MAX_VISIBLE_WARNINGS = 4;
+
+/**
+ * Read a File's bytes. Prefers the modern `arrayBuffer()`; falls back to
+ * FileReader for environments (e.g. some jsdom builds) whose Blob lacks it —
+ * same posture as the formats registry's byte normalizer.
+ */
+function readFileBytes(file: File): Promise<ArrayBuffer> {
+  if (typeof file.arrayBuffer === 'function') return file.arrayBuffer();
+  return new Promise<ArrayBuffer>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as ArrayBuffer);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsArrayBuffer(file);
+  });
+}
+
+export function ImportThemeSection({ onImported, allowLayouts = false }: ImportThemeSectionProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [status, setStatus] = useState<string | null>(null);
+  const [warnings, setWarnings] = useState<string[]>([]);
+  const [dragOver, setDragOver] = useState(false);
+
+  const handleFile = useCallback(
+    async (file: File) => {
+      if (!SUPPORTED_RE.test(file.name)) {
+        setError('Only .docx, .pptx, or .xlsx files carry a theme.');
+        return;
+      }
+      setBusy(true);
+      setError(null);
+      setStatus(null);
+      setWarnings([]);
+      try {
+        const buffer = await readFileBytes(file);
+        const { inferThemeFromFile } = await import('@bendyline/squisq-formats/infer');
+        const nameHint = file.name.replace(/\.[^.]+$/, '');
+        const result = await inferThemeFromFile(buffer, {
+          inferLayouts: allowLayouts,
+          nameHint,
+        });
+        const layouts = result.layouts ?? [];
+        onImported(draftPatchFromImportedTheme(result.theme), {
+          theme: result.theme,
+          ...(layouts.length > 0 ? { layouts } : {}),
+          warnings: result.warnings,
+          fileName: file.name,
+        });
+        setStatus(
+          layouts.length > 0
+            ? `Imported colors and fonts from ${file.name} — ${layouts.length} slide layout${
+                layouts.length === 1 ? '' : 's'
+              } will be saved with the document.`
+            : `Imported colors and fonts from ${file.name}.`,
+        );
+        setWarnings(result.warnings);
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : 'Could not read a theme from that file.');
+      } finally {
+        setBusy(false);
+        if (inputRef.current) inputRef.current.value = '';
+      }
+    },
+    [allowLayouts, onImported],
+  );
+
+  // Local drag handling only — never let the editor's global drop routing
+  // treat a theme-source file as a document import.
+  const onDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragOver(true);
+  }, []);
+  const onDragLeave = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragOver(false);
+  }, []);
+  const onDrop = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      e.stopPropagation();
+      setDragOver(false);
+      const file = e.dataTransfer.files?.[0];
+      if (file) void handleFile(file);
+    },
+    [handleFile],
+  );
+
+  const visibleWarnings = warnings.slice(0, MAX_VISIBLE_WARNINGS);
+  const hiddenWarnings = warnings.length - visibleWarnings.length;
+
+  return (
+    <div className="squisq-theme-import">
+      <div
+        className={`squisq-theme-import-drop${dragOver ? ' squisq-theme-import-drop--active' : ''}${
+          busy ? ' squisq-theme-import-drop--busy' : ''
+        }`}
+        onDragOver={onDragOver}
+        onDragLeave={onDragLeave}
+        onDrop={onDrop}
+      >
+        <button
+          type="button"
+          className="squisq-theme-customizer-button"
+          onClick={() => inputRef.current?.click()}
+          disabled={busy}
+        >
+          {busy ? 'Reading…' : 'Choose file…'}
+        </button>
+        <span className="squisq-theme-import-hint">or drop a .docx / .pptx / .xlsx here</span>
+        <input
+          ref={inputRef}
+          type="file"
+          accept={ACCEPT}
+          style={{ display: 'none' }}
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            if (file) void handleFile(file);
+          }}
+          aria-label="Import theme from file"
+        />
+      </div>
+      {error && (
+        <div className="squisq-theme-import-error" role="alert">
+          {error}
+        </div>
+      )}
+      {status && <div className="squisq-theme-import-status">{status}</div>}
+      {visibleWarnings.length > 0 && (
+        <ul className="squisq-theme-import-warnings">
+          {visibleWarnings.map((w, i) => (
+            <li key={i}>{w}</li>
+          ))}
+          {hiddenWarnings > 0 && <li>…and {hiddenWarnings} more</li>}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/customThemes/__tests__/customThemeLibrary.test.ts

@@ -11,6 +11,7 @@ import {
   saveLibraryTheme,
   deleteLibraryTheme,
   clearThemeLibrary,
+  THEME_LIBRARY_STORAGE_KEY,
 } from '../customThemeLibrary';
 import { compileTheme } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
@@ -48,4 +49,12 @@ describe('customThemeLibrary', () => {
     clearThemeLibrary();
     expect(listLibraryThemes()).toEqual([]);
   });
+
+  it('filters invalid stored entries instead of crashing sort', () => {
+    window.localStorage.setItem(
+      THEME_LIBRARY_STORAGE_KEY,
+      JSON.stringify({ version: 1, themes: [null, {}, theme('valid')] }),
+    );
+    expect(listLibraryThemes().map((entry) => entry.id)).toEqual(['valid']);
+  });
 });

package/src/customThemes/__tests__/importThemeSection.test.tsx

@@ -0,0 +1,192 @@
+/**
+ * ImportThemeSection — the "infer theme from a file" affordance. Verifies the
+ * draft patch handed to hosts, error handling, drop-type gating, and that a
+ * designer save with imported layouts writes theme + selection + templates in
+ * a single frontmatter update.
+ */
+
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { CustomTemplateDefinition, Theme } from '@bendyline/squisq/schemas';
+import { compileTheme } from '@bendyline/squisq/schemas';
+import { ImportThemeSection } from '../ImportThemeSection';
+import { draftPatchFromImportedTheme } from '../themeDraft';
+import { EditorProvider, useEditorContext } from '../../EditorContext';
+import { PreviewSettingsProvider, usePreviewSettings } from '../../PreviewControls';
+
+const { inferMock } = vi.hoisted(() => ({ inferMock: vi.fn() }));
+vi.mock('@bendyline/squisq-formats/infer', () => ({ inferThemeFromFile: inferMock }));
+
+afterEach(() => {
+  cleanup();
+  inferMock.mockReset();
+});
+
+const importedTheme: Theme = compileTheme({
+  id: 'custom-deck',
+  name: 'Deck',
+  seedColors: { primary: '#4472c4', background: '#fdfdf8', text: '#1a1a2e' },
+  typography: {
+    titleFont: { stackId: 'playfair' },
+    bodyFont: { custom: { name: 'Aptos', fallback: 'sans-serif' } },
+  },
+  colorSchemes: { accent1: { bg: '#101020', text: '#e2e8f0', accent: '#4472c4' } },
+});
+
+const importedLayout: CustomTemplateDefinition = {
+  name: 'pptx-two-content',
+  label: 'Two Content',
+  viewport: { width: 1920, height: 1080 },
+  layers: [
+    {
+      id: 'title',
+      type: 'text',
+      position: { x: '5%', y: '10%', width: '90%', height: '20%' },
+      content: { text: '{title}', style: { fontSize: 88, color: '#111111' } },
+    },
+  ],
+};
+
+function pickFile(name = 'deck.pptx'): void {
+  const file = new File([new Uint8Array([0x50, 0x4b, 3, 4])], name);
+  fireEvent.change(screen.getByLabelText('Import theme from file'), {
+    target: { files: [file] },
+  });
+}
+
+describe('ImportThemeSection', () => {
+  it('imports a theme and hands the host a draft patch + layouts', async () => {
+    inferMock.mockResolvedValue({
+      theme: importedTheme,
+      extraction: { sourceFormat: 'pptx', colorMap: { bg1: 'lt1', tx1: 'dk1' }, warnings: [] },
+      layouts: [importedLayout],
+      warnings: ['theme: accent4 color could not be resolved; dropped'],
+    });
+    const onImported = vi.fn();
+    render(<ImportThemeSection allowLayouts onImported={onImported} />);
+
+    pickFile();
+    await waitFor(() => expect(onImported).toHaveBeenCalledTimes(1));
+
+    expect(inferMock).toHaveBeenCalledWith(expect.anything(), {
+      inferLayouts: true,
+      nameHint: 'deck',
+    });
+
+    const [patch, result] = onImported.mock.calls[0]!;
+    expect(patch.name).toBe('Deck');
+    expect(patch.seeds.primary).toBe('#4472c4');
+    expect(patch.accentsEdited).toBe(true);
+    expect(patch.accents).toEqual([{ key: 'accent1', color: '#4472c4' }]);
+    expect(patch.titleFont).toEqual({ kind: 'curated', stackId: 'playfair' });
+    expect(patch.bodyFont).toEqual({
+      kind: 'custom',
+      customName: 'Aptos',
+      customFallback: 'sans-serif',
+    });
+    // The patch never touches base or style presets.
+    expect('baseId' in patch).toBe(false);
+    expect('borderRadius' in patch).toBe(false);
+
+    expect(result.layouts).toHaveLength(1);
+    expect(result.fileName).toBe('deck.pptx');
+    expect(screen.getByText(/1 slide layout/)).toBeTruthy();
+    expect(screen.getByText(/accent4/)).toBeTruthy();
+  });
+
+  it('shows the inference error and never fires onImported', async () => {
+    inferMock.mockRejectedValue(new Error('No theme part found in this file.'));
+    const onImported = vi.fn();
+    render(<ImportThemeSection onImported={onImported} />);
+
+    pickFile();
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain('No theme part found'),
+    );
+    expect(onImported).not.toHaveBeenCalled();
+  });
+
+  it('rejects unsupported file types dropped on the zone', async () => {
+    const onImported = vi.fn();
+    const { container } = render(<ImportThemeSection onImported={onImported} />);
+    const zone = container.querySelector('.squisq-theme-import-drop')!;
+    fireEvent.drop(zone, {
+      dataTransfer: { files: [new File(['x'], 'notes.txt')] },
+    });
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain('Only .docx, .pptx, or .xlsx'),
+    );
+    expect(inferMock).not.toHaveBeenCalled();
+    expect(onImported).not.toHaveBeenCalled();
+  });
+});
+
+describe('draftPatchFromImportedTheme', () => {
+  it('carries seeds/fonts/accents and nothing else', () => {
+    const patch = draftPatchFromImportedTheme(importedTheme);
+    expect(Object.keys(patch).sort()).toEqual([
+      'accents',
+      'accentsEdited',
+      'bodyFont',
+      'name',
+      'seeds',
+      'titleFont',
+    ]);
+    expect(patch.seeds).toMatchObject({ primary: '#4472c4', background: '#fdfdf8' });
+  });
+});
+
+// ── Designer save with imported layouts → single frontmatter write ───
+
+function DesignerSaveHarness() {
+  const settings = usePreviewSettings();
+  const { markdownSource } = useEditorContext();
+  return (
+    <div>
+      <button type="button" onClick={() => settings.openThemeDesigner(null)}>
+        open designer
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          settings.themeDesigner?.onSave(importedTheme, 'doc', { templates: [importedLayout] })
+        }
+      >
+        save with layouts
+      </button>
+      <pre data-testid="markdown-source">{markdownSource}</pre>
+    </div>
+  );
+}
+
+function HarnessRoot() {
+  const { doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <DesignerSaveHarness />
+    </PreviewSettingsProvider>
+  );
+}
+
+describe('theme designer save with imported layouts', () => {
+  it('writes theme payload, selection, and templates in one frontmatter update', async () => {
+    render(
+      <EditorProvider initialMarkdown={'# Hello\n\nBody.\n'}>
+        <HarnessRoot />
+      </EditorProvider>,
+    );
+
+    fireEvent.click(screen.getByText('open designer'));
+    fireEvent.click(screen.getByText('save with layouts'));
+
+    await waitFor(() => {
+      const source = screen.getByTestId('markdown-source').textContent ?? '';
+      expect(source).toContain('squisq-theme: custom-deck');
+      expect(source).toContain('squisq-custom-themes');
+      expect(source).toContain('squisq-custom-templates');
+      expect(source).toContain('pptx-two-content');
+    });
+  });
+});

package/src/customThemes/customThemeLibrary.ts

@@ -14,7 +14,7 @@
  * unavailable.
  */
 
-import type { Theme } from '@bendyline/squisq/schemas';
+import { validateTheme, type Theme } from '@bendyline/squisq/schemas';
 
 export const THEME_LIBRARY_STORAGE_KEY = 'squisq:custom-theme-library';
 
@@ -38,12 +38,15 @@ function safeStorage(): Storage | null {
 function readPayload(): LibraryPayload {
   const storage = safeStorage();
   if (!storage) return { version: 1, themes: [] };
-  const raw = storage.getItem(THEME_LIBRARY_STORAGE_KEY);
-  if (!raw) return { version: 1, themes: [] };
   try {
+    const raw = storage.getItem(THEME_LIBRARY_STORAGE_KEY);
+    if (!raw) return { version: 1, themes: [] };
     const parsed = JSON.parse(raw) as Partial<LibraryPayload>;
     if (parsed && Array.isArray(parsed.themes)) {
-      return { version: 1, themes: parsed.themes };
+      return {
+        version: 1,
+        themes: parsed.themes.filter((theme): theme is Theme => validateTheme(theme).valid),
+      };
     }
   } catch {
     // Corrupt payload — drop it.

package/src/customThemes/index.ts

@@ -27,5 +27,11 @@ export {
   CustomThemeDialog,
   type CustomThemeDialogProps,
   type ThemeSaveTarget,
+  type ThemeSaveExtras,
 } from './CustomThemeDialog';
-export { compileDraft, themeToDraft, type Draft } from './themeDraft';
+export {
+  ImportThemeSection,
+  type ImportThemeSectionProps,
+  type ImportedThemeResult,
+} from './ImportThemeSection';
+export { compileDraft, themeToDraft, draftPatchFromImportedTheme, type Draft } from './themeDraft';

package/src/customThemes/themeDraft.ts

@@ -15,7 +15,7 @@ import type {
   ThemeSeedColors,
   ThemeColorScheme,
 } from '@bendyline/squisq/schemas';
-import { compileTheme, deriveScale, isHex } from '@bendyline/squisq/schemas';
+import { accentToColorScheme, compileTheme } from '@bendyline/squisq/schemas';
 
 // ── Preset → schema-value tables ────────────────────────────────────
 
@@ -164,14 +164,12 @@ export function accentsFromTheme(theme: Theme | null): AccentInput[] {
 }
 
 /**
- * Expand one accent color into a full `{bg, text, accent}` color scheme via
- * the OKLCh scale — dark saturated bg, light readable text, the picked accent.
- * Falls back to a neutral scheme when the input isn't a valid hex.
+ * Expand one accent color into a full `{bg, text, accent}` color scheme.
+ * Delegates to core's `accentToColorScheme` so file-import theme inference
+ * and the editor's accent list derive identical schemes.
  */
 export function schemeFromAccent(accent: string): ThemeColorScheme {
-  if (!isHex(accent)) return { bg: '#1a202c', text: '#e2e8f0', accent: '#63b3ed' };
-  const scale = deriveScale(accent, 0.3);
-  return { bg: scale.darker2, text: scale.lighter2, accent: scale.base };
+  return accentToColorScheme(accent);
 }
 
 export function themeToDraft(theme: Theme | null): Draft {
@@ -220,6 +218,24 @@ export function slugify(s: string): string {
   );
 }
 
+/**
+ * Draft patch from a theme inferred from an imported office file: name,
+ * seeds, accents (marked authored so the file's schemes survive a re-save),
+ * and fonts. Deliberately leaves `baseId` and the style presets untouched —
+ * the user's in-progress choices there aren't the file's to overwrite.
+ */
+export function draftPatchFromImportedTheme(theme: Theme): Partial<Draft> {
+  const d = themeToDraft(theme);
+  return {
+    name: d.name,
+    seeds: d.seeds,
+    accents: d.accents,
+    accentsEdited: d.accents.length > 0,
+    titleFont: d.titleFont,
+    bodyFont: d.bodyFont,
+  };
+}
+
 export interface CompileDraftOptions {
   /** Existing id to preserve across edits (keeps `squisq-theme` selection stable). */
   existingId?: string;

package/src/diagram/DiagramCanvas.tsx

@@ -22,8 +22,9 @@ import {
   type SceneCommand,
 } from '../scene';
 import type { SceneTextEditConfig } from '../scene/text/sceneTextConfig';
+import type { SceneTextChannel } from '../scene/text/sceneTextChannel';
 import { markdownToTiptap } from '../tiptapBridge';
-import type { DiagramRFNode, DiagramRFEdge } from './useDiagramData';
+import type { DiagramNode, DiagramEdge } from './types';
 import { DIAGRAM_VIEWPORT, DIAGRAM_TOOLS } from './diagramConstants';
 
 export type DiagramCommand =
@@ -36,8 +37,8 @@ export type DiagramCommand =
   | { kind: 'removeNode'; nodeId: string };
 
 interface DiagramCanvasProps {
-  nodes: DiagramRFNode[];
-  edges: DiagramRFEdge[];
+  nodes: DiagramNode[];
+  edges: DiagramEdge[];
   onCommand: (cmd: DiagramCommand) => void;
   /** When true, render the maximize button. Click toggles `onToggleMaximize`. */
   showMaximize?: boolean;
@@ -54,6 +55,8 @@ interface DiagramCanvasProps {
   onActiveToolIdChange?: (id: string) => void;
   /** Forwarded to the Scene so the host can drive a Delete action. */
   onSelectionChange?: (ids: ReadonlySet<string>) => void;
+  /** Per-editor toolbar bridge for detached scene roots. */
+  textChannel?: SceneTextChannel;
 }
 
 const TOOLS = DIAGRAM_TOOLS;
@@ -68,6 +71,7 @@ export function DiagramCanvas({
   activeToolId: controlledToolId,
   onActiveToolIdChange,
   onSelectionChange,
+  textChannel,
 }: DiagramCanvasProps) {
   const scene = useMemo(
     () => buildDiagramScene(incomingNodes, incomingEdges),
@@ -171,6 +175,7 @@ export function DiagramCanvas({
   incomingNodesRef.current = incomingNodes;
   const textConfig = useMemo<SceneTextEditConfig>(
     () => ({
+      channel: textChannel,
       resolveEditableId: (id) => (nodeIdFromCardLayerId(id) ? id : null),
       getHtml: (id) => {
         const nodeId = nodeIdFromCardLayerId(id);
@@ -184,7 +189,7 @@ export function DiagramCanvas({
       },
       level: 'inline',
     }),
-    [handleSceneCommand],
+    [handleSceneCommand, textChannel],
   );
 
   return (

package/src/diagram/types.ts

@@ -0,0 +1,35 @@
+/** Data shapes consumed by `DiagramCanvas` / `buildDiagramScene`. */
+
+import type { DiagramEdgeAnchor } from '@bendyline/squisq/schemas';
+import type { ConnectorRouting } from '@bendyline/squisq/doc';
+
+export interface DiagramNode {
+  id: string;
+  position: { x: number; y: number };
+  data: { label: string };
+  type?: string;
+  /** Per-node width override in canvas units. */
+  width?: number;
+  /** Per-node height override in canvas units. */
+  height?: number;
+  /** Render as a background container card (top-anchored label, muted fill). */
+  kind?: 'container';
+}
+
+export interface DiagramEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+  /** False → no end arrowhead. Undefined keeps the diagram default (arrow). */
+  directed?: boolean;
+  sourceAnchor?: DiagramEdgeAnchor;
+  targetAnchor?: DiagramEdgeAnchor;
+  routing?: ConnectorRouting;
+}
+
+export interface DiagramData {
+  nodes: DiagramNode[];
+  edges: DiagramEdge[];
+  warnings: string[];
+}