@bendyline/squisq-editor-react 1.6.0 → 1.6.1

package/src/__tests__/previewControls.test.tsx

@@ -0,0 +1,70 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { EditorProvider, useEditorContext } from '../EditorContext';
+import { PreviewModeSwitch, PreviewSettingsProvider, usePreviewSettings } from '../PreviewControls';
+
+function ModeProbe() {
+  const { activeDisplayMode } = usePreviewSettings();
+  return <div data-testid="active-mode">{activeDisplayMode}</div>;
+}
+
+function PreviewHarness() {
+  const { doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <PreviewModeSwitch />
+      <ModeProbe />
+    </PreviewSettingsProvider>
+  );
+}
+
+function renderPreviewControls(markdown: string) {
+  render(
+    <EditorProvider initialMarkdown={markdown}>
+      <PreviewHarness />
+    </EditorProvider>,
+  );
+}
+
+afterEach(() => cleanup());
+
+describe('PreviewModeSwitch', () => {
+  it('labels the plain document preview as Document and the styled view as Page', () => {
+    renderPreviewControls('# Hello');
+
+    const labels = screen
+      .getAllByRole('button')
+      .map((button) => button.textContent)
+      .filter(Boolean);
+
+    expect(labels).toEqual(['Video', 'Slideshow', 'Page', 'Document']);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Document' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('page');
+
+    fireEvent.click(screen.getByRole('button', { name: 'Page' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('linear');
+  });
+
+  it('maps product-facing display-mode frontmatter to the correct renderer values', async () => {
+    renderPreviewControls('---\ndisplay-mode: document\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('page');
+    });
+    expect(screen.getByRole('button', { name: 'Document' }).getAttribute('aria-pressed')).toBe(
+      'true',
+    );
+
+    cleanup();
+    renderPreviewControls('---\ndisplay-mode: page\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('linear');
+    });
+    expect(screen.getByRole('button', { name: 'Page' }).getAttribute('aria-pressed')).toBe('true');
+  });
+});

package/src/__tests__/useJsonEditorTokens.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME } from '@bendyline/squisq/schemas';
+import { useJsonEditorTokens } from '../jsonEditor/useJsonEditorTokens';
+
+type StyleBag = Record<string, string>;
+
+/** Install a matchMedia stub whose `(prefers-color-scheme: dark)` resolves to `dark`. */
+function mockPrefersDark(dark: boolean): void {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    value: (query: string) => ({
+      matches: dark && query.includes('dark'),
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(() => false),
+    }),
+  });
+}
+
+describe('useJsonEditorTokens', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('emits jsonform-prefixed tokens', () => {
+    mockPrefersDark(false);
+    const { result } = renderHook(() => useJsonEditorTokens(DEFAULT_THEME, LIGHT_SURFACE));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-jsonform-bg']).toBe(LIGHT_SURFACE.background);
+    expect(style).toHaveProperty('--squisq-jsonform-warning');
+    expect(style).toHaveProperty('--squisq-jsonform-input-bg');
+  });
+
+  it("responds to a dark OS preference under surface='auto' (reactive via useAutoSurface)", () => {
+    mockPrefersDark(true);
+    const { result } = renderHook(() => useJsonEditorTokens(DEFAULT_THEME, 'auto'));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-jsonform-bg']).toBe(DARK_SURFACE.background);
+    expect(style['--squisq-jsonform-text']).toBe(DARK_SURFACE.text);
+    expect(result.current.theme.colors.background).toBe(DARK_SURFACE.background);
+  });
+
+  it("uses light surface under surface='auto' when the OS prefers light", () => {
+    mockPrefersDark(false);
+    const { result } = renderHook(() => useJsonEditorTokens(DEFAULT_THEME, 'auto'));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-jsonform-bg']).toBe(LIGHT_SURFACE.background);
+  });
+
+  beforeEach(() => {
+    // Default to a defined matchMedia so the hook's useAutoSurface can subscribe.
+    mockPrefersDark(false);
+  });
+});

package/src/__tests__/useMediaRecorder.test.ts

