@springbrand/file-renderers 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# `@springbrand/file-renderers`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared semantic renderer boundary for Workspace files in SP's first-class
+File Canvas.
+
+This package contains the reviewed contracts, typed registry, and the first
+read-only Markdown, code, image, SVG, HTML, media, CSV, JSON, JSONL, YAML,
+TOML, XML, Notebook, ZIP, PDF, DOCX, XLSX, PPTX, GLB, WASM, Drawio,
+Excalidraw, and Mermaid
+renderers. SP's File Canvas consumes them through its Workspace host adapter.
+The package is designed for the observation phase while keeping a typed
+boundary for later editing.
+
+## Ownership
+
+- SP/Rapp owns the File Canvas controller and consumes the shared renderer
+  implementations.
+- This package owns Workspace file format semantics only.
+- `fileFormatFor` selects a renderer format; `fileContentKindFor` classifies
+  code and JSON-like files without expanding renderer support.
+  Compound formats such as `.excalidraw.json` and `.drawio.xml` keep their
+  renderer identity before generic suffix classification.
+- Chat Attachment admission consumes this package's `attachmentFormatFor` and
+  `validateAttachmentBytes` boundary. A non-`unknown` Renderer format is
+  uploadable; HEIC/HEIF are input-only browser conversion aliases that become
+  JPEG before upload.
+- Workspace/Space owns authorization, file versions, locks, leases, and writes.
+- The package never accesses Workspace HTTP, WebSocket, tokens, or storage.
+
+The former Doop iframe projection and protocol have been removed. SP owns the
+only production File Canvas, using its existing Severn connection and Workspace
+client. Renderer behavior is integrated through the SP Canvas controller, not
+through a second runtime.
+
+Workspace identity and version facts belong to SP/Space. The Canvas controller
+keeps the authoritative snapshot next to the parsed renderer document instead
+of copying those facts into this package. `RendererInput`, document models, and
+resource requests therefore contain no Workspace scope, path, resource ID,
+content version, or mutation revision.
+
+## Observation flow
+
+Every renderer is bound to one format and one model type:
+
+```ts
+interface FileRenderer<
+  F extends FileRendererFormat,
+  Model extends RendererModel<F>,
+> {
+  readonly format: F;
+  parse(
+    input: RendererInput<F>,
+    context: RendererParseContext,
+  ): Promise<ParsedDocument<F, Model>>;
+  render(
+    document: ParsedDocument<F, Model>,
+    context: RendererRenderContext,
+  ): ReactNode;
+}
+```
+
+`RendererInput<F>` contains only format semantics: format, name, MIME type, and
+payload. It binds the payload encoding to the format. The registry keeps that
+format and model relationship when a renderer is looked up. A Markdown renderer
+cannot receive an XLSX input or render a PDF document at the type boundary.
+
+The parsed model is a discriminated union:
+
+- `structure: "frame"` carries renderer-specific frame data and never has a
+  component `root`.
+- `structure: "structured"` carries a component tree and never has a frame
+  payload.
+
+A format may choose either shape for a particular renderer. A PDF renderer can
+start as a Frame renderer and a later version can provide a structured page
+model without changing the package-wide contract.
+
+`createFileRendererRegistry()` builds an immutable registry from an ordered
+renderer list. It preserves the concrete format/model pair at typed lookups,
+copies the registration order, and rejects duplicate formats instead of making
+the winner depend on import order.
+
+Parsing has one lifecycle contract: `parse()` resolves a `ParsedDocument`,
+observes the host `AbortSignal`, or throws. Request generation, stale-result
+discarding, retries, error presentation, and snapshot caching remain in the SP
+Canvas controller; the shared package does not create a parallel task state
+machine.
+
+## Host boundary
+
+Parsing and rendering receive a host context containing:
+
+- `signal`, so a superseded parse or resource request can be cancelled;
+- `basePath`, the Workspace-relative resolution base;
+- `resources.resolve()`, the only way a renderer asks for linked resources.
+
+The shared renderer classifies references and their purpose (`image`,
+`stylesheet`, `script`, and so on). The host creates a resolver already bound to
+the authoritative file snapshot. That resolver owns authentication, Workspace
+access, authorization, caching, and the decision to return a safe URL,
+text/bytes, `missing`, or `blocked`. Renderers never call Workspace APIs
+directly, and hosts do not duplicate format-specific reference parsing. The
+Markdown renderer preserves relative `href` and `src` references through its
+Streamdown pipeline before resolving them through this boundary, so the browser
+cannot reinterpret them against the SP page origin. Notebook Markdown cells
+reuse the same renderer and resolver context.
+
+Attachment admission and Renderer parsing are deliberately separate stages.
+The API validates authoritative bytes enough to reject format mismatches,
+unsafe OOXML containers, and invalid binary signatures, then stores the
+canonical media type. A malformed but recognized text document may still be
+uploaded so its Renderer can return a source-preserving parse diagnostic. The
+Agent's optional Understanding pipeline remains narrower than upload or
+preview support and does not mark unsupported evidence as a failed upload.
+
+## One capability source
+
+`ParsedDocument.capability` is the only capability declaration. There is no
+second `lockScope` field on the model, no static capability copy on the
+renderer, and no separate output capability object.
+
+The capability is one of:
+
+- `mode: "observe"` for the current read-only phase;
+- `mode: "edit", lock.scope: "frame"` with a whole-document serialization
+  contract;
+- `mode: "edit", lock.scope: "node"` for a structured model only.
+
+The node branch is structurally required to provide all four prerequisites:
+
+1. stable node identity;
+2. a serialization boundary locator and serializer;
+3. comparable node versions;
+4. a disjoint-mutation checker.
+
+The type system cannot manufacture a node capability from boolean flags, and a
+Frame model cannot receive the node capability. These interfaces reserve the
+future edit seam; they do not acquire locks, call CAS, write files, or decide
+whether an operation is authorized.
+
+## Format slots
+
+Markdown, code, image, SVG, HTML, media, CSV, PDF, DOCX, XLSX, PPTX, GLB,
+WASM, Drawio, Excalidraw, Mermaid, JSON, JSONL, YAML, TOML, XML, Notebook,
+and ZIP are implemented as read-only renderers following SP's current preview
+semantics.
+SP's live Canvas and revision history use the same preview surface for every
+implemented format. The host retains the exact text payload for Preview/Source
+switching in both views, including syntax-highlighted Code; binary formats
+offer the original download without fabricating text Source. The host's model
+map is checked against every `FileRendererFormat`, and dispatch is exhaustive
+for recognized formats so a new slot cannot silently fall back to a blank Canvas.
+Most deliberately use Frame models until stable structured identity and
+lossless serialization are reviewed. Valid JSON has a source-preserving
+structured preview, invalid JSON a diagnostic Frame, and JSONL a per-record
+Frame; neither advertises node editing. The code renderer recognizes Python,
+TypeScript/TSX, JavaScript/JSX, CSS/SCSS, SQL, and Bash while preserving exact
+source. SVG is a separate text format with a static sanitized image preview
+and exact original Source in both Canvas views. WASM is a binary metadata-only
+preview with download, never generated source or module execution. Other text
+and binary formats continue through the host fallback. The shared
+`isBinaryFileFormat()` policy lets current and historical Canvas reads agree
+on payload encoding. DOCX, XLSX, and PPTX use SP's shared strict OOXML guard
+before retaining original bytes in read-only Frames. Each format then loads its
+`@silurus/ooxml` Canvas viewer from a separate entry point when mounted. DOCX
+and XLSX reuse their viewer's parsed model for a semantic HTML companion:
+DOCX exposes headings, lists, tables, and validated HTTP(S) links; XLSX exposes
+worksheet tables with row and column headers. The former separate extractors
+remain removed. Viewer-owned workers and canvases are destroyed on unmount or
+render cancellation; failures show a download fallback.
+PDF uses PDF.js for a local canvas viewer and reports interactive forms,
+attachments, JavaScript, and rich-media objects as static-preview limitations;
+it never executes or exposes those embedded objects.
+SP bounds both current and historical previews of these formats to 20 MiB
+before parsing. PPTX uses the `ppt` slot only for modern `.pptx` files and does
+not attempt legacy `.ppt` decoding. The viewers render locally without
+resolving Workspace resources, media playback, or remote fonts. DOCX allows
+validated HTTP(S) links; XLSX and PPTX hyperlinks remain disabled. The shared
+OOXML guard remains a separate security inspection, not a second display
+engine; viewer resource budgets match its ZIP limits.
+Other directories reserve sibling format slots; a slot is not an implementation
+promise until its parser, security policy, resource behavior, model,
+serialization, and tests are reviewed.
+
+HTML uses the shared bounded resource projector for both live and historical
+previews. The live view reads linked assets through the Chat-scoped Workspace
+client; history resolves the same links only within the selected revision's
+manifest root, never from the current Workspace. The host keeps its sandboxed,
+opaque-origin preview separate from the exact original Source and download.
+Switching files or revisions aborts outstanding linked-resource requests.
+
+Format selection is suffix-first. A supported filename suffix is authoritative;
+MIME is used as a fallback when the filename has no recognized suffix, including
+an unknown suffix. Renderer parsing still validates the actual payload before a
+preview is shown, so MIME metadata never bypasses a renderer's content checks.
+CSV additionally detects UTF-8 and UTF-16 with or without a BOM, rejects invalid
+or unreliable encodings, and recognizes comma, semicolon, tab, and pipe
+delimiters from consistent parsed rows. Ambiguous or low-confidence multi-column
+input fails rather than being silently split with the wrong delimiter; a file
+that contains no reliable delimiter remains a single column.
+JSON and JSONL use the same parser and tree view but separate format contracts.
+The paged tree presentation is also reused by configuration formats and ZIP;
+each format keeps its own parsing and identity semantics.
+The parser preserves duplicate keys and exact numeric source tokens; it bounds
+JSON to 512 KiB and JSONL to 2 MiB. SP's existing bounded read path applies
+those limits to both live and historical previews. Specialized
+`.excalidraw.json` continues to take precedence over generic `.json`.
+YAML, TOML, and XML share the JSON tree's paged presentation, not its parser or
+model. YAML preserves source ranges without expanding aliases; TOML keeps large
+integers as BigInt and does not invent per-value source ranges; XML is displayed
+as inert text nodes with DOCTYPE and processing instructions rejected. All three
+have a 512 KiB limit, bounded tree depth and node count, and diagnostic Frames
+for invalid files. Their component IDs are view-local only: node editing and
+lossless structured serialization are not claimed.
+
+The Notebook renderer accepts `.ipynb` or an extensionless notebook MIME as
+bounded JSON text. It reuses the package's Markdown, Code, and raster Image
+surfaces for cells and safe outputs, while never running code or rendering rich
+HTML/SVG outputs. It caps the input at 2 MiB, displays at most 200 cells and
+20 outputs per cell, and bounds displayed text and embedded images. Both Canvas
+views offer exact Source and the original download.
+
+The ZIP renderer accepts `.zip` or an extensionless ZIP MIME as binary bytes.
+It reuses SP's strict ZIP inspector for path, entry, CRC, compression, and
+expanded-size checks. A 10 MiB input limit, 1,000 entries, 64 MiB total
+expansion, and 16-level path ceiling bound the preview. Its Frame contains
+only directory paths and sizes, presented through the shared paged tree; it
+never keeps entry contents, extracts into the Workspace, or executes files.
+ZIP has no text Source tab; the original archive remains downloadable. Invalid
+and excessive archives show diagnostic Frames instead of partial listings.
+
+The media renderer accepts browser-native audio and video formats as binary Frame
+models. It uses local Blob URLs for the lifetime of the rendered component, keeps
+native playback controls enabled, and never starts playback automatically. Media
+bytes are not decoded by the package and no remote resource is resolved.
+
+The GLB renderer accepts only self-contained glTF 2.0 binary models. It
+validates bounded GLB chunks and embedded references before lazily loading
+`<model-viewer>` with camera controls. SP limits current and historical GLB
+reads to 10 MiB using the renderer's own size constant. External references,
+decoder extensions, and `.gltf` JSON remain unsupported; the model is an
+observable Frame, not a stable editable scene graph.
+
+The diagram renderers are also read-only Frames. Drawio accepts bounded plain
+or compressed multi-page XML and displays a simplified semantic diagram;
+Excalidraw uses its official exporter to produce a static drawing from bounded
+JSON and embedded raster assets; Mermaid uses its official strict renderer.
+Excalidraw SVG is displayed in an inert CSP-limited iframe. Mermaid renders
+inside a separate script-enabled, opaque-origin iframe with a restrictive CSP;
+only its packaged runtime script and local data images/fonts are permitted.
+Generated navigation is removed. None resolves remote or Workspace-linked
+assets, starts an editor, or declares node locks. The Canvas offers the
+original source alongside the diagram preview.
+
+## Type tests
+
+`type-tests/contracts.typecheck.ts` is compiled by the package check:
+
+```bash
+pnpm --filter @springbrand/file-renderers check
+```
+
+The file uses `@ts-expect-error` assertions to ensure these invalid contracts
+remain rejected: cross-format parse/render, missing host cancellation context,
+bytes supplied to a text format, Workspace identity/version facts inserted into
+renderer contracts, a Frame model with `root`, an incomplete node lock, and a
+node lock attached to a Frame model.

