@deckbuilderkit/editor 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@deckbuilderkit/editor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/editor"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./http": "./src/http.ts",
+    "./options": "./src/options.ts"
+  },
+  "dependencies": {
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/language": "^6.13.1",
+    "@codemirror/legacy-modes": "^6.5.5",
+    "@codemirror/lint": "^6.9.7",
+    "@codemirror/merge": "^6.12.2",
+    "@codemirror/search": "^6.7.2",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.14",
+    "@deckbuilderkit/server-core": "0.1.0",
+    "@deckbuilderkit/ui": "0.1.0",
+    "@lezer/common": "^1.5.0",
+    "@lezer/highlight": "^1.2.5",
+    "@lezer/markdown": "^1.8.0",
+    "dompurify": "^3.4.16",
+    "marked": "^18.1.0",
+    "pdfjs-dist": "4.10.38"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@types/react-dom": "^18.3.1"
+  }
+}

package/src/ArchiveView.tsx

@@ -0,0 +1,111 @@
+import { fileIconOf, formatBytes, Icon, PanelBanner, t } from '@deckbuilderkit/ui';
+import { useMemo, useState } from 'react';
+
+/** What `/api/fs/archive` returns. */
+export interface ArchiveContent {
+  entries: { path: string; dir: boolean; size: number; mtime: number; encrypted: boolean }[];
+  truncated: boolean;
+}
+
+interface Node {
+  name: string;
+  path: string;
+  dir: boolean;
+  size: number;
+  mtime: number;
+  encrypted: boolean;
+  children: Node[];
+}
+
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+
+function treeOf(entries: ArchiveContent['entries']): Node {
+  const root: Node = { name: '', path: '', dir: true, size: 0, mtime: 0, encrypted: false, children: [] };
+  const byPath = new Map<string, Node>([['', root]]);
+  const folder = (path: string): Node => {
+    const known = byPath.get(path);
+    if (known) return known;
+    const i = path.lastIndexOf('/');
+    const node: Node = { name: path.slice(i + 1), path, dir: true, size: 0, mtime: 0, encrypted: false, children: [] };
+    byPath.set(path, node);
+    folder(i < 0 ? '' : path.slice(0, i)).children.push(node);
+    return node;
+  };
+  for (const e of entries) {
+    const path = e.path.replace(/^\.?\/+|\/+$/g, '');
+    if (!path) continue;
+    if (e.dir) {
+      folder(path).mtime = e.mtime;
+      continue;
+    }
+    const i = path.lastIndexOf('/');
+    folder(i < 0 ? '' : path.slice(0, i)).children.push({ name: path.slice(i + 1), path, dir: false, size: e.size, mtime: e.mtime, encrypted: e.encrypted, children: [] });
+  }
+  const finish = (n: Node): number => {
+    n.children.sort((a, b) => Number(b.dir) - Number(a.dir) || collator.compare(a.name, b.name));
+    if (n.dir) n.size = n.children.reduce((sum, c) => sum + finish(c), 0);
+    return n.size;
+  };
+  finish(root);
+  return root;
+}
+
+/** The files of an archive as a folder tree with sizes and dates, and a filter. */
+export function ArchiveView({ archive }: { archive: ArchiveContent }) {
+  const tree = useMemo(() => treeOf(archive.entries), [archive]);
+  const files = useMemo(() => archive.entries.filter((e) => !e.dir), [archive]);
+  const total = useMemo(() => files.reduce((sum, e) => sum + e.size, 0), [files]);
+  const [open, setOpen] = useState<Set<string>>(() => new Set(tree.children.length === 1 && tree.children[0]!.dir ? [tree.children[0]!.path] : []));
+  const [filter, setFilter] = useState('');
+  const q = filter.trim().toLowerCase();
+
+  const rows: { node: Node; depth: number }[] = [];
+  const walk = (n: Node, depth: number) => {
+    for (const c of n.children) {
+      if (q) {
+        if (c.dir) walk(c, depth);
+        else if (c.path.toLowerCase().includes(q)) rows.push({ node: c, depth: 0 });
+      } else {
+        rows.push({ node: c, depth });
+        if (c.dir && open.has(c.path)) walk(c, depth + 1);
+      }
+    }
+  };
+  walk(tree, 0);
+
+  const toggle = (path: string) =>
+    setOpen((s) => {
+      const next = new Set(s);
+      if (!next.delete(path)) next.add(path);
+      return next;
+    });
+
+  return (
+    <div className="file-preview">
+      {archive.truncated && <PanelBanner tone="warn" icon="alert">{t('archive.truncated')}</PanelBanner>}
+      <div className="file-preview-bar archive-bar">
+        <span className="archive-summary">{t('archive.summary', { count: files.length, size: formatBytes(total) })}</span>
+        <input className="input archive-filter" value={filter} onChange={(e) => setFilter(e.target.value)} placeholder={t('archive.filter')} aria-label={t('archive.filter')} />
+      </div>
+      <div className="file-preview-body archive-body">
+        {rows.length === 0 && <div className="archive-empty">{t('archive.empty')}</div>}
+        {rows.map(({ node, depth }) => (
+          <div
+            key={node.path}
+            className={`archive-row${node.dir ? ' archive-dir' : ''}`}
+            style={{ paddingLeft: 8 + depth * 16 }}
+            onClick={node.dir && !q ? () => toggle(node.path) : undefined}
+          >
+            <span className="archive-name" title={node.path}>
+              <Icon name={node.dir ? 'folder' : fileIconOf(node.name).icon} size={14} />
+              <span>{q ? node.path : node.name}</span>
+              {node.encrypted && <span title={t('archive.encrypted')}>🔒</span>}
+            </span>
+            <span className="archive-size">{formatBytes(node.size)}</span>
+            <span className="archive-date">{node.mtime ? new Date(node.mtime).toLocaleString() : ''}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/CodeEditor.tsx

@@ -0,0 +1,265 @@
+import { autocompletion, closeBracketsKeymap, completionKeymap } from '@codemirror/autocomplete';
+import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
+import { indentOnInput } from '@codemirror/language';
+import { type Diagnostic, lintGutter, linter } from '@codemirror/lint';
+import { highlightSelectionMatches, searchKeymap } from '@codemirror/search';
+import { Annotation, Compartment, EditorState, type Extension, Prec } from '@codemirror/state';
+import { EditorView, keymap, placeholder as placeholderExt } from '@codemirror/view';
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { type EditorOptions, editorOptionsExtension, useEditorOptions } from './editorOptions';
+import { type Lang, languageFor, type SqlDialect, type SqlSchema } from './languages';
+import { formatSql, type SqlFormatOptions } from './sql/format';
+import { type SqlProblem, sqlLint as runSqlLint } from './sql/lint';
+import { sqlMarkerHighlight } from './sql/markerHighlight';
+import { statementAt } from './sql/statements';
+import { sqlProblemMessage } from './sqlProblems';
+import { themeExtension } from './theme';
+
+export interface CodeEditorProps {
+  value: string;
+  lang: Lang;
+  onChange?(value: string): void;
+  /** Mod-Enter runs the statement under the cursor (or the selection); Mod-Shift-Enter runs everything. */
+  onRun?(value: string, mode: RunMode): void;
+  readOnly?: boolean;
+  placeholder?: string;
+  sqlDialect?: SqlDialect;
+  /** Table → columns, for SQL completion. */
+  sqlSchema?: SqlSchema;
+  /** CSS length; a number is px. Without it the editor grows with its content. */
+  height?: number | string;
+  autoFocus?: boolean;
+  /** Scroll position as a fraction (0..1) of the scroll range. */
+  onScroll?(fraction: number): void;
+  /** Extra extensions, swapped in place when the value changes. */
+  extensions?: Extension;
+  /** Wrap long lines; default off. */
+  wrap?: boolean;
+  /** The cursor and selection, on load and whenever they change. */
+  onSelection?(info: SelectionInfo): void;
+  /** Editor preferences; without it the app-wide ones (EditorOptionsContext), else the built-in defaults. */
+  options?: EditorOptions;
+  /** Underlines SQL lint problems (see `sqlLint`), with a gutter marker per line. */
+  sqlLint?: boolean;
+  /** The problems of each lint pass while `sqlLint` is on; [] when it turns off. */
+  onSqlProblems?(problems: SqlProblem[]): void;
+}
+
+export type RunMode = 'statement' | 'all';
+
+export interface CodeEditorHandle {
+  view: EditorView | null;
+  getSelectionText(): string;
+  /** The selection if any, else the SQL statement at the cursor, else the whole document. */
+  getRunText(): string;
+  replaceRange(from: number, to: number, text: string): void;
+  /** Formats the selection if any, else the whole document, as one undoable change. No-op when nothing changes. */
+  format(options: SqlFormatOptions): void;
+  focus(): void;
+  /** Selects from..to (or puts the cursor at from), scrolls it to the center and focuses the editor. */
+  reveal(from: number, to?: number): void;
+}
+
+/** Where the main cursor is (1-based) and how much is selected, for a status bar. */
+export interface SelectionInfo {
+  line: number;
+  col: number;
+  /** Characters selected over all selections. */
+  selected: number;
+  selections: number;
+  /** Offset of the main cursor. */
+  pos: number;
+}
+
+export function selectionInfo(state: EditorState): SelectionInfo {
+  const { main, ranges } = state.selection;
+  const line = state.doc.lineAt(main.head);
+  return { line: line.number, col: main.head - line.from + 1, selected: ranges.reduce((n, r) => n + r.to - r.from, 0), selections: ranges.length, pos: main.head };
+}
+
+function langExt(lang: Lang, sqlDialect?: SqlDialect, sqlSchema?: SqlSchema): Extension {
+  const base = languageFor(lang, { sqlDialect, sqlSchema });
+  return lang === 'sql' ? [base, sqlMarkerHighlight] : base;
+}
+
+/** Marks the transaction that loads an outside `value`, so it doesn't echo back through onChange. */
+const external = Annotation.define<boolean>();
+
+/** A CodeMirror 6 editor; one view for the component's lifetime, options swapped in place. */
+export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function CodeEditor({
+  value, lang, onChange, onRun, readOnly = false, placeholder, sqlDialect, sqlSchema, height, autoFocus, onScroll, extensions, wrap = false, onSelection, options, sqlLint = false, onSqlProblems,
+}, ref) {
+  const contextOptions = useEditorOptions();
+  const optionsExt = editorOptionsExtension(options ?? contextOptions);
+  const optionsKey = JSON.stringify(options ?? contextOptions ?? null);
+  const host = useRef<HTMLDivElement>(null);
+  const view = useRef<EditorView | null>(null);
+  const compartments = useRef({ lang: new Compartment(), readOnly: new Compartment(), placeholder: new Compartment(), extra: new Compartment(), options: new Compartment(), wrap: new Compartment(), lint: new Compartment() }).current;
+  // The callbacks change every render; the view's extensions read them through this ref.
+  const handlers = useRef({ onChange, onRun, onScroll, onSelection, onSqlProblems });
+  handlers.current = { onChange, onRun, onScroll, onSelection, onSqlProblems };
+  const lintExt = (on: boolean): Extension => (on ? sqlLintExtension((p) => handlers.current.onSqlProblems?.(p)) : []);
+  const langRef = useRef(lang);
+  langRef.current = lang;
+
+  const selectionText = (s: EditorState) => s.selection.ranges.map((r) => s.sliceDoc(r.from, r.to)).join('\n');
+  const runText = (s: EditorState) => {
+    const selected = selectionText(s);
+    if (selected.trim()) return selected;
+    const doc = s.doc.toString();
+    if (langRef.current !== 'sql') return doc;
+    return statementAt(doc, s.selection.main.head)?.text ?? doc;
+  };
+
+  useImperativeHandle(ref, () => ({
+    get view() {
+      return view.current;
+    },
+    getSelectionText: () => (view.current ? selectionText(view.current.state) : ''),
+    getRunText: () => (view.current ? runText(view.current.state) : ''),
+    replaceRange: (from, to, text) => view.current?.dispatch({ changes: { from, to, insert: text }, selection: { anchor: from + text.length } }),
+    format: (options) => {
+      const v = view.current;
+      if (!v) return;
+      const { main } = v.state.selection;
+      const from = main.empty ? 0 : main.from;
+      const to = main.empty ? v.state.doc.length : main.to;
+      const original = v.state.sliceDoc(from, to);
+      const formatted = formatSql(original, options);
+      if (formatted === original) return;
+      v.dispatch({
+        changes: { from, to, insert: formatted },
+        selection: main.empty ? { anchor: Math.min(main.head, from + formatted.length) } : { anchor: from, head: from + formatted.length },
+      });
+    },
+    focus: () => view.current?.focus(),
+    reveal: (from, to) => {
+      const v = view.current;
+      if (!v) return;
+      const len = v.state.doc.length;
+      const a = Math.max(0, Math.min(from, len));
+      const b = to === undefined ? a : Math.max(0, Math.min(to, len));
+      v.dispatch({ selection: { anchor: a, head: b }, effects: EditorView.scrollIntoView(a, { y: 'center' }) });
+      v.focus();
+    },
+  }), []);
+
+  useEffect(() => {
+    const v = new EditorView({
+      parent: host.current!,
+      state: EditorState.create({
+        doc: value,
+        extensions: [
+          Prec.highest(keymap.of([
+            { key: 'Mod-Enter', run: (ed) => {
+              const onRun = handlers.current.onRun;
+              if (!onRun) return false;
+              onRun(runText(ed.state), 'statement');
+              return true;
+            } },
+            { key: 'Mod-Shift-Enter', run: (ed) => {
+              const onRun = handlers.current.onRun;
+              if (!onRun) return false;
+              onRun(ed.state.doc.toString(), 'all');
+              return true;
+            } },
+          ])),
+          compartments.options.of(optionsExt),
+          history(),
+          indentOnInput(),
+          autocompletion(),
+          highlightSelectionMatches(),
+          keymap.of([...closeBracketsKeymap, ...defaultKeymap, ...searchKeymap, ...historyKeymap, ...completionKeymap, indentWithTab]),
+          compartments.lang.of(langExt(lang, sqlDialect, sqlSchema)),
+          compartments.readOnly.of(readOnlyExt(readOnly)),
+          compartments.placeholder.of(placeholder ? placeholderExt(placeholder) : []),
+          themeExtension,
+          compartments.extra.of(extensions ?? []),
+          compartments.wrap.of(wrap ? EditorView.lineWrapping : []),
+          compartments.lint.of(lintExt(sqlLint)),
+          EditorView.domEventHandlers({
+            scroll: (_e, ed) => {
+              const { scrollTop, scrollHeight, clientHeight } = ed.scrollDOM;
+              const range = scrollHeight - clientHeight;
+              handlers.current.onScroll?.(range > 0 ? scrollTop / range : 0);
+            },
+          }),
+          EditorView.updateListener.of((u) => {
+            if (u.docChanged || u.selectionSet) handlers.current.onSelection?.(selectionInfo(u.state));
+            if (!u.docChanged || u.transactions.some((tr) => tr.annotation(external))) return;
+            handlers.current.onChange?.(u.state.doc.toString());
+          }),
+        ],
+      }),
+    });
+    view.current = v;
+    handlers.current.onSelection?.(selectionInfo(v.state));
+    if (autoFocus) v.focus();
+    return () => {
+      v.destroy();
+      view.current = null;
+    };
+    // Created once; the effects below keep it in step with the props.
+  }, []);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.lang.reconfigure(langExt(lang, sqlDialect, sqlSchema)) });
+  }, [lang, sqlDialect, sqlSchema]);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.wrap.reconfigure(wrap ? EditorView.lineWrapping : []) });
+  }, [wrap]);
+
+  const lintReady = useRef(false);
+  useEffect(() => {
+    // The first run is the view's own initial config.
+    if (!lintReady.current) {
+      lintReady.current = true;
+      return;
+    }
+    view.current?.dispatch({ effects: compartments.lint.reconfigure(lintExt(sqlLint)) });
+    if (!sqlLint) handlers.current.onSqlProblems?.([]);
+  }, [sqlLint]);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.options.reconfigure(optionsExt) });
+  }, [optionsKey]);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.extra.reconfigure(extensions ?? []) });
+  }, [extensions]);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.readOnly.reconfigure(readOnlyExt(readOnly)) });
+  }, [readOnly]);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: compartments.placeholder.reconfigure(placeholder ? placeholderExt(placeholder) : []) });
+  }, [placeholder]);
+
+  useEffect(() => {
+    const v = view.current;
+    if (!v || v.state.doc.toString() === value) return;
+    v.dispatch({ changes: { from: 0, to: v.state.doc.length, insert: value }, annotations: external.of(true) });
+  }, [value]);
+
+  return <div ref={host} className="code-editor" style={height === undefined ? undefined : { height }} />;
+});
+
+const readOnlyExt = (readOnly: boolean) => EditorState.readOnly.of(readOnly);
+
+/** Lint diagnostics from `sqlLint`, messages from the `sqlLint.<code>` labels, plus a gutter. */
+export function sqlLintExtension(onProblems?: (problems: SqlProblem[]) => void): Extension {
+  return [
+    linter((view) => {
+      const problems = runSqlLint(view.state.doc.toString());
+      onProblems?.(problems);
+      const len = view.state.doc.length;
+      return problems.map((p): Diagnostic => {
+        const from = Math.max(0, Math.min(p.from, len));
+        return { from, to: Math.max(from, Math.min(p.to, len)), severity: p.severity, message: sqlProblemMessage(p), source: 'SQL' };
+      });
+    }, { delay: 500 }),
+    lintGutter(),
+  ];
+}