@@ -165,6 +165,23 @@ describe('useMediaRecorder lifecycle', () => {
     expect(result.current.stream).not.toBeNull();
   });
 
+  it('defaults to the mic source when called with no options', async () => {
+    const { result } = renderHook(() => useMediaRecorder());
+
+    expect(result.current.state).toBe('idle');
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    // Mic path: audio-only capture via getUserMedia, lands in `audio/`.
+    expect(result.current.state).toBe('ready');
+    expect(result.current.mimeType).toMatch(/^audio\/webm/);
+    expect(result.current.directory).toBe('audio');
+    const getUserMedia = navigator.mediaDevices.getUserMedia as ReturnType<typeof vi.fn>;
+    expect(getUserMedia).toHaveBeenCalled();
+  });
+
   it('camera includes the mic by default', async () => {
     const { result } = renderHook(() => useMediaRecorder({ source: 'camera' }));
     await act(async () => {

package/src/codeContext/CodeContextSectionView.tsx

@@ -0,0 +1,124 @@
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { MarkdownRenderer } from '@bendyline/squisq-react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { CodeContext, CodeContextSection } from './types';
+
+/**
+ * One context section rendered inside a Monaco view zone: a single-line
+ * disclosure strip, plus the full markdown body while expanded. The body is
+ * rendered lazily — a file with 100 collapsed sections parses 100 one-liners,
+ * nothing more.
+ */
+export interface CodeContextSectionViewProps {
+  section: Omit<CodeContextSection, 'line'>;
+  expanded: boolean;
+  onToggle: (id: string) => void;
+  linkSchemes?: readonly string[] | undefined;
+  onLinkClick?: CodeContext['onLinkClick'] | undefined;
+  /** Native `#L<n>` handling: reveal that line in the editor. */
+  onRevealLine: (line: number) => void;
+  /** Reports the rendered content height so the zone can be resized to fit. */
+  onMeasure: (id: string, px: number) => void;
+}
+
+export function CodeContextSectionView({
+  section,
+  expanded,
+  onToggle,
+  linkSchemes,
+  onLinkClick,
+  onRevealLine,
+  onMeasure,
+}: CodeContextSectionViewProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  const stripNodes = useMemo(
+    () => parseMarkdown(section.summaryMarkdown).children,
+    [section.summaryMarkdown],
+  );
+  const bodyNodes = useMemo(
+    () => (expanded && section.markdown ? parseMarkdown(section.markdown).children : null),
+    [expanded, section.markdown],
+  );
+
+  // Height feedback loop: report the content's real height whenever it
+  // changes. Monaco display:none's offscreen zones and ResizeObserver reports
+  // 0×0 for those — ignore zeros so scrolled-away zones keep their height.
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const report = () => {
+      const h = el.offsetHeight;
+      if (h > 0) onMeasure(section.id, h);
+    };
+    report();
+    const ro = new ResizeObserver(report);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [section.id, onMeasure]);
+
+  // Delegated link interception. `#L<n>` reveals natively; everything else
+  // goes to the host callback (returning false opts back into default
+  // navigation).
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a');
+      if (!anchor) return;
+      const href = anchor.getAttribute('href') ?? '';
+      const lineMatch = /^#L(\d+)$/.exec(href);
+      if (lineMatch) {
+        e.preventDefault();
+        e.stopPropagation();
+        onRevealLine(Number(lineMatch[1]));
+        return;
+      }
+      if (onLinkClick) {
+        const handled = onLinkClick(href, { sectionId: section.id });
+        if (handled !== false) {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+      }
+    },
+    [onLinkClick, onRevealLine, section.id],
+  );
+
+  // Keep Monaco's container-level mousedown handler from hijacking clicks
+  // and text selection inside the section.
+  const stopMouseDown = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation();
+  }, []);
+
+  return (
+    // Click handler is delegated anchor interception only; keyboard users
+    // reach links natively and the strip itself is a real <button>.
+    <div
+      ref={rootRef}
+      className={`squisq-ccx-section${expanded ? ' squisq-ccx-section--expanded' : ''}`}
+      onClick={handleClick}
+      onMouseDown={stopMouseDown}
+    >
+      <button
+        type="button"
+        className="squisq-ccx-strip"
+        aria-expanded={expanded}
+        onClick={() => onToggle(section.id)}
+      >
+        <span className="squisq-ccx-chevron" aria-hidden="true">
+          {expanded ? '▾' : '▸'}
+        </span>
+        <span className="squisq-ccx-strip-text">
+          <MarkdownRenderer nodes={stripNodes} {...(linkSchemes ? { linkSchemes } : {})} />
+        </span>
+      </button>
+      {expanded &&
+        (bodyNodes ? (
+          <div className="squisq-ccx-body">
+            <MarkdownRenderer nodes={bodyNodes} {...(linkSchemes ? { linkSchemes } : {})} />
+          </div>
+        ) : (
+          <div className="squisq-ccx-body squisq-ccx-body--loading">Loading…</div>
+        ))}
+    </div>
+  );
+}

