@medicine-wheel/app 0.24.0 → 0.25.0

package/app/api/episodes/[id]/files/[...path]/route.ts

@@ -0,0 +1,66 @@
+import { NextResponse } from "next/server";
+import { fileResponse } from "@medicine-wheel/episode-vessel/http";
+import { ANONYMOUS_CAPABILITIES } from "@medicine-wheel/episode-vessel/permissions";
+import { episodeFolderOf, openEpisodeGate } from "@/lib/episode-files";
+
+/**
+ * One file of an episode's room, by kind, read-only.
+ *
+ *   GET /api/episodes/<chronicle:folder>/files/<file>
+ *
+ * This is the address `@medicine-wheel/episode-ui` reads a file from: text as
+ * JSON with its revision, an image inline, media whole or by byte range, a
+ * document as an attachment. The serving is `@medicine-wheel/episode-vessel/http`'s,
+ * the same door Miadi's room uses. The wheel only decides who is asking: a
+ * visitor, because it has no sign-in, so `ceremonies/` and `captures/` stay
+ * outside the room and an episode for the community stays closed.
+ *
+ * There is no PUT. The wheel reads an episode; Miadi writes it.
+ * Ref jgwill/medicine-wheel#166.
+ */
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+const STATUS_OF_STATE: Record<string, number> = {
+  "no-root": 503,
+  absent: 404,
+  community: 403,
+};
+
+function answer(body: Record<string, unknown>, status: number) {
+  return NextResponse.json(body, { status, headers: { "cache-control": "no-store" } });
+}
+
+function decoded(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string; path: string[] }> },
+) {
+  const { id: rawId, path: segments } = await params;
+  const id = decoded(rawId);
+  const folder = episodeFolderOf(id);
+  if (!folder) {
+    return answer(
+      { state: "not-an-episode", error: `Not an episode id: ${id}. Expected chronicle:<episode folder>.` },
+      400,
+    );
+  }
+
+  const gate = openEpisodeGate(folder);
+  if (gate.state !== "open") return answer(gate, STATUS_OF_STATE[gate.state] ?? 400);
+
+  const file = (segments ?? []).map(decoded).join("/");
+  return fileResponse(request, folder, file, {
+    root: gate.root,
+    capabilities: ANONYMOUS_CAPABILITIES,
+    mayReadOutsideRoom: false,
+  });
+}

