@bendyline/squisq-editor-react 1.6.0 → 1.6.2

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;
+}

package/src/diagram/DiagramWidget.tsx

@@ -18,6 +18,7 @@ import { DiagramMaximizedOverlay } from './DiagramMaximizedOverlay';
 import { useDiagramData } from './useDiagramData';
 import { findDiagramHeadingPos } from './DiagramExtension';
 import { SceneBlockToolbar, type SceneBlockAction } from '../scene/SceneBlockToolbar';
+import { SceneSideToolbar } from '../scene/SceneSideToolbar';
 import { nodeIdFromCardLayerId, NODE_WIDTH, NODE_HEIGHT } from '../scene';
 import { Icon } from '../Icon';
 import {
@@ -226,8 +227,6 @@ export function DiagramWidget({ editor, headingKey, fallbackParentPos, host }: D
     />
   );
 
-  const sideToolbar = <div className="squisq-scene-side-toolbar">{toolbar}</div>;
-
   if (maximized) {
     return (
       <div
@@ -235,9 +234,10 @@ export function DiagramWidget({ editor, headingKey, fallbackParentPos, host }: D
         style={effectiveHeight != null ? { height: effectiveHeight } : undefined}
       >
         <DiagramMaximizedOverlay host={host ?? null} onClose={() => setMaximized(false)}>
+          {/* Maximized has a full screen for a static right column — no collapse. */}
           <div className="squisq-scene-block-max">
             {canvas}
-            {sideToolbar}
+            <div className="squisq-scene-side-toolbar">{toolbar}</div>
           </div>
         </DiagramMaximizedOverlay>
       </div>
@@ -246,6 +246,9 @@ export function DiagramWidget({ editor, headingKey, fallbackParentPos, host }: D
 
   return (
     <div className="squisq-scene-shell">
+      {/* Before the canvas so the narrow-width fallback bar sits above it; the
+        wide-width gutter column is absolute and unaffected by DOM order. */}
+      <SceneSideToolbar>{toolbar}</SceneSideToolbar>
       <div
         className="squisq-diagram-inline"
         ref={inlineRef}
@@ -262,7 +265,6 @@ export function DiagramWidget({ editor, headingKey, fallbackParentPos, host }: D
           title="Drag to resize · double-click to reset"
         />
       </div>
-      {sideToolbar}
     </div>
   );
 }

package/src/headingTransition.ts

@@ -6,16 +6,13 @@
  *
  * - Markdown (Monaco): operate on the raw heading line string.
  * - WYSIWYG (Tiptap): operate on the heading node's `dataBlockAttrs` string
- *   (the inner of the Pandoc `{…}` block, no braces — matching how
- *   `tiptapBridge` stores and re-emits it).
+ *   (Pandoc `{…}` inner) and `dataTemplateParams` string (the params inside
+ *   the squisq-native `{[…]}` annotation).
  *
- * Transitions are stored in the Pandoc `{#id .class key=value}` attribute
- * block, NOT the `{[template …]}` annotation. That mirrors the canonical
- * serializer (`core/doc/docToMarkdown.ts` → `ensureTransitionAttributes`,
- * which always emits the `{…}` form) and `diagram/diagramCommands.ts`, so a
- * value set here round-trips through a Doc render without being duplicated
- * or moved. Reads still look at the `{[…]}` params too, so a hand-typed
- * `{[title transition=fade]}` shows up in the picker.
+ * The editor writes transitions to the squisq-native `{[…]}` annotation by
+ * default. It still reads legacy Pandoc `{transition=…}` attributes and
+ * removes/migrates those keys when rewriting, so the two channels cannot drift
+ * after a toolbar edit.
  *
  * All the brace-matching / tokenizing / serializing is delegated to the
  * shared core helpers so this stays in lockstep with the parser by import
@@ -29,6 +26,7 @@ import {
   serializePandocAttributes,
   tokenizeAttrTokens,
   splitKeyValueToken,
+  quoteAttrValue,
   type HeadingAttributes,
 } from '@bendyline/squisq/markdown';
 
@@ -85,6 +83,14 @@ function applyFieldsToParams(
   return out;
 }
 
+function removeFieldsFromAttrs(attrs: HeadingAttributes): HeadingAttributes {
+  if (!attrs.params) return attrs;
+  const params = applyFieldsToParams(attrs.params, EMPTY_TRANSITION);
+  if (Object.keys(params).length > 0) attrs.params = params;
+  else delete attrs.params;
+  return attrs;
+}
+
 /** Parse a bare `key=value …` token string into a params map. */
 function paramsFromTokenString(input: string, skipFirstToken: boolean): Record<string, string> {
   const tokens = tokenizeAttrTokens(input);
@@ -96,6 +102,39 @@ function paramsFromTokenString(input: string, skipFirstToken: boolean): Record<s
   return params;
 }
 
+function templatePartsFromInner(inner: string | null | undefined): {
+  template: string | undefined;
+  params: Record<string, string>;
+} {
+  if (!inner) return { template: undefined, params: {} };
+  const tokens = tokenizeAttrTokens(inner);
+  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
+  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
+  const startIdx = template ? 1 : 0;
+  const params: Record<string, string> = {};
+  for (const token of tokens.slice(startIdx)) {
+    const kv = splitKeyValueToken(token);
+    if (kv) params[kv.key] = kv.value;
+  }
+  return { template, params };
+}
+
+function paramsToInner(params: Record<string, string>): string | null {
+  const parts = Object.entries(params).map(([key, value]) => `${key}=${quoteAttrValue(value)}`);
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
+function templateAnnotationOrNull(
+  template: string | undefined,
+  params: Record<string, string>,
+): string | null {
+  const parts: string[] = [];
+  if (template) parts.push(template);
+  const paramInner = paramsToInner(params);
+  if (paramInner) parts.push(paramInner);
+  return parts.length > 0 ? `{[${parts.join(' ')}]}` : null;
+}
+
 // ============================================
 // Heading line (Markdown / Monaco view)
 // ============================================
@@ -141,7 +180,7 @@ function splitHeadingLine(line: string): SplitHeadingLine | null {
 
 /**
  * Read the transition fields off a heading line. Looks in both the Pandoc
- * `{…}` block (canonical) and the `{[…]}` template params (hand-typed),
+ * `{…}` block (legacy) and the `{[…]}` template params (canonical),
  * with the Pandoc block taking precedence. Returns the empty transition for
  * non-heading lines.
  */
@@ -149,7 +188,7 @@ export function readHeadingLineTransition(line: string): TransitionFields {
   const split = splitHeadingLine(line);
   if (!split) return { ...EMPTY_TRANSITION };
   const fromTemplate = split.templateText
-    ? paramsFromTokenString(stripTemplateBraces(split.templateText), true)
+    ? templatePartsFromInner(stripTemplateBraces(split.templateText)).params
     : {};
   const fromPandoc = split.pandocInner
     ? (parsePandocAttrTokens(split.pandocInner).params ?? {})
@@ -159,8 +198,9 @@ export function readHeadingLineTransition(line: string): TransitionFields {
 
 /**
  * Return `line` with its transition rewritten from `next`, writing into the
- * Pandoc `{…}` block and leaving the `{[…]}` template annotation untouched.
- * Non-heading lines are returned unchanged.
+ * squisq-native `{[…]}` annotation. Legacy Pandoc transition keys are removed
+ * while preserving ids, classes, and other Pandoc params. Non-heading lines are
+ * returned unchanged.
  */
 export function setHeadingLineTransition(line: string, next: TransitionFields): string {
   const split = splitHeadingLine(line);
@@ -168,12 +208,18 @@ export function setHeadingLineTransition(line: string, next: TransitionFields):
   const attrs: HeadingAttributes = split.pandocInner
     ? parsePandocAttrTokens(split.pandocInner)
     : {};
-  attrs.params = applyFieldsToParams(attrs.params ?? {}, next);
+  removeFieldsFromAttrs(attrs);
   const pandoc = pandocBlockOrNull(attrs);
 
+  const templateParts = templatePartsFromInner(
+    split.templateText ? stripTemplateBraces(split.templateText) : null,
+  );
+  const templateParams = applyFieldsToParams(templateParts.params, next);
+  const template = templateAnnotationOrNull(templateParts.template, templateParams);
+
   let out = split.prefix + split.text;
   if (pandoc) out += ` ${pandoc}`;
-  if (split.templateText) out += ` ${split.templateText}`;
+  if (template) out += ` ${template}`;
   return out;
 }
 
@@ -188,8 +234,10 @@ function stripTemplateBraces(templateText: string): string {
 // ============================================
 
 /**
- * Read the transition fields from a heading node's `dataBlockAttrs` (Pandoc
- * inner) plus `dataTemplateParams` (the `{[…]}` params). Pandoc wins.
+ * Read the transition fields from a heading node's `dataBlockAttrs` (legacy
+ * Pandoc inner) plus `dataTemplateParams` (canonical `{[…]}` params). Pandoc
+ * wins so the picker mirrors the value that `markdownToDoc` will render when
+ * both channels are present.
  */
 export function readBlockAttrsTransition(
   blockAttrsInner: string | null | undefined,
@@ -200,11 +248,38 @@ export function readBlockAttrsTransition(
   return fieldsFromParams({ ...fromTemplate, ...fromPandoc });
 }
 
+export interface HeadingTransitionAttrs {
+  /** Inner of the Pandoc `{…}` block, without braces. */
+  blockAttrsInner: string | null;
+  /** Param string inside the `{[…]}` annotation, without the template token. */
+  templateParams: string | null;
+}
+
+/**
+ * Rewrite a heading node's transition for Tiptap, writing the transition
+ * family into `dataTemplateParams` and removing any legacy transition keys
+ * from `dataBlockAttrs`.
+ */
+export function setHeadingAttrsTransition(
+  blockAttrsInner: string | null | undefined,
+  templateParams: string | null | undefined,
+  next: TransitionFields,
+): HeadingTransitionAttrs {
+  const attrs: HeadingAttributes = blockAttrsInner ? parsePandocAttrTokens(blockAttrsInner) : {};
+  removeFieldsFromAttrs(attrs);
+  const pandoc = pandocBlockOrNull(attrs);
+
+  const params = applyFieldsToParams(paramsFromTokenString(templateParams ?? '', false), next);
+  return {
+    blockAttrsInner: pandoc ? pandoc.slice(1, -1) : null,
+    templateParams: paramsToInner(params),
+  };
+}
+
 /**
- * Rewrite the transition in a heading node's `dataBlockAttrs` inner string.
- * Returns the new inner (no braces), or null when the block carries no
- * attributes at all — matching how `tiptapBridge` stores `dataBlockAttrs`
- * (absent attribute → null, not `{}`).
+ * Legacy single-channel writer for callers that only own `dataBlockAttrs`.
+ * Internal editor surfaces should use {@link setHeadingAttrsTransition} so new
+ * transition edits land in the squisq-native `{[…]}` params.
  */
 export function setBlockAttrsTransition(
   blockAttrsInner: string | null | undefined,

package/src/index.ts

@@ -19,7 +19,11 @@
 
 // Shell (top-level component)
 export { EditorShell } from './EditorShell.js';
-export type { EditorShellProps, EditorTheme } from './EditorShell.js';
+export type { EditorShellProps, EditorColorScheme } from './EditorShell.js';
+
+// Code-context sections (host-supplied markdown injected into the code surface)
+export { CodeContextZones } from './codeContext/CodeContextZones.js';
+export type { CodeContext, CodeContextSection } from './codeContext/types.js';
 
 // FolderView — standalone folder browser surface (companion to the shell)
 export { FolderView } from './FolderView.js';
@@ -100,6 +104,8 @@ export type { EmojiEntry, EmojiCategory } from './emojiData.js';
 export {
   PreviewSettingsProvider,
   PreviewToolbarControls,
+  PreviewModeSwitch,
+  PreviewFormatSwitch,
   usePreviewSettings,
 } from './PreviewControls.js';
 export type { PreviewSettings } from './PreviewControls.js';
@@ -135,10 +141,11 @@ export {
   readHeadingLineTransition,
   setHeadingLineTransition,
   readBlockAttrsTransition,
+  setHeadingAttrsTransition,
   setBlockAttrsTransition,
   EMPTY_TRANSITION,
 } from './headingTransition.js';
-export type { TransitionFields } from './headingTransition.js';
+export type { HeadingTransitionAttrs, TransitionFields } from './headingTransition.js';
 export {
   readBlockAttrsParams,
   readBlockAttrsValue,
@@ -178,6 +185,31 @@ export {
   processTextFiles,
 } from './utils/dropUtils.js';
 
+// Monaco lazy loader — exported so hosts embedding RawEditor-like surfaces
+// can share the same load-once Monaco bootstrap.
+export { useMonacoLoader } from './useMonacoLoader.js';
+export type { UseMonacoLoaderResult } from './useMonacoLoader.js';
+
+// Custom themes — provider stack (doc frontmatter + browser-local library)
+export { CustomThemeProvider, useCustomThemes, useDocCustomThemes } from './customThemes/index.js';
+export type {
+  CustomThemeContextValue,
+  CustomThemeProviderProps,
+  DocCustomThemes,
+} from './customThemes/index.js';
+
+// Custom templates — provider stack (doc frontmatter + browser-local library)
+export {
+  CustomTemplateProvider,
+  useCustomTemplates,
+  useDocCustomTemplates,
+} from './customTemplates/index.js';
+export type {
+  CustomTemplateContextValue,
+  CustomTemplateProviderProps,
+  DocCustomTemplates,
+} from './customTemplates/index.js';
+
 // Bridge utilities
 export { markdownToTiptap, tiptapToMarkdown } from './tiptapBridge.js';