@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/design-canvas-react/lazy.d.ts

@@ -1,6 +1,21 @@
-import 'react';
-export { a as DesignCanvasChromeLazy, c as DesignCanvasFullProps, d as DesignCanvasLazy } from '../lazy-DrkVyDpe.js';
-export { D as DesignCanvasProps } from '../command-stack-TNPWJCzW.js';
-import '../model-DnfO_PdJ.js';
-import '../operations-ByJ6yXOW.js';
-import '../theme/index.js';
+/**
+ * Lazy-loaded entry points for the design canvas editor. Products that do not
+ * need the editor on initial load import `DesignCanvasLazy` (the batteries-
+ * included composition) or `DesignCanvasChromeLazy` (raw chrome only) instead
+ * of importing the components directly. Each chunk loads on first render; a
+ * Suspense boundary in the product provides the fallback.
+ *
+ * `DesignCanvasLazy` — `DesignCanvasEditor`: chrome + workspace sharing one
+ *   command stack. This is what products mount.
+ *
+ * `DesignCanvasChromeLazy` — `DesignCanvas`: raw chrome with render-prop API.
+ *   Use when the product supplies its own `renderWorkspace` and `renderThumbnail`.
+ */
+import type { DesignCanvasFullProps } from './components/DesignCanvas';
+import type { DesignCanvasProps } from './contracts';
+export type { DesignCanvasFullProps };
+export type { DesignCanvasProps };
+/** Batteries-included editor: chrome + workspace on one shared stack. */
+export declare const DesignCanvasLazy: import("react").LazyExoticComponent<typeof import("./components").DesignCanvasEditor>;
+/** Raw chrome only — use when supplying a custom renderWorkspace/renderThumbnail. */
+export declare const DesignCanvasChromeLazy: import("react").LazyExoticComponent<typeof import("./components").DesignCanvas>;

package/dist/documents/docx.d.ts

@@ -0,0 +1,50 @@
+/**
+ * DOCX → plain text, one paragraph per line.
+ *
+ * The main document part is resolved through the OPC relationship graph
+ * (`_rels/.rels` → the `officeDocument` relationship's target) rather than
+ * assuming `word/document.xml`, because the part name is a producer's choice,
+ * not a constant.
+ *
+ * WordprocessingML text lives in `<w:t>` runs. Everything else is markup, with
+ * four exceptions that carry meaning a reader would otherwise lose: `<w:tab/>`,
+ * `<w:br/>`, `<w:cr/>`, and the paragraph boundary `</w:p>`. Two element bodies
+ * are deliberately DROPPED — `<w:instrText>` (field instruction codes such as
+ * `HYPERLINK "…"`, which are machinery, not prose) and `<w:delText>` (text a
+ * tracked-changes revision deleted; extracting it would show a reader words the
+ * author removed).
+ *
+ * One line per paragraph, not blank-line-separated paragraphs: extractors
+ * downstream match line-anchored patterns against form and contract text, so a
+ * predictable line structure is the useful shape.
+ */
+import type { DocumentOutcome, DocxExtractionDetail } from './types';
+import { type ReadZipEntryOptions } from './zip';
+/** Resolve XML character/entity references. Unknown entities are left verbatim
+ *  rather than dropped, so nothing silently disappears from a document. */
+export declare function decodeXmlEntities(input: string): string;
+export interface DocxText {
+    readonly text: string;
+    readonly paragraphCount: number;
+}
+/**
+ * Walk WordprocessingML and emit its readable text.
+ *
+ * Hand-scanned rather than regex-split because comments and CDATA sections may
+ * contain `>`; a `/<[^>]*>/` scan ends the tag early on the first one and
+ * corrupts everything after it.
+ */
+export declare function wordprocessingXmlToText(xml: string): DocxText;
+/**
+ * Extract the readable text of a `.docx` / `.docm` package. Every failure names
+ * the archive-level cause; a package this cannot read is an error, never an
+ * empty document.
+ *
+ * `zip.maxUncompressedBytes` bounds what each part may expand to. It defaults
+ * to the zip reader's own ceiling, which is what keeps a deflate bomb inside a
+ * small `.docx` a typed error instead of an out-of-memory crash.
+ */
+export declare function extractDocxText(bytes: Uint8Array, mediaType: string, zip?: ReadZipEntryOptions): Promise<DocumentOutcome<{
+    text: string;
+    detail: DocxExtractionDetail;
+}>>;