package/app/api/episodes/[id]/files/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { EpisodePathError } from "@miadi/episode-vessel";
+import { EpisodePathError } from "@medicine-wheel/episode-vessel";
 import { episodeFolderOf, openEpisodeRoom, readEpisodeRoomText } from "@/lib/episode-files";
 
 /**
@@ -7,9 +7,10 @@ import { episodeFolderOf, openEpisodeRoom, readEpisodeRoomText } from "@/lib/epi
  *
  *   GET /api/episodes/<chronicle:folder>/files              the room's listing
  *   GET /api/episodes/<chronicle:folder>/files?path=<file>  one text file, whole
+ *   GET /api/episodes/<chronicle:folder>/files/<file>       one file, by kind (`[...path]/route.ts`)
  *
  * The rules — containment, the room, the audience — are `lib/episode-files.ts`
- * and, beneath it, `@miadi/episode-vessel`. This file only says them in HTTP.
+ * and, beneath it, `@medicine-wheel/episode-vessel`. This file only says them in HTTP.
  * Every answer carries a `state`, so a page can tell "this host has no
  * chronicle" from "this episode is not on this host" from "this episode is for
  * the community" — three empty lists that mean three different things.

package/app/episodes/[id]/page.tsx

@@ -6,7 +6,7 @@
  *
  * What this is, from the node itself, with the episodes before and after it in
  * the chronicle. What it holds, from its folder — read-only, through the rules
- * `@miadi/episode-vessel` states for every surface that opens one (see
+ * `@medicine-wheel/episode-vessel` states for every surface that opens one (see
  * `components/episode-files-panel.tsx`). What was said and gathered for it —
  * ceremonies, diary, inquiry weaves, plan perspectives, captures — from routes
  * that filtered by episode long before any page asked them

package/components/episode-files-panel.tsx

@@ -1,47 +1,64 @@
 "use client";
 
 /**
- * An episode's folder on the episode page — listed, and any text file read in
- * place. Read-only: the wheel reads an episode, Miadi writes it.
+ * An episode's folder on the episode page, drawn by `@medicine-wheel/episode-ui`:
+ * the files workspace Miadi's room and gmtermux mount too, here read-only. Its
+ * folders, markdown preview, source view, images and media come from the
+ * package; this file only knows the wheel's routes and its palette. The wheel
+ * reads an episode; Miadi writes it.
  *
- * Files are listed in the folders their paths name, every one open to begin
- * with, so a reader can tell which folder a file is in.
+ * The open file is the page's address (`?file=<path>&mode=preview|source`), so
+ * a reload or a shared link lands on the same file, and Back returns to the one
+ * opened before.
  *
- * Text is shown as text. Markdown is not rendered here: rendering it means a
- * renderer and a sanitizer between an episode's files and this page, and plain
- * text is already readable. Media and documents are listed, not played.
- *
- * @see app/api/episodes/[id]/files/route.ts — and the rules it states
+ * @see app/api/episodes/[id]/files/route.ts — the listing, and why a room is closed
+ * @see app/api/episodes/[id]/files/[...path]/route.ts — one file, by kind
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { EpisodeFileTree } from "@/components/episode-file-tree";
-import { buildFileTree, folderPaths } from "@/lib/episode-file-tree";
-
-type EpisodeFile = {
-  relativePath: string;
-  name: string;
-  kind: "text" | "document" | "media";
-  size: number;
-  modifiedAt: string;
-  previewable: boolean;
-  guidance: boolean;
-};
+import { useEffect, useMemo, useState } from "react";
+import {
+  EpisodeFiles,
+  httpEpisodeFiles,
+  useEpisodeFilesAddress,
+  type EpisodeCapabilitiesView,
+  type EpisodeFileView,
+  type EpisodeUITheme,
+} from "@medicine-wheel/episode-ui";
+import "@medicine-wheel/episode-ui/styles.css";
 
 type Room =
-  | { state: "open"; episode_path: string; files: EpisodeFile[] }
+  | { state: "open"; episode_path: string; files: EpisodeFileView[] }
   | { state: "no-root" }
   | { state: "absent"; episode_path: string }
   | { state: "community"; episode_path: string }
   | { state: "not-an-episode" | "refused" | "error"; error?: string };
 
-type Opened = { path: string; content?: string; error?: string };
+/** A visitor's capabilities: the wheel has no sign-in, so it browses and reads. */
+const READ_ONLY: EpisodeCapabilitiesView = {
+  browse: true,
+  read: true,
+  edit: false,
+  upload: false,
+  attachCapture: false,
+  writeCeremonyNote: false,
+  attachToCeremony: false,
+};
 
