@spunto/design-system 0.27.0 → 0.30.0

package/README.md

@@ -188,7 +188,7 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   provider is also the umbrella that mounts the tooltip delay group and the overlay
   portal container the dialogs/selects render into.
 
-## Domain components — `/workers`, `/devcontainer`, `/projects`
+## Domain components — `/workers`, `/devcontainer`, `/projects`, `/tasks`
 
 Everything above is domain-free: a `Button` knows nothing about Spunto. Components
 that **do** know a Spunto concept live behind their own entry point, so the root
@@ -201,6 +201,7 @@ import { Button, Card } from "@spunto/design-system"
 import { WorkerCard } from "@spunto/design-system/workers"                                  // domain
 import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
 import { ProjectForm, ProjectPanel } from "@spunto/design-system/projects"                   // domain
+import { TaskList, TaskCockpit, TaskEventStream } from "@spunto/design-system/tasks"         // domain
 import { Section, ProductHeader } from "@spunto/design-system/marketing"                     // not a domain — see below
 ```
 
@@ -292,6 +293,39 @@ hand-typed reference that degrades cleanly.
   `DevcontainerFeatureEntry` and `VscodeExtensionEntry` are all-optional, and an
   unknown registry degrades to a monogram instead of an invented author.
 
+### `@spunto/design-system/tasks`
+
+Delegated work — a task is a worker, a branch, an agent session and something to
+review. Every surface that shows one:
+
+- **`TaskList`** — one project's tasks grouped by state in the order a task travels
+  (queued → running → in review, then failed and done, folded), Accept/Drop on the row.
+- **`TaskConversationList`** (+ `TaskConversationPlaceholder`) — every conversation of
+  an organization as a messaging app's list: search, state chips whose counts ignore
+  the filter, grouped rows. Fully controlled. Sized by `pointer-coarse`, not width.
+- **`TaskCockpit`** / **`TaskCockpitMobile`** — one conversation, as a **layout**: top
+  bar + Accept/Drop, the Session/Diff switch, and where each slot goes. The panels are
+  slots filled with the package's own components (`session`/`diff` are render
+  functions receiving the switch to draw in their header). The phone one is its own
+  screen — a `visualViewport`-sized layer, details in a sheet, Drop at the bottom.
+- **`TaskEventStream`** — the agent session (RFC 0020): prose first, tool calls folded
+  into runs ("read 8 files · ran 3 commands"), the session-wide tool stack in a sheet,
+  virtualized (`@tanstack/react-virtual`), opened at its end, paging older history as
+  the reader scrolls up. **`TaskComposer`** under it says *why* it is closed when it is.
+- **`TaskDiffPanel`** — the branch's diff: summary as a prop, each file's patch through
+  `loadPatch` (a promise; the component owns per-file loading state), intra-line
+  highlighting, and a sentence for every reason it could not be read.
+- **`TaskDetails`** (`sidebar` | `sheet`) with **`TaskMachine`**, **`TaskBoot`**,
+  `TaskSessionUsage`, `TaskPullRequest`, `TaskCommandLog` — the facts about a task, in
+  one order, instead of two hand-kept copies.
+- **`NewTaskDialog`** — delegating: prompt, files, title, base branch, model.
+- Vocabulary and helpers: `TaskStateBadge`, `taskStateConfig`, `useElapsed`,
+  `AgentMarkdown`, `useAttachmentDraft`/`prepareFile`/`TaskFiles` (files, RFC 0022),
+  `runStats`/`toolVerb`/`toolSubject`, `bootSteps`, `indexTasksByWorker`.
+
+Same rules as `/workers`: nothing fetches, types are structural and lax
+(`TaskItem`, `TaskEvent`, `TaskDiff`…), links go through `render.link`.
+
 ### `@spunto/design-system/projects`
 
 - **`ProjectForm`** — the whole "compose a dev environment" screen: identity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.27.0",
+  "version": "0.30.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,10 @@
       "types": "./src/components/devcontainer/index.ts",
       "import": "./src/components/devcontainer/index.ts"
     },
+    "./tasks": {
+      "types": "./src/components/tasks/index.ts",
+      "import": "./src/components/tasks/index.ts"
+    },
     "./projects": {
       "types": "./src/components/projects/index.ts",
       "import": "./src/components/projects/index.ts"
@@ -70,6 +74,7 @@
     "brand:export": "node scripts/export-logo.ts"
   },
   "dependencies": {
+    "@tanstack/react-virtual": "^3.14.13",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-search": "^0.16.0",
     "@xterm/addon-web-links": "^0.12.0",

package/src/components/sheet.tsx

@@ -76,6 +76,8 @@ export interface SheetContentProps extends SheetPrimitive.Popup.Props {
   size?: SheetSize
   /** Draws the ✕ in the top corner. @default true */
   showClose?: boolean
+  /** Merged onto the backdrop — e.g. a `z-*` to match a raised `className` on the panel. */
+  backdropClassName?: string
 }
 
 /**
@@ -93,6 +95,7 @@ function SheetContent({
   side = "right",
   size = "md",
   showClose = true,
+  backdropClassName,
   ...props
 }: SheetContentProps) {
   const container = useOverlayContainer()
@@ -101,7 +104,10 @@ function SheetContent({
     <SheetPrimitive.Portal container={container ?? undefined}>
       <SheetPrimitive.Backdrop
         data-slot="sheet-backdrop"
-        className="fixed inset-0 z-50 bg-black/40 backdrop-blur-[2px] transition-opacity duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:bg-black/60"
+        className={cn(
+          "fixed inset-0 z-50 bg-black/40 backdrop-blur-[2px] transition-opacity duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:bg-black/60",
+          backdropClassName
+        )}
       />
       <SheetPrimitive.Popup
         data-slot="sheet-content"

package/src/components/tasks/agent-markdown.tsx

@@ -0,0 +1,322 @@
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/**
+ * Markdown, for what an agent actually writes.
+ *
+ * An agent's messages are markdown — headings, `**bold**`, bullet lists, fenced code — and
+ * rendering them as raw text turns a summary into `1. **Lecture** — \`README.md\` lu`, which is
+ * exactly what was on screen before this existed. It is not a stylistic detail: the message is
+ * the one thing on the page written *for* the reader.
+ *
+ * Hand-written rather than pulled from a library, for two reasons. The subset is small and
+ * bounded (this is CLI output, not user-authored documents), and everything here builds React
+ * nodes — there is no `dangerouslySetInnerHTML` anywhere, so a message that contains HTML is
+ * text, not markup. An MDX pipeline is built for files we wrote ourselves; running arbitrary
+ * agent output through one would be a different risk entirely.
+ *
+ * What it does not do, deliberately: nested lists, images, reference links, `_italic_`. Those
+ * degrade to their source text, which is readable — the failure mode is "less pretty", never
+ * "loses what the agent said".
+ */
+
+/**
+ * `code`, **bold**, *italic*, [text](url), bare https?:// URLs. Bare URLs matter as much as
+ * bracketed ones: a harness pastes a raw link ("PR opened at https://github.com/…") far more
+ * often than it writes markdown syntax for one.
+ *
+ * Emphasis and link text are re-scanned rather than emitted as text: an agent announcing a PR
+ * writes `**https://github.com/…/289**` — the URL it most wants you to click is exactly the one
+ * it emphasised, and a plain <strong> would have swallowed it. Recursion terminates because the
+ * inner text is always strictly shorter than the token it came from.
+ */
+const INLINE =
+  /(`[^`\n]+`|\*\*[^*\n]+\*\*|\*[^*\n]+\*|\[[^\]\n]+\]\([^)\s]+\)|https?:\/\/[^\s<>()\[\]]+)/g
+
+export function renderInlineMarkdown(text: string, keyPrefix: string): ReactNode[] {
+  return text.split(INLINE).map((token, i) => {
+    const key = `${keyPrefix}-${i}`
+    if (!token) return null
+    if (token.startsWith("`") && token.endsWith("`")) {
+      return (
+        <code key={key} className="rounded bg-muted px-1 py-0.5 font-mono text-[0.9em]">
+          {token.slice(1, -1)}
+        </code>
+      )
+    }
+    if (token.startsWith("**") && token.endsWith("**")) {
+      return (
+        <strong key={key} className="font-semibold">
+          {renderInlineMarkdown(token.slice(2, -2), key)}
+        </strong>
+      )
+    }
+    if (token.startsWith("*") && token.endsWith("*") && token.length > 2) {
+      return <em key={key}>{renderInlineMarkdown(token.slice(1, -1), key)}</em>
+    }
+    const link = /^\[([^\]]+)\]\(([^)\s]+)\)$/.exec(token)
+    if (link) {
+      const href = link[2]
+      // Only http(s): an agent can write any string, and a `javascript:` href would be a link
+      // the reader has no way to tell apart from a real one.
+      if (/^https?:\/\//i.test(href)) {
+        return (
+          <a key={key} href={href} target="_blank" rel="noreferrer" className="text-primary underline underline-offset-2">
+            {renderInlineMarkdown(link[1], key)}
+          </a>
+        )
+      }
+      return <span key={key}>{renderInlineMarkdown(link[1], key)}</span>
+    }
+    if (/^https?:\/\//i.test(token)) {
+      // Sentence punctuation trailing a bare URL ("… see https://x.dev/y.") is not part of the
+      // link — split it back out so the period doesn't 404.
+      const trailing = /[.,;:!?]+$/.exec(token)?.[0] ?? ""
+      const href = trailing ? token.slice(0, -trailing.length) : token
+      return (
+        <span key={key}>
+          <a href={href} target="_blank" rel="noreferrer" className="text-primary underline underline-offset-2 break-all">
+            {href}
+          </a>
+          {trailing}
+        </span>
+      )
+    }
+    return <span key={key}>{token}</span>
+  })
+}
+
+type Align = "left" | "center" | "right" | null
+
+/**
+ * Split a table row on its cell separators.
+ *
+ * GFM cuts a row on pipes *before* any inline parsing, so `\|` is the only way to put a literal
+ * pipe in a cell — which also means a pipe inside a code span still splits, there and here.
+ * The leading and trailing pipes are optional decoration, not empty cells.
+ */
+function splitRow(line: string): string[] {
+  const trimmed = line.trim()
+  const cells: string[] = []
+  let cell = ""
+  for (let i = 0; i < trimmed.length; i++) {
+    if (trimmed[i] === "\\" && trimmed[i + 1] === "|") {
+      cell += "|"
+      i++
+      continue
+    }
+    if (trimmed[i] === "|") {
+      cells.push(cell)
+      cell = ""
+      continue
+    }
+    cell += trimmed[i]
+  }
+  cells.push(cell)
+  if (cells.length > 1 && trimmed.startsWith("|")) cells.shift()
+  if (cells.length > 1 && /(^|[^\\])\|$/.test(trimmed)) cells.pop()
+  return cells.map((c) => c.trim())
+}
+
+/** `| --- | :---: |` → one alignment per column, or null if this isn't a delimiter row. */
+function delimiterRow(line: string | undefined): Align[] | null {
+  if (line === undefined || !line.includes("-")) return null
+  const cells = splitRow(line)
+  if (!cells.length) return null
+  const align: Align[] = []
+  for (const cell of cells) {
+    if (!/^:?-+:?$/.test(cell)) return null
+    const left = cell.startsWith(":")
+    const right = cell.endsWith(":")
+    align.push(left && right ? "center" : right ? "right" : left ? "left" : null)
+  }
+  return align
+}
+
+/**
+ * A table starts at a header row only if the very next line is a delimiter row with the same
+ * number of columns — the rule that keeps a prose line that happens to contain a pipe from
+ * being read as a one-row table.
+ */
+function tableAt(lines: string[], i: number): { align: Align[]; head: string[] } | null {
+  if (!/(^|[^\\])\|/.test(lines[i] ?? "")) return null
+  const align = delimiterRow(lines[i + 1])
+  if (!align) return null
+  const head = splitRow(lines[i])
+  return head.length === align.length ? { align, head } : null
+}
+
+type Block =
+  | { kind: "p"; lines: string[] }
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "list"; ordered: boolean; items: string[] }
+  | { kind: "code"; lang: string | null; lines: string[] }
+  | { kind: "quote"; lines: string[] }
+  | { kind: "table"; align: Align[]; head: string[]; rows: string[][] }
+
+/** Group lines into blocks. One pass, no lookahead beyond the current block. */
+function parse(source: string): Block[] {
+  const blocks: Block[] = []
+  const lines = source.replace(/\r\n/g, "\n").split("\n")
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    const fence = /^```(\w*)\s*$/.exec(line)
+    if (fence) {
+      const body: string[] = []
+      i++
+      while (i < lines.length && !/^```\s*$/.test(lines[i])) body.push(lines[i++])
+      i++ // closing fence, or the end of the message if the agent was cut off mid-block
+      blocks.push({ kind: "code", lang: fence[1] || null, lines: body })
+      continue
+    }
+
+    const table = tableAt(lines, i)
+    if (table) {
+      const rows: string[][] = []
+      i += 2
+      // A row is padded or clipped to the header's width: an agent writing a table by hand
+      // miscounts a cell far more often than it means to start a new block.
+      while (i < lines.length && lines[i].trim() !== "" && /(^|[^\\])\|/.test(lines[i])) {
+        const cells = splitRow(lines[i++])
+        rows.push(table.head.map((_, c) => cells[c] ?? ""))
+      }
+      blocks.push({ kind: "table", align: table.align, head: table.head, rows })
+      continue
+    }
+
+    const heading = /^(#{1,4})\s+(.*)$/.exec(line)
+    if (heading) {
+      blocks.push({ kind: "heading", level: heading[1].length, text: heading[2] })
+      i++
+      continue
+    }
+
+    if (/^\s*([-*+])\s+/.test(line) || /^\s*\d+[.)]\s+/.test(line)) {
+      const ordered = /^\s*\d+[.)]\s+/.test(line)
+      const items: string[] = []
+      while (i < lines.length && (ordered ? /^\s*\d+[.)]\s+/ : /^\s*([-*+])\s+/).test(lines[i])) {
+        items.push(lines[i].replace(ordered ? /^\s*\d+[.)]\s+/ : /^\s*([-*+])\s+/, ""))
+        i++
+      }
+      blocks.push({ kind: "list", ordered, items })
+      continue
+    }
+
+    if (/^>\s?/.test(line)) {
+      const body: string[] = []
+      while (i < lines.length && /^>\s?/.test(lines[i])) body.push(lines[i++].replace(/^>\s?/, ""))
+      blocks.push({ kind: "quote", lines: body })
+      continue
+    }
+
+    if (line.trim() === "") {
+      i++
+      continue
+    }
+
+    const body: string[] = []
+    while (
+      i < lines.length &&
+      lines[i].trim() !== "" &&
+      !/^```/.test(lines[i]) &&
+      !/^#{1,4}\s/.test(lines[i]) &&
+      !/^\s*([-*+])\s+/.test(lines[i]) &&
+      !/^\s*\d+[.)]\s+/.test(lines[i]) &&
+      !/^>\s?/.test(lines[i]) &&
+      !tableAt(lines, i)
+    ) {
+      body.push(lines[i++])
+    }
+    blocks.push({ kind: "p", lines: body })
+  }
+
+  return blocks
+}
+
+const ALIGN_CLASS = { left: "text-left", center: "text-center", right: "text-right" } as const
+
+const HEADING_CLASS = ["text-base font-semibold", "text-sm font-semibold", "text-sm font-medium", "text-sm font-medium"]
+
+export function AgentMarkdown({ text, className }: { text: string; className?: string }) {
+  const blocks = parse(text)
+  return (
+    <div className={cn("space-y-2 text-sm leading-6 [&>*:first-child]:mt-0", className)}>
+      {blocks.map((block, i) => {
+        switch (block.kind) {
+          case "heading":
+            return (
+              <p key={i} className={cn("mt-3", HEADING_CLASS[block.level - 1])}>
+                {renderInlineMarkdown(block.text, `h${i}`)}
+              </p>
+            )
+          case "code":
+            return (
+              <pre
+                key={i}
+                className="overflow-x-auto rounded-md border bg-muted/60 px-3 py-2 font-mono text-[12px] leading-relaxed"
+              >
+                <code>{block.lines.join("\n")}</code>
+              </pre>
+            )
+          case "list": {
+            const Tag = block.ordered ? "ol" : "ul"
+            return (
+              <Tag key={i} className={cn("space-y-1 pl-5", block.ordered ? "list-decimal" : "list-disc")}>
+                {block.items.map((item, j) => (
+                  <li key={j} className="marker:text-muted-foreground">{renderInlineMarkdown(item, `l${i}-${j}`)}</li>
+                ))}
+              </Tag>
+            )
+          }
+          case "table":
+            // Scrollable rather than wrapped: a comparison table is read across a row, and a
+            // column squeezed to two characters of width loses the comparison entirely.
+            return (
+              <div key={i} className="overflow-x-auto rounded-md border">
+                <table className="w-full border-collapse text-[13px]">
+                  <thead className="bg-muted/50">
+                    <tr>
+                      {block.head.map((cell, c) => (
+                        <th
+                          key={c}
+                          className={cn(
+                            "whitespace-nowrap px-2.5 py-1.5 font-medium",
+                            ALIGN_CLASS[block.align[c] ?? "left"],
+                          )}
+                        >
+                          {renderInlineMarkdown(cell, `th${i}-${c}`)}
+                        </th>
+                      ))}
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {block.rows.map((row, r) => (
+                      <tr key={r} className="border-t">
+                        {row.map((cell, c) => (
+                          <td key={c} className={cn("px-2.5 py-1.5 align-top", ALIGN_CLASS[block.align[c] ?? "left"])}>
+                            {renderInlineMarkdown(cell, `td${i}-${r}-${c}`)}
+                          </td>
+                        ))}
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )
+          case "quote":
+            return (
+              <blockquote key={i} className="border-l-2 border-border pl-3 text-muted-foreground">
+                {renderInlineMarkdown(block.lines.join(" "), `q${i}`)}
+              </blockquote>
+            )
+          default:
+            return <p key={i}>{renderInlineMarkdown(block.lines.join("\n"), `p${i}`)}</p>
+        }
+      })}
+    </div>
+  )
+}

package/src/components/tasks/attachments.ts

@@ -0,0 +1,152 @@
+import type { DraftFile } from "./types"
+
+/**
+ * Preparing a file for a turn, in the browser.
+ *
+ * Almost everything passes through untouched — a PDF is a PDF, a CSV is a CSV. The one thing that
+ * gets work done to it is an **image**, and for a specific reason: a model downscales anything
+ * past 1568 px on its longest edge before it looks at it, so sending a 4K screenshot spends
+ * bandwidth, database and (on the way through the worker) a second of file writing to deliver
+ * pixels that are thrown away. A pasted retina screenshot routinely goes from 3 MB to under
+ * 200 KB this way, and the model sees exactly the same thing.
+ *
+ * A small image is left alone: re-encoding a crisp PNG of a terminal into a lossy format to save
+ * nothing is how screenshots of text become unreadable.
+ *
+ * The result travels as base64 in the JSON body of the turn, next to the words — one request, so
+ * a half-sent message is not a state anyone has to think about.
+ */
+
+export const MAX_FILES_PER_TURN = 10
+
+/** Matches the API's own ceiling — a refusal after the upload is a worse refusal. */
+export const MAX_FILE_BYTES = 10 * 1024 * 1024
+
+/** And in total, so ten files at the ceiling is not a 100 MB request. */
+export const MAX_TURN_BYTES = 25 * 1024 * 1024
+
+/** The four the API will hand back with their own content type, so the four that get a thumbnail. */
+export const PREVIEWABLE_MEDIA_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"]
+
+/** What a model downscales to anyway. Past this, pixels cost and buy nothing. */
+const MAX_EDGE = 1568
+
+/** Under this, an image is already cheap and keeps its original encoding, untouched. */
+const KEEP_AS_IS_BYTES = 400 * 1024
+
+
+export function isPreviewable(mediaType: string): boolean {
+  return PREVIEWABLE_MEDIA_TYPES.includes(mediaType)
+}
+
+/** Every file in a paste or a drop — a clipboard carries its payload as a file among others. */
+export function filesFrom(list: FileList | File[] | DataTransferItemList | null): File[] {
+  if (!list) return []
+  const files: File[] = []
+  for (const entry of Array.from(list as ArrayLike<File | DataTransferItem>)) {
+    const file = entry instanceof File ? entry : entry.kind === "file" ? entry.getAsFile() : null
+    if (file) files.push(file)
+  }
+  return files
+}
+
+/**
+ * One file, ready to send. `null` when it cannot be used — past the ceiling even after shrinking,
+ * or bytes the browser could not read at all.
+ *
+ * A file with no media type (which happens: an extensionless file, or one the OS has no opinion
+ * about) is sent as `application/octet-stream` rather than refused. The platform stores bytes; it
+ * is not in a position to be fussy about what someone calls them.
+ */
+export async function prepareFile(file: File): Promise<DraftFile | null> {
+  const shrunk = await shrink(file)
+  const usable = shrunk ?? file
+  if (usable.size === 0 || usable.size > MAX_FILE_BYTES) return null
+  const data = await toBase64(usable)
+  if (data === null) return null
+  const mediaType = usable.type || "application/octet-stream"
+  return {
+    key: `${file.name}-${file.lastModified}-${Math.random().toString(36).slice(2, 8)}`,
+    // A pasted screenshot has no name of its own; the browser calls it `image.png` and that will
+    // do — it is what the agent will see the file called.
+    name: file.name || (isPreviewable(mediaType) ? "image.png" : "file"),
+    mediaType,
+    data,
+    bytes: usable.size,
+    previewUrl: isPreviewable(mediaType) ? URL.createObjectURL(usable) : null,
+  }
+}
+
+/**
+ * Re-encode, but only when it actually buys something — and only for an image.
+ *
+ * A GIF is left alone whatever its size: it may be animated, and a canvas would silently keep the
+ * first frame — a quiet loss is worse than a large file. Anything the browser cannot decode comes
+ * back as `null` and the original is sent as it is; the API is the one that says no.
+ */
+async function shrink(file: File): Promise<File | null> {
+  if (!isPreviewable(file.type) || file.type === "image/gif") return null
+  if (file.size <= KEEP_AS_IS_BYTES) return null
+  if (typeof createImageBitmap !== "function") return null
+
+  let bitmap: ImageBitmap
+  try {
+    bitmap = await createImageBitmap(file)
+  } catch {
+    return null
+  }
+  const scale = Math.min(1, MAX_EDGE / Math.max(bitmap.width, bitmap.height))
+  const width = Math.max(1, Math.round(bitmap.width * scale))
+  const height = Math.max(1, Math.round(bitmap.height * scale))
+
+  const canvas = document.createElement("canvas")
+  canvas.width = width
+  canvas.height = height
+  const ctx = canvas.getContext("2d")
+  if (!ctx) {
+    bitmap.close()
+    return null
+  }
+  ctx.drawImage(bitmap, 0, 0, width, height)
+  bitmap.close()
+
+  // WebP for both: it beats PNG on a screenshot at a quality no reader can tell apart, and beats
+  // JPEG on the flat colour and hard edges a screenshot is mostly made of.
+  const blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/webp", 0.9))
+  if (!blob || blob.size >= file.size) return null
+  return new File([blob], `${file.name || "image"}.webp`, { type: "image/webp" })
+}
+
+function toBase64(file: Blob): Promise<string | null> {
+  return new Promise((resolve) => {
+    const reader = new FileReader()
+    reader.onerror = () => resolve(null)
+    reader.onload = () => {
+      const result = typeof reader.result === "string" ? reader.result : ""
+      const comma = result.indexOf(",")
+      resolve(comma === -1 ? null : result.slice(comma + 1))
+    }
+    reader.readAsDataURL(file)
+  })
+}
+
+/** Human-readable size — small enough to sit under a thumbnail or next to a file name. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * The short, upper-case tag shown on a non-image file's tile — `PDF`, `CSV`, `ZST`.
+ *
+ * From the name rather than the media type, because that is what the reader themselves would say
+ * the file is, and because a media type is frequently `application/octet-stream` for exactly the
+ * files whose extension is most informative.
+ */
+export function fileKind(name: string, mediaType: string): string {
+  const ext = /\.([A-Za-z0-9]{1,8})$/.exec(name)?.[1]
+  if (ext) return ext.toUpperCase()
+  const subtype = mediaType.split("/")[1]?.replace(/^x-|\+.*$/g, "")
+  return (subtype ?? "file").slice(0, 5).toUpperCase()
+}