package/src/codeContext/CodeContextZoneManager.ts

@@ -0,0 +1,149 @@
+import type { editor as MonacoEditorNs } from 'monaco-editor';
+import { type ZoneSpec, diffContextSections } from './diffContextSections';
+
+type MonacoEditor = MonacoEditorNs.IStandaloneCodeEditor;
+
+/**
+ * Owns the Monaco view zones behind the code-context sections. React-free —
+ * the React layer portals content into the zone dom nodes it hands out and
+ * feeds measured heights back via {@link setHeight}.
+ *
+ * Zone mechanics this leans on (monaco 0.50):
+ * - `changeViewZones` batches adds/removes/layouts into one whitespace
+ *   re-layout.
+ * - `layoutZone(id)` re-reads the zone delegate, so mutating our own
+ *   delegate's `afterLineNumber`/`heightInPx` then calling layoutZone both
+ *   moves and resizes without remove/re-add churn (expanded DOM survives).
+ * - Zone dom nodes live in `.view-zones` (absolutely positioned, offscreen
+ *   ones display:none'd by Monaco). They sit BELOW `.view-lines` in hit-test
+ *   order, so the stylesheet raises `.squisq-ccx-zone` with a z-index and
+ *   `pointer-events: auto` to make section content clickable.
+ * - Model swaps invalidate zone ids; the owner listens to onDidChangeModel
+ *   and rebuilds.
+ */
+export class CodeContextZoneManager {
+  private readonly editor: MonacoEditor;
+  private entries = new Map<
+    string,
+    {
+      zoneId: string;
+      delegate: MonacoEditorNs.IViewZone;
+      domNode: HTMLDivElement;
+      spec: ZoneSpec;
+    }
+  >();
+  private listeners = new Set<() => void>();
+  private modelListener: { dispose(): void } | null = null;
+  private disposed = false;
+
+  /** Initial height estimate for a strip; the ResizeObserver corrects it. */
+  static readonly INITIAL_HEIGHT_PX = 28;
+
+  constructor(editor: MonacoEditor) {
+    this.editor = editor;
+    // A model swap (file change / external reset) invalidates every zone id.
+    // Drop our bookkeeping; the next sync() recreates zones against the new
+    // model.
+    this.modelListener = editor.onDidChangeModel(() => {
+      this.entries.clear();
+      this.emit();
+    });
+  }
+
+  /** Reconcile the live zones against `specs` in one changeViewZones batch. */
+  sync(specs: ZoneSpec[]): void {
+    if (this.disposed) return;
+    const prev = [...this.entries.values()].map((e) => e.spec);
+    const { add, remove, move } = diffContextSections(prev, specs);
+    if (add.length === 0 && remove.length === 0 && move.length === 0) return;
+
+    this.editor.changeViewZones((accessor) => {
+      for (const id of remove) {
+        const entry = this.entries.get(id);
+        if (!entry) continue;
+        accessor.removeZone(entry.zoneId);
+        this.entries.delete(id);
+      }
+      for (const spec of move) {
+        const entry = this.entries.get(spec.id);
+        if (!entry) continue;
+        entry.spec = spec;
+        entry.delegate.afterLineNumber = Math.max(spec.line - 1, 0);
+        setOrdinal(entry.delegate, spec.ordinal);
+        accessor.layoutZone(entry.zoneId);
+      }
+      for (const spec of add) {
+        const domNode = document.createElement('div');
+        domNode.className = 'squisq-ccx-zone';
+        domNode.dataset.sectionId = spec.id;
+        const delegate: MonacoEditorNs.IViewZone = {
+          afterLineNumber: Math.max(spec.line - 1, 0),
+          heightInPx: CodeContextZoneManager.INITIAL_HEIGHT_PX,
+          domNode,
+          suppressMouseDown: true,
+        };
+        setOrdinal(delegate, spec.ordinal);
+        const zoneId = accessor.addZone(delegate);
+        this.entries.set(spec.id, { zoneId, delegate, domNode, spec });
+      }
+    });
+    this.emit();
+  }
+
+  /** Measured-content feedback: resize the zone to fit its rendered DOM. */
+  setHeight(id: string, px: number): void {
+    if (this.disposed) return;
+    const entry = this.entries.get(id);
+    if (!entry) return;
+    const height = Math.max(Math.ceil(px), 1);
+    if (Math.abs((entry.delegate.heightInPx ?? 0) - height) < 1) return;
+    entry.delegate.heightInPx = height;
+    this.editor.changeViewZones((accessor) => {
+      accessor.layoutZone(entry.zoneId);
+    });
+  }
+
+  getDomNode(id: string): HTMLDivElement | undefined {
+    return this.entries.get(id)?.domNode;
+  }
+
+  liveIds(): string[] {
+    return [...this.entries.keys()];
+  }
+
+  /** Fires after sync/model-change so the React layer rebuilds its portals. */
+  onDidChangeZones(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.modelListener?.dispose();
+    this.modelListener = null;
+    if (this.entries.size > 0) {
+      try {
+        this.editor.changeViewZones((accessor) => {
+          for (const entry of this.entries.values()) accessor.removeZone(entry.zoneId);
+        });
+      } catch {
+        // Editor already disposed — its zones died with it.
+      }
+    }
+    this.entries.clear();
+    this.listeners.clear();
+  }
+
+  private emit(): void {
+    for (const cb of [...this.listeners]) cb();
+  }
+}
+
+/**
+ * `ordinal` orders zones sharing an afterLineNumber (monaco 0.50 supports it
+ * but the public IViewZone typing lags behind) — hence the structural write.
+ */
+function setOrdinal(zone: MonacoEditorNs.IViewZone, ordinal: number): void {
+  (zone as MonacoEditorNs.IViewZone & { ordinal?: number }).ordinal = ordinal;
+}