package/dist/documents/extract.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The extraction pipeline: size gate → media type → (PDF: classify, then
+ * extract) / (DOCX: OPC read) / (text: strict decode).
+ *
+ * Two rules make this safe to build a product on.
+ *
+ * 1. **Classify before extracting a PDF.** The wasm engine's `extractText`
+ *    panics (`RuntimeError: unreachable`) on any page with no text layer, and
+ *    that is measured, not theoretical — including on `mixed` documents where
+ *    only ONE page is an image. Classification runs first and decides whether
+ *    extraction is even reachable, which is also what produces the OCR signal.
+ * 2. **A scanned PDF is `pdf-needs-ocr`, never an empty string.** Both hand-
+ *    rolled predecessors of this module got this right and it is the single
+ *    behaviour a product cannot afford to lose: silent empty text lets a
+ *    downstream model answer confidently about a document nobody read.
+ */
+import type { DocumentOutcome, ExtractedDocument, PdfClassification, PdfEngine, PdfTextFormat } from './types';
+/** 25 MB — the cap both predecessor implementations converged on, and roughly
+ *  the point where a Worker's memory budget stops tolerating a full decode. */
+export declare const DEFAULT_MAX_DOCUMENT_BYTES: number;
+export interface ExtractDocumentOptions {
+    /** The type the upload declared. Falls back to `filename`'s extension when
+     *  missing or `application/octet-stream`. */
+    readonly mediaType?: string;
+    /** Used to resolve the media type, and named in error messages. */
+    readonly filename?: string;
+    /** Required to extract PDFs. Supplied by the caller because the wasm asset
+     *  must come from the consumer's bundler — see
+     *  `@tangle-network/agent-app/documents/pdf-inspector`. */
+    readonly pdf?: PdfEngine;
+    /** Byte cap on the uploaded ARCHIVE, default
+     *  {@link DEFAULT_MAX_DOCUMENT_BYTES}. */
+    readonly maxBytes?: number;
+    /**
+     * Byte cap on what any ONE part of an Office package may expand to, default
+     * {@link DEFAULT_MAX_ZIP_ENTRY_BYTES}.
+     *
+     * A separate dial from {@link maxBytes} because they bound different things:
+     * deflate reaches ~1000:1 on repetitive input, so capping the upload does
+     * nothing to cap the decompression it asks for.
+     */
+    readonly maxUncompressedPartBytes?: number;
+    /**
+     * Plain text (default) preserves source line breaks, which line-anchored
+     * parsers depend on; markdown carries headings and page markers but reflows
+     * lines into paragraphs.
+     *
+     * A *preference*, because of exactly one measured case: on a partially
+     * scanned PDF the plain-text engine panics, and only the markdown engine can
+     * recover the pages that do have text. The result reports what you actually
+     * got in {@link PdfExtractionDetail.textFormat} — check it when the
+     * distinction matters.
+     */
+    readonly preferredPdfFormat?: PdfTextFormat;
+}
+/**
+ * Classify a PDF: whether it has a text layer, and which pages do not.
+ *
+ * Safe on every input — classification is what makes extraction safe, so it can
+ * never be the thing that panics. Call this directly when a product wants to
+ * show "3 of 40 pages need OCR" before deciding to extract.
+ */
+export declare function classifyPdfDocument(bytes: Uint8Array, pdf: PdfEngine): DocumentOutcome<PdfClassification>;
+/**
+ * Extract a document's text.
+ *
+ * Every failure is a typed {@link DocumentExtractionError} naming the stage it
+ * stopped at; nothing throws, and success never carries empty text.
+ */
+export declare function extractDocument(input: ArrayBuffer | Uint8Array, options?: ExtractDocumentOptions): Promise<DocumentOutcome<ExtractedDocument>>;
+export interface DocumentExtractorConfig {
+    readonly pdf?: PdfEngine;
+    readonly maxBytes?: number;
+    readonly maxUncompressedPartBytes?: number;
+    readonly preferredPdfFormat?: PdfTextFormat;
+}
+export interface DocumentExtractor {
+    readonly extract: (input: ArrayBuffer | Uint8Array, options?: Omit<ExtractDocumentOptions, 'pdf' | 'maxBytes' | 'maxUncompressedPartBytes' | 'preferredPdfFormat'>) => Promise<DocumentOutcome<ExtractedDocument>>;
+    /** Classify a PDF without extracting. Fails with `pdf-engine-unavailable`
+     *  when the extractor was built without a PDF engine. */
+    readonly classifyPdf: (input: ArrayBuffer | Uint8Array) => DocumentOutcome<PdfClassification>;
+}
+/**
+ * Bind an engine and limits once, at worker start, so call sites read
+ * `documents.extract(bytes, { mediaType })` and never re-wire the wasm.
+ */
+export declare function createDocumentExtractor(config?: DocumentExtractorConfig): DocumentExtractor;

