dsh-better-sidebar 0.10.0

package/src/client/chunk-loader.ts

@@ -0,0 +1,196 @@
+/**
+ * Lazy chunk loader for the client bundle. The heavy preview/terminal
+ * libraries (Univer, docx-preview, pptx-renderer, CodeMirror, xterm — the
+ * office/terminal/editor stacks, tens of MB) live in separate build-time
+ * bundles (`lib/client-<name>.js`) fetched only on first use of the feature
+ * that needs them, so startup downloads/parses only the ~1MB core bundle.
+ *
+ * How a chunk script works (see tsdown.config.ts chunkBundle):
+ *
+ *   globalThis.__dshChunks__ = globalThis.__dshChunks__ || {};
+ *   globalThis.__dshChunks__["terminal"] = (require) => { ...exports };
+ *
+ * The script registers its factory on a plugin-owned global registry (NOT
+ * through window.__ModuleLoader__.load — the module loader's import() only
+ * resolves seed words, shell-own modules, registered factories, and boot
+ * graph rows; a chunk id is none of those, so resolution would be version-
+ * dependent). Materialization is plugin-owned:
+ *
+ * 1. inject <script src="/sidebar/bundle/<name>.js"> (classic same-origin
+ *    script; the official /plugins/<id>/client.js route cannot serve
+ *    arbitrary file names, so the plugin's own host route serves the chunks),
+ * 2. read the factory from the global registry,
+ * 3. call it with a require that resolves the platform externals through
+ *    `__DSH_MODULES__.import(spec)` — the seed-word branch, the one part of
+ *    the module system that is stable across versions.
+ *
+ * Caching contract (three layers, each with a failure path):
+ * - In-memory: one in-flight promise per chunk, memoized until
+ *   {@link resetChunks}; a failed load removes its entry so the next call
+ *   retries from scratch.
+ * - Script execution: each re-execution overwrites the global registry slot
+ *   (assignment, never registration) — no "duplicate factory registration"
+ *   class of errors; a failed materialization clears the cache so the retry
+ *   re-injects and re-executes.
+ * - HTTP: the bundle route revalidates every request (`cache-control:
+ *   no-cache` + ETag, 304 when unchanged), so page refreshes and HMR
+ *   re-activations never re-download a multi-MB chunk that did not change.
+ *
+ * HMR: each plugin activation calls {@link resetChunks}, which drops the
+ * in-memory cache (and any test registry), so a hot-reloaded core bundle
+ * re-fetches and re-executes the current chunk scripts on the next lazy
+ * open. Chunk-only source edits still need a manual page refresh (the HMR
+ * poll watches only client.js).
+ */
+export type ChunkName = 'docx' | 'xlsx' | 'pptx' | 'terminal' | 'editor'
+
+/** The module exports a chunk factory provides (namespace-ish record). */
+export type ChunkExports = Record<string, unknown>
+
+/** A chunk factory: (require) => exports (the chunk's CJS closure shape). */
+type ChunkFactory = (require: (spec: string) => unknown) => ChunkExports
+
+/**
+ * The platform externals a chunk bundle may require (mirror of
+ * CLIENT_EXTERNALS in tsdown.config.ts — the chunk builds keep these
+ * external and the loader resolves them here). A superset is safe: the
+ * require only answers what the chunk actually asks for.
+ */
+export const CHUNK_EXTERNALS: readonly string[] = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  'cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-web-react',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-schema-form',
+  '@deepseek-ai/dsh-client-runtime/client',
+]
+
+/** Chunk script endpoint served by the plugin host half (src/bundle-route.ts). */
+const CHUNK_URL = (name: ChunkName): string => `/sidebar/bundle/${name}.js`
+
+/** The client module system surface this loader needs (window.__DSH_MODULES__). */
+interface ChunkModuleSystem {
+  import(specifier: string): Promise<unknown>
+}
+
+/** Resolve the shell-installed module system (set before any plugin activates). */
+function moduleSystem(): ChunkModuleSystem | undefined {
+  return (globalThis as { __DSH_MODULES__?: ChunkModuleSystem }).__DSH_MODULES__
+}
+
+/** The plugin-owned chunk factory registry the chunk scripts populate. */
+interface ChunkRegistry {
+  [name: string]: ChunkFactory | undefined
+}
+
+function chunkRegistry(): ChunkRegistry {
+  const g = globalThis as { __dshChunks__?: ChunkRegistry }
+  return g.__dshChunks__ ??= {}
+}
+
+/** Script-load hook; tests replace it with a stub (the default needs a real DOM + network). */
+export type ChunkScriptLoader = (src: string) => Promise<void>
+
+const defaultScriptLoader: ChunkScriptLoader = (src) => new Promise((resolve, reject) => {
+  const el = document.createElement('script')
+  el.async = true
+  el.src = src
+  el.addEventListener('load', () => {
+    el.remove()
+    resolve()
+  }, { once: true })
+  el.addEventListener('error', () => {
+    el.remove()
+    reject(new Error(`[dsh-better-sidebar] chunk script ${src} failed to load`))
+  }, { once: true })
+  document.head.append(el)
+})
+
+let scriptLoader: ChunkScriptLoader = defaultScriptLoader
+
+/** Test hook: replace the chunk-script loader (pass null to restore the default). */
+export function setChunkScriptLoaderForTests(loader: ChunkScriptLoader | null): void {
+  scriptLoader = loader ?? defaultScriptLoader
+}
+
+/** Test/dev hook: resolve a chunk without fetching a script (e.g. vitest). */
+const testLoaders = new Map<ChunkName, () => Promise<ChunkExports>>()
+export function registerChunkForTests(name: ChunkName, loader: () => Promise<ChunkExports>): void {
+  testLoaders.set(name, loader)
+}
+
+/** Memoized externals require, resolved once per page from the seed table. */
+let externalsRequire: ((spec: string) => unknown) | undefined
+
+async function buildExternalsRequire(modules: ChunkModuleSystem): Promise<(spec: string) => unknown> {
+  if (externalsRequire !== undefined) return externalsRequire
+  // Per-spec tolerance: a spec the running DSH version cannot resolve (e.g.
+  // the runtime/client exemption row) stays unresolved until a chunk
+  // actually requires it — only then it is a loud error.
+  const entries = await Promise.all(CHUNK_EXTERNALS.map(async (spec) => {
+    try {
+      return [spec, await modules.import(spec)] as const
+    } catch {
+      return [spec, undefined] as const
+    }
+  }))
+  const table = new Map<string, unknown>(entries)
+  externalsRequire = (spec: string): unknown => {
+    if (!table.has(spec)) {
+      // Single quotes: the bundle-consistency scan regexes for require("...")
+      // lexical calls — a double-quoted literal here would trip it.
+      throw new Error(`[dsh-better-sidebar] chunk require('${spec}') missed the module table`)
+    }
+    return table.get(spec)
+  }
+  return externalsRequire
+}
+
+/** In-flight/memoized chunk loads; a failure removes its entry so a retry re-fetches. */
+const cache = new Map<ChunkName, Promise<ChunkExports>>()
+
+/**
+ * Load (once) and materialize a lazy chunk, returning its module exports.
+ * Concurrent callers share one in-flight load; a failure clears the cache
+ * entry so the next call retries (the script re-executes and overwrites its
+ * global registry slot — assignments are idempotent).
+ * @param name - the chunk to load.
+ */
+export function loadChunk(name: ChunkName): Promise<ChunkExports> {
+  const cached = cache.get(name)
+  if (cached !== undefined) return cached
+  const task = (async (): Promise<ChunkExports> => {
+    const test = testLoaders.get(name)
+    if (test !== undefined) return test()
+    const modules = moduleSystem()
+    if (modules === undefined) {
+      throw new Error(`[dsh-better-sidebar] chunk "${name}": client module system unavailable`)
+    }
+    await scriptLoader(CHUNK_URL(name))
+    const factory = chunkRegistry()[name]
+    if (typeof factory !== 'function') {
+      throw new Error(`[dsh-better-sidebar] chunk "${name}" script did not register its factory`)
+    }
+    const require = await buildExternalsRequire(modules)
+    return factory(require)
+  })()
+  cache.set(name, task)
+  void task.catch(() => { cache.delete(name) })
+  return task
+}
+
+/**
+ * Drop all chunk state for a fresh plugin activation (HMR-safe): clear the
+ * in-memory cache and any test-registry entries, so the next lazy open
+ * re-fetches and re-executes the current chunk scripts (the registry slots
+ * are overwritten by the re-execution — no cleanup needed).
+ */
+export function resetChunks(): void {
+  cache.clear()
+  testLoaders.clear()
+  externalsRequire = undefined
+}