package/dist/file-renderers/src/attachment-format.d.ts

@@ -0,0 +1,17 @@
+import { type DetectedFileFormat, type FileFormatInput } from "./file-format";
+/**
+ * Formats which can cross the Attachment boundary. `text` is the Canvas
+ * source fallback for plain text files; `unknown` never crosses the boundary.
+ */
+export type AttachmentFormat = Exclude<DetectedFileFormat, "unknown">;
+/**
+ * These are the canonical media types returned by the upload boundary. The
+ * list is intentionally owned by the renderer package so HTTP, Web, and Agent
+ * cannot grow separate format lists.
+ */
+export declare const ATTACHMENT_MEDIA_TYPES: readonly ["application/json", "application/javascript", "application/pdf", "application/sql", "application/toml", "application/typescript", "application/xhtml+xml", "application/vnd.excalidraw+json", "application/vnd.jgraph.mxfile", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/wasm", "application/x-ipynb+json", "application/x-ndjson", "application/x-python", "application/x-python-code", "application/x-sh", "application/x-sql", "application/x-typescript", "application/xml", "application/yaml", "application/zip", "audio/aac", "audio/flac", "audio/mp4", "audio/mpeg", "audio/ogg", "audio/wav", "audio/webm", "image/apng", "image/avif", "image/gif", "image/jpeg", "image/png", "image/svg+xml", "image/webp", "model/gltf-binary", "text/csv", "text/css", "text/html", "text/javascript", "text/markdown", "text/plain", "text/python", "text/typescript", "text/vnd.mermaid", "text/x-python", "text/x-scss", "text/x-sh", "text/x-sql", "video/mp4", "video/ogg", "video/webm"];
+export type AttachmentMediaType = (typeof ATTACHMENT_MEDIA_TYPES)[number];
+export declare function attachmentFormatFor(input: FileFormatInput): AttachmentFormat | null;
+export declare function isSupportedAttachmentInput(input: FileFormatInput): boolean;
+export declare function isAttachmentMediaType(value: string): value is AttachmentMediaType;
+export declare function attachmentMediaTypeFor(input: FileFormatInput, format?: AttachmentFormat | null): AttachmentMediaType | null;

package/dist/file-renderers/src/attachment-format.js

@@ -0,0 +1,180 @@
+import { codeLanguageFor, normalizedCodeMimeType, } from "./code/mime";
+import { configMimeTypeFor } from "./config/mime";
+import { csvMimeTypeFor } from "./csv/mime";
+import { docxMimeTypeFor } from "./docx/mime";
+import { drawioMimeTypeFor } from "./drawio/mime";
+import { excalidrawMimeTypeFor } from "./excalidraw/mime";
+import { fileFormatFor } from "./file-format";
+import { glbMimeTypeFor } from "./glb/mime";
+import { htmlMimeTypeFor } from "./html/mime";
+import { imageMimeTypeFor, isSupportedImageMimeType } from "./image/mime";
+import { jsonlMimeTypeFor, jsonMimeTypeFor } from "./json/mime";
+import { isSupportedMarkdownInput } from "./markdown/mime";
+import { canonicalMediaMimeType, mediaMimeTypeFor } from "./media/mime";
+import { mermaidMimeTypeFor } from "./mermaid/mime";
+import { NOTEBOOK_MIME_TYPE } from "./notebook/mime";
+import { pdfMimeTypeFor } from "./pdf/mime";
+import { pptMimeTypeFor } from "./ppt/mime";
+import { svgMimeTypeFor } from "./svg/mime";
+import { wasmMimeTypeFor } from "./wasm/mime";
+import { xlsxMimeTypeFor } from "./xlsx/mime";
+import { ZIP_MIME_TYPE, isSupportedZipInput } from "./zip/mime";
+/**
+ * These are the canonical media types returned by the upload boundary. The
+ * list is intentionally owned by the renderer package so HTTP, Web, and Agent
+ * cannot grow separate format lists.
+ */
+export const ATTACHMENT_MEDIA_TYPES = [
+    "application/json",
+    "application/javascript",
+    "application/pdf",
+    "application/sql",
+    "application/toml",
+    "application/typescript",
+    "application/xhtml+xml",
+    "application/vnd.excalidraw+json",
+    "application/vnd.jgraph.mxfile",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/wasm",
+    "application/x-ipynb+json",
+    "application/x-ndjson",
+    "application/x-python",
+    "application/x-python-code",
+    "application/x-sh",
+    "application/x-sql",
+    "application/x-typescript",
+    "application/xml",
+    "application/yaml",
+    "application/zip",
+    "audio/aac",
+    "audio/flac",
+    "audio/mp4",
+    "audio/mpeg",
+    "audio/ogg",
+    "audio/wav",
+    "audio/webm",
+    "image/apng",
+    "image/avif",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/svg+xml",
+    "image/webp",
+    "model/gltf-binary",
+    "text/csv",
+    "text/css",
+    "text/html",
+    "text/javascript",
+    "text/markdown",
+    "text/plain",
+    "text/python",
+    "text/typescript",
+    "text/vnd.mermaid",
+    "text/x-python",
+    "text/x-scss",
+    "text/x-sh",
+    "text/x-sql",
+    "video/mp4",
+    "video/ogg",
+    "video/webm",
+];
+const ATTACHMENT_MEDIA_TYPE_SET = new Set(ATTACHMENT_MEDIA_TYPES);
+export function attachmentFormatFor(input) {
+    const format = fileFormatFor(input);
+    return format === "unknown" ? null : format;
+}
+export function isSupportedAttachmentInput(input) {
+    return attachmentFormatFor(input) !== null;
+}
+export function isAttachmentMediaType(value) {
+    return ATTACHMENT_MEDIA_TYPE_SET.has(value);
+}
+export function attachmentMediaTypeFor(input, format = attachmentFormatFor(input)) {
+    if (!format)
+        return null;
+    const mimeInput = { name: "", mimeType: input.mimeType };
+    switch (format) {
+        case "image": {
+            const mediaType = imageMimeTypeFor(input) ?? imageMimeTypeFor(mimeInput) ??
+                normalizedMimeType(input.mimeType);
+            return isSupportedImageMimeType(mediaType) ? asAttachmentMediaType(mediaType) : null;
+        }
+        case "media":
+            return asAttachmentMediaType(mediaMimeTypeFor(input) ?? mediaMimeTypeFor(mimeInput) ?? canonicalMediaMimeType(input.mimeType));
+        case "html":
+            return asAttachmentMediaType(htmlMimeTypeFor(input) ?? htmlMimeTypeFor(mimeInput));
+        case "markdown":
+            return isSupportedMarkdownInput(input) || isSupportedMarkdownInput(mimeInput)
+                ? "text/markdown"
+                : null;
+        case "csv":
+            return asAttachmentMediaType(csvMimeTypeFor(input) ?? csvMimeTypeFor(mimeInput));
+        case "json":
+            return asAttachmentMediaType(jsonMimeTypeFor(input) ?? jsonMimeTypeFor(mimeInput));
+        case "jsonl":
+            return asAttachmentMediaType(jsonlMimeTypeFor(input) ?? jsonlMimeTypeFor(mimeInput));
+        case "docx":
+            return asAttachmentMediaType(docxMimeTypeFor(input) ?? docxMimeTypeFor(mimeInput));
+        case "xlsx":
+            return asAttachmentMediaType(xlsxMimeTypeFor(input) ?? xlsxMimeTypeFor(mimeInput));
+        case "ppt":
+            return asAttachmentMediaType(pptMimeTypeFor(input) ?? pptMimeTypeFor(mimeInput));
+        case "pdf":
+            return asAttachmentMediaType(pdfMimeTypeFor(input) ?? pdfMimeTypeFor(mimeInput));
+        case "glb":
+            return asAttachmentMediaType(glbMimeTypeFor(input) ?? glbMimeTypeFor(mimeInput));
+        case "wasm":
+            return asAttachmentMediaType(wasmMimeTypeFor(input) ?? wasmMimeTypeFor(mimeInput));
+        case "zip":
+            return isSupportedZipInput(input) || isSupportedZipInput(mimeInput) ? ZIP_MIME_TYPE : null;
+        case "drawio":
+            return asAttachmentMediaType(drawioMimeTypeFor(input) ?? drawioMimeTypeFor(mimeInput));
+        case "excalidraw":
+            return asAttachmentMediaType(excalidrawMimeTypeFor(input) ?? excalidrawMimeTypeFor(mimeInput));
+        case "svg":
+            return asAttachmentMediaType(svgMimeTypeFor(input) ?? svgMimeTypeFor(mimeInput));
+        case "mermaid":
+            return asAttachmentMediaType(mermaidMimeTypeFor(input) ?? mermaidMimeTypeFor(mimeInput));
+        case "notebook":
+            return NOTEBOOK_MIME_TYPE;
+        case "yaml":
+        case "toml":
+        case "xml": {
+            const configFormat = configMimeTypeFor(input) ?? configMimeTypeFor(mimeInput);
+            if (!configFormat)
+                return null;
+            return configFormat === "yaml"
+                ? "application/yaml"
+                : configFormat === "toml"
+                    ? "application/toml"
+                    : "application/xml";
+        }
+        case "code": {
+            if (!codeLanguageFor(input) && !codeLanguageFor(mimeInput))
+                return null;
+            const mediaType = normalizedCodeMimeType(input.mimeType);
+            return isCodeMimeType(mediaType) ? asAttachmentMediaType(mediaType) : "text/plain";
+        }
+        case "text":
+            return "text/plain";
+    }
+}
+function normalizedMimeType(value) {
+    return value?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function asAttachmentMediaType(value) {
+    return value && ATTACHMENT_MEDIA_TYPE_SET.has(value)
+        ? value
+        : null;
+}
+function isCodeMimeType(value) {
+    return value === "application/javascript" || value === "application/typescript" ||
+        value === "application/sql" || value === "text/css" || value === "text/javascript" ||
+        value === "text/python" || value === "text/typescript" || value === "text/x-python" ||
+        value === "text/x-scss" || value === "text/x-sh" || value === "text/x-sql" ||
+        value === "application/x-python" || value === "application/x-python-code" ||
+        value === "application/x-sh" || value === "application/x-sql" ||
+        value === "application/x-typescript";
+}

package/dist/file-renderers/src/attachment.d.ts

@@ -0,0 +1,17 @@
+import { type AttachmentFormat, type AttachmentMediaType } from "./attachment-format";
+import type { FileFormatInput } from "./file-format";
+export * from "./attachment-format";
+export type AttachmentImageMediaTypeReader = (bytes: Uint8Array) => Promise<string | null>;
+export type ValidatedAttachment = {
+    readonly format: AttachmentFormat;
+    readonly mediaType: AttachmentMediaType;
+};
+/**
+ * Validates the byte-level facts needed before an Attachment becomes durable.
+ * Renderer parsing remains responsible for parse diagnostics and format-specific
+ * preview errors; upload admission only rejects a format mismatch or unsafe
+ * container.
+ */
+export declare function validateAttachmentBytes(input: FileFormatInput & {
+    readonly bytes: Uint8Array;
+}, readImageMediaType: AttachmentImageMediaTypeReader): Promise<ValidatedAttachment | null>;

package/dist/file-renderers/src/attachment.js

@@ -0,0 +1,96 @@
+import { hasZipSignature, inspectSafeOoxml, isStrictUtf8 } from "../../utils/src/index.js";
+import { attachmentFormatFor, attachmentMediaTypeFor, isAttachmentMediaType, } from "./attachment-format";
+import { isSupportedImageMimeType } from "./image/mime";
+import { isValidMediaBytes } from "./media/validate";
+export * from "./attachment-format";
+/**
+ * Validates the byte-level facts needed before an Attachment becomes durable.
+ * Renderer parsing remains responsible for parse diagnostics and format-specific
+ * preview errors; upload admission only rejects a format mismatch or unsafe
+ * container.
+ */
+export async function validateAttachmentBytes(input, readImageMediaType) {
+    const format = attachmentFormatFor(input);
+    if (!format || input.bytes.byteLength === 0)
+        return null;
+    switch (format) {
+        case "image": {
+            const mediaType = normalizedMimeType(await readImageMediaType(input.bytes));
+            if (!isSupportedImageMimeType(mediaType) || !isAttachmentMediaType(mediaType))
+                return null;
+            return { format, mediaType };
+        }
+        case "docx":
+            if (!await safeOoxml(input.bytes, "docx"))
+                return null;
+            break;
+        case "xlsx":
+            if (!await safeOoxml(input.bytes, "xlsx"))
+                return null;
+            break;
+        case "ppt":
+            if (!await safeOoxml(input.bytes, "pptx"))
+                return null;
+            break;
+        case "pdf":
+            if (!hasAsciiPrefix(input.bytes, "%PDF-"))
+                return null;
+            break;
+        case "zip":
+            if (!hasZipSignature(input.bytes))
+                return null;
+            break;
+        case "glb":
+            if (!hasAsciiPrefix(input.bytes, "glTF") || input.bytes[4] !== 2)
+                return null;
+            break;
+        case "wasm":
+            if (!hasBytes(input.bytes, [0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
+                return null;
+            break;
+        case "media":
+            break;
+        default:
+            if (!isTextPayload(input.bytes))
+                return null;
+            break;
+    }
+    const mediaType = attachmentMediaTypeFor(input, format);
+    if (!mediaType)
+        return null;
+    if (format === "media" && !isValidMediaBytes(input.bytes, mediaType))
+        return null;
+    return { format, mediaType };
+}
+function normalizedMimeType(value) {
+    return value?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isTextPayload(bytes) {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe
+        ? "utf-16le"
+        : bytes[0] === 0xfe && bytes[1] === 0xff
+            ? "utf-16be"
+            : "utf-8";
+    try {
+        const text = new TextDecoder(encoding, { fatal: true, ignoreBOM: false }).decode(bytes);
+        return encoding !== "utf-8" || isStrictUtf8(bytes) ? !text.includes("\u0000") : false;
+    }
+    catch {
+        return false;
+    }
+}
+function hasAsciiPrefix(bytes, value) {
+    return hasBytes(bytes, [...value].map((character) => character.charCodeAt(0)));
+}
+function hasBytes(bytes, expected) {
+    return expected.every((value, index) => bytes[index] === value);
+}
+async function safeOoxml(bytes, kind) {
+    try {
+        await inspectSafeOoxml(bytes, kind);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/file-renderers/src/code/index.d.ts

@@ -0,0 +1,19 @@
+import type { FileRenderer, FrameDocumentModel, RendererInput } from "../contracts";
+import { type CodeLanguage } from "./mime";
+export { codeLanguageFor, type CodeLanguage } from "./mime";
+type CodeFrame = {
+    readonly text: string;
+    readonly language: CodeLanguage;
+};
+export type CodeModel = FrameDocumentModel<"code", CodeFrame>;
+export declare class UnsupportedCodeLanguageError extends Error {
+    readonly fileName: string;
+    readonly mimeType: string;
+    constructor(input: Pick<RendererInput<"code">, "name" | "mimeType">);
+}
+export declare function CodeDocument({ text, language, signal, }: {
+    readonly text: string;
+    readonly language: string;
+    readonly signal?: AbortSignal;
+}): import("react").JSX.Element;
+export declare const codeRenderer: FileRenderer<"code", CodeModel>;