@vibefield/rosetta-room 0.0.0-stage → 0.1.0

package/dist/components/file-viewer/syntax/tokenize.js

@@ -0,0 +1,289 @@
+// One tokenizer, many languages. Everything a language differs by lives in
+// its `Grammar` table; this file is the single pass that reads one.
+//
+// It is a lexer and nothing more: it never looks further than the next
+// character, so it can be wrong about anything that needs a parser to know
+// (a regex literal that looks like division, a generic that looks like a
+// comparison). It is wrong quietly — the worst case is a span in the wrong
+// colour, never a span that disappears.
+//
+// Every pattern here is sticky (`y`) and matched against the whole text at an
+// offset. The obvious spelling — `pattern.exec(text.slice(index))` — copies
+// the rest of the file once per token, which is quadratic and turns a 2 MB
+// source file into a frozen window.
+/** `1_000`, `0xFF`, `1.5e-9`, `42u32` — with the suffix the systems
+ * languages hang off the end. */
+const NUMBER = /(?:0[xX][0-9a-fA-F_]+|0[bB][01_]+|0[oO][0-7_]+|(?:\d[\d_]*(?:\.\d[\d_]*)?|\.\d[\d_]*)(?:[eE][+-]?\d+)?)(?:[a-zA-Z_][a-zA-Z0-9_]*)?/y;
+const IDENTIFIER = /[A-Za-z_$][A-Za-z0-9_$]*/y;
+const WHITESPACE = /[ \t\r\n]+/y;
+/** Structure the eye is meant to skip over. */
+const OPERATOR_CHARS = new Set("+-*/%=<>!&|^~?:;,.()[]{}@#\\");
+class Cursor {
+    index = 0;
+    /** The last token that was not pure whitespace, which is the only context a
+     * one-character lookbehind ever needs. */
+    lastKind = null;
+    lastText = "";
+    out = [];
+    /** Text emitted as `plain` but not yet flushed, so a run of plain
+     * characters lands as one token instead of one token per character. */
+    pending = "";
+    text;
+    // Spelled out rather than as a parameter property: the latter is TypeScript
+    // that EMITS code, so a plain `node --strip-types` probe of this module
+    // refuses the file. The tokenizer is worth being able to run that way.
+    constructor(text) {
+        this.text = text;
+    }
+    get done() {
+        return this.index >= this.text.length;
+    }
+    peek(offset = 0) {
+        return this.text[this.index + offset] ?? "";
+    }
+    /** Does the source read `literal` right here? */
+    looking(literal) {
+        return literal.length > 0 && this.text.startsWith(literal, this.index);
+    }
+    /** Match a STICKY pattern at the cursor. */
+    match(pattern) {
+        pattern.lastIndex = this.index;
+        const found = pattern.exec(this.text);
+        return found === null ? null : found[0];
+    }
+    /** The next character that is not a space or a tab, without moving. */
+    peekNonSpace(from) {
+        let i = from;
+        while (i < this.text.length && (this.text[i] === " " || this.text[i] === "\t"))
+            i += 1;
+        return this.text[i] ?? "";
+    }
+    /** Emit `text` as `kind` and advance past it. */
+    take(kind, text) {
+        if (text.length === 0)
+            return;
+        const significant = text.trim();
+        if (significant !== "") {
+            this.lastKind = kind;
+            this.lastText = significant;
+        }
+        if (kind === "plain") {
+            this.pending += text;
+        }
+        else {
+            this.flush();
+            this.out.push({ kind, text });
+        }
+        this.index += text.length;
+    }
+    /** Retag the last token, for the lookahead a lexer can only do afterwards
+     * (a JSON key is a string until the `:` proves otherwise). */
+    retagLast(kind) {
+        const last = this.out[this.out.length - 1];
+        if (last !== undefined && this.pending === "") {
+            this.out[this.out.length - 1] = { kind, text: last.text };
+        }
+    }
+    /** Consume through `closer`, or to the end of the text if it never closes —
+     * an unterminated comment is a fact about the file, not a crash. */
+    consumeUntil(opener, closer, escape) {
+        const from = this.index + opener.length;
+        if (escape === undefined) {
+            const end = this.text.indexOf(closer, from);
+            return end === -1 ? this.text.slice(this.index) : this.text.slice(this.index, end + closer.length);
+        }
+        let i = from;
+        while (i < this.text.length) {
+            if (this.text.startsWith(escape, i)) {
+                i += escape.length + 1;
+                continue;
+            }
+            if (this.text.startsWith(closer, i)) {
+                return this.text.slice(this.index, i + closer.length);
+            }
+            i += 1;
+        }
+        return this.text.slice(this.index);
+    }
+    finish() {
+        this.flush();
+        return this.out;
+    }
+    flush() {
+        if (this.pending === "")
+            return;
+        this.out.push({ kind: "plain", text: this.pending });
+        this.pending = "";
+    }
+}
+function classifyIdentifier(word, grammar, next) {
+    if (grammar.keywords?.has(word))
+        return "keyword";
+    if (grammar.constants?.has(word))
+        return "constant";
+    if (grammar.types?.has(word))
+        return "type";
+    // A capital outranks the call position: `new Uint8Array(...)`,
+    // `String::from(...)` and `<Button …>` are types being used, and painting
+    // them as functions teaches the reader that the two are the same thing.
+    // `HTML` and `X` are shouted constants or one letter, and a rule without
+    // the lowercase test paints most of a C header amber.
+    if (grammar.capitalIsType === true && /^[A-Z]/.test(word) && /[a-z]/.test(word))
+        return "type";
+    if (next === "(")
+        return "function";
+    if (grammar.propertyBeforeColon === true && next === ":")
+        return "property";
+    return "plain";
+}
+/** `'a` is a lifetime and `'a'` is a character, and only the character after
+ * the identifier tells them apart. */
+function readsAsLifetime(cursor) {
+    if (!/[A-Za-z_]/.test(cursor.peek(1)))
+        return false;
+    let offset = 1;
+    while (/[A-Za-z0-9_]/.test(cursor.peek(offset)))
+        offset += 1;
+    return cursor.peek(offset) !== "'";
+}
+const LIFETIME = /'[A-Za-z0-9_]+/y;
+/** A literal, with character classes read as units so a `/` inside `[^/]`
+ * does not end it, and the flags taken along. */
+const REGEX_LITERAL = /\/(?![*/])(?:\[(?:[^\]\\\n]|\\.)*\]|[^/\\\n[]|\\.)+\/[dgimsuvy]*/y;
+/** Keywords a regex may follow. After anything else that is a VALUE — an
+ * identifier, a number, a closing bracket — the slash is division. */
+const REGEX_KEYWORDS = new Set([
+    "return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "case",
+    "do", "else", "yield", "await", "throw",
+]);
+/**
+ * Is the `/` at the cursor opening a literal, or dividing?
+ *
+ * No lexer can always be right about this — `a++ /b/ g` is legal division —
+ * but the previous significant token answers it for every line anyone
+ * actually writes, and being wrong costs a span its colour and nothing else.
+ */
+function startsRegex(cursor) {
+    if (cursor.lastKind === null)
+        return true;
+    if (cursor.lastKind === "operator")
+        return cursor.lastText !== ")" && cursor.lastText !== "]";
+    if (cursor.lastKind === "keyword")
+        return REGEX_KEYWORDS.has(cursor.lastText);
+    return false;
+}
+/** Sigil-led variable patterns, built once per grammar rather than once per
+ * character — the same quadratic trap the sticky patterns avoid. */
+const sigilPatterns = new WeakMap();
+function sigilsOf(grammar) {
+    const cached = sigilPatterns.get(grammar);
+    if (cached !== undefined)
+        return cached;
+    const built = (grammar.variableSigils ?? []).map((sigil) => [sigil, new RegExp(`${sigil.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[A-Za-z_{][A-Za-z0-9_}]*`, "y")]);
+    sigilPatterns.set(grammar, built);
+    return built;
+}
+export function tokenize(text, grammar) {
+    const cursor = new Cursor(text);
+    const sigils = sigilsOf(grammar);
+    while (!cursor.done) {
+        const char = cursor.peek();
+        // Whitespace, in one run. Newlines included — lines are cut afterwards,
+        // so a block comment stays one token across all of them.
+        if (char === " " || char === "\t" || char === "\n" || char === "\r") {
+            cursor.take("plain", cursor.match(WHITESPACE) ?? char);
+            continue;
+        }
+        const block = grammar.blockComments?.find(([open]) => cursor.looking(open));
+        if (block !== undefined) {
+            cursor.take("comment", cursor.consumeUntil(block[0], block[1]));
+            continue;
+        }
+        const lineComment = grammar.lineComments?.find((open) => cursor.looking(open));
+        if (lineComment !== undefined) {
+            const end = text.indexOf("\n", cursor.index);
+            cursor.take("comment", text.slice(cursor.index, end === -1 ? text.length : end));
+            continue;
+        }
+        if (grammar.annotation !== undefined) {
+            const annotation = cursor.match(grammar.annotation);
+            if (annotation !== null && annotation.length > 0) {
+                cursor.take("type", annotation);
+                continue;
+            }
+        }
+        if (char === "'" && grammar.lifetimeQuote === true && readsAsLifetime(cursor)) {
+            cursor.take("type", cursor.match(LIFETIME) ?? "'");
+            continue;
+        }
+        if (char === "/" && grammar.regexLiterals === true && startsRegex(cursor)) {
+            const literal = cursor.match(REGEX_LITERAL);
+            if (literal !== null) {
+                // A literal is text quoted from another language, which is what a
+                // string is; it takes the same accent for the same reason.
+                cursor.take("string", literal);
+                continue;
+            }
+        }
+        const string = grammar.strings?.find((rule) => cursor.looking(rule.open));
+        if (string !== undefined) {
+            const raw = cursor.consumeUntil(string.open, string.close ?? string.open, string.escape);
+            // A single-line literal that ran past a newline never closed: stop at
+            // the line, so one stray quote does not paint the rest of the file.
+            const newline = string.multiline === true ? -1 : raw.indexOf("\n");
+            cursor.take("string", newline === -1 ? raw : raw.slice(0, newline));
+            if (grammar.propertyBeforeColon === true && cursor.peekNonSpace(cursor.index) === ":") {
+                cursor.retagLast("property");
+            }
+            continue;
+        }
+        const sigil = sigils.find(([lead]) => cursor.looking(lead));
+        if (sigil !== undefined) {
+            const variable = cursor.match(sigil[1]);
+            if (variable !== null) {
+                cursor.take("constant", variable);
+                continue;
+            }
+        }
+        if (/[0-9]/.test(char) || (char === "." && /[0-9]/.test(cursor.peek(1)))) {
+            const number = cursor.match(NUMBER);
+            if (number !== null) {
+                cursor.take("number", number);
+                continue;
+            }
+        }
+        const word = cursor.match(IDENTIFIER);
+        if (word !== null) {
+            const next = cursor.peekNonSpace(cursor.index + word.length);
+            cursor.take(classifyIdentifier(word, grammar, next), word);
+            continue;
+        }
+        cursor.take(OPERATOR_CHARS.has(char) ? "operator" : "plain", char);
+    }
+    return cursor.finish();
+}
+/**
+ * Cut a token stream into lines. Tokens that span newlines — block comments,
+ * template literals, docstrings — are split, and each piece keeps its kind,
+ * which is the whole reason tokenizing runs over the file rather than over
+ * each line in turn.
+ */
+export function splitLines(tokens) {
+    const lines = [[]];
+    for (const token of tokens) {
+        if (!token.text.includes("\n")) {
+            if (token.text.length > 0)
+                lines[lines.length - 1].push(token);
+            continue;
+        }
+        const pieces = token.text.split("\n");
+        for (const [index, piece] of pieces.entries()) {
+            if (index > 0)
+                lines.push([]);
+            const trimmed = piece.endsWith("\r") ? piece.slice(0, -1) : piece;
+            if (trimmed.length > 0)
+                lines[lines.length - 1].push({ kind: token.kind, text: trimmed });
+        }
+    }
+    return lines;
+}