package/src/client/chunks/docx.tsx

@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .docx preview (docx-preview + jszip). Built as
+ * `lib/client-docx.js` and registered under `dsh-better-sidebar/docx` —
+ * fetched only when a .docx is first opened (see chunk-loader.ts and
+ * docs/plans/2026-08-12-lazy-chunks-design.md). Never import this module
+ * from the core bundle: it pulls the office library into the startup path.
+ */
+export { DocxView } from '../docx-view.tsx'

package/src/client/chunks/editor.tsx

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the code/markdown/html text editor (CodeMirror 6 + the
+ * language packages). Built as `lib/client-editor.js` and registered under
+ * `dsh-better-sidebar/editor` — fetched only when a text file is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls CodeMirror into
+ * the startup path.
+ */
+export { TextEditor } from '../TextEditor.tsx'

package/src/client/chunks/pptx.tsx

@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .pptx preview (pptx-renderer). Built as
+ * `lib/client-pptx.js` and registered under `dsh-better-sidebar/pptx` —
+ * fetched only when a .pptx is first opened (see chunk-loader.ts and
+ * docs/plans/2026-08-12-lazy-chunks-design.md). Never import this module
+ * from the core bundle: it pulls the renderer into the startup path.
+ */
+export { PptxView } from '../PptxView.tsx'

