@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/editor-targets.js

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { createExternalProcessEnv } from "./paseo-env.js";
+import { findExecutable } from "../executable-resolution/executable-resolution.js";
+import { spawnProcess } from "../utils/spawn.js";
+const EDITOR_TARGETS = [
+    { id: "cursor", label: "Cursor", command: "cursor" },
+    { id: "vscode", label: "VS Code", command: "code" },
+    { id: "webstorm", label: "WebStorm", command: "webstorm" },
+    { id: "zed", label: "Zed", command: "zed" },
+    { id: "finder", label: "Finder", command: "open", platforms: ["darwin"] },
+    { id: "explorer", label: "Explorer", command: "explorer", platforms: ["win32"] },
+    {
+        id: "file-manager",
+        label: "File Manager",
+        command: "xdg-open",
+        excludedPlatforms: ["darwin", "win32"],
+    },
+];
+function isAbsolutePath(value) {
+    return posix.isAbsolute(value) || win32.isAbsolute(value);
+}
+function isTargetSupportedOnPlatform(target, platform) {
+    if (target.platforms && !target.platforms.includes(platform)) {
+        return false;
+    }
+    if (target.excludedPlatforms?.includes(platform)) {
+        return false;
+    }
+    return true;
+}
+function resolveEditorTargetDefinition(editorId) {
+    const target = EDITOR_TARGETS.find((entry) => entry.id === editorId);
+    if (!target) {
+        throw new Error(`Unknown editor target: ${editorId}`);
+    }
+    return target;
+}
+export async function listAvailableEditorTargets(dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const findExecutableFn = dependencies.findExecutable ?? findExecutable;
+    const supportedTargets = EDITOR_TARGETS.filter((target) => isTargetSupportedOnPlatform(target, platform));
+    const executables = await Promise.all(supportedTargets.map((target) => findExecutableFn(target.command)));
+    const results = [];
+    for (let i = 0; i < supportedTargets.length; i += 1) {
+        if (!executables[i])
+            continue;
+        const target = supportedTargets[i];
+        results.push({
+            id: target.id,
+            label: target.label,
+        });
+    }
+    return results;
+}
+async function resolveEditorLaunch(input) {
+    const target = resolveEditorTargetDefinition(input.editorId);
+    if (!isTargetSupportedOnPlatform(target, input.platform)) {
+        throw new Error(`Editor target unavailable: ${target.label}`);
+    }
+    const executable = await input.findExecutableFn(target.command);
+    if (!executable) {
+        throw new Error(`Editor target unavailable: ${target.label}`);
+    }
+    return {
+        command: executable,
+        args: [input.path],
+    };
+}
+export async function openInEditorTarget(input, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const pathToOpen = input.path.trim();
+    const existsSyncFn = dependencies.existsSync ?? existsSync;
+    const findExecutableFn = dependencies.findExecutable ?? findExecutable;
+    const spawnFn = dependencies.spawn ?? spawnProcess;
+    if (!pathToOpen || !isAbsolutePath(pathToOpen)) {
+        throw new Error("Editor target path must be an absolute local path");
+    }
+    if (!existsSyncFn(pathToOpen)) {
+        throw new Error(`Path does not exist: ${pathToOpen}`);
+    }
+    const launch = await resolveEditorLaunch({
+        editorId: input.editorId,
+        path: pathToOpen,
+        platform,
+        findExecutableFn,
+    });
+    await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnFn(launch.command, launch.args, {
+                detached: true,
+                env: createExternalProcessEnv(process.env),
+                shell: platform === "win32",
+                stdio: "ignore",
+            });
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=editor-targets.js.map

package/dist/server/server/ensure-workspace-for-create.d.ts

@@ -0,0 +1,30 @@
+import type { FirstAgentContext } from "@hyperdrive.bot/fleet-protocol/messages";
+import type { PersistedWorkspaceRecord } from "./workspace-registry.js";
+export interface EnsureWorkspaceForCreateDeps {
+    /** Every known workspace record, archived ones included. */
+    listWorkspaces: () => Promise<PersistedWorkspaceRecord[]>;
+    /** Mints a brand new local-checkout workspace for `cwd`. */
+    createWorkspace: (input: {
+        cwd: string;
+        title: string | null;
+    }) => Promise<PersistedWorkspaceRecord>;
+    /** Queues "name this workspace from its first agent's prompt". */
+    scheduleAutoName: (input: {
+        workspaceId: string;
+        cwd: string;
+        firstAgentContext: FirstAgentContext;
+    }) => void;
+    /** Derives the workspace title from the first agent's prompt. */
+    resolveTitle: (firstAgentContext?: FirstAgentContext) => string | null;
+}
+export interface EnsureWorkspaceForCreateResult {
+    workspaceId: string;
+    /**
+     * True only when this call minted a workspace. Auto-naming is gated on it:
+     * renaming a REUSED workspace from the first prompt would overwrite a name the
+     * user already has.
+     */
+    createdWorkspace: boolean;
+}
+export declare function ensureWorkspaceForCreate(cwd: string, firstAgentContext: FirstAgentContext | undefined, deps: EnsureWorkspaceForCreateDeps): Promise<EnsureWorkspaceForCreateResult>;
+//# sourceMappingURL=ensure-workspace-for-create.d.ts.map

package/dist/server/server/ensure-workspace-for-create.js

@@ -0,0 +1,20 @@
+import { resolveExistingWorkspaceIdForCreate } from "./resolve-workspace-id-for-path.js";
+export async function ensureWorkspaceForCreate(cwd, firstAgentContext, deps) {
+    const existingWorkspaceId = resolveExistingWorkspaceIdForCreate(cwd, await deps.listWorkspaces());
+    if (existingWorkspaceId) {
+        return { workspaceId: existingWorkspaceId, createdWorkspace: false };
+    }
+    const workspace = await deps.createWorkspace({
+        cwd,
+        title: deps.resolveTitle(firstAgentContext),
+    });
+    if (firstAgentContext) {
+        deps.scheduleAutoName({
+            workspaceId: workspace.workspaceId,
+            cwd: workspace.cwd,
+            firstAgentContext,
+        });
+    }
+    return { workspaceId: workspace.workspaceId, createdWorkspace: true };
+}
+//# sourceMappingURL=ensure-workspace-for-create.js.map

package/dist/server/server/exports.d.ts

@@ -0,0 +1,28 @@
+export { createPaseoDaemon, type PaseoDaemon, type PaseoDaemonConfig } from "./bootstrap.js";
+export { loadConfig, type CliConfigOverrides } from "./config.js";
+export { resolvePaseoHome } from "./paseo-home.js";
+export { getOrCreateServerId } from "./server-id.js";
+export { createRootLogger, type LogLevel, type LogFormat } from "./logger.js";
+export { loadPersistedConfig, savePersistedConfig, type PersistedConfig, } from "./persisted-config.js";
+export { hashDaemonPassword, isBearerTokenValid } from "./auth.js";
+export { generateLocalPairingOffer, type LocalPairingOffer } from "./pairing-offer.js";
+export { ConnectionOfferSchema, decodeOfferFragmentPayload, parseConnectionOfferFromUrl, type ConnectionOffer, } from "@hyperdrive.bot/fleet-protocol/connection-offer";
+export { buildRelayWebSocketUrl } from "@hyperdrive.bot/fleet-protocol/daemon-endpoints";
+export { buildDaemonWebSocketUrl, deriveLabelFromEndpoint, normalizeHostPort, parseConnectionUri, shouldUseTlsForDefaultHostedRelay, } from "@hyperdrive.bot/fleet-protocol/daemon-endpoints";
+export { PARENT_AGENT_ID_LABEL } from "@hyperdrive.bot/fleet-protocol/agent-labels";
+export { DirectTcpHostConnectionSchema, type DirectTcpHostConnection, type NormalizedDirectTcpHostConnection, } from "@hyperdrive.bot/fleet-protocol/host-connection-schema";
+export { ensureLocalSpeechModels, listLocalSpeechModels, type LocalSpeechModelId, type LocalSttModelId, type LocalTtsModelId, } from "./speech/providers/local/models.js";
+export { applySherpaLoaderEnv, resolveSherpaLoaderEnv, sherpaLoaderEnvKey, sherpaPlatformArch, sherpaPlatformPackageName, type SherpaLoaderEnvKey, type SherpaLoaderEnvResolution, } from "./speech/providers/local/sherpa/sherpa-runtime-env.js";
+export { type ProviderOverride, type ProviderProfileModel, } from "./agent/provider-launch-config.js";
+export { findExecutable } from "../executable-resolution/executable-resolution.js";
+export { execCommand, spawnProcess } from "../utils/spawn.js";
+export { AGENT_PROVIDER_DEFINITIONS, BUILTIN_PROVIDER_IDS, type AgentProviderDefinition, } from "@hyperdrive.bot/fleet-protocol/provider-manifest";
+export type { AgentMode, AgentUsage, AgentCapabilityFlags, AgentPermissionRequest, AgentTimelineItem, ProviderSnapshotEntry, } from "./agent/agent-sdk-types.js";
+export { curateAgentActivity } from "./agent/activity-curator.js";
+export { getStructuredAgentResponse, StructuredAgentResponseError, StructuredAgentFallbackError, DEFAULT_STRUCTURED_GENERATION_PROVIDERS, generateStructuredAgentResponseWithFallback, type AgentCaller, type JsonSchema, type StructuredGenerationAttempt, type StructuredGenerationProvider, type StructuredAgentGenerationOptions, type StructuredAgentGenerationWithFallbackOptions, type StructuredAgentResponseOptions, } from "./agent/agent-response-loop.js";
+export type { AgentSnapshotPayload, AgentStreamEventPayload, AgentStreamMessage, } from "@hyperdrive.bot/fleet-protocol/messages";
+export { currentLinkPath, previousLinkPath, readSlotVersion, resolveSlotWorkerEntry, slotPath, slotWorkerEntryCandidates, slotsRoot, updateStatePath, } from "./update/slots.js";
+export { DAEMON_PACKAGE_NAME, compareVersions, distTagForChannel, fetchChannelVersion, fetchDistTags, isNewer, type ReleaseChannel, type RegistryLookup, } from "./update/registry.js";
+export { EMPTY_UPDATE_STATE, ensureInstallId, isPinned, readUpdateState, writeUpdateState, type UpdateState, } from "./update/state.js";
+export { pruneSlots, rollback, stageVersion, swapTo, verifySlot, type InstallerDeps, type VerifyResult, } from "./update/installer.js";
+//# sourceMappingURL=exports.d.ts.map

package/dist/server/server/exports.js

@@ -0,0 +1,31 @@
+// CLI exports for @hyperdrive.bot/fleet-server
+export { createPaseoDaemon } from "./bootstrap.js";
+export { loadConfig } from "./config.js";
+export { resolvePaseoHome } from "./paseo-home.js";
+export { getOrCreateServerId } from "./server-id.js";
+export { createRootLogger } from "./logger.js";
+export { loadPersistedConfig, savePersistedConfig, } from "./persisted-config.js";
+export { hashDaemonPassword, isBearerTokenValid } from "./auth.js";
+export { generateLocalPairingOffer } from "./pairing-offer.js";
+export { ConnectionOfferSchema, decodeOfferFragmentPayload, parseConnectionOfferFromUrl, } from "@hyperdrive.bot/fleet-protocol/connection-offer";
+export { buildRelayWebSocketUrl } from "@hyperdrive.bot/fleet-protocol/daemon-endpoints";
+export { buildDaemonWebSocketUrl, deriveLabelFromEndpoint, normalizeHostPort, parseConnectionUri, shouldUseTlsForDefaultHostedRelay, } from "@hyperdrive.bot/fleet-protocol/daemon-endpoints";
+export { PARENT_AGENT_ID_LABEL } from "@hyperdrive.bot/fleet-protocol/agent-labels";
+export { DirectTcpHostConnectionSchema, } from "@hyperdrive.bot/fleet-protocol/host-connection-schema";
+export { ensureLocalSpeechModels, listLocalSpeechModels, } from "./speech/providers/local/models.js";
+export { applySherpaLoaderEnv, resolveSherpaLoaderEnv, sherpaLoaderEnvKey, sherpaPlatformArch, sherpaPlatformPackageName, } from "./speech/providers/local/sherpa/sherpa-runtime-env.js";
+export { findExecutable } from "../executable-resolution/executable-resolution.js";
+export { execCommand, spawnProcess } from "../utils/spawn.js";
+// Provider manifest (source of truth for provider definitions)
+export { AGENT_PROVIDER_DEFINITIONS, BUILTIN_PROVIDER_IDS, } from "@hyperdrive.bot/fleet-protocol/provider-manifest";
+// Agent activity curator for CLI logs
+export { curateAgentActivity } from "./agent/activity-curator.js";
+export { getStructuredAgentResponse, StructuredAgentResponseError, StructuredAgentFallbackError, DEFAULT_STRUCTURED_GENERATION_PROVIDERS, generateStructuredAgentResponseWithFallback, } from "./agent/agent-response-loop.js";
+// Daemon self-update: slot layout, registry lookups, staging and rollback.
+// Surfaced here because the server's `exports` map only permits the package root,
+// and `paseo daemon update` in the CLI orchestrates these.
+export { currentLinkPath, previousLinkPath, readSlotVersion, resolveSlotWorkerEntry, slotPath, slotWorkerEntryCandidates, slotsRoot, updateStatePath, } from "./update/slots.js";
+export { DAEMON_PACKAGE_NAME, compareVersions, distTagForChannel, fetchChannelVersion, fetchDistTags, isNewer, } from "./update/registry.js";
+export { EMPTY_UPDATE_STATE, ensureInstallId, isPinned, readUpdateState, writeUpdateState, } from "./update/state.js";
+export { pruneSlots, rollback, stageVersion, swapTo, verifySlot, } from "./update/installer.js";
+//# sourceMappingURL=exports.js.map

package/dist/server/server/file-download/token-store.d.ts

@@ -0,0 +1,24 @@
+export interface DownloadTokenEntry {
+    token: string;
+    path: string;
+    absolutePath: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    expiresAt: number;
+}
+interface DownloadTokenStoreOptions {
+    ttlMs: number;
+    now?: () => number;
+}
+export declare class DownloadTokenStore {
+    private readonly ttlMs;
+    private readonly now;
+    private readonly tokens;
+    constructor(options: DownloadTokenStoreOptions);
+    issueToken(input: Omit<DownloadTokenEntry, "token" | "expiresAt">): DownloadTokenEntry;
+    consumeToken(token: string): DownloadTokenEntry | null;
+    private pruneExpired;
+}
+export {};
+//# sourceMappingURL=token-store.d.ts.map

package/dist/server/server/file-download/token-store.js

@@ -0,0 +1,40 @@
+import { randomUUID } from "node:crypto";
+export class DownloadTokenStore {
+    constructor(options) {
+        this.tokens = new Map();
+        this.ttlMs = options.ttlMs;
+        this.now = options.now ?? (() => Date.now());
+    }
+    issueToken(input) {
+        this.pruneExpired();
+        const token = randomUUID();
+        const expiresAt = this.now() + this.ttlMs;
+        const entry = {
+            ...input,
+            token,
+            expiresAt,
+        };
+        this.tokens.set(token, entry);
+        return entry;
+    }
+    consumeToken(token) {
+        const entry = this.tokens.get(token);
+        if (!entry) {
+            return null;
+        }
+        this.tokens.delete(token);
+        if (entry.expiresAt <= this.now()) {
+            return null;
+        }
+        return entry;
+    }
+    pruneExpired() {
+        const now = this.now();
+        for (const [token, entry] of this.tokens) {
+            if (entry.expiresAt <= now) {
+                this.tokens.delete(token);
+            }
+        }
+    }
+}
+//# sourceMappingURL=token-store.js.map

package/dist/server/server/file-explorer/file-download-frames.d.ts

@@ -0,0 +1,27 @@
+import type { z } from "zod";
+import { type FileBeginMetadataSchema } from "@hyperdrive.bot/fleet-protocol/binary-frames/index";
+export interface EncodeFileDownloadFramesParams {
+    requestId: string;
+    metadata: z.infer<typeof FileBeginMetadataSchema>;
+    read: (buf: Buffer, offset: number, length: number, position: number) => Promise<{
+        bytesRead: number;
+    }>;
+    chunkSize?: number;
+}
+/**
+ * Encode a file download as a relay-safe stream of binary frames:
+ * `FileBegin` (carrying the metadata) → N × `FileChunk` (each ≤ chunkSize) → `FileEnd`.
+ *
+ * This is the download-direction twin of the upload chunker — it consumes the same
+ * `encodeFileTransferFrame` codec and the same `UPLOAD_CHUNK_SIZE_BYTES` constant, so
+ * no single frame's payload can exceed the 256 KiB ceiling (keeping it well under the
+ * relay's 32 MiB per-message cap and preventing head-of-line blocking of voice/terminal
+ * frames on the shared WebSocket).
+ *
+ * The byte source is supplied via `read` (positioned reads from offset 0) so the caller
+ * owns the file handle and the helper stays pure/testable with an in-memory buffer.
+ *
+ * @returns an async generator yielding the encoded frames in order.
+ */
+export declare function encodeFileDownloadFrames({ requestId, metadata, read, chunkSize, }: EncodeFileDownloadFramesParams): AsyncGenerator<Uint8Array>;
+//# sourceMappingURL=file-download-frames.d.ts.map

package/dist/server/server/file-explorer/file-download-frames.js

@@ -0,0 +1,47 @@
+import { encodeFileTransferFrame, FileTransferOpcode, } from "@hyperdrive.bot/fleet-protocol/binary-frames/index";
+import { UPLOAD_CHUNK_SIZE_BYTES } from "@hyperdrive.bot/fleet-protocol/binary-frames/chunk-size";
+/**
+ * Encode a file download as a relay-safe stream of binary frames:
+ * `FileBegin` (carrying the metadata) → N × `FileChunk` (each ≤ chunkSize) → `FileEnd`.
+ *
+ * This is the download-direction twin of the upload chunker — it consumes the same
+ * `encodeFileTransferFrame` codec and the same `UPLOAD_CHUNK_SIZE_BYTES` constant, so
+ * no single frame's payload can exceed the 256 KiB ceiling (keeping it well under the
+ * relay's 32 MiB per-message cap and preventing head-of-line blocking of voice/terminal
+ * frames on the shared WebSocket).
+ *
+ * The byte source is supplied via `read` (positioned reads from offset 0) so the caller
+ * owns the file handle and the helper stays pure/testable with an in-memory buffer.
+ *
+ * @returns an async generator yielding the encoded frames in order.
+ */
+export async function* encodeFileDownloadFrames({ requestId, metadata, read, chunkSize = UPLOAD_CHUNK_SIZE_BYTES, }) {
+    yield encodeFileTransferFrame({
+        opcode: FileTransferOpcode.FileBegin,
+        requestId,
+        metadata,
+    });
+    // One reusable read buffer for the whole stream. This is safe because
+    // encodeFileTransferFrame copies the payload (`bytes.set(payload, …)` in
+    // file-transfer.ts) — the subarray handed to each FileChunk is never aliased
+    // after the yield. Do NOT "fix" this into a per-chunk allocation.
+    const buffer = Buffer.allocUnsafe(chunkSize);
+    let position = 0;
+    for (;;) {
+        const { bytesRead } = await read(buffer, 0, chunkSize, position);
+        if (bytesRead === 0) {
+            break;
+        }
+        position += bytesRead;
+        yield encodeFileTransferFrame({
+            opcode: FileTransferOpcode.FileChunk,
+            requestId,
+            payload: buffer.subarray(0, bytesRead),
+        });
+    }
+    yield encodeFileTransferFrame({
+        opcode: FileTransferOpcode.FileEnd,
+        requestId,
+    });
+}
+//# sourceMappingURL=file-download-frames.js.map

package/dist/server/server/file-explorer/mime-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Mime resolution for the file explorer.
+ *
+ * The explorer used to label every non-image binary `application/octet-stream`, which
+ * threw away the one piece of information a client needs to decide whether it can render
+ * the file. The bytes already reach the client over the relay-safe FileChunk stream, so
+ * the mime type is the only thing standing between a PDF and a rendered PDF.
+ *
+ * Resolution order is extension first (cheap, and the only signal for text-ish formats
+ * that have no magic number), then magic bytes (authoritative, and the only signal for a
+ * file whose extension is wrong or missing).
+ *
+ * `ExplorerFileKind` deliberately stays `"text" | "image" | "binary"`. Adding members
+ * would narrow nothing but WOULD break older clients parsing the enum, so a PDF stays
+ * `kind: "binary"` on the wire and is identified by its mime.
+ */
+/** Extensions the explorer serves as `kind: "image"` and renders inline as an image. */
+export declare const IMAGE_MIME_TYPES: Record<string, string>;
+/**
+ * Extensions for binary formats we can name. Being in this map does NOT promise the
+ * client can render it - naming an `.xlsx` honestly is what lets the client say
+ * "Excel workbook, 340 KB" with a download button instead of shrugging.
+ */
+export declare const BINARY_MIME_TYPES: Record<string, string>;
+declare const OCTET_STREAM = "application/octet-stream";
+/**
+ * Identify a file from its leading bytes.
+ *
+ * @param bytes - the detection prefix. Only the first ~32 bytes are ever consulted, so
+ *   passing a bounded prefix instead of the whole file is both valid and preferred.
+ * @returns the mime type, or `null` when no signature matches.
+ */
+export declare function sniffMimeFromMagicBytes(bytes: Uint8Array): string | null;
+/**
+ * Resolve the mime type of a binary file.
+ *
+ * Extension wins when we know it, because a `.docx` and a `.zip` are byte-identical at
+ * the magic-number level and the extension is the only thing that tells them apart.
+ * Magic bytes are the fallback for unknown or missing extensions.
+ *
+ * @returns a concrete mime type, or `application/octet-stream` when the file is genuinely
+ *   unidentifiable. Callers must treat octet-stream as "show metadata and a download",
+ *   never as an error.
+ */
+export declare function resolveBinaryMimeType({ extension, detectionBytes, }: {
+    extension: string;
+    detectionBytes: Uint8Array;
+}): string;
+/**
+ * Whether a resolved mime should be served as `kind: "image"`.
+ *
+ * SVG is intentionally included: the client renders it inside an `<img>`, where scripts
+ * do not execute. Do not reuse this predicate to decide whether SVG may be inlined into
+ * the DOM or loaded in an `<object>` - both of those DO execute script.
+ */
+export declare function isImageMimeType(mime: string): boolean;
+export { OCTET_STREAM };
+//# sourceMappingURL=mime-types.d.ts.map

package/dist/server/server/file-explorer/mime-types.js

@@ -0,0 +1,212 @@
+/**
+ * Mime resolution for the file explorer.
+ *
+ * The explorer used to label every non-image binary `application/octet-stream`, which
+ * threw away the one piece of information a client needs to decide whether it can render
+ * the file. The bytes already reach the client over the relay-safe FileChunk stream, so
+ * the mime type is the only thing standing between a PDF and a rendered PDF.
+ *
+ * Resolution order is extension first (cheap, and the only signal for text-ish formats
+ * that have no magic number), then magic bytes (authoritative, and the only signal for a
+ * file whose extension is wrong or missing).
+ *
+ * `ExplorerFileKind` deliberately stays `"text" | "image" | "binary"`. Adding members
+ * would narrow nothing but WOULD break older clients parsing the enum, so a PDF stays
+ * `kind: "binary"` on the wire and is identified by its mime.
+ */
+/** Extensions the explorer serves as `kind: "image"` and renders inline as an image. */
+export const IMAGE_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".avif": "image/avif",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".apng": "image/apng",
+};
+/**
+ * Extensions for binary formats we can name. Being in this map does NOT promise the
+ * client can render it - naming an `.xlsx` honestly is what lets the client say
+ * "Excel workbook, 340 KB" with a download button instead of shrugging.
+ */
+export const BINARY_MIME_TYPES = {
+    // Documents
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".odt": "application/vnd.oasis.opendocument.text",
+    ".ods": "application/vnd.oasis.opendocument.spreadsheet",
+    ".rtf": "application/rtf",
+    ".epub": "application/epub+zip",
+    // Video
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".mkv": "video/x-matroska",
+    ".avi": "video/x-msvideo",
+    ".ogv": "video/ogg",
+    // Audio
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac",
+    ".wav": "audio/wav",
+    ".flac": "audio/flac",
+    ".ogg": "audio/ogg",
+    ".oga": "audio/ogg",
+    ".opus": "audio/opus",
+    // Fonts
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    // Archives and databases (named, never rendered)
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+    ".tgz": "application/gzip",
+    ".bz2": "application/x-bzip2",
+    ".xz": "application/x-xz",
+    ".7z": "application/x-7z-compressed",
+    ".rar": "application/vnd.rar",
+    ".sqlite": "application/vnd.sqlite3",
+    ".sqlite3": "application/vnd.sqlite3",
+    ".db": "application/vnd.sqlite3",
+    ".wasm": "application/wasm",
+};
+const OCTET_STREAM = "application/octet-stream";
+const textBytes = (value) => Array.from(value, (char) => char.charCodeAt(0));
+/**
+ * ISO base media files (mp4, mov, avif, heic) all start with a box length followed by
+ * `ftyp` at offset 4, and are told apart only by the brand at offset 8.
+ */
+const isoBrandSignature = (brand, mime) => ({
+    offset: 4,
+    pattern: [...textBytes("ftyp"), ...textBytes(brand)],
+    mime,
+});
+/**
+ * Ordered most-specific first. RIFF containers must be checked before any prefix-only
+ * pattern that could also match them.
+ */
+const MAGIC_SIGNATURES = [
+    // Images
+    { offset: 0, pattern: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], mime: "image/png" },
+    { offset: 0, pattern: [0xff, 0xd8, 0xff], mime: "image/jpeg" },
+    { offset: 0, pattern: textBytes("GIF8"), mime: "image/gif" },
+    { offset: 0, pattern: [0x42, 0x4d], mime: "image/bmp" },
+    { offset: 0, pattern: [0x00, 0x00, 0x01, 0x00], mime: "image/x-icon" },
+    { offset: 0, pattern: [0x49, 0x49, 0x2a, 0x00], mime: "image/tiff" },
+    { offset: 0, pattern: [0x4d, 0x4d, 0x00, 0x2a], mime: "image/tiff" },
+    // RIFF containers: same first 4 bytes, disambiguated at offset 8.
+    { offset: 8, pattern: textBytes("WEBP"), mime: "image/webp" },
+    { offset: 8, pattern: textBytes("WAVE"), mime: "audio/wav" },
+    { offset: 8, pattern: textBytes("AVI "), mime: "video/x-msvideo" },
+    // ISO base media brands
+    isoBrandSignature("avif", "image/avif"),
+    isoBrandSignature("avis", "image/avif"),
+    isoBrandSignature("heic", "image/heic"),
+    isoBrandSignature("heix", "image/heic"),
+    isoBrandSignature("mif1", "image/heif"),
+    isoBrandSignature("qt  ", "video/quicktime"),
+    isoBrandSignature("isom", "video/mp4"),
+    isoBrandSignature("iso2", "video/mp4"),
+    isoBrandSignature("mp41", "video/mp4"),
+    isoBrandSignature("mp42", "video/mp4"),
+    isoBrandSignature("M4V ", "video/mp4"),
+    isoBrandSignature("M4A ", "audio/mp4"),
+    // Documents
+    { offset: 0, pattern: textBytes("%PDF-"), mime: "application/pdf" },
+    { offset: 0, pattern: textBytes("{\\rtf"), mime: "application/rtf" },
+    // Audio and video
+    { offset: 0, pattern: [0x1a, 0x45, 0xdf, 0xa3], mime: "video/webm" },
+    { offset: 0, pattern: textBytes("OggS"), mime: "audio/ogg" },
+    { offset: 0, pattern: textBytes("fLaC"), mime: "audio/flac" },
+    { offset: 0, pattern: textBytes("ID3"), mime: "audio/mpeg" },
+    { offset: 0, pattern: [0xff, 0xfb], mime: "audio/mpeg" },
+    { offset: 0, pattern: [0xff, 0xf3], mime: "audio/mpeg" },
+    // Fonts
+    { offset: 0, pattern: textBytes("wOFF"), mime: "font/woff" },
+    { offset: 0, pattern: textBytes("wOF2"), mime: "font/woff2" },
+    { offset: 0, pattern: textBytes("OTTO"), mime: "font/otf" },
+    { offset: 0, pattern: [0x00, 0x01, 0x00, 0x00, 0x00], mime: "font/ttf" },
+    // Archives and databases
+    { offset: 0, pattern: textBytes("SQLite format 3"), mime: "application/vnd.sqlite3" },
+    { offset: 0, pattern: [0x1f, 0x8b], mime: "application/gzip" },
+    { offset: 0, pattern: [0x42, 0x5a, 0x68], mime: "application/x-bzip2" },
+    { offset: 0, pattern: [0xfd, ...textBytes("7zXZ")], mime: "application/x-xz" },
+    { offset: 0, pattern: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], mime: "application/x-7z-compressed" },
+    { offset: 0, pattern: textBytes("Rar!"), mime: "application/vnd.rar" },
+    { offset: 0, pattern: [0x00, 0x61, 0x73, 0x6d], mime: "application/wasm" },
+    // ZIP last: docx/xlsx/pptx/epub are all ZIPs, so an extension hit must win over this.
+    { offset: 0, pattern: [0x50, 0x4b, 0x03, 0x04], mime: "application/zip" },
+];
+function matchesSignature(bytes, signature) {
+    const end = signature.offset + signature.pattern.length;
+    if (bytes.length < end) {
+        return false;
+    }
+    for (let index = 0; index < signature.pattern.length; index += 1) {
+        const expected = signature.pattern[index];
+        if (expected !== null && bytes[signature.offset + index] !== expected) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Identify a file from its leading bytes.
+ *
+ * @param bytes - the detection prefix. Only the first ~32 bytes are ever consulted, so
+ *   passing a bounded prefix instead of the whole file is both valid and preferred.
+ * @returns the mime type, or `null` when no signature matches.
+ */
+export function sniffMimeFromMagicBytes(bytes) {
+    for (const signature of MAGIC_SIGNATURES) {
+        if (matchesSignature(bytes, signature)) {
+            return signature.mime;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the mime type of a binary file.
+ *
+ * Extension wins when we know it, because a `.docx` and a `.zip` are byte-identical at
+ * the magic-number level and the extension is the only thing that tells them apart.
+ * Magic bytes are the fallback for unknown or missing extensions.
+ *
+ * @returns a concrete mime type, or `application/octet-stream` when the file is genuinely
+ *   unidentifiable. Callers must treat octet-stream as "show metadata and a download",
+ *   never as an error.
+ */
+export function resolveBinaryMimeType({ extension, detectionBytes, }) {
+    const fromExtension = BINARY_MIME_TYPES[extension] ?? IMAGE_MIME_TYPES[extension];
+    if (fromExtension) {
+        return fromExtension;
+    }
+    return sniffMimeFromMagicBytes(detectionBytes) ?? OCTET_STREAM;
+}
+/**
+ * Whether a resolved mime should be served as `kind: "image"`.
+ *
+ * SVG is intentionally included: the client renders it inside an `<img>`, where scripts
+ * do not execute. Do not reuse this predicate to decide whether SVG may be inlined into
+ * the DOM or loaded in an `<object>` - both of those DO execute script.
+ */
+export function isImageMimeType(mime) {
+    return mime.startsWith("image/");
+}
+export { OCTET_STREAM };
+//# sourceMappingURL=mime-types.js.map