package/src/codeContext/CodeContextZones.tsx

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useEditorContext } from '../EditorContext';
+import { CodeContextZoneManager } from './CodeContextZoneManager';
+import { CodeContextSectionView } from './CodeContextSectionView';
+import type { ZoneSpec } from './diffContextSections';
+import type { CodeContext, CodeContextSection } from './types';
+
+/**
+ * Bridges a host-supplied {@link CodeContext} onto the live Monaco editor:
+ * owns a {@link CodeContextZoneManager} per editor instance, reconciles zones
+ * when the context prop changes, and portals a `CodeContextSectionView` into
+ * each zone's dom node. Mounted by EditorShell in code mode; also exported
+ * for hosts composing a custom shell around `RawEditor`.
+ */
+export function CodeContextZones({ options }: { options: CodeContext }) {
+  const { monacoEditor } = useEditorContext();
+  const [manager, setManager] = useState<CodeContextZoneManager | null>(null);
+  // Bumped whenever the zone set changes so portals rebuild.
+  const [, setZonesVersion] = useState(0);
+  // Expansion state per section id: seeded from defaultExpanded the first
+  // time an id appears; the user's toggle wins afterwards.
+  const [expandedById, setExpandedById] = useState<Record<string, boolean>>({});
+  const seenIds = useRef(new Set<string>());
+
+  useEffect(() => {
+    if (!monacoEditor) return;
+    const mgr = new CodeContextZoneManager(monacoEditor);
+    const off = mgr.onDidChangeZones(() => setZonesVersion((v) => v + 1));
+    setManager(mgr);
+    return () => {
+      off();
+      mgr.dispose();
+      setManager(null);
+    };
+  }, [monacoEditor]);
+
+  const fileTop = options.fileTop;
+  const sections = options.sections;
+
+  // Resolved render list: fileTop pinned above line 1 at ordinal 0, then the
+  // host's sections in array order.
+  const resolved = useMemo(() => {
+    const out: Array<{ spec: ZoneSpec; section: Omit<CodeContextSection, 'line'> }> = [];
+    if (fileTop) {
+      out.push({ spec: { id: fileTop.id, line: 0, ordinal: 0 }, section: fileTop });
+    }
+    sections?.forEach((s, i) => {
+      out.push({ spec: { id: s.id, line: s.line, ordinal: i + 1 }, section: s });
+    });
+    return out;
+  }, [fileTop, sections]);
+
+  useEffect(() => {
+    if (!manager) return;
+    manager.sync(resolved.map((r) => r.spec));
+    // Seed expansion defaults for ids we haven't seen before (sections can
+    // arrive after mount).
+    setExpandedById((prev) => {
+      let next: Record<string, boolean> | null = null;
+      for (const { section } of resolved) {
+        if (seenIds.current.has(section.id)) continue;
+        seenIds.current.add(section.id);
+        if (section.defaultExpanded) {
+          next = next ?? { ...prev };
+          next[section.id] = true;
+        }
+      }
+      return next ?? prev;
+    });
+  }, [manager, resolved]);
+
+  const onToggleSection = options.onToggleSection;
+  const handleToggle = useCallback(
+    (id: string) => {
+      setExpandedById((prev) => {
+        const expanded = !prev[id];
+        onToggleSection?.(id, expanded);
+        return { ...prev, [id]: expanded };
+      });
+    },
+    [onToggleSection],
+  );
+
+  const handleMeasure = useCallback(
+    (id: string, px: number) => manager?.setHeight(id, px),
+    [manager],
+  );
+
+  const handleRevealLine = useCallback(
+    (line: number) => {
+      monacoEditor?.revealLineInCenter(line);
+      monacoEditor?.setPosition({ lineNumber: line, column: 1 });
+    },
+    [monacoEditor],
+  );
+
+  if (!manager) return null;
+  return (
+    <>
+      {resolved.map(({ section }) => {
+        const domNode = manager.getDomNode(section.id);
+        if (!domNode) return null;
+        return createPortal(
+          <CodeContextSectionView
+            key={section.id}
+            section={section}
+            expanded={!!expandedById[section.id]}
+            onToggle={handleToggle}
+            linkSchemes={options.linkSchemes}
+            onLinkClick={options.onLinkClick}
+            onRevealLine={handleRevealLine}
+            onMeasure={handleMeasure}
+          />,
+          domNode,
+          section.id,
+        );
+      })}
+    </>
+  );
+}