package/src/client/chunks/terminal.tsx

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the interactive terminal (xterm + fit addon). Built as
+ * `lib/client-terminal.js` and registered under
+ * `dsh-better-sidebar/terminal` — fetched only when a terminal tab is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls xterm (and its
+ * stylesheet) into the startup path.
+ */
+export { TerminalView } from '../TerminalView.tsx'

package/src/client/chunks/xlsx.tsx

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the .xlsx preview (Univer family + SheetJS, several MB).
+ * Built as `lib/client-xlsx.js` and registered under
+ * `dsh-better-sidebar/xlsx` — fetched only when a .xlsx is first opened
+ * (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls Univer into the
+ * startup path.
+ */
+export { XlsxView } from '../xlsx-view.tsx'

package/src/client/cm-themes.ts

@@ -0,0 +1,129 @@
+/**
+ * CodeMirror 6 theme pieces for the sidebar editor. The editor surface
+ * (background, caret, gutter) rides the DSH theme tokens so it blends with
+ * the panel in both schemes; only the syntax token colors need concrete
+ * values, and those come from the same designed palettes the app's code
+ * surfaces use — the one-dark family for dark, the one-light family for
+ * light. The scheme flip reconfigures these via a compartment (see
+ * TextEditor), so the document, undo history and scroll survive re-theming.
+ */
+import { Compartment } from '@codemirror/state'
+import { HighlightStyle, syntaxHighlighting } from '@codemirror/language'
+import { tags, type Tag } from '@lezer/highlight'
+import { EditorView } from '@codemirror/view'
+
+/** Token-driven surface shared by both schemes (pure CSS values). */
+export const cmSurfaceTheme = EditorView.theme({
+  '&': {
+    height: '100%',
+    fontSize: '13px',
+    backgroundColor: 'transparent',
+    color: 'var(--dsw-alias-label-primary)',
+  },
+  '.cm-scroller': {
+    overflow: 'auto',
+    fontFamily: 'var(--ds-font-family-code)',
+  },
+  '.cm-content': {
+    caretColor: 'var(--dsw-alias-label-primary)',
+  },
+  '.cm-gutters': {
+    backgroundColor: 'transparent',
+    color: 'var(--dsw-alias-label-tertiary)',
+    border: 'none',
+  },
+})
+
+/** Scheme-specific surface tints (selection, active line). */
+function cmSurfaceTint(dark: boolean): ReturnType<typeof EditorView.theme> {
+  return EditorView.theme({
+    '.cm-selectionBackground, .cm-focused .cm-selectionBackground, ::selection': {
+      backgroundColor: dark ? 'rgba(255,255,255,0.22)' : 'rgba(0,0,0,0.12)',
+    },
+    '.cm-activeLine, .cm-activeLineGutter': {
+      backgroundColor: dark ? 'rgba(255,255,255,0.04)' : 'rgba(0,0,0,0.03)',
+    },
+  })
+}
+
+/** One syntax rule: a tag (or tag set) mapped to a concrete color/style. */
+interface HighlightRule {
+  tag: Tag | readonly Tag[]
+  color?: string
+  fontStyle?: string
+}
+
+/** one-dark syntax palette (mirrors @codemirror/theme-one-dark). */
+const HIGHLIGHTS_DARK: HighlightRule[] = [
+  { tag: tags.comment, color: '#5c6370', fontStyle: 'italic' },
+  { tag: tags.keyword, color: '#c678dd' },
+  { tag: tags.string, color: '#98c379' },
+  { tag: tags.number, color: '#d19a66' },
+  { tag: tags.bool, color: '#d19a66' },
+  { tag: tags.atom, color: '#d19a66' },
+  { tag: tags.typeName, color: '#e5c07b' },
+  { tag: tags.className, color: '#e5c07b' },
+  { tag: tags.propertyName, color: '#e06c75' },
+  { tag: tags.function(tags.variableName), color: '#61afef' },
+  { tag: tags.variableName, color: '#e06c75' },
+  { tag: tags.operator, color: '#56b6c2' },
+  { tag: tags.tagName, color: '#e06c75' },
+  { tag: tags.attributeName, color: '#d19a66' },
+  { tag: tags.heading, color: '#e06c75', fontStyle: 'bold' },
+  { tag: tags.emphasis, fontStyle: 'italic' },
+  { tag: tags.strong, fontStyle: 'bold' },
+  { tag: tags.link, color: '#61afef', fontStyle: 'underline' },
+  { tag: tags.meta, color: '#e5c07b' },
+  { tag: tags.invalid, color: '#ffffff', fontStyle: 'bold' },
+]
+
+/** one-light syntax palette (the light counterpart of one-dark). */
+const HIGHLIGHTS_LIGHT: HighlightRule[] = [
+  { tag: tags.comment, color: '#a0a1a7', fontStyle: 'italic' },
+  { tag: tags.keyword, color: '#a626a4' },
+  { tag: tags.string, color: '#50a14f' },
+  { tag: tags.number, color: '#986801' },
+  { tag: tags.bool, color: '#0184bc' },
+  { tag: tags.atom, color: '#0184bc' },
+  { tag: tags.typeName, color: '#c18401' },
+  { tag: tags.className, color: '#c18401' },
+  { tag: tags.propertyName, color: '#e45649' },
+  { tag: tags.function(tags.variableName), color: '#c18401' },
+  { tag: tags.variableName, color: '#e45649' },
+  { tag: tags.operator, color: '#383a42' },
+  { tag: tags.tagName, color: '#e45649' },
+  { tag: tags.attributeName, color: '#986801' },
+  { tag: tags.heading, color: '#e45649', fontStyle: 'bold' },
+  { tag: tags.emphasis, fontStyle: 'italic' },
+  { tag: tags.strong, fontStyle: 'bold' },
+  { tag: tags.link, color: '#4078f2', fontStyle: 'underline' },
+  { tag: tags.meta, color: '#c18401' },
+  { tag: tags.invalid, color: '#ffffff', fontStyle: 'bold' },
+]
+
+/** The scheme-dependent extension pair (surface tint + syntax highlight). */
+function cmThemeExtensions(dark: boolean): Array<ReturnType<typeof EditorView.theme>> {
+  return [
+    cmSurfaceTint(dark),
+    syntaxHighlighting(HighlightStyle.define(dark ? HIGHLIGHTS_DARK : HIGHLIGHTS_LIGHT)),
+  ]
+}
+
+/**
+ * A Compartment holding the two scheme-dependent extensions. Created once
+ * per editor view; a scheme flip dispatches `reconfigure(dark)` on it, so
+ * the document, undo history, scroll and keymaps survive re-theming.
+ */
+export class CmThemeCompartment {
+  private readonly compartment = new Compartment()
+
+  /** `of(...)` payload for EditorState.create. */
+  of(dark: boolean): ReturnType<Compartment['of']> {
+    return this.compartment.of(cmThemeExtensions(dark))
+  }
+
+  /** Reconfigure for a new scheme. */
+  reconfigure(dark: boolean): ReturnType<Compartment['reconfigure']> {
+    return this.compartment.reconfigure(cmThemeExtensions(dark))
+  }
+}

package/src/client/conversation-draft.ts

@@ -0,0 +1,29 @@
+/**
+ * Append text to the current session's composer draft through the
+ * conversation service — the shared path behind the explorer's @-reference
+ * button and the viewer selection popup. The service is resolved lazily
+ * through `ctx.get` (the inject-free read the app's own plugins use); a
+ * missing service or scope degrades to a logged no-op, never a crash.
+ */
+import type { Context, SidebarConversation } from '../context-types.ts'
+
+/**
+ * Append `text` to the session's composer draft (space-separated, like the
+ * @-mentions). Returns false — and logs — when the conversation service or
+ * the session scope is unavailable.
+ */
+export function appendToDraft(ctx: Context, sessionId: string, text: string): boolean {
+  try {
+    const actx = ctx.sessions.scope(sessionId)
+    if (actx === undefined) return false
+    const conversation = ctx.get('conversation') as SidebarConversation | undefined
+    if (conversation === undefined) return false
+    const input = conversation.input.for(actx)
+    const draft = input.state.getSnapshot().draft
+    input.setDraft(draft.trim() === '' ? text : `${draft} ${text}`)
+    return true
+  } catch (error) {
+    console.warn('[dsh-better-sidebar] draft insert failed:', error)
+    return false
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,5 @@
+/** CSS Modules class-map declaration (tsdown compiles .module.css at build). */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/client/docx-view.tsx

@@ -0,0 +1,113 @@
+/**
+ * The .docx preview component: renders via docx-preview (preserved
+ * styles/images/tables). Lives in its own module (split out of the former
+ * office-view.tsx) so it builds as a standalone lazy chunk
+ * (`lib/client-docx.js`) — the library is loaded only when a .docx is first
+ * opened, and never pulls in the Univer/xlsx stack.
+ *
+ * Errors degrade to the shared download-button affordance, so a corrupted /
+ * encrypted / oversized file always leaves the user with a way to get it.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { mediaUrl } from './api.ts'
+import { t } from './locales.ts'
+import { BinaryFallback, type LoadState, type OfficeViewProps } from './office-shared.tsx'
+import css from './sidebar.module.css'
+
+/**
+ * Render a .docx file via docx-preview. The library renders into a container
+ * div (no canvas); images and styles are inlined. Unmounting clears the
+ * container's innerHTML — docx-preview has no dispose API, but tearing down
+ * the DOM is enough.
+ */
+export function DocxView(props: OfficeViewProps): JSX.Element {
+  const { scope, path, title } = props
+  const viewportRef = useRef<HTMLDivElement>(null)
+  const wrapRef = useRef<HTMLDivElement>(null)
+  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
+  const [zoom, setZoom] = useState(100)
+
+  useEffect(() => {
+    let cancelled = false
+    const container = viewportRef.current
+    const wrap = wrapRef.current
+    if (container === null || wrap === null) return
+    setZoom(100)
+    void (async () => {
+      try {
+        const response = await fetch(mediaUrl(scope, path))
+        if (cancelled) return
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`)
+        }
+        const buf = await response.arrayBuffer()
+        if (cancelled) return
+        // docx-preview ships its own CSS through the className option; the
+        // wrapper div scopes its render output.
+        const { renderAsync } = await import('docx-preview')
+        await renderAsync(buf, wrap, undefined, {
+          className: 'docx',
+          inWrapper: true,
+          ignoreWidth: false,
+          ignoreHeight: false,
+          breakPages: true,
+          experimental: false,
+        })
+        if (!cancelled) setLoad({ status: 'ready' })
+      } catch (error) {
+        if (!cancelled) {
+          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+        }
+      }
+    })()
+    return () => {
+      cancelled = true
+      // Tear down the rendered DOM so a reopen starts clean.
+      if (wrap !== null) wrap.innerHTML = ''
+    }
+  }, [scope.sessionId, scope.cwd, path])
+
+  useEffect(() => {
+    const viewport = viewportRef.current
+    if (viewport === null) return
+    const onWheel = (event: WheelEvent): void => {
+      if (!event.altKey) return
+      event.preventDefault()
+      const delta = event.deltaY < 0 ? 10 : -10
+      setZoom(current => Math.max(50, Math.min(200, current + delta)))
+    }
+    viewport.addEventListener('wheel', onWheel, { passive: false })
+    return () => { viewport.removeEventListener('wheel', onWheel) }
+  }, [])
+
+  return (
+    <div className={css.editorDocx}>
+      <div className={css.editorDocxViewport} ref={viewportRef}>
+        {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
+        {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
+        {load.status !== 'error' && (
+          <div
+            className={css.editorDocxWrap}
+            ref={wrapRef}
+            aria-label={title}
+            style={{ zoom: zoom / 100 }}
+          />
+        )}
+      </div>
+      <div className={css.editorDocxZoom}>
+        <span className={css.editorDocxZoomHint}>{t('zoomHint')}</span>
+        <input
+          className={css.editorDocxZoomRange}
+          type="range"
+          min={50}
+          max={200}
+          step={10}
+          value={zoom}
+          aria-label={t('zoom')}
+          onChange={(event) => { setZoom(Number(event.currentTarget.value)) }}
+        />
+        <span className={css.editorDocxZoomValue}>{zoom}%</span>
+      </div>
+    </div>
+  )
+}

package/src/client/editor-load.ts

@@ -0,0 +1,92 @@
+/**
+ * Pure editor-load planning: the decision logic the editor host needs to
+ * turn a matched file viewer + a host fs.read result into a render action.
+ * Kept dependency-free (no React, no fetch) so the strategy dispatch is
+ * unit-testable and the wire contract (head bytes, binary flag) is pinned.
+ *
+ * The host flow this module drives:
+ *   1. `matchFileViewer(path)` picks a viewer by extension/priority.
+ *   2. `planFirstMatch` dispatches its fetchStrategy.
+ *   3. An fsRead viewer fetches through the host; `planFsReadOutcome`
+ *      decides what to do with the result — including the head-based
+ *      re-match that lets a `detect` viewer claim a binary the extension
+ *      match could not see (the builtin NUL probe on `binary-download`).
+ */
+import type { FileViewerDescriptor } from './service.ts'
+
+/** One host fs.read result (mirror of the wire; `head` present when binary). */
+export interface FsReadOutcome {
+  binary: boolean
+  content: string
+  truncated: boolean
+  /** base64 of the first bytes (present on binary reads; sniffing material). */
+  head?: string
+}
+
+/** What the editor host should do next. */
+export type EditorLoadAction =
+  /** No renderer: show the download UI. */
+  | { kind: 'binary' }
+  /** Render `viewer`'s component with the carried payload. */
+  | { kind: 'render'; viewer: FileViewerDescriptor; content?: string; truncated?: boolean; mediaUrl?: string; customData?: unknown }
+  /** Fetch the file through the host (fsRead strategy). */
+  | { kind: 'fetchFsRead'; viewer: FileViewerDescriptor }
+  /** Call the viewer's load() and render with its return value. */
+  | { kind: 'customLoad'; viewer: FileViewerDescriptor }
+
+/** Decode the host's base64 head bytes into the sniffing buffer. */
+export function decodeHead(headBase64: string): Uint8Array {
+  const binary = atob(headBase64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+/**
+ * Dispatch one matched viewer's fetchStrategy. A missing viewer or a
+ * `binary-download` strategy both mean "no client-side renderer" → the
+ * download UI. `mediaUrlOf` builds the media URL for `mediaUrl`/`none`
+ * strategies (pure, but scope-bound — injected by the host).
+ */
+export function planFirstMatch(
+  viewer: FileViewerDescriptor | undefined,
+  mediaUrlOf: () => string,
+): EditorLoadAction {
+  if (viewer === undefined || viewer.fetchStrategy === 'binary-download') return { kind: 'binary' }
+  switch (viewer.fetchStrategy) {
+    case 'mediaUrl':
+    case 'none':
+      return { kind: 'render', viewer, mediaUrl: mediaUrlOf() }
+    case 'custom':
+      return { kind: 'customLoad', viewer }
+    case 'fsRead':
+      return { kind: 'fetchFsRead', viewer }
+  }
+}
+
+/**
+ * Decide what an fsRead result means for the editor.
+ * - Text: the first match stands (content is valid for any fsRead viewer).
+ * - Binary: the host head bytes enable a re-match — a `detect` viewer (e.g.
+ *   a plugin sniffing a binary format) may claim the file. `custom` viewers
+ *   load their own bytes; `mediaUrl`/`none` viewers render the media route;
+ *   an fsRead viewer or nothing cannot render binary → download UI.
+ */
+export function planFsReadOutcome(
+  viewer: FileViewerDescriptor,
+  result: FsReadOutcome,
+  rematch: (head: Uint8Array) => FileViewerDescriptor | undefined,
+  mediaUrlOf: () => string,
+): EditorLoadAction {
+  if (!result.binary) {
+    return { kind: 'render', viewer, content: result.content, truncated: result.truncated }
+  }
+  const claimed = result.head === undefined ? undefined : rematch(decodeHead(result.head))
+  if (claimed !== undefined && claimed.fetchStrategy === 'custom') {
+    return { kind: 'customLoad', viewer: claimed }
+  }
+  if (claimed !== undefined && (claimed.fetchStrategy === 'mediaUrl' || claimed.fetchStrategy === 'none')) {
+    return { kind: 'render', viewer: claimed, mediaUrl: mediaUrlOf() }
+  }
+  return { kind: 'binary' }
+}