package/dist/components/file-viewer/syntax/types.d.ts

@@ -0,0 +1,74 @@
+export type TokenKind = 
+/** `// like this` — the quietest step of the ramp, never a hue. */
+"comment"
+/** A literal run of text: quoted, templated, or heredoc'd. */
+ | "string"
+/** A numeric literal. Shares its accent with `constant`: both are values. */
+ | "number"
+/** `fn`, `const`, `impl`, `async` — the language's own words. */
+ | "keyword"
+/** A named type. Also markup's attribute names, which play the same part. */
+ | "type"
+/** A name in call position. */
+ | "function"
+/** `true`, `null`, `None`, `self` — a value the language names for you. */
+ | "constant"
+/** An object key, a config key, a markup attribute. */
+ | "property"
+/** A markup element name. Shares its accent with `keyword`. */
+ | "tag"
+/** Brackets, commas, arrows — structure the eye skips. */
+ | "operator"
+/** Everything else: identifiers, prose, whitespace. */
+ | "plain";
+export interface Token {
+    readonly kind: TokenKind;
+    readonly text: string;
+}
+/** One source line's worth of tokens. Never contains a newline. */
+export type TokenLine = readonly Token[];
+/** How one flavour of string literal opens, closes and escapes. */
+export interface StringRule {
+    readonly open: string;
+    /** Defaults to `open`. */
+    readonly close?: string;
+    /** May a newline appear inside it? */
+    readonly multiline?: boolean;
+    /** The escape character, if the literal has one. */
+    readonly escape?: string;
+}
+/**
+ * One language's shape, as data. The tokenizer is one function; a language is
+ * a table — which is what makes adding one a five-line change rather than a
+ * new code path.
+ */
+export interface Grammar {
+    readonly lineComments?: readonly string[];
+    readonly blockComments?: readonly (readonly [string, string])[];
+    /** Tried in order, so `"""` must be listed before `"`. */
+    readonly strings?: readonly StringRule[];
+    readonly keywords?: ReadonlySet<string>;
+    /** Values the language names: `true`, `nil`, `self`. */
+    readonly constants?: ReadonlySet<string>;
+    /** Types the language ships with: `u32`, `String`, `boolean`. */
+    readonly types?: ReadonlySet<string>;
+    /** Whether an identifier that starts with a capital reads as a type. */
+    readonly capitalIsType?: boolean;
+    /** `#[derive]`, `@override`, `#pragma` — a sigil-led annotation. */
+    readonly annotation?: RegExp;
+    /** An identifier before `:` is a key. True for JSON and object literals. */
+    readonly propertyBeforeColon?: boolean;
+    /**
+     * `'a` is a lifetime, `'a'` is a character. Rust needs this told to it;
+     * every other language with `'` strings does not.
+     */
+    readonly lifetimeQuote?: boolean;
+    /** Sigil-led variables — shell's `$PATH`, Ruby's `@ivar`. */
+    readonly variableSigils?: readonly string[];
+    /**
+     * `/` opens a literal as well as dividing. Only the JS family has the
+     * ambiguity, and only what came BEFORE the slash can settle it — see
+     * `startsRegex`.
+     */
+    readonly regexLiterals?: boolean;
+}