package/src/codeContext/diffContextSections.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure reconciler for context-section zones. Diffs the previous resolved spec
+ * list against the next by section id, so the zone layer can apply one
+ * changeViewZones batch: create `add`, delete `remove`, and re-anchor `move`
+ * (same id, different line or ordinal). Content-only changes are not the zone
+ * layer's business — React re-renders the portal and the resize observer
+ * corrects the height.
+ */
+
+export interface ZoneSpec {
+  id: string;
+  /** 1-based anchor line (0 = file-top, above line 1). */
+  line: number;
+  /** Stable order among zones sharing an anchor line. */
+  ordinal: number;
+}
+
+export interface ZoneDiff {
+  add: ZoneSpec[];
+  remove: string[];
+  move: ZoneSpec[];
+}
+
+export function diffContextSections(prev: ZoneSpec[], next: ZoneSpec[]): ZoneDiff {
+  const prevById = new Map(prev.map((z) => [z.id, z]));
+  const nextIds = new Set<string>();
+  const add: ZoneSpec[] = [];
+  const move: ZoneSpec[] = [];
+  for (const spec of next) {
+    if (nextIds.has(spec.id)) continue; // duplicate id — first occurrence wins
+    nextIds.add(spec.id);
+    const before = prevById.get(spec.id);
+    if (!before) add.push(spec);
+    else if (before.line !== spec.line || before.ordinal !== spec.ordinal) move.push(spec);
+  }
+  const remove = prev.filter((z) => !nextIds.has(z.id)).map((z) => z.id);
+  return { add, remove, move };
+}