package/src/CodeView.tsx

@@ -0,0 +1,67 @@
+import { openSearchPanel, searchKeymap } from '@codemirror/search';
+import { Compartment, EditorState } from '@codemirror/state';
+import { drawSelection, EditorView, keymap, lineNumbers as lineNumbersExt } from '@codemirror/view';
+import { useEffect, useRef } from 'react';
+import { type Lang, languageFor } from './languages';
+import { themeExtension } from './theme';
+
+/** Characters; longer documents render as a plain `<pre>`. */
+export const CODE_VIEW_LIMIT = 2_000_000;
+
+const optionsExt = (lang: Lang, wrap: boolean, lineNumbers: boolean) => [
+  languageFor(lang),
+  wrap ? EditorView.lineWrapping : [],
+  lineNumbers ? lineNumbersExt() : [],
+];
+
+/** Read-only, highlighted text (searchable with Mod-f). */
+export function CodeView({ value, lang, wrap = false, lineNumbers = false }: { value: string; lang: Lang; wrap?: boolean; lineNumbers?: boolean }) {
+  if (value.length > CODE_VIEW_LIMIT) return <pre className={wrap ? 'code-view-plain wrap' : 'code-view-plain'}>{value}</pre>;
+  return <HighlightedView value={value} lang={lang} wrap={wrap} lineNumbers={lineNumbers} />;
+}
+
+function HighlightedView({ value, lang, wrap, lineNumbers }: { value: string; lang: Lang; wrap: boolean; lineNumbers: boolean }) {
+  const host = useRef<HTMLDivElement>(null);
+  const view = useRef<EditorView | null>(null);
+  const options = useRef(new Compartment()).current;
+
+  useEffect(() => {
+    const v = new EditorView({
+      parent: host.current!,
+      state: EditorState.create({
+        doc: value,
+        extensions: [
+          EditorState.readOnly.of(true),
+          drawSelection(),
+          keymap.of(searchKeymap),
+          options.of(optionsExt(lang, wrap, lineNumbers)),
+          themeExtension,
+        ],
+      }),
+    });
+    view.current = v;
+    return () => {
+      v.destroy();
+      view.current = null;
+    };
+  }, []);
+
+  useEffect(() => {
+    view.current?.dispatch({ effects: options.reconfigure(optionsExt(lang, wrap, lineNumbers)) });
+  }, [lang, wrap, lineNumbers]);
+
+  useEffect(() => {
+    const v = view.current;
+    if (v && v.state.doc.toString() !== value) v.dispatch({ changes: { from: 0, to: v.state.doc.length, insert: value } });
+  }, [value]);
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    const v = view.current;
+    if (!v || !(e.ctrlKey || e.metaKey) || e.altKey || e.key.toLowerCase() !== 'f') return;
+    e.preventDefault();
+    v.focus();
+    openSearchPanel(v);
+  };
+
+  return <div ref={host} className="code-view" tabIndex={-1} onKeyDown={onKeyDown} onMouseDown={(e) => { if (e.target === host.current) view.current?.focus(); }} />;
+}