package/dist/documents/index.d.ts

@@ -1,233 +1,27 @@
-import { P as PdfEngine, a as PdfTextFormat, D as DocumentOutcome, E as ExtractedDocument, b as PdfClassification, c as DocxExtractionDetail, d as DocumentFormat } from '../types-DrBidf3O.js';
-export { e as DocumentExtractionError, f as DocumentExtractionErrorCode, g as DocumentExtractionStage, h as PdfContentKind, i as PdfExtractionDetail, j as PdfPageClassification } from '../types-DrBidf3O.js';
-
 /**
- * The extraction pipeline: size gate → media type → (PDF: classify, then
- * extract) / (DOCX: OPC read) / (text: strict decode).
- *
- * Two rules make this safe to build a product on.
- *
- * 1. **Classify before extracting a PDF.** The wasm engine's `extractText`
- *    panics (`RuntimeError: unreachable`) on any page with no text layer, and
- *    that is measured, not theoretical — including on `mixed` documents where
- *    only ONE page is an image. Classification runs first and decides whether
- *    extraction is even reachable, which is also what produces the OCR signal.
- * 2. **A scanned PDF is `pdf-needs-ocr`, never an empty string.** Both hand-
- *    rolled predecessors of this module got this right and it is the single
- *    behaviour a product cannot afford to lose: silent empty text lets a
- *    downstream model answer confidently about a document nobody read.
- */
-
-/** 25 MB — the cap both predecessor implementations converged on, and roughly
- *  the point where a Worker's memory budget stops tolerating a full decode. */
-declare const DEFAULT_MAX_DOCUMENT_BYTES: number;
-interface ExtractDocumentOptions {
-    /** The type the upload declared. Falls back to `filename`'s extension when
-     *  missing or `application/octet-stream`. */
-    readonly mediaType?: string;
-    /** Used to resolve the media type, and named in error messages. */
-    readonly filename?: string;
-    /** Required to extract PDFs. Supplied by the caller because the wasm asset
-     *  must come from the consumer's bundler — see
-     *  `@tangle-network/agent-app/documents/pdf-inspector`. */
-    readonly pdf?: PdfEngine;
-    /** Byte cap on the uploaded ARCHIVE, default
-     *  {@link DEFAULT_MAX_DOCUMENT_BYTES}. */
-    readonly maxBytes?: number;
-    /**
-     * Byte cap on what any ONE part of an Office package may expand to, default
-     * {@link DEFAULT_MAX_ZIP_ENTRY_BYTES}.
-     *
-     * A separate dial from {@link maxBytes} because they bound different things:
-     * deflate reaches ~1000:1 on repetitive input, so capping the upload does
-     * nothing to cap the decompression it asks for.
-     */
-    readonly maxUncompressedPartBytes?: number;
-    /**
-     * Plain text (default) preserves source line breaks, which line-anchored
-     * parsers depend on; markdown carries headings and page markers but reflows
-     * lines into paragraphs.
-     *
-     * A *preference*, because of exactly one measured case: on a partially
-     * scanned PDF the plain-text engine panics, and only the markdown engine can
-     * recover the pages that do have text. The result reports what you actually
-     * got in {@link PdfExtractionDetail.textFormat} — check it when the
-     * distinction matters.
-     */
-    readonly preferredPdfFormat?: PdfTextFormat;
-}
-/**
- * Classify a PDF: whether it has a text layer, and which pages do not.
- *
- * Safe on every input — classification is what makes extraction safe, so it can
- * never be the thing that panics. Call this directly when a product wants to
- * show "3 of 40 pages need OCR" before deciding to extract.
- */
-declare function classifyPdfDocument(bytes: Uint8Array, pdf: PdfEngine): DocumentOutcome<PdfClassification>;
-/**
- * Extract a document's text.
- *
- * Every failure is a typed {@link DocumentExtractionError} naming the stage it
- * stopped at; nothing throws, and success never carries empty text.
- */
-declare function extractDocument(input: ArrayBuffer | Uint8Array, options?: ExtractDocumentOptions): Promise<DocumentOutcome<ExtractedDocument>>;
-interface DocumentExtractorConfig {
-    readonly pdf?: PdfEngine;
-    readonly maxBytes?: number;
-    readonly maxUncompressedPartBytes?: number;
-    readonly preferredPdfFormat?: PdfTextFormat;
-}
-interface DocumentExtractor {
-    readonly extract: (input: ArrayBuffer | Uint8Array, options?: Omit<ExtractDocumentOptions, 'pdf' | 'maxBytes' | 'maxUncompressedPartBytes' | 'preferredPdfFormat'>) => Promise<DocumentOutcome<ExtractedDocument>>;
-    /** Classify a PDF without extracting. Fails with `pdf-engine-unavailable`
-     *  when the extractor was built without a PDF engine. */
-    readonly classifyPdf: (input: ArrayBuffer | Uint8Array) => DocumentOutcome<PdfClassification>;
-}
-/**
- * Bind an engine and limits once, at worker start, so call sites read
- * `documents.extract(bytes, { mediaType })` and never re-wire the wasm.
- */
-declare function createDocumentExtractor(config?: DocumentExtractorConfig): DocumentExtractor;
-
-/**
- * The slice of PKZIP an OOXML package needs: read the central directory, then
- * inflate one named entry.
- *
- * Why not a zip library: DOCX text extraction is the only reason this module
- * needs a zip, and the runtime already supplies the hard part —
- * `DecompressionStream('deflate-raw')` is a standard API present in workerd
- * and in Node, so the whole reader is header arithmetic plus a stream. Pulling
- * a zip package in would put ten transitive Node-shaped dependencies into every
- * consumer's Worker bundle to avoid ~120 lines.
- *
- * The CENTRAL DIRECTORY is the source of truth, not the local headers: an
- * archive written with data descriptors (streamed output) carries zeros for
- * the sizes in its local headers, and reading those is the classic way a
- * hand-rolled zip reader silently returns nothing.
- */
-type ZipOutcome<T> = {
-    succeeded: true;
-    value: T;
-} | {
-    succeeded: false;
-    error: string;
-};
-interface ZipEntry {
-    readonly name: string;
-    readonly compressionMethod: number;
-    readonly compressedSize: number;
-    readonly uncompressedSize: number;
-    readonly localHeaderOffset: number;
-    readonly encrypted: boolean;
-}
-/** Read every central-directory entry. Names are decoded as UTF-8, which is
- *  what OOXML producers write (general-purpose bit 11). */
-declare function readZipDirectory(bytes: Uint8Array): ZipOutcome<ZipEntry[]>;
-/**
- * Ceiling on what ONE entry may expand to. A deflate stream reaches ~1000:1 on
- * repetitive input, so an archive small enough to pass any upload gate can ask
- * for gigabytes: measured here, a 305,893-byte archive declared a single entry
- * expanding to 314,572,800 bytes. A Cloudflare Worker isolate has 128 MB, so
- * that is an out-of-memory crash, not a slow path — and a crash is not a typed
- * error a product can report. 32 MB is far past any real Office part (the main
- * document of a 400-page contract is single-digit MB) and far under the
- * isolate's budget.
- */
-declare const DEFAULT_MAX_ZIP_ENTRY_BYTES: number;
-/** Options for {@link readZipEntry}. */
-interface ReadZipEntryOptions {
-    /** Ceiling on the entry's UNCOMPRESSED size. Defaults to
-     *  {@link DEFAULT_MAX_ZIP_ENTRY_BYTES}. Checked against the directory's
-     *  declared size before any inflate runs, and again against the real output
-     *  as it streams, because the declared size is the archive's claim. */
-    readonly maxUncompressedBytes?: number;
-}
-/** Inflate one entry's bytes. The local header supplies only the variable-length
- *  field sizes needed to find the payload; sizes come from the directory. */
-declare function readZipEntry(bytes: Uint8Array, entry: ZipEntry, options?: ReadZipEntryOptions): Promise<ZipOutcome<Uint8Array>>;
-
-/**
- * DOCX → plain text, one paragraph per line.
- *
- * The main document part is resolved through the OPC relationship graph
- * (`_rels/.rels` → the `officeDocument` relationship's target) rather than
- * assuming `word/document.xml`, because the part name is a producer's choice,
- * not a constant.
- *
- * WordprocessingML text lives in `<w:t>` runs. Everything else is markup, with
- * four exceptions that carry meaning a reader would otherwise lose: `<w:tab/>`,
- * `<w:br/>`, `<w:cr/>`, and the paragraph boundary `</w:p>`. Two element bodies
- * are deliberately DROPPED — `<w:instrText>` (field instruction codes such as
- * `HYPERLINK "…"`, which are machinery, not prose) and `<w:delText>` (text a
- * tracked-changes revision deleted; extracting it would show a reader words the
- * author removed).
- *
- * One line per paragraph, not blank-line-separated paragraphs: extractors
- * downstream match line-anchored patterns against form and contract text, so a
- * predictable line structure is the useful shape.
- */
-
-/** Resolve XML character/entity references. Unknown entities are left verbatim
- *  rather than dropped, so nothing silently disappears from a document. */
-declare function decodeXmlEntities(input: string): string;
-interface DocxText {
-    readonly text: string;
-    readonly paragraphCount: number;
-}
-/**
- * Walk WordprocessingML and emit its readable text.
- *
- * Hand-scanned rather than regex-split because comments and CDATA sections may
- * contain `>`; a `/<[^>]*>/` scan ends the tag early on the first one and
- * corrupts everything after it.
- */
-declare function wordprocessingXmlToText(xml: string): DocxText;
-/**
- * Extract the readable text of a `.docx` / `.docm` package. Every failure names
- * the archive-level cause; a package this cannot read is an error, never an
- * empty document.
- *
- * `zip.maxUncompressedBytes` bounds what each part may expand to. It defaults
- * to the zip reader's own ceiling, which is what keeps a deflate bomb inside a
- * small `.docx` a typed error instead of an out-of-memory crash.
- */
-declare function extractDocxText(bytes: Uint8Array, mediaType: string, zip?: ReadZipEntryOptions): Promise<DocumentOutcome<{
-    text: string;
-    detail: DocxExtractionDetail;
-}>>;
-
-/**
- * Media type → extraction format. Resolution order is declared type first,
- * filename extension second (products routinely receive `application/octet-stream`
- * from a browser upload), and nothing else — byte sniffing belongs to the
- * upload gate that reads untrusted bytes, not to the extractor that has already
- * been handed a decision.
- */
-
-/** OOXML WordprocessingML — the `.docx` a word processor writes. */
-declare const DOCX_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
-/** Macro-enabled WordprocessingML (`.docm`). Same part structure, so text
- *  extraction is identical; the VBA project is never read or executed. */
-declare const DOCM_MEDIA_TYPE = "application/vnd.ms-word.document.macroEnabled.12";
-declare const PDF_MEDIA_TYPE = "application/pdf";
-interface ResolvedMediaType {
-    readonly format: DocumentFormat;
-    /** Canonical media type for the resolved format. */
-    readonly mediaType: string;
-}
-/** Strip parameters and case from a media type: `Text/Plain; charset=utf-8` →
- *  `text/plain`. */
-declare function normalizeMediaType(mediaType: string): string;
-interface ResolveMediaTypeInput {
-    /** The type the upload declared. May be empty or `application/octet-stream`. */
-    readonly mediaType?: string;
-    /** Consulted only when `mediaType` is missing or generic. */
-    readonly filename?: string;
-}
-/**
- * Decide which extractor handles these bytes. Fails loud rather than guessing:
- * an unrecognized type names itself and lists what is supported.
- */
-declare function resolveMediaType(input: ResolveMediaTypeInput): DocumentOutcome<ResolvedMediaType>;
-
-export { DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_ZIP_ENTRY_BYTES, DOCM_MEDIA_TYPE, DOCX_MEDIA_TYPE, type DocumentExtractor, type DocumentExtractorConfig, DocumentFormat, DocumentOutcome, DocxExtractionDetail, type DocxText, type ExtractDocumentOptions, ExtractedDocument, PDF_MEDIA_TYPE, PdfClassification, PdfEngine, PdfTextFormat, type ReadZipEntryOptions, type ResolveMediaTypeInput, type ResolvedMediaType, type ZipEntry, type ZipOutcome, classifyPdfDocument, createDocumentExtractor, decodeXmlEntities, extractDocument, extractDocxText, normalizeMediaType, readZipDirectory, readZipEntry, resolveMediaType, wordprocessingXmlToText };
+ * Document text extraction — the upload-side capability every vertical needs
+ * before a model can read anything a user sends: PDF, DOCX, and text in, plain
+ * text plus a stage-named failure out.
+ *
+ * **This entry imports nothing.** The PDF engine arrives through the
+ * {@link PdfEngine} seam because its wasm has to be a build-time asset from the
+ * consumer's own bundler; `@tangle-network/agent-app/documents/pdf-inspector`
+ * is the shipped implementation, on its own subpath so a product that handles
+ * only DOCX and text never installs the wasm package. DOCX needs no dependency
+ * at all — `DecompressionStream` is a runtime API in both workerd and Node.
+ *
+ * **The scanned-PDF contract.** A PDF with no text layer fails with
+ * `pdf-needs-ocr` carrying the page-level classification. It is never an empty
+ * string: a product that receives `''` from a scan will happily let a model
+ * answer questions about a document nobody read. OCR itself is NOT here — it
+ * belongs to the sandbox image (ocrmypdf/tesseract), and this module's job is
+ * to hand the caller a signal precise enough to route to it.
+ *
+ * Wiring, including the exact Cloudflare vite-plugin wasm delivery, is in
+ * `docs/documents-module.md`.
+ */
+export { classifyPdfDocument, createDocumentExtractor, DEFAULT_MAX_DOCUMENT_BYTES, extractDocument, type DocumentExtractor, type DocumentExtractorConfig, type ExtractDocumentOptions, } from './extract';
+export { decodeXmlEntities, extractDocxText, wordprocessingXmlToText, type DocxText } from './docx';
+export { DOCM_MEDIA_TYPE, DOCX_MEDIA_TYPE, normalizeMediaType, PDF_MEDIA_TYPE, resolveMediaType, type ResolvedMediaType, type ResolveMediaTypeInput, } from './media-type';
+export { DEFAULT_MAX_ZIP_ENTRY_BYTES, readZipDirectory, readZipEntry, type ReadZipEntryOptions, type ZipEntry, type ZipOutcome, } from './zip';
+export type { DocumentExtractionError, DocumentExtractionErrorCode, DocumentExtractionStage, DocumentFormat, DocumentOutcome, DocxExtractionDetail, ExtractedDocument, PdfClassification, PdfContentKind, PdfEngine, PdfExtractionDetail, PdfPageClassification, PdfTextFormat, } from './types';

