@1agh/maude 0.57.0 → 0.58.0

package/README.md

@@ -175,7 +175,11 @@ pnpm version            # = bash scripts/changesets-version.sh
                         #   → re-runs scripts/check-version-parity.sh
 
 git commit -am "chore: release v$(node -p "require('./package.json').version")"
-git tag "v$(node -p "require('./package.json').version")"
+# ANNOTATED (-a -m) is required — `git push --follow-tags` only pushes annotated
+# tags. A lightweight `git tag vX.Y.Z` will silently stay local and no release
+# workflow ever fires.
+VER="v$(node -p "require('./package.json').version")"
+git tag -a "$VER" -m "$VER"
 git push --follow-tags
 ```
 

package/apps/studio/api.ts

@@ -117,6 +117,33 @@ export const SKIP_DIRS = new Set([
 ]);
 const HIDDEN_OK = new Set(['.ai', '.claude', '.design']);
 
+// feature-studio-file-preview — binary/media extensions the tree lists so a
+// DS's assets/{fonts,graphics,logos,photos,...} files show up (previously
+// only their parent folders did, via findFiles's dirsOut accounting). Kept as
+// an explicit enumerated list rather than a broad pattern so it can never
+// accidentally widen to swallow runtime JSON — findFiles already excludes
+// `_`-prefixed entries before this list is even consulted.
+const PREVIEW_ASSET_EXTS = [
+  '.svg',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.mp4',
+  '.webm',
+  '.mov',
+  '.mp3',
+  '.wav',
+  '.ogg',
+  '.m4a',
+];
+
 // ---------- File tree ----------
 
 /**
@@ -181,7 +208,31 @@ async function findFiles(
     if (e.isDirectory()) {
       dirsOut?.push(rel);
       out.push(...(await findFiles(full, rel, exts, dirsOut)));
-    } else if (exts.some((x) => e.name.toLowerCase().endsWith(x))) out.push(rel);
+    } else if (e.isFile() && exts.some((x) => e.name.toLowerCase().endsWith(x))) {
+      // feature-studio-file-preview security review — `e.isFile()` (not just
+      // "not a directory") excludes symlinks: a symlink Dirent is neither
+      // isDirectory() nor isFile(), so without this check a symlink dropped
+      // into an assets/ folder (e.g. pointing at ~/.ssh/id_rsa, named to fit
+      // an allowlisted extension) would be listed and, since this feature
+      // makes every listed row one-click-fetchable, served straight into the
+      // preview panel.
+      //
+      // A HARDLINK survives `isFile()` (hardlinks are, by design, ordinary
+      // files — same inode, indistinguishable from the "original" at the
+      // Dirent level), so it needs a second check: `nlink > 1` means this
+      // directory entry shares its inode with at least one other name
+      // somewhere on the filesystem. A design system's own assets are never
+      // legitimately multiply-linked, so excluding them closes the same
+      // one-click-disclosure path for a hardlink planted at, say, a
+      // teammate's readable dotfile.
+      try {
+        const st = await lstat(full);
+        if (st.nlink > 1) continue;
+      } catch {
+        continue;
+      }
+      out.push(rel);
+    }
   }
   return out;
 }
@@ -5268,15 +5319,29 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       const isDs = g.label === 'Design system' || /^system(\/|$)/.test(g.path);
       // Always include canvas sidecars (`.meta.json`, `.css`, `.registry.json`)
       // so the client can nest them under their primary `.tsx` / `.html`. DS
-      // groups additionally surface `.md` for README + SKILL docs.
+      // groups additionally surface `.md` for README + SKILL docs, plus
+      // PREVIEW_ASSET_EXTS (images/fonts/video/audio) so assets/ subfolders
+      // list their files instead of rendering as permanently-empty tree nodes
+      // (feature-studio-file-preview) — click-time behavior lives client-side
+      // in FileRow's previewKind() branch.
       // feature-file-tree-drag-drop-folders (Task 6) — `dirs` accumulates
       // every directory in this group (incl. empty ones) via the SAME
       // traversal, so a freshly `mkdir`'d folder with no files yet is still
       // representable in the tree.
       const dirs: string[] = [];
       const filePaths = isDs
-        ? await findFiles(groupAbs, groupRel, ['.tsx', '.html', '.md', '.css', '.json'], dirs)
-        : await findFiles(groupAbs, groupRel, ['.tsx', '.html', '.css', '.json'], dirs);
+        ? await findFiles(
+            groupAbs,
+            groupRel,
+            ['.tsx', '.html', '.md', '.css', '.json', ...PREVIEW_ASSET_EXTS],
+            dirs
+          )
+        : await findFiles(
+            groupAbs,
+            groupRel,
+            ['.tsx', '.html', '.css', '.json', ...PREVIEW_ASSET_EXTS],
+            dirs
+          );
       // DDR-093 — record each `.tsx` canvas's design system. canvasUrl() only
       // injects tokens for `.tsx`, so skip everything else. Path-owned DS wins
       // (system/<ds>/…); otherwise the sidecar's `meta.designSystem`, defaulting

package/apps/studio/client/app.jsx

@@ -38,6 +38,7 @@ import OnboardingWizard from './panels/OnboardingWizard.jsx';
 import { ReadinessDialog } from './panels/ReadinessList.jsx';
 import IntroVideoDialog from './panels/IntroVideoDialog.jsx';
 import BrandUploadPanel from './panels/BrandUploadPanel.jsx';
+import { FilePreview, sanitizeDisplayText } from './panels/file-preview.jsx';
 import SetupChecklistDialog, { useSetupReadiness } from './panels/SetupChecklist.jsx';
 import TimelinePanel from './panels/TimelinePanel.jsx';
 import { parseCompTimeline } from './panels/timeline-parse.js';
@@ -189,6 +190,23 @@ function DockSlot({ side, width, open, ids, activeId, onPick, children, labels =
   );
 }
 const CANVAS_EXT_RE = /\.(tsx|html?)$/i;
+// feature-studio-file-preview — classifies a non-canvas tree row so FileRow
+// can open an inline preview instead of the old inert no-op. Kept in sync
+// with apps/studio/api.ts's PREVIEW_ASSET_EXTS (server won't list anything
+// outside this set anyway, but the client stays explicit rather than
+// assuming server-side filtering).
+const PREVIEW_KIND_RULES = [
+  [/\.md$/i, 'markdown'],
+  [/\.(css|json|txt|ya?ml)$/i, 'text'],
+  [/\.(svg|png|jpe?g|gif|webp|avif)$/i, 'image'],
+  [/\.(mp4|webm|mov)$/i, 'video'],
+  [/\.(mp3|wav|ogg|m4a)$/i, 'audio'],
+  [/\.(woff2?|ttf|otf)$/i, 'font'],
+];
+function previewKind(name) {
+  for (const [re, kind] of PREVIEW_KIND_RULES) if (re.test(name)) return kind;
+  return null;
+}
 // Shared testid-slug derivation (desktop-e2e skill convention: kebab-case,
 // designRoot-stripped, extension-stripped) — mirrors FileRow's inline
 // `canvas-row-<slug>` computation so DirRow / the row-menu trigger use the
@@ -2024,7 +2042,9 @@ function DsFolderRow({ name, dsName, depth, defaultOpen, active, onOpenSystem, c
 function FileRow({
   file,
   activePath,
+  previewPath,
   onOpen,
+  onPreview,
   onDelete,
   openCount: oc,
   depth,
@@ -2035,12 +2055,20 @@ function FileRow({
   drag,
   menu,
 }) {
-  const isSel = file.path === activePath;
+  // feature-studio-file-preview (a11y fix) — a previewed row must expose
+  // aria-selected too, or a screen-reader user gets no confirmation their
+  // click did anything (a11y-auditor finding: state never changed).
+  const isSel = file.path === activePath || file.path === previewPath;
   const isCanvas = CANVAS_EXT_RE.test(file.name);
-  // Non-canvas rows (PROJECT *.md, RUNTIME _active.json, ...) are display-only —
-  // clicking them doesn't open an iframe; we leave the click as no-op + cursor
-  // hint via `aria-disabled`.
-  const inert = !isCanvas;
+  // feature-studio-file-preview — RUNTIME rows (_active.json, _server.json, …)
+  // stay inert no matter their extension: they're gitignored process state,
+  // never user-facing content, and must not become previewable just because
+  // `.json` also matches the `text` preview kind (DDR-115 exclusion).
+  const pKind = !isCanvas && kind !== 'runtime' ? previewKind(file.name) : null;
+  // Non-canvas, non-previewable rows (RUNTIME files, unrecognized extensions)
+  // are display-only — clicking them doesn't open anything; we leave the
+  // click as no-op + cursor hint via `aria-disabled`.
+  const inert = !isCanvas && !pKind;
   const label = isCanvas ? displayName(file.name) : file.name;
   // Delete only real canvases in a deletable group (onDelete is undefined for the
   // DS group + runtime files); the server enforces the rest.
@@ -2087,7 +2115,8 @@ function FileRow({
       style={{ paddingLeft: TREE_INDENT_BASE + depth * TREE_INDENT_STEP + 'px' }}
       title={file.path + (oc ? ` — ${oc} open` : inert ? ' (file index only)' : '')}
       onClick={() => {
-        if (!inert) onOpen(file.path);
+        if (isCanvas) onOpen(file.path);
+        else if (pKind) onPreview?.(file.path);
       }}
       onContextMenu={
         canMove ? (e) => menu.openAt(e, { kind: 'file', path: file.path, dir: fileDir }) : undefined
@@ -2158,7 +2187,9 @@ function CanvasRow({
   depth,
   kind,
   activePath,
+  previewPath,
   onOpen,
+  onPreview,
   onDelete,
   openCount: oc,
   showHidden,
@@ -2182,7 +2213,9 @@ function CanvasRow({
       <FileRow
         file={primary}
         activePath={activePath}
+        previewPath={previewPath}
         onOpen={onOpen}
+        onPreview={onPreview}
         onDelete={onDelete}
         openCount={oc}
         depth={depth}
@@ -2282,7 +2315,9 @@ function CanvasRow({
             key={sc.path}
             file={sc}
             activePath={activePath}
+            previewPath={previewPath}
             onOpen={onOpen}
+            onPreview={onPreview}
             openCount={0}
             depth={depth + 1}
             kind={kind}
@@ -2296,7 +2331,9 @@ function CanvasRow({
 function Tree({
   node,
   activePath,
+  previewPath,
   onOpen,
+  onPreview,
   commentsByFile,
   depth = 1,
   kind,
@@ -2324,8 +2361,20 @@ function Tree({
   const files = node._files || [];
   // VS Code-style sidecar grouping. Canvas (`.tsx`/`.html`) becomes the primary
   // row; same-basename non-canvas files (`.meta.json`, `.css`, …) collapse
-  // under it. Orphans surface only when `showHidden` is on.
+  // under it. Meta/doc orphans (README.md, tokens.css, …) surface only when
+  // `showHidden` is on; media/asset orphans (images, fonts, video, audio —
+  // feature-studio-file-preview) are content the user asked to see by
+  // default, not sidecar noise, so they always render.
   const { canvases, orphans } = useMemo(() => groupBySidecar(files), [files]);
+  const { mediaOrphans, metaOrphans } = useMemo(() => {
+    const media = [];
+    const meta = [];
+    for (const entry of orphans) {
+      const k = previewKind(entry.primary.name);
+      (k === 'image' || k === 'video' || k === 'audio' || k === 'font' ? media : meta).push(entry);
+    }
+    return { mediaOrphans: media, metaOrphans: meta };
+  }, [orphans]);
   const hasSearch = !!(search && search.trim());
   // DS-folder lookup: only meaningful at the top level of a DS group. The
   // server emits `dsFolders: [{name, folder}, ...]` so the client knows which
@@ -2351,7 +2400,9 @@ function Tree({
             primary={entry.primary}
             sidecars={entry.sidecars}
             activePath={activePath}
+            previewPath={previewPath}
             onOpen={onOpen}
+            onPreview={onPreview}
             onDelete={onDelete}
             openCount={openCount(commentsByFile[entry.primary.path])}
             depth={depth}
@@ -2365,13 +2416,28 @@ function Tree({
           />
         );
       })}
+      {mediaOrphans.map((entry) => (
+        <FileRow
+          key={entry.primary.path}
+          file={entry.primary}
+          activePath={activePath}
+          previewPath={previewPath}
+          onOpen={onOpen}
+          onPreview={onPreview}
+          openCount={openCount(commentsByFile[entry.primary.path])}
+          depth={depth}
+          kind={kind}
+        />
+      ))}
       {showHidden &&
-        orphans.map((entry) => (
+        metaOrphans.map((entry) => (
           <FileRow
             key={entry.primary.path}
             file={entry.primary}
             activePath={activePath}
+            previewPath={previewPath}
             onOpen={onOpen}
+            onPreview={onPreview}
             openCount={openCount(commentsByFile[entry.primary.path])}
             depth={depth}
             kind={kind}
@@ -2385,7 +2451,9 @@ function Tree({
           <Tree
             node={node[d]}
             activePath={activePath}
+            previewPath={previewPath}
             onOpen={onOpen}
+            onPreview={onPreview}
             commentsByFile={commentsByFile}
             depth={depth + 1}
             kind={kind}
@@ -2468,8 +2536,10 @@ function Sidebar({
   cloud,
   groups,
   activePath,
+  previewPath,
   activeDsName,
   onOpen,
+  onPreview,
   onOpenSystem,
   wsConnected,
   search,
@@ -2829,7 +2899,9 @@ function Sidebar({
                   <Tree
                     node={g.tree}
                     activePath={activePath}
+                    previewPath={previewPath}
                     onOpen={onOpen}
+                    onPreview={onPreview}
                     commentsByFile={commentsByFile}
                     depth={1}
                     kind={g.kind}
@@ -4205,10 +4277,38 @@ function Viewport({
   onIframeLoad,
   showQuickSetup,
   onStartQuickSetup,
+  previewPath,
 }) {
+  // feature-studio-file-preview (a11y fix) — a11y-auditor found the preview
+  // overlay gave keyboard/AT users no signal anything happened: the click
+  // stayed on the (unrelated) tree row, nothing was announced, and the
+  // scrollable region itself wasn't in the tab order. Moving focus onto the
+  // region on open covers all three: it's a real focus change (AT announces
+  // the new `role="region"` + its label), and a focused element with
+  // `overflow: auto` is keyboard-scrollable (arrow/Page keys) without a
+  // separate tabIndex fix.
+  const previewRef = useRef(null);
+  useEffect(() => {
+    if (previewPath) previewRef.current?.focus();
+  }, [previewPath]);
   return (
     <div className="viewport st-stage" data-tour="viewport">
-      {tabs.length === 0 && (
+      {previewPath && (
+        // feature-studio-file-preview — an overlay, not a tab: the canvas
+        // iframe (if any) stays mounted underneath so switching back to it
+        // is instant and never remounts. previewPath is intentionally never
+        // written into `tabs`/`activePath` (see App()'s onPreview).
+        <div
+          ref={previewRef}
+          className="st-file-preview-overlay"
+          role="region"
+          aria-label={`Preview: ${sanitizeDisplayText(basename(previewPath))}`}
+          tabIndex={0}
+        >
+          <FilePreview path={previewPath} kind={previewKind(basename(previewPath))} />
+        </div>
+      )}
+      {tabs.length === 0 && !previewPath && (
         <div className="st-empty">
           <div className="st-empty-brand">
             <span className="st-brand-mark">
@@ -4567,6 +4667,7 @@ function StatusBar({
   unpushed = 0,
   changesOpen = false,
   onOpenChanges,
+  version,
 }) {
   const isSystem = activePath === SYSTEM_TAB;
   const text =
@@ -4690,6 +4791,19 @@ function StatusBar({
         </span>
       )}
 
+      {/* Which release this is. Reading it used to mean probing production by
+          hand — and the desktop, the browser and a cloud tab all serve the same
+          client, so one slot covers all three. Absent on an older server that
+          omits `version` from /_config, exactly as `cloud` and `canvasToken`
+          already are. */}
+      {version && (
+        <span className="st-sb-slot st-sb-version" role="group" aria-label="Maude version">
+          <span className="val" data-testid="statusbar-version">
+            v{version}
+          </span>
+        </span>
+      )}
+
       <button
         type="button"
         className="st-sb-theme"
@@ -9176,6 +9290,14 @@ function App() {
   const [project, setProject] = useState('Design');
   const [tabs, setTabs] = useState([]);
   const [activePath, setActivePath] = useState(null);
+  // feature-studio-file-preview — deliberately separate from `tabs`/
+  // `activePath`: a previewed file was never a canvas, so it must never
+  // trigger the WS `active`/`tabs` broadcasts, the compile-skeleton loading
+  // state, or iframe registration that openTab()/openSystem() drive.
+  const [previewPath, setPreviewPath] = useState(null);
+  const onPreview = useCallback((path) => {
+    setPreviewPath(path);
+  }, []);
   const [selected, setSelected] = useState(null);
   // Phase 12.3 — latest selection, readable from the (stale-closure) onMessage
   // handler so an HMR reload (triggered by a CSS/attr edit) can re-select the
@@ -9446,6 +9568,10 @@ function App() {
           // both of these went missing and the cloud studio rendered without
           // its chrome and with every canvas iframe unauthenticated.
           canvasToken: data.canvasToken,
+          // Which release this server is — rendered as the status-bar chip.
+          // Undefined on a server too old to report it, which is why the chip
+          // renders conditionally rather than printing `vundefined`.
+          version: data.version,
           // C2/C4 — `{ dashboardUrl, projectName, user, role }` when this is a
           // cloud tab. Its presence is what tells the shared client it is in a
           // browser tab on somebody else's machine; `user`/`role` are what let
@@ -11170,6 +11296,7 @@ function App() {
     });
     setActivePath(path);
     setFocusedCommentId(null);
+    setPreviewPath(null);
     // Canvas-compile skeleton — cleared by the iframe's dgn:'loaded' message,
     // the onLoad fallback timer (legacy .html), or a hard 15s cap.
     if (path !== SYSTEM_TAB) setLoadingPath(path);
@@ -14076,8 +14203,10 @@ function App() {
           readOnly={viewerMode}
           groups={groups}
           activePath={activePath}
+          previewPath={previewPath}
           activeDsName={activePath === SYSTEM_TAB ? (systemData?.ds?.name ?? null) : null}
           onOpen={openTab}
+          onPreview={onPreview}
           onOpenSystem={openSystem}
           wsConnected={wsConnected}
           search={search}
@@ -14419,6 +14548,7 @@ function App() {
                 isNativeApp() && !viewerMode && !!setupReadiness && !setupReadiness.ready
               }
               onStartQuickSetup={() => setQuickSetupOpen(true)}
+              previewPath={previewPath}
             />
           </div>
           {rightActive && (
@@ -15168,6 +15298,7 @@ function App() {
           unpushed={gitStatus?.unpushed || 0}
           changesOpen={changesOpen}
           onOpenChanges={gitStatus?.repo ? () => setChangesOpen(true) : undefined}
+          version={cfg?.version}
         />
       </div>
       {presentMode && (

package/apps/studio/client/panels/chat-markdown.jsx

@@ -1,8 +1,11 @@
-// Compact, XSS-safe markdown renderer for the ACP chat feed. Builds React nodes
-// directly (never innerHTML) so agent output can't inject markup. Covers the
-// subset a coding agent actually emits: fenced code blocks, headings, bullet +
-// numbered lists, bold / italic / inline code, and http(s) links. Anything else
-// falls through as plain (pre-wrapped) text. No new dependency.
+// Compact, XSS-safe markdown renderer for the ACP chat feed (and, since
+// feature-studio-file-preview, arbitrary repo .md files previewed in the
+// Files tree). Builds React nodes directly (never innerHTML) so neither
+// agent output nor untrusted file content can inject markup. Covers the
+// subset a coding agent actually emits plus GFM pipe tables (common in repo
+// docs): fenced code blocks, headings, bullet + numbered lists, pipe tables,
+// bold / italic / inline code, and http(s) links. Anything else falls
+// through as plain (pre-wrapped) text. No new dependency.
 
 function safeHref(url) {
   // Only allow http(s) — never javascript:/data:/etc.
@@ -47,6 +50,33 @@ function inline(text) {
   return out;
 }
 
+// GFM pipe tables: a header row, a separator row (---/:---/---:/:---:  per
+// column), then zero or more data rows — all lines containing at least one
+// unescaped `|`.
+const TABLE_ROW_RE = /\|/;
+const TABLE_SEP_CELL_RE = /^:?-+:?$/;
+
+function splitTableRow(line) {
+  let l = line.trim();
+  if (l.startsWith('|')) l = l.slice(1);
+  if (l.endsWith('|')) l = l.slice(0, -1);
+  // Split on `|` not preceded by `\` (an escaped pipe stays literal in a cell).
+  return l.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'));
+}
+
+function tableSeparatorAligns(line) {
+  const cells = splitTableRow(line);
+  if (!cells.length || !cells.every((c) => TABLE_SEP_CELL_RE.test(c))) return null;
+  return cells.map((c) => {
+    const left = c.startsWith(':');
+    const right = c.endsWith(':');
+    if (left && right) return 'center';
+    if (right) return 'right';
+    if (left) return 'left';
+    return null;
+  });
+}
+
 export function Markdown({ text }) {
   const lines = String(text).split('\n');
   const blocks = [];
@@ -108,6 +138,47 @@ export function Markdown({ text }) {
       continue;
     }
 
+    // GFM pipe table: header row + a valid separator row immediately after.
+    if (TABLE_ROW_RE.test(line) && i + 1 < lines.length) {
+      const aligns = tableSeparatorAligns(lines[i + 1]);
+      if (aligns) {
+        const header = splitTableRow(line);
+        i += 2;
+        const rows = [];
+        while (i < lines.length && lines[i].trim() !== '' && TABLE_ROW_RE.test(lines[i])) {
+          rows.push(splitTableRow(lines[i]));
+          i++;
+        }
+        blocks.push(
+          <div key={key++} className="chat-md-table-wrap">
+            <table className="chat-md-table">
+              <thead>
+                <tr>
+                  {header.map((c, ci) => (
+                    <th key={ci} style={aligns[ci] ? { textAlign: aligns[ci] } : undefined}>
+                      {inline(c)}
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {rows.map((r, ri) => (
+                  <tr key={ri}>
+                    {header.map((_, ci) => (
+                      <td key={ci} style={aligns[ci] ? { textAlign: aligns[ci] } : undefined}>
+                        {r[ci] !== undefined ? inline(r[ci]) : ''}
+                      </td>
+                    ))}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        );
+        continue;
+      }
+    }
+
     // Blank line → paragraph separator.
     if (line.trim() === '') {
       i++;

package/apps/studio/client/panels/file-preview.jsx

@@ -0,0 +1,115 @@
+// feature-studio-file-preview — inline preview for a non-canvas tree row
+// (markdown / text / image / video / audio / font). Reuses the existing
+// static byte-serving route (no new server endpoint) and the chat panel's
+// hand-rolled Markdown renderer — no new dependency.
+
+import { useEffect, useState } from 'react';
+import { Markdown } from './chat-markdown.jsx';
+
+const TEXT_PREVIEW_MAX_BYTES = 2 * 1024 * 1024; // 2 MB — beyond this, just show a size note
+
+function basename(p) {
+  return p.split('/').pop() || p;
+}
+
+// Bidi-override control chars (U+202A-E, U+2066-9) let a crafted filename
+// visually disguise its own name/extension (the classic "invoice‮gnp.exe"
+// trick) wherever we render a raw path/name as text — strip them before
+// display. Doesn't affect matching (previewKind() regexes run on the
+// unstripped name), only what a human/AT reads.
+export function sanitizeDisplayText(s) {
+  return String(s).replace(/[\u202a-\u202e\u2066-\u2069]/g, '');
+}
+
+function useFetchedText(url, enabled) {
+  const [state, setState] = useState({ loading: true, error: null, text: '', tooLarge: false });
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    setState({ loading: true, error: null, text: '', tooLarge: false });
+    fetch(url)
+      .then(async (r) => {
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        const len = Number(r.headers.get('content-length') || 0);
+        if (len > TEXT_PREVIEW_MAX_BYTES) {
+          if (!cancelled) setState({ loading: false, error: null, text: '', tooLarge: len });
+          return;
+        }
+        const text = await r.text();
+        if (!cancelled) setState({ loading: false, error: null, text, tooLarge: false });
+      })
+      .catch((err) => {
+        if (!cancelled) setState({ loading: false, error: err.message || 'Failed to load', text: '', tooLarge: false });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [url, enabled]);
+  return state;
+}
+
+function TextPreview({ url, name, as }) {
+  const { loading, error, text, tooLarge } = useFetchedText(url, true);
+  if (loading) return <div className="st-file-preview-status">Loading {name}…</div>;
+  if (error) return <div className="st-file-preview-status st-file-preview-error">Couldn't load {name}: {error}</div>;
+  if (tooLarge) {
+    return (
+      <div className="st-file-preview-status">
+        {name} is {Math.round(tooLarge / 1024)} KB — too large to preview inline.
+      </div>
+    );
+  }
+  if (as === 'markdown') return <div className="st-file-preview-markdown"><Markdown text={text} /></div>;
+  return <pre className="st-file-preview-text">{text}</pre>;
+}
+
+// CSS-string-literal escape for a value interpolated inside url("...") —
+// filenames can contain arbitrary characters (only "/" and NUL are forbidden
+// on disk), so an unescaped `"` or `\` could break out of the string and
+// inject arbitrary rules into the live app-shell stylesheet (not just the
+// sandboxed canvas iframe). family is already alnum/hyphen-only; this covers
+// the url() side of the same interpolation.
+function cssStringEscape(s) {
+  // CSS input-preprocessing (CSS Syntax Module Level 3 §3.3) normalizes CR,
+  // CRLF, AND FORM FEED (\f, U+000C) to a single LF before tokenizing, so an
+  // unescaped \f terminates a double-quoted string exactly like \r/\n does —
+  // strip all three, not just the two obvious ones.
+  return String(s).replace(/[\\"]/g, (c) => `\\${c}`).replace(/[\r\n\f]/g, '');
+}
+
+function FontPreview({ url, name }) {
+  const family = `st-preview-font-${name.replace(/[^a-z0-9]+/gi, '-')}`;
+  return (
+    <div className="st-file-preview-font">
+      <style>{`@font-face { font-family: "${family}"; src: url("${cssStringEscape(url)}"); }`}</style>
+      <div className="st-file-preview-font-specimen" style={{ fontFamily: family }}>
+        <div className="st-file-preview-font-lg">The quick brown fox</div>
+        <div className="st-file-preview-font-md">jumps over the lazy dog</div>
+        <div className="st-file-preview-font-sm">ABCDEFGHIJKLM abcdefghijklm 0123456789</div>
+      </div>
+    </div>
+  );
+}
+
+export function FilePreview({ path, kind }) {
+  if (!path || !kind) return null;
+  const url = `/${path}`;
+  const name = sanitizeDisplayText(basename(path));
+  return (
+    <div className="st-file-preview" data-kind={kind}>
+      <h2 className="st-file-preview-header">{sanitizeDisplayText(path)}</h2>
+      <div className="st-file-preview-body">
+        {kind === 'markdown' && <TextPreview url={url} name={name} as="markdown" />}
+        {kind === 'text' && <TextPreview url={url} name={name} as="text" />}
+        {kind === 'image' && (
+          <div className="st-file-preview-image-wrap">
+            <img src={url} alt={`Preview: ${name}`} className="st-file-preview-image" />
+          </div>
+        )}
+        {kind === 'video' && <video key={url} src={url} controls className="st-file-preview-media" />}
+        {kind === 'audio' && <audio key={url} src={url} controls className="st-file-preview-audio" />}
+        {kind === 'font' && <FontPreview url={url} name={name} />}
+      </div>
+    </div>
+  );
+}