package/src/DiffView.tsx

@@ -0,0 +1,139 @@
+import { getOriginalDoc, goToNextChunk, goToPreviousChunk, MergeView, originalDocChangeEffect, unifiedMergeView } from '@codemirror/merge';
+import { searchKeymap } from '@codemirror/search';
+import { ChangeSet, Compartment, EditorState, type Extension } from '@codemirror/state';
+import { drawSelection, EditorView, keymap, lineNumbers } from '@codemirror/view';
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { type Lang, languageFor } from './languages';
+import { themeExtension } from './theme';
+
+export type DiffMode = 'split' | 'inline';
+
+/** Imperative API: move the selection to the next/previous change (F7 / Shift+F7). */
+export interface DiffViewHandle {
+  next(): boolean;
+  prev(): boolean;
+}
+
+export interface DiffViewProps {
+  original: string;
+  modified: string;
+  lang?: Lang;
+  mode: DiffMode;
+  /** When given, a Split/Inline toggle is shown above the diff. */
+  onModeChange?: (mode: DiffMode) => void;
+  modeLabels?: { split: string; inline: string };
+}
+
+const COLLAPSE = { margin: 3, minSize: 4 };
+const chunkKeys = keymap.of([{ key: 'F7', run: goToNextChunk, shift: goToPreviousChunk }, ...searchKeymap]);
+
+const baseExt = (lang: Compartment, l: Lang): Extension => [
+  EditorState.readOnly.of(true),
+  EditorView.editable.of(false),
+  drawSelection(),
+  lineNumbers(),
+  chunkKeys,
+  lang.of(languageFor(l)),
+  themeExtension,
+];
+
+const replaceAll = (v: EditorView, text: string) => {
+  if (v.state.doc.toString() !== text) v.dispatch({ changes: { from: 0, to: v.state.doc.length, insert: text } });
+};
+
+/** Read-only diff of two strings: side by side (`split`) or unified (`inline`). */
+export const DiffView = forwardRef<DiffViewHandle, DiffViewProps>(function DiffView(
+  { original, modified, lang = 'text', mode, onModeChange, modeLabels = { split: 'Split', inline: 'Inline' } },
+  ref,
+) {
+  const host = useRef<HTMLDivElement>(null);
+  const merge = useRef<MergeView | null>(null);
+  const unified = useRef<EditorView | null>(null);
+  const langA = useRef(new Compartment()).current;
+  const langB = useRef(new Compartment()).current;
+  const latest = useRef({ original, modified, lang });
+  latest.current = { original, modified, lang };
+
+  useEffect(() => {
+    const { original, modified, lang } = latest.current;
+    if (mode === 'split') {
+      merge.current = new MergeView({
+        parent: host.current!,
+        a: { doc: original, extensions: baseExt(langA, lang) },
+        b: { doc: modified, extensions: baseExt(langB, lang) },
+        collapseUnchanged: COLLAPSE,
+        highlightChanges: true,
+        gutter: true,
+      });
+    } else {
+      unified.current = new EditorView({
+        parent: host.current!,
+        state: EditorState.create({
+          doc: modified,
+          extensions: [baseExt(langB, lang), unifiedMergeView({ original, mergeControls: false, collapseUnchanged: COLLAPSE })],
+        }),
+      });
+    }
+    return () => {
+      merge.current?.destroy();
+      unified.current?.destroy();
+      merge.current = null;
+      unified.current = null;
+    };
+  }, [mode]);
+
+  useEffect(() => {
+    const m = merge.current;
+    if (m) {
+      replaceAll(m.a, original);
+      replaceAll(m.b, modified);
+      return;
+    }
+    const u = unified.current;
+    if (!u) return;
+    const old = getOriginalDoc(u.state);
+    if (old.toString() !== original) {
+      const changes = ChangeSet.of({ from: 0, to: old.length, insert: original }, old.length);
+      u.dispatch({ effects: originalDocChangeEffect(u.state, changes) });
+    }
+    replaceAll(u, modified);
+  }, [original, modified]);
+
+  useEffect(() => {
+    const m = merge.current;
+    if (m) {
+      m.a.dispatch({ effects: langA.reconfigure(languageFor(lang)) });
+      m.b.dispatch({ effects: langB.reconfigure(languageFor(lang)) });
+    } else unified.current?.dispatch({ effects: langB.reconfigure(languageFor(lang)) });
+  }, [lang]);
+
+  useImperativeHandle(ref, () => {
+    const target = () => {
+      const m = merge.current;
+      if (m) return m.a.hasFocus ? m.a : m.b;
+      return unified.current;
+    };
+    const run = (cmd: typeof goToNextChunk) => {
+      const v = target();
+      if (!v) return false;
+      v.focus();
+      return cmd(v);
+    };
+    return { next: () => run(goToNextChunk), prev: () => run(goToPreviousChunk) };
+  }, []);
+
+  return (
+    <div className="diff-view">
+      {onModeChange && (
+        <div className="diff-view-bar" role="group">
+          {(['split', 'inline'] as const).map((m) => (
+            <button key={m} type="button" className={m === mode ? 'active' : undefined} aria-pressed={m === mode} onClick={() => onModeChange(m)}>
+              {modeLabels[m]}
+            </button>
+          ))}
+        </div>
+      )}
+      <div ref={host} className={`diff-view-body diff-${mode}`} />
+    </div>
+  );
+});