package/dist/components/file-viewer/syntax/types.js

@@ -0,0 +1,13 @@
+// What a highlighter is allowed to say about a piece of code.
+//
+// The kind set is CLOSED, and deliberately small. DESIGN.md §2.6 gives the
+// room eight curated accents for closed sets — "these group and label; they
+// never signal state" — and a token kind is exactly that: a label on a span
+// of someone else's document. Six of the eight are spent here; red and pink
+// are left alone, because red means failure everywhere else in this room and
+// a reader must not learn a second meaning for it.
+//
+// This is a HIGHLIGHTER, not a parser. It knows a string from a comment from
+// a keyword. It does not resolve types, scopes or imports, and nothing built
+// on it may claim it does.
+export {};

package/dist/components/file-viewer/types.d.ts

@@ -0,0 +1,111 @@
+import type { ComponentType, ReactNode } from "react";
+import type { Language } from "./syntax/index.js";
+/** A file the viewer has been asked to show. */
+export interface FileHandle {
+    /** Stable identity for this open — remounts the body and cancels the last
+     * read when it changes. */
+    readonly key: string;
+    readonly name: string;
+    /** Absolute path, when the caller can derive one. `null` costs the reader
+     * the path line and path-only acts; it never costs them the
+     * file, because reading goes through the source, not the path. */
+    readonly path: string | null;
+    /** Known byte length; a negative value means the source has not supplied
+     * a size yet. Reads also check their actual length before rendering. */
+    readonly size: number;
+    /**
+     * Whatever the source needs to find the file again — an entry id, a
+     * handle, a URL. OPAQUE here on purpose: the only code allowed to read it
+     * is the source that wrote it, which is what keeps the viewer free of any
+     * knowledge of where files come from.
+     */
+    readonly ref?: unknown;
+}
+/** Where bytes come from. A caller can be a mille engine, a fixture, or a
+ * test. */
+export interface FileSource {
+    read(handle: FileHandle, signal: AbortSignal): Promise<Uint8Array>;
+    /** Sized, browser-cacheable resources. The source owns address validation;
+     * a viewer never needs to copy full-image bytes to show a small thumbnail. */
+    image?: ((handle: FileHandle) => ImageResource | null) | undefined;
+    /**
+     * A unified diff of this handle, for a view whose payload is `"compare"`.
+     *
+     * Optional, because most sources have one version of a file and nothing to
+     * compare it to. A source that omits it must never resolve a kind that
+     * asks for one — the registry decides that from the name, and a diff is
+     * only ever asked for by a caller that built the handle.
+     */
+    compare?(handle: FileHandle, signal: AbortSignal): Promise<{
+        readonly unified: string;
+    }>;
+}
+/** The sized renditions a source may address. */
+export type ImageRendition = "full" | "preview" | "rail" | "tile" | "tile2x";
+/** An image address: now, once the source has it, or not at all. */
+export type ImageUrl = string | null | PromiseLike<string | null>;
+/** Sized, browser-loadable renditions of one image, asked for one at a time:
+ * a source that must fetch before it can address an image fetches only the
+ * rendition a view shows. */
+export interface ImageResource {
+    /** Stable for this image: the same key asks for the same bytes. */
+    readonly key: string;
+    url(rendition: ImageRendition): ImageUrl;
+    readonly width?: number | undefined;
+    readonly height?: number | undefined;
+}
+/** A view's own switch, rendered as the room's one switch shape. */
+export interface ViewMode {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * An act the dialog can offer for a file. Named rather than supplied as a
+ * closure: a view is a data table, and the side effects live in the one place
+ * that is allowed to have them.
+ */
+export type ViewerActionId = "copy-path" | "open-in-browser";
+export interface ViewerDefinition {
+    readonly id: string;
+    /** How the content must arrive. `"text"` also gets `OpenFile.text`
+     * decoded; `"compare"` asks the source for a unified diff instead of
+     * bytes, and the file's own size limit does not apply — git bounds its
+     * own output, and a one-line change to a huge file is a small diff. */
+    readonly payload: "text" | "bytes" | "compare";
+    /** The most this view will read. Over it, the dialog says so and reads
+     * nothing — a limit the reader is told is a fact; a hang is not. */
+    readonly maxBytes: number;
+    readonly modes?: readonly ViewMode[];
+    readonly actions?: readonly ViewerActionId[];
+    readonly Body: ComponentType<ViewBodyProps>;
+}
+/** What the registry decided a file is. */
+export interface FileKind {
+    readonly viewer: ViewerDefinition;
+    /** The chip beside the name: "TypeScript", "Markdown", "PNG". */
+    readonly label: string;
+    /** Set when the body highlights source. */
+    readonly language: Language | null;
+    /** Set when the body needs a blob: `image/png`, `image/svg+xml`. */
+    readonly mime: string | null;
+}
+/** A file that has been read. */
+export interface OpenFile {
+    readonly handle: FileHandle;
+    readonly kind: FileKind;
+    readonly bytes: Uint8Array;
+    /** Decoded UTF-8, or `null` for a view whose payload is `"bytes"`. */
+    readonly text: string | null;
+    /** The unified diff, for a `"compare"` view. */
+    readonly unified: string | null;
+    readonly image?: ImageResource;
+    readonly imageAttempt?: number;
+}
+export interface ViewBodyProps {
+    readonly onRetry?: (() => void) | undefined;
+    /** Optional rich Markdown presentation supplied by the content owner. */
+    readonly renderMarkdown?: ((text: string) => ReactNode) | undefined;
+    readonly file: OpenFile;
+    /** The current mode's id, or `""` for a view with no modes. */
+    readonly mode: string;
+}

package/dist/components/file-viewer/types.js

@@ -0,0 +1,8 @@
+// The file viewer's contract, and the whole reason it is a peer of the
+// worktree column rather than a part of it: nothing here knows what a mille
+// engine is, what a project is, or where the bytes came from. Hand it a name,
+// a size and something that can produce bytes, and it shows the file.
+//
+// That seam is what lets the same dialog serve a search result, a session's
+// footprint or a dropped path later without being rewritten.
+export {};

package/dist/components/file-viewer/use-file-content.d.ts

@@ -0,0 +1,26 @@
+import type { FileHandle, FileSource, OpenFile } from "./types.js";
+export type FileContent = {
+    readonly status: "reading";
+} | {
+    readonly status: "empty";
+} | {
+    readonly status: "too-large";
+    readonly limit: number;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+} | {
+    readonly status: "ready";
+    readonly file: OpenFile;
+};
+/**
+ * Read `handle` through `source`.
+ *
+ * `source` must be stable across renders — it identifies the engine the read
+ * goes to, and a fresh object every render would re-read the file on every
+ * render. The worktree column memoizes one per engine.
+ */
+export declare function useFileContent(handle: FileHandle | null, source: FileSource, 
+/** Set when the caller is opening a CHANGE rather than a file — the one
+ * decision the registry cannot make from a name. */
+asDiff?: boolean, attempt?: number, asImage?: boolean): FileContent;

package/dist/components/file-viewer/use-file-content.js

@@ -0,0 +1,144 @@
+// Reading one file, and every honest thing that can happen instead.
+//
+// Two of the five states are answered WITHOUT reading anything, from the size
+// the tree already knows: an empty file, and a file past the view's limit.
+// That ordering is the point — a viewer that discovers a 400 MB file by
+// loading it has already done the damage by the time it can report it.
+import { useEffect, useState } from "react";
+import { BINARY_KIND, diffKind, imageKind, looksBinary, resolveKind } from "./registry.js";
+const READING = { status: "reading" };
+/** What a failed read can be told about itself. mille raises a
+ * `FileSystemError` carrying a POSIX code, which is the most useful half. */
+function describe(error) {
+    if (error === null || typeof error !== "object")
+        return "the read failed";
+    const { code, message } = error;
+    if (typeof code === "string" && code !== "") {
+        return typeof message === "string" && message !== "" ? `${code} · ${message}` : code;
+    }
+    return typeof message === "string" && message !== "" ? message : "the read failed";
+}
+function decode(bytes) {
+    const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+    // A byte-order mark is an encoding artefact, not the file's first
+    // character, and left in place it shows up as a blank glyph on line one.
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * Read `handle` through `source`.
+ *
+ * `source` must be stable across renders — it identifies the engine the read
+ * goes to, and a fresh object every render would re-read the file on every
+ * render. The worktree column memoizes one per engine.
+ */
+export function useFileContent(handle, source, 
+/** Set when the caller is opening a CHANGE rather than a file — the one
+ * decision the registry cannot make from a name. */
+asDiff = false, attempt = 0, asImage = false) {
+    const [state, setState] = useState({
+        handleKey: null,
+        source: null,
+        asDiff: false,
+        asImage: false,
+        value: READING,
+    });
+    useEffect(() => {
+        if (handle === null) {
+            setState({ handleKey: null, source, asDiff, asImage, value: READING });
+            return;
+        }
+        const publish = (value) => {
+            setState({ handleKey: handle.key, source, asDiff, asImage, value });
+        };
+        const kind = asDiff ? diffKind(handle.name) : asImage ? imageKind(handle.name) : resolveKind(handle.name);
+        if (!asDiff && (asImage || kind.viewer.id === "image")) {
+            try {
+                const image = source.image?.(handle);
+                if (image) {
+                    publish({ status: "ready", file: { handle, kind: imageKind("Image"),
+                            bytes: new Uint8Array(0), text: null, unified: null, image, imageAttempt: attempt } });
+                    return;
+                }
+            }
+            catch (error) {
+                publish({ status: "failed", reason: describe(error) });
+                return;
+            }
+        }
+        if (kind.viewer.payload === "compare") {
+            if (source.compare === undefined) {
+                publish({ status: "failed", reason: "this source has nothing to compare against" });
+                return;
+            }
+            publish(READING);
+            const comparing = new AbortController();
+            void source
+                .compare(handle, comparing.signal)
+                .then(({ unified }) => {
+                if (comparing.signal.aborted)
+                    return;
+                publish({
+                    status: "ready",
+                    file: { handle, kind, bytes: new Uint8Array(0), text: null, unified },
+                });
+            })
+                .catch((error) => {
+                if (comparing.signal.aborted)
+                    return;
+                publish({ status: "failed", reason: describe(error) });
+            });
+            return () => comparing.abort();
+        }
+        if (handle.size === 0) {
+            publish({ status: "empty" });
+            return;
+        }
+        if (handle.size > kind.viewer.maxBytes) {
+            publish({ status: "too-large", limit: kind.viewer.maxBytes });
+            return;
+        }
+        publish(READING);
+        const controller = new AbortController();
+        void (async () => {
+            try {
+                const bytes = await source.read(handle, controller.signal);
+                if (controller.signal.aborted)
+                    return;
+                // The name said text and the bytes disagree. The bytes win: this is
+                // the one place a file's kind is decided by what is in it, and it can
+                // only ever downgrade — a hex dump claims less, never more.
+                const binary = kind.viewer.payload === "text" && looksBinary(bytes);
+                const resolved = asImage ? imageKind(handle.name, bytes) : binary ? BINARY_KIND : kind;
+                if (bytes.byteLength > resolved.viewer.maxBytes) {
+                    publish({ status: "too-large", limit: resolved.viewer.maxBytes });
+                    return;
+                }
+                publish({
+                    status: "ready",
+                    file: {
+                        handle,
+                        kind: resolved,
+                        bytes,
+                        text: resolved.viewer.payload === "text" ? decode(bytes) : null,
+                        unified: null,
+                    },
+                });
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                publish({ status: "failed", reason: describe(error) });
+            }
+        })();
+        return () => controller.abort();
+    }, [handle, source, asDiff, attempt, asImage]);
+    // Effects change after render. Without an identity check, the first frame
+    // after switching files carries the previous file's state — harmlessly
+    // visible before, but unacceptable once an action can export those bytes.
+    return state.handleKey === (handle?.key ?? null) &&
+        state.source === source &&
+        state.asImage === asImage &&
+        state.asDiff === asDiff
+        ? state.value
+        : READING;
+}

package/dist/components/file-viewer/views/BinaryView.d.ts

@@ -0,0 +1,2 @@
+import type { ViewBodyProps } from "../types.js";
+export declare function BinaryView({ file }: ViewBodyProps): import("react").JSX.Element;