package/dist/documents/media-type.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Media type → extraction format. Resolution order is declared type first,
+ * filename extension second (products routinely receive `application/octet-stream`
+ * from a browser upload), and nothing else — byte sniffing belongs to the
+ * upload gate that reads untrusted bytes, not to the extractor that has already
+ * been handed a decision.
+ */
+import type { DocumentFormat, DocumentOutcome } from './types';
+/** OOXML WordprocessingML — the `.docx` a word processor writes. */
+export declare const DOCX_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** Macro-enabled WordprocessingML (`.docm`). Same part structure, so text
+ *  extraction is identical; the VBA project is never read or executed. */
+export declare const DOCM_MEDIA_TYPE = "application/vnd.ms-word.document.macroEnabled.12";
+export declare const PDF_MEDIA_TYPE = "application/pdf";
+export interface ResolvedMediaType {
+    readonly format: DocumentFormat;
+    /** Canonical media type for the resolved format. */
+    readonly mediaType: string;
+}
+/** Strip parameters and case from a media type: `Text/Plain; charset=utf-8` →
+ *  `text/plain`. */
+export declare function normalizeMediaType(mediaType: string): string;
+export interface ResolveMediaTypeInput {
+    /** The type the upload declared. May be empty or `application/octet-stream`. */
+    readonly mediaType?: string;
+    /** Consulted only when `mediaType` is missing or generic. */
+    readonly filename?: string;
+}
+/**
+ * Decide which extractor handles these bytes. Fails loud rather than guessing:
+ * an unrecognized type names itself and lists what is supported.
+ */
+export declare function resolveMediaType(input: ResolveMediaTypeInput): DocumentOutcome<ResolvedMediaType>;