package/src/EnvView.tsx

@@ -0,0 +1,42 @@
+import { Icon, t } from '@deckbuilderkit/ui';
+import { useMemo, useState } from 'react';
+import { parseEnv } from './table';
+
+/** A `.env` file as a list of variables with their values hidden until revealed. */
+export function EnvView({ text }: { text: string }) {
+  const lines = useMemo(() => parseEnv(text), [text]);
+  const [shown, setShown] = useState<Set<string>>(new Set());
+  const keys = lines.flatMap((l) => (l.key ? [l.key] : []));
+  const allShown = keys.length > 0 && keys.every((k) => shown.has(k));
+
+  const toggle = (key: string) =>
+    setShown((s) => {
+      const next = new Set(s);
+      if (!next.delete(key)) next.add(key);
+      return next;
+    });
+
+  return (
+    <div className="file-preview">
+      <div className="file-preview-bar">
+        <button className="btn btn-ghost btn-sm" onClick={() => setShown(allShown ? new Set() : new Set(keys))}>
+          {allShown ? t('preview.hideAll') : t('preview.revealAll')}
+        </button>
+      </div>
+      <div className="file-preview-body">
+        {keys.length === 0 && <div className="archive-empty">{t('preview.empty')}</div>}
+        {lines.map((l, i) => l.key === null
+          ? (l.raw.trim() ? <div key={i} className="env-row env-comment">{l.raw}</div> : null)
+          : (
+            <div key={i} className="env-row">
+              <span className="env-key">{l.key}</span>
+              <span className="env-value">{shown.has(l.key) ? l.value : l.value ? '••••••••' : ''}</span>
+              <button className="btn btn-ghost btn-sm btn-icon" onClick={() => toggle(l.key!)} aria-label={shown.has(l.key) ? t('preview.hide') : t('preview.reveal')} title={shown.has(l.key) ? t('preview.hide') : t('preview.reveal')}>
+                <Icon name={shown.has(l.key) ? 'lock' : 'key'} size={14} />
+              </button>
+            </div>
+          ))}
+      </div>
+    </div>
+  );
+}