-function formatSize(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
-}
+/** The wheel's tokens (`src/ui-components/src/tokens.css`), so the workspace reads as part of the page. */
+const THEME: EpisodeUITheme = {
+  background: "var(--mw-bg)",
+  card: "var(--mw-card)",
+  text: "var(--mw-fg)",
+  textDim: "var(--mw-muted)",
+  muted: "var(--mw-muted)",
+  accent: "var(--mw-primary)",
+  border: "var(--mw-border)",
+  success: "#5ac37d",
+  warning: "#e0a458",
+  mono: "var(--font-mono)",
+};
+
+const encodePath = (relativePath: string) => relativePath.split("/").map(encodeURIComponent).join("/");
 
 /** Why a folder is not shown, in words a reader can act on. */
 function closedReason(room: Room): string | null {
@@ -62,18 +79,12 @@ function closedReason(room: Room): string | null {
 export function EpisodeFilesPanel({ episodeId }: { episodeId: string }) {
   const base = `/api/episodes/${encodeURIComponent(episodeId)}/files`;
   const [room, setRoom] = useState<Room | null>(null);
-  const [opened, setOpened] = useState<Opened | null>(null);
-  // The path last asked for, so a slow answer for an earlier click cannot
-  // replace the file the reader opened after it.
-  const wanted = useRef<string | null>(null);
-  // Folders the reader closed. The tree opens fully; only a closed folder is remembered.
-  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set());
+  const address = useEpisodeFilesAddress();
 
   useEffect(() => {
     let live = true;
     setRoom(null);
-    setOpened(null);
-    fetch(base)
+    fetch(base, { cache: "no-store" })
       .then((res) => res.json())
       .then((body: Room) => live && setRoom(body))
       .catch((e) => live && setRoom({ state: "error", error: e instanceof Error ? e.message : String(e) }));
@@ -82,120 +93,25 @@ export function EpisodeFilesPanel({ episodeId }: { episodeId: string }) {
     };
   }, [base]);
 
-  const toggle = useCallback(
-    async (file: EpisodeFile) => {
-      if (wanted.current === file.relativePath) {
-        wanted.current = null;
-        setOpened(null);
-        return;
-      }
-      wanted.current = file.relativePath;
-      setOpened({ path: file.relativePath });
-      let next: Opened;
-      try {
-        const res = await fetch(`${base}?path=${encodeURIComponent(file.relativePath)}`);
-        const body = await res.json();
-        next = res.ok
-          ? { path: file.relativePath, content: body.content }
-          : { path: file.relativePath, error: body.error ?? body.state ?? `HTTP ${res.status}` };
-      } catch (e) {
-        next = { path: file.relativePath, error: e instanceof Error ? e.message : String(e) };
-      }
-      if (wanted.current === file.relativePath) setOpened(next);
-    },
+  // `save` exists because the service type asks for it; with `edit: false` the
+  // workspace never offers it, and the route has no PUT to answer it.
+  const service = useMemo(
+    () => httpEpisodeFiles({ fileUrl: (file) => `${base}/${encodePath(file.relativePath)}` }),
     [base],
   );
 
-  const files = useMemo(() => (room?.state === "open" ? room.files : []), [room]);
-  const tree = useMemo(() => buildFileTree(files), [files]);
-  const folders = useMemo(() => folderPaths(tree), [tree]);
-  const allClosed = folders.length > 0 && folders.every((path) => collapsed.has(path));
-
-  const toggleFolder = useCallback(
-    (path: string) =>
-      setCollapsed((current) => {
-        const next = new Set(current);
-        if (!next.delete(path)) next.add(path);
-        return next;
-      }),
-    [],
-  );
+  if (room === null) return <p className="text-sm text-muted-foreground">Opening the folder…</p>;
+  if (room.state !== "open") return <p className="text-sm text-muted-foreground">{closedReason(room)}</p>;
 
   return (
-    <section>
-      <div className="flex items-baseline justify-between gap-3 mb-2">
-        <h2 className="text-sm font-semibold">
-          Files {files.length > 0 && `(${files.length})`}
-        </h2>
-        {folders.length > 0 && (
-          <button
-            type="button"
-            onClick={() => setCollapsed(allClosed ? new Set() : new Set(folders))}
-            className="text-xs text-muted-foreground hover:underline"
-          >
-            {allClosed ? "Expand all" : "Collapse all"}
-          </button>
-        )}
-      </div>
-
-      {room === null ? (
-        <p className="text-sm text-muted-foreground">Opening the folder…</p>
-      ) : room.state !== "open" ? (
-        <p className="text-sm text-muted-foreground">{closedReason(room)}</p>
-      ) : files.length === 0 ? (
-        <p className="text-sm text-muted-foreground">The folder holds nothing the room shows.</p>
-      ) : (
-        <EpisodeFileTree
-          tree={tree}
-          collapsed={collapsed}
-          onToggleFolder={toggleFolder}
-          renderFile={(file, name) => {
-            const isOpen = opened?.path === file.relativePath;
-            return (
-              <>
-                <div className="p-2 border rounded-lg bg-card flex items-baseline justify-between gap-3 flex-wrap">
-                  {file.previewable ? (
-                    <button
-                      onClick={() => toggle(file)}
-                      title={file.relativePath}
-                      className="text-sm font-mono text-left break-all hover:underline"
-                      aria-expanded={isOpen}
-                    >
-                      {isOpen ? "▾" : "▸"} {name}
-                    </button>
-                  ) : (
-                    <span
-                      title={file.relativePath}
-                      className="text-sm font-mono break-all text-muted-foreground"
-                    >
-                      {name}
-                    </span>
-                  )}
-                  <span className="text-xs text-muted-foreground shrink-0 flex gap-2 items-baseline">
-                    {file.guidance && <span className="mw-badge">guidance</span>}
-                    {!file.previewable && <span className="mw-badge">{file.kind}</span>}
-                    <span>{formatSize(file.size)}</span>
-                    <span>{file.modifiedAt.slice(0, 10)}</span>
-                  </span>
-                </div>
-                {isOpen && (
-                  <div className="mt-1 p-3 border rounded-lg bg-card">
-                    {opened?.error ? (
-                      <p className="text-sm text-muted-foreground">{opened.error}</p>
-                    ) : opened?.content === undefined ? (
-                      <p className="text-sm text-muted-foreground">Reading…</p>
-                    ) : (
-                      <pre className="text-xs font-mono whitespace-pre-wrap break-words max-h-[70vh] overflow-auto">
-                        {opened.content}
-                      </pre>
-                    )}
-                  </div>
-                )}
-              </>
-            );
-          }}
-        />
-      )}
-    </section>
+    <EpisodeFiles
+      {...address}
+      files={room.files}
+      capabilities={READ_ONLY}
+      service={service}
+      theme={THEME}
+      title="Files"
+      emptyLabel="The folder holds nothing the room shows."
+    />
   );
 }

package/dist/cli/mw.js

@@ -80,8 +80,15 @@ function resolveMcpPath() {
     const fromModules = path.join(packageRoot, 'node_modules', '@medicine-wheel', 'mcp', 'dist', 'index.js');
     if (fs.existsSync(fromModules))
         return fromModules;
+    // The package itself, not a file inside it. @medicine-wheel/mcp has an
+    // `exports` map whose "." is ./dist/index.js (the server) and which does not
+    // export "./dist/index.js", so resolving that subpath throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED. A global install of app and mcp side by side
+    // (`npm i -g @medicine-wheel/app @medicine-wheel/mcp`) therefore found no
+    // server, and every installed `mw chart` said "MCP server path not found"
+    // until 0.24.1. Found by RELEASING.md step 7 on 0.24.0.
     try {
-        return require.resolve('@medicine-wheel/mcp/dist/index.js', {
+        return require.resolve('@medicine-wheel/mcp', {
             paths: [packageRoot, process.cwd()],
         });
     }

package/lib/episode-files.ts

@@ -8,10 +8,12 @@
  * Episodes tab could show an episode's name and nothing it contains.
  *
  * The rules for what an episode folder holds and what may be read from it are
- * not written here. They live in `@miadi/episode-vessel`, published from
- * jgwill/Miadi and used by every other surface that opens a vessel — the Miadi
- * room and its file routes, the terminal browser, the phone. A second copy of
- * them here is how two surfaces come to disagree about what is private.
+ * not written here. They live in `@medicine-wheel/episode-vessel`, published
+ * from this repo's `src/episode-vessel`, and every other surface that opens a
+ * vessel takes them from there: the Miadi room through `@miadi/episode-vessel`,
+ * which re-exports it, the terminal browser, the phone. A second copy of them
+ * here is how two surfaces come to disagree about what is private
+ * (jgwill/medicine-wheel#166).
  *
  * Two of those rules decide what the wheel shows. Both are applied as for a
  * visitor, because the wheel has no signed-in reader:
@@ -38,7 +40,7 @@ import {
   resolveEpisodeFile,
   type EpisodeFile,
   type FileRevision,
-} from "@miadi/episode-vessel";
+} from "@medicine-wheel/episode-vessel";
 
 export type { EpisodeFile };
 
@@ -116,6 +118,19 @@ function gate(folder: string, root: string | null): EpisodeRoomClosed | null {
   return null;
 }
 
+/**
+ * Whether one episode's room opens on this host, and from which chronicle root.
+ * The gate a listing and a read pass through, for a route that hands the read
+ * itself to `@medicine-wheel/episode-vessel/http`.
+ */
+export function openEpisodeGate(
+  folder: string,
+  options: EpisodeRootOptions = {},
+): { state: "open"; root: string } | EpisodeRoomClosed {
+  const root = rootOf(options);
+  return gate(folder, root) ?? { state: "open", root: root! };
+}
+
 /** The files of one episode's room: everything the vessel lists except what is outside the room. */
 export function openEpisodeRoom(folder: string, options: EpisodeRootOptions = {}): EpisodeRoom {
   const root = rootOf(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -27,6 +27,8 @@
   "//workspaces": "TOPOLOGICAL ORDER — do not alphabetize. `npm run <script> --workspaces` executes in THIS array's order, not in dependency order: a package listed before a package it imports builds first and fails TS2307 on any tree without a stale dist/. Roots first (ontology-core, creative-orientation, session-reader), then their dependents, mcp last. A new package goes after everything it imports.",
   "workspaces": [
     "src/ontology-core",
+    "src/episode-vessel",
+    "src/episode-ui",
     "src/infra",
     "src/capabilities",
     "src/developer-repository-mapping",
@@ -94,34 +96,35 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.24.0",
-    "@medicine-wheel/ceremony-protocol": "^0.24.0",
-    "@medicine-wheel/community-identity": "^0.24.0",
-    "@medicine-wheel/community-review": "^0.24.0",
-    "@medicine-wheel/consent-lifecycle": "^0.24.0",
-    "@medicine-wheel/creative-orientation": "^0.24.0",
-    "@medicine-wheel/data-store": "^0.24.0",
-    "@medicine-wheel/data-store-postgres": "^0.24.0",
-    "@medicine-wheel/events": "^0.24.0",
-    "@medicine-wheel/fire-keeper": "^0.24.0",
-    "@medicine-wheel/github-ceremony": "^0.24.0",
-    "@medicine-wheel/graph-viz": "^0.24.0",
-    "@medicine-wheel/honcho": "^0.24.0",
-    "@medicine-wheel/importance-unit": "^0.24.0",
-    "@medicine-wheel/mcp": "^4.24.0",
-    "@medicine-wheel/memory": "^0.24.0",
-    "@medicine-wheel/narrative-cluster": "^0.24.0",
-    "@medicine-wheel/narrative-engine": "^0.24.0",
-    "@medicine-wheel/ontology-core": "^0.24.0",
-    "@medicine-wheel/perception-layer": "^0.24.0",
-    "@medicine-wheel/prompt-decomposition": "^0.24.0",
-    "@medicine-wheel/relational-index": "^0.24.0",
-    "@medicine-wheel/relational-query": "^0.24.0",
-    "@medicine-wheel/session-reader": "^0.24.0",
-    "@medicine-wheel/storage-provider": "^0.24.0",
-    "@medicine-wheel/transformation-tracker": "^0.24.0",
-    "@medicine-wheel/ui-components": "^0.24.0",
-    "@miadi/episode-vessel": "^0.2.1",
+    "@medicine-wheel/ceremonial-diary": "^0.25.0",
+    "@medicine-wheel/ceremony-protocol": "^0.25.0",
+    "@medicine-wheel/community-identity": "^0.25.0",
+    "@medicine-wheel/community-review": "^0.25.0",
+    "@medicine-wheel/consent-lifecycle": "^0.25.0",
+    "@medicine-wheel/creative-orientation": "^0.25.0",
+    "@medicine-wheel/data-store": "^0.25.0",
+    "@medicine-wheel/data-store-postgres": "^0.25.0",
+    "@medicine-wheel/episode-ui": "^0.25.0",
+    "@medicine-wheel/episode-vessel": "^0.25.0",
+    "@medicine-wheel/events": "^0.25.0",
+    "@medicine-wheel/fire-keeper": "^0.25.0",
+    "@medicine-wheel/github-ceremony": "^0.25.0",
+    "@medicine-wheel/graph-viz": "^0.25.0",
+    "@medicine-wheel/honcho": "^0.25.0",
+    "@medicine-wheel/importance-unit": "^0.25.0",
+    "@medicine-wheel/mcp": "^4.25.0",
+    "@medicine-wheel/memory": "^0.25.0",
+    "@medicine-wheel/narrative-cluster": "^0.25.0",
+    "@medicine-wheel/narrative-engine": "^0.25.0",
+    "@medicine-wheel/ontology-core": "^0.25.0",
+    "@medicine-wheel/perception-layer": "^0.25.0",
+    "@medicine-wheel/prompt-decomposition": "^0.25.0",
+    "@medicine-wheel/relational-index": "^0.25.0",
+    "@medicine-wheel/relational-query": "^0.25.0",
+    "@medicine-wheel/session-reader": "^0.25.0",
+    "@medicine-wheel/storage-provider": "^0.25.0",
+    "@medicine-wheel/transformation-tracker": "^0.25.0",
+    "@medicine-wheel/ui-components": "^0.25.0",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",

package/components/episode-file-tree.tsx

@@ -1,67 +0,0 @@
-/**
- * The folders of an episode, drawn — every one open to begin with, so a file's
- * folder is plain to see. Presentational: the panel owns which folders are
- * closed and how a file's own row looks.
- *
- * @see lib/episode-file-tree.ts — how the paths are grouped and in what order
- */
-
-import type { ReactNode } from "react";
-import type { FileTreeFolder, TreeableFile } from "@/lib/episode-file-tree";
-
-export interface EpisodeFileTreeProps<T extends TreeableFile> {
-  tree: FileTreeFolder<T>;
-  /** Paths of the folders the reader closed. Any folder not here is open. */
-  collapsed: ReadonlySet<string>;
-  onToggleFolder: (path: string) => void;
-  /** One file's row, and whatever opens beneath it. `name` is the path's last segment. */
-  renderFile: (file: T, name: string) => ReactNode;
-}
-
-export function EpisodeFileTree<T extends TreeableFile>({
-  tree,
-  collapsed,
-  onToggleFolder,
-  renderFile,
-}: EpisodeFileTreeProps<T>) {
-  return (
-    <ul className="space-y-1">
-      {tree.children.map((node) => {
-        if (node.type === "file") {
-          return <li key={node.path}>{renderFile(node.file, node.name)}</li>;
-        }
-        const isOpen = !collapsed.has(node.path);
-        return (
-          <li key={node.path} data-folder={node.path}>
-            <button
-              type="button"
-              onClick={() => onToggleFolder(node.path)}
-              aria-expanded={isOpen}
-              title={node.path}
-              className="w-full p-2 flex items-baseline gap-2 text-left text-sm font-semibold hover:underline"
-            >
-              <span aria-hidden="true" className="text-muted-foreground w-[1ch]">
-                {isOpen ? "▾" : "▸"}
-              </span>
-              <span aria-hidden="true">{isOpen ? "📂" : "📁"}</span>
-              <span className="font-mono break-all">{node.name}</span>
-              <span className="ml-auto text-xs font-normal text-muted-foreground shrink-0">
-                {node.fileCount} {node.fileCount === 1 ? "file" : "files"}
-              </span>
-            </button>
-            {isOpen && (
-              <div className="ml-4 pl-2 border-l">
-                <EpisodeFileTree
-                  tree={node}
-                  collapsed={collapsed}
-                  onToggleFolder={onToggleFolder}
-                  renderFile={renderFile}
-                />
-              </div>
-            )}
-          </li>
-        );
-      })}
-    </ul>
-  );
-}

package/lib/episode-file-tree.ts

@@ -1,135 +0,0 @@
-/**
- * An episode's files, grouped into the folders their paths name.
- *
- * `listEpisodeFiles` returns files with the path each sits at, and no folders,
- * so the Files section printed whole paths one under another and a reader could
- * not tell which folder a file was in. This builds the folders back from the
- * paths, so the panel can draw them.
- *
- * This is layout, not a rule about what an episode shows — those live in
- * `@miadi/episode-vessel` and in `lib/episode-files.ts`, and nothing here
- * decides what may be listed or read. The same grouping is drawn in Miadi's room
- * by `@miadi/episode-ui` (`buildFileTree`); the wheel keeps its own small copy
- * until it takes that package, and the two are meant to agree on order:
- *
- *  1. a `README.md`;
- *  2. the folders, by name;
- *  3. the files — text, documents, guidance, then media — by name.
- *
- * Names compare numerically, so `chapter-2` comes before `chapter-10`.
- */
-
-/** The part of a listed file the grouping reads. Any richer shape passes through untouched. */
-export interface TreeableFile {
-  relativePath: string;
-  name: string;
-  kind: string;
-  guidance: boolean;
-}
-
-export interface FileTreeFile<T extends TreeableFile> {
-  type: "file";
-  /** The last segment of the path. */
-  name: string;
-  path: string;
-  file: T;
-}
-
-export interface FileTreeFolder<T extends TreeableFile> {
-  type: "folder";
-  /** The last segment of the path. Empty for the root. */
-  name: string;
-  /** The path from the episode root. Empty for the root. */
-  path: string;
-  children: FileTreeNode<T>[];
-  /** Every file beneath this folder, at any depth. */
-  fileCount: number;
-}
-
-export type FileTreeNode<T extends TreeableFile> = FileTreeFile<T> | FileTreeFolder<T>;
-
-const compareNames = (left: string, right: string): number =>
-  left.localeCompare(right, undefined, { numeric: true, sensitivity: "base" }) ||
-  (left < right ? -1 : left > right ? 1 : 0);
-
-function rank(file: TreeableFile): number {
-  if (/^README\.md$/i.test(file.name)) return 0;
-  if (file.guidance) return 3;
-  if (file.kind === "text") return 1;
-  if (file.kind === "document") return 2;
-  return 4;
-}
-
-function order<T extends TreeableFile>(folder: FileTreeFolder<T>): void {
-  const folders = folder.children.filter((n): n is FileTreeFolder<T> => n.type === "folder");
-  const files = folder.children.filter((n): n is FileTreeFile<T> => n.type === "file");
-  folders.sort((a, b) => compareNames(a.name, b.name));
-  files.sort((a, b) => rank(a.file) - rank(b.file) || compareNames(a.name, b.name));
-  folder.children = [
-    ...files.filter((n) => rank(n.file) === 0),
-    ...folders,
-    ...files.filter((n) => rank(n.file) !== 0),
-  ];
-  folders.forEach(order);
-}
-
-/**
- * Group `files` into folders by path. A path listed twice is kept once, and a
- * folder exists only because a file is beneath it.
- */
-export function buildFileTree<T extends TreeableFile>(files: readonly T[]): FileTreeFolder<T> {
-  const root: FileTreeFolder<T> = { type: "folder", name: "", path: "", children: [], fileCount: 0 };
-  const folders = new Map<string, FileTreeFolder<T>>([["", root]]);
-  const seen = new Set<string>();
-
-  const folderAt = (path: string): FileTreeFolder<T> => {
-    const known = folders.get(path);
-    if (known) return known;
-    const cut = path.lastIndexOf("/");
-    const parent = folderAt(cut === -1 ? "" : path.slice(0, cut));
-    const created: FileTreeFolder<T> = {
-      type: "folder",
-      name: cut === -1 ? path : path.slice(cut + 1),
-      path,
-      children: [],
-      fileCount: 0,
-    };
-    folders.set(path, created);
-    parent.children.push(created);
-    return created;
-  };
-
-  for (const file of files) {
-    if (seen.has(file.relativePath)) continue;
-    seen.add(file.relativePath);
-    const cut = file.relativePath.lastIndexOf("/");
-    const parent = folderAt(cut === -1 ? "" : file.relativePath.slice(0, cut));
-    parent.children.push({
-      type: "file",
-      name: cut === -1 ? file.relativePath : file.relativePath.slice(cut + 1),
-      path: file.relativePath,
-      file,
-    });
-    for (let path = parent.path; ; path = path.slice(0, Math.max(path.lastIndexOf("/"), 0))) {
-      folders.get(path)!.fileCount += 1;
-      if (!path) break;
-    }
-  }
-
-  order(root);
-  return root;
-}
-
-/** Every folder path in the tree, outermost first. The root is not one. */
-export function folderPaths<T extends TreeableFile>(tree: FileTreeFolder<T>): string[] {
-  const paths: string[] = [];
-  const walk = (folder: FileTreeFolder<T>) => {
-    for (const child of folder.children) {
-      if (child.type !== "folder") continue;
-      paths.push(child.path);
-      walk(child);
-    }
-  };
-  walk(tree);
-  return paths;
-}