package/dist/documents/pdf-inspector.d.ts

@@ -1,5 +1,3 @@
-import { P as PdfEngine, D as DocumentOutcome } from '../types-DrBidf3O.js';
-
 /**
  * The wasm-backed {@link PdfEngine}, binding `@firecrawl/pdf-inspector-wasm`
  * (MIT, Rust→wasm).
@@ -34,27 +32,25 @@ import { P as PdfEngine, D as DocumentOutcome } from '../types-DrBidf3O.js';
  *   of a fully text-based 2-page PDF as needing OCR — so the classification a
  *   caller sees always comes from `detectPdf`.
  */
-
+import type { DocumentOutcome, PdfEngine } from './types';
 /**
  * The compiled wasm, or a thunk that produces it on first use.
  *
  * A Worker passes the `.wasm` module import (a `WebAssembly.Module`); Node
  * passes raw bytes. A thunk defers reading either until a PDF actually arrives.
  */
-type PdfInspectorWasm = WebAssembly.Module | BufferSource | (() => WebAssembly.Module | BufferSource);
+export type PdfInspectorWasm = WebAssembly.Module | BufferSource | (() => WebAssembly.Module | BufferSource);
 /** Instantiate the engine for this isolate. Idempotent; safe to call per
  *  request. Exported so a product can warm the wasm at startup instead of
  *  paying instantiation on a user's first upload. */