package/src/codeContext/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Host-supplied context sections rendered INSIDE the Monaco (raw/code)
+ * surface: collapsible markdown blurbs injected above anchor lines, plus an
+ * optional file-top summary. Squisq stays host-agnostic — anchors are plain
+ * line numbers, ids are opaque strings, links are intercepted via callback.
+ *
+ * Accessibility note: Monaco marks its view-zone layer `aria-hidden`, so
+ * sections are invisible to screen readers in v1.
+ */
+
+/**
+ * One host-supplied markdown blurb anchored above a line of the code buffer.
+ * Rendered as a compact one-line strip that expands in place to the full
+ * markdown body.
+ */
+export interface CodeContextSection {
+  /**
+   * Stable identity used to reconcile zones across prop updates — e.g. a
+   * symbol id like 'resolveImportEdges@60'. Zones are diffed by id: same id +
+   * new line moves the zone; same id + new markdown re-renders in place; a
+   * new id creates a new zone.
+   */
+  id: string;
+  /**
+   * 1-based line the section renders ABOVE. Out-of-range values are clamped
+   * by Monaco. In editable buffers the zone rides Monaco's whitespace
+   * semantics — it shifts as lines are inserted/deleted above it and
+   * collapses onto the previous line if its anchor lines are deleted. Squisq
+   * never re-derives anchors from edits; the host re-supplies lines when it
+   * re-analyzes the file.
+   */
+  line: number;
+  /**
+   * Compact markdown for the collapsed strip. Rendered on one line (block
+   * structure flattened, overflow ellipsized). Links work here too and go
+   * through `onLinkClick`.
+   */
+  summaryMarkdown: string;
+  /**
+   * Full markdown body shown when expanded. Omit while still loading — the
+   * expanded view shows a muted loading row and fills in when a later prop
+   * update supplies it.
+   */
+  markdown?: string;
+  /** Start expanded. The user's toggle wins after first interaction. Default false. */
+  defaultExpanded?: boolean;
+}
+
+/** The full context dictionary passed to `EditorShell.codeContext`. */
+export interface CodeContext {
+  /**
+   * Section pinned above line 1 (file summary). Rendered before any line-1
+   * `sections` entry. `line` is implicit.
+   */
+  fileTop?: Omit<CodeContextSection, 'line'>;
+  /** Line-anchored sections. Array order is preserved for equal lines. */
+  sections?: CodeContextSection[];
+  /**
+   * Extra URI schemes section links may use (e.g. `['gezel-nav']`).
+   * http/https/mailto/tel are always allowed; executable schemes
+   * (javascript:, data:) are never allowed regardless.
+   */
+  linkSchemes?: readonly string[];
+  /**
+   * Intercepts link clicks inside sections, receiving the href exactly as
+   * authored in the markdown. Return `false` to let the browser's default
+   * navigation proceed; any other return (or void) suppresses it. Fragment
+   * links of the form `#L<digits>` are handled natively by squisq (reveal
+   * that line in the editor) and never reach this callback. When omitted:
+   * http(s)/mailto links open normally, custom-scheme links do nothing.
+   */
+  onLinkClick?: (href: string, meta: { sectionId: string }) => boolean | undefined;
+  /** Notified on expand/collapse — lets hosts lazy-load bodies on first expand. */
+  onToggleSection?: (sectionId: string, expanded: boolean) => void;
+}