-declare function initPdfInspector(wasm: PdfInspectorWasm): DocumentOutcome<{
+export declare function initPdfInspector(wasm: PdfInspectorWasm): DocumentOutcome<{
     version: string;
 }>;
 /** Whether the engine has been instantiated in this isolate. */
-declare function isPdfInspectorReady(): boolean;
+export declare function isPdfInspectorReady(): boolean;
 /**
  * Build the wasm-backed engine. Instantiation is lazy — the first classify or
  * extract call initializes it — so importing this costs nothing until a PDF
  * arrives.
  */
-declare function createPdfInspectorEngine(wasm: PdfInspectorWasm): PdfEngine;
-
-export { type PdfInspectorWasm, createPdfInspectorEngine, initPdfInspector, isPdfInspectorReady };
+export declare function createPdfInspectorEngine(wasm: PdfInspectorWasm): PdfEngine;

package/dist/{types-DrBidf3O.d.ts → documents/types.d.ts}

@@ -4,10 +4,10 @@
  * port that keeps the wasm binding out of this module's import graph.
  */
 /** What kind of extraction a media type routes to. */
-type DocumentFormat = 'pdf' | 'docx' | 'text';
+export type DocumentFormat = 'pdf' | 'docx' | 'text';
 /** Where extraction stopped. Surfaced on every error so a product can tell a
  *  user WHERE it failed rather than "extraction failed". */
-type DocumentExtractionStage = 'size-check' | 'media-type' | 'classify' | 'extract' | 'decode';
+export type DocumentExtractionStage = 'size-check' | 'media-type' | 'classify' | 'extract' | 'decode';
 /**
  * Why extraction stopped.
  *
@@ -16,8 +16,8 @@ type DocumentExtractionStage = 'size-check' | 'media-type' | 'classify' | 'extra
  * and never a generic failure — a caller matches on it to offer the OCR path
  * (see {@link PdfClassification.pagesNeedingOcr} for which pages).
  */
-type DocumentExtractionErrorCode = 'too-large' | 'unsupported-media-type' | 'pdf-engine-unavailable' | 'pdf-needs-ocr' | 'classification-failed' | 'extraction-failed' | 'malformed-archive' | 'decode-failed' | 'empty-document';
-interface DocumentExtractionError {
+export type DocumentExtractionErrorCode = 'too-large' | 'unsupported-media-type' | 'pdf-engine-unavailable' | 'pdf-needs-ocr' | 'classification-failed' | 'extraction-failed' | 'malformed-archive' | 'decode-failed' | 'empty-document';
+export interface DocumentExtractionError {
     readonly code: DocumentExtractionErrorCode;
     readonly stage: DocumentExtractionStage;
     /** Human-readable and safe to show a user: names the stage's cause. */
@@ -27,7 +27,7 @@ interface DocumentExtractionError {
     /** Present on `pdf-needs-ocr` — the page-level detail the OCR handoff needs. */
     readonly classification?: PdfClassification;
 }
-type DocumentOutcome<T> = {
+export type DocumentOutcome<T> = {
     succeeded: true;
     value: T;
 } | {
@@ -44,8 +44,8 @@ type DocumentOutcome<T> = {
  *   need OCR).
  * - `mixed` — some pages have text, some do not.
  */
-type PdfContentKind = 'text-based' | 'scanned' | 'image-based' | 'mixed';
-interface PdfPageClassification {
+export type PdfContentKind = 'text-based' | 'scanned' | 'image-based' | 'mixed';
+export interface PdfPageClassification {
     /** 1-indexed, the number a person sees in a viewer. */
     readonly pageNumber: number;
     /** 0-indexed, for array math. */
@@ -56,7 +56,7 @@ interface PdfPageClassification {
     readonly hasTable: boolean;
     readonly hasColumns: boolean;
 }
-interface PdfClassification {
+export interface PdfClassification {
     readonly kind: PdfContentKind;
     readonly pageCount: number;
     /** Engine confidence in `kind`, 0..1. */
@@ -76,7 +76,7 @@ interface PdfClassification {
 }
 /** Plain text preserves the source's line breaks; markdown carries structure
  *  (headings, page markers) but reflows lines into paragraphs. */
-type PdfTextFormat = 'text' | 'markdown';
+export type PdfTextFormat = 'text' | 'markdown';
 /**
  * The seam that keeps `@firecrawl/pdf-inspector-wasm` out of this module.
  *
@@ -86,14 +86,14 @@ type PdfTextFormat = 'text' | 'markdown';
  * caller; `@tangle-network/agent-app/documents/pdf-inspector` ships the one
  * that binds the firecrawl engine.
  */
-interface PdfEngine {
+export interface PdfEngine {
     /** Must not panic on scanned input — classification is what makes extraction
      *  safe, so it runs first on every document. */
     readonly classify: (bytes: Uint8Array) => DocumentOutcome<PdfClassification>;
     /** Called only after `classify` says the requested pages carry text. */
     readonly extract: (bytes: Uint8Array, format: PdfTextFormat) => DocumentOutcome<string>;
 }
-interface PdfExtractionDetail {
+export interface PdfExtractionDetail {
     readonly classification: PdfClassification;
     /** What the text actually is — see {@link ExtractDocumentOptions.preferredPdfFormat}
      *  for the one case where it differs from what was asked for. */
@@ -101,12 +101,12 @@ interface PdfExtractionDetail {
     /** Text came from a subset of pages; the rest need OCR. */
     readonly partial: boolean;
 }
-interface DocxExtractionDetail {
+export interface DocxExtractionDetail {
     /** The OPC part the text came from, resolved through `_rels/.rels`. */
     readonly part: string;
     readonly paragraphCount: number;
 }
-interface ExtractedDocument {
+export interface ExtractedDocument {
     /** Never empty — an empty extraction is the `empty-document` error instead. */
     readonly text: string;
     readonly format: DocumentFormat;
@@ -119,5 +119,3 @@ interface ExtractedDocument {
     /** Non-fatal facts the caller should surface (e.g. pages left un-OCR'd). */
     readonly warnings: readonly string[];
 }
-
-export type { DocumentOutcome as D, ExtractedDocument as E, PdfEngine as P, PdfTextFormat as a, PdfClassification as b, DocxExtractionDetail as c, DocumentFormat as d, DocumentExtractionError as e, DocumentExtractionErrorCode as f, DocumentExtractionStage as g, PdfContentKind as h, PdfExtractionDetail as i, PdfPageClassification as j };