tabulark 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to Tabulark are documented here. The project follows
+[Semantic Versioning](https://semver.org/); public JavaScript entry points are
+additive-only throughout the 0.1.x line.
+
+## 0.1.0
+
+- Establish the stable browser-facing API and the official local-format adapter
+  host.
+- Add local Apache Parquet and Excel (BIFF8/XLSX) preview adapters.
+- Add spreadsheet presentation metadata for the Canvas view.
+
+## 0.0.4
+
+Published before the 0.1.0 release train.

package/README.md

@@ -1,157 +1,262 @@
 # Tabulark
 
-> A WebAssembly-first engine for fast, format-agnostic tabular data preview in the browser.
+> **Status: M4 complete; 0.1.0 release candidate in progress.** The M4
+> CSV/TSV and Apache Arrow IPC milestone completed at `1d79837`, including CI,
+> GitHub Pages, and a deployed-URL smoke. The package has not yet been published
+> as 0.1.0; see the [M4 completion record](docs/m4-completion.md) and the
+> [release policy](docs/releasing.md).
 
-**One table model for every tabular source.**
+Tabulark is a WebAssembly-first browser primitive for previewing local tabular
+data without uploading it. A module Worker owns parsing, bounded byte access,
+adapter state, cancellation, and cleanup. A Canvas viewport renders visible
+cells while a bounded semantic grid supplies keyboard and screen-reader access.
 
-**Status: pre-alpha design and prototyping.**
+[Try the playground](https://ronbb.github.io/tabulark/) · [Architecture](docs/architecture.md) · [API stability](docs/api-stability.md) · [Testing](docs/testing.md)
 
-> [!IMPORTANT]
-> Tabulark is currently in the design and prototyping stage. There is no stable
-> public API or production-ready release yet. The architecture, formats, and
-> performance characteristics described below are goals, not shipped features.
+## Supported local formats
 
-## Why Tabulark?
+The 0.1.0 source tree contains four immutable official adapters. Each adapter
+is a separate, lazily loaded WebAssembly artifact; creating an engine loads no
+WASM and opening one format does not fetch unused artifacts.
 
-Tabular data reaches web applications through many formats, but preview
-interfaces repeatedly reimplement parsing, data transfer, caching, and
-rendering for each one.
+| Format | Official ID | Stable entry point | 0.1 contract |
+| --- | --- | --- | --- |
+| CSV/TSV | `tabulark:delimited` | `tabulark` | Explicit delimiter, header, and strict/lenient modes |
+| Arrow IPC | `tabulark:arrow-ipc` | `tabulark/arrow` | File/Stream; none, LZ4, and Zstd IPC compression |
+| Parquet | `tabulark:parquet` | `tabulark/parquet` | Range-driven row-group/column projection and the documented codec set |
+| Excel | `tabulark:excel` | `tabulark/excel` | Excel 97–2003 BIFF8 XLS and OOXML XLSX, including static presentation |
 
-Tabulark is being designed as composable browser infrastructure that presents
-those sources through one format-agnostic `Table` model. It is a preview engine,
-not a spreadsheet application.
+Remote sources, arbitrary adapter/module URLs, public third-party adapters,
+persistent caches, formula calculation, editing, and document-level Excel
+round-tripping are outside 0.1.
 
-## Design principles
+## Install and build
 
-- One `Table` abstraction for every supported data source.
-- Independently loadable source adapters, including format-specific parsers.
-- Parsing and data ownership outside the browser main thread, with WebAssembly
-  as the primary runtime for performance-sensitive components.
-- Demand-driven access instead of copying an entire dataset into JavaScript.
-- Viewport-oriented rendering, with Canvas as the first planned renderer.
-- Framework-neutral, composable building blocks.
+The npm package has no production JavaScript dependencies. It targets modern
+Chromium and requires Node 20 or newer to build from source. Rust 1.85 is the
+minimum supported Rust version.
 
-## Target architecture
+```sh
+npm ci
+npm run build
+npm run check
+npm run test:browser
+```
 
-```text
-Data source
-    -> source adapter
-    -> Worker / WebAssembly runtime
-    -> unified Table model and cache
-    -> viewport query API
-    -> renderer
-    -> application UI
+`npm run build` creates five public JavaScript entry points, a generic Worker,
+and independent Delimited, Arrow, Parquet, and Excel WASM artifacts under
+`dist/wasm/`.
+
+## Stable JavaScript API
+
+Register only the adapters an engine may use. The allow-list is immutable for
+that engine's lifetime, and the only accepted source inputs are `File`, `Blob`,
+and `ArrayBuffer`.
+
+```ts
+import { createEngine, delimitedAdapter } from "tabulark";
+import { arrowIpcAdapter } from "tabulark/arrow";
+import { parquetAdapter } from "tabulark/parquet";
+import { excelAdapter } from "tabulark/excel";
+
+const engine = await createEngine({
+  adapters: [delimitedAdapter, arrowIpcAdapter, parquetAdapter, excelAdapter],
+});
+
+const csv = await engine.open(csvFile, {
+  adapter: delimitedAdapter,
+  adapterOptions: {
+    dialect: "csv",
+    header: "first-row",
+    mode: "lenient",
+  },
+});
+
+const parquet = await engine.open(parquetFile, {
+  adapter: parquetAdapter,
+  adapterOptions: { sourceName: parquetFile.name },
+});
+
+const workbook = await engine.open(excelFile, {
+  adapter: excelAdapter,
+  adapterOptions: { format: "auto", sourceName: excelFile.name },
+});
 ```
 
-This architecture is intentionally provisional while the first end-to-end
-prototype is being developed.
+Adapter selection is explicit. Excel's `format: "auto"` and Arrow's
+`container: "auto"` inspect source bytes; filename extensions never select or
+authenticate a format.
+
+`ArrayBuffer` ownership is retained by default. Set `transferInput: true` only
+when intentionally detaching an `ArrayBuffer`; using it with a `Blob` or
+`File` returns `INVALID_ARGUMENT`.
+
+### Tables, logical batches, and presentation
+
+```ts
+const table = await workbook.openTable(workbook.tables[0].id);
+const batch = await table.readRange({
+  rowStart: 0,
+  rowCount: 100,
+  columnStart: 0,
+  columnCount: table.metadata.schema.columns.length,
+});
+
+const nativeRows = batch.toRows();
+const displayRows = batch.toDisplayRows();
+const presentation = await table.getPresentation();
+const visiblePresentation = await table.readPresentationRange(batch.range);
+```
 
-## Current scaffold
+The stable `TableBatch` exposes logical data, its returned range, columns, and
+logical accessors. WASM buffer regions, wire descriptors, protocol versions,
+adapter ABI versions, and physical batch layout are private implementation
+details.
+
+`toRows()` preserves native values such as `bigint`, `Uint8Array`, decimals,
+temporal values, lists, structs, maps, and unions. `toDisplayRows()` returns
+only `(string | null)[][]` for rendering, accessibility, sizing, and copy.
+
+Excel tables can return a `spreadsheet-v1` presentation. It includes sheet
+visibility, frozen rows/columns, sparse row and column sizes/hidden state, a
+deduplicated static style table, range-aligned style IDs, and intersecting
+merged cells. Styles cover number formats, fonts, colors, fills, borders, and
+alignment. The high-level Canvas view uses presentation automatically:
+
+```ts
+const view = createCanvasTableView({
+  container,
+  table,
+  presentation: "auto", // default; use "ignore" for logical data only
+});
+```
 
-The repository currently contains:
+Forced-colors mode overrides workbook colors while retaining dimensions,
+merges, alignment, and font emphasis.
 
-- A minimal Rust crate with an experimental `TableShape` value type.
-- A minimal ESM npm entry point with matching shape metadata.
-- Version synchronization and package dry-run checks.
-- GitHub Actions prepared for OIDC-based publication to crates.io and npm after
-  the initial registry bootstrap and Trusted Publisher configuration.
+Low-level painter, controller, layout, hit-testing, and selection primitives
+live under `tabulark/experimental` and carry no compatibility promise.
 
-No parser, Worker runtime, WebAssembly bridge, cache, or renderer has been
-implemented yet.
+## Format behavior
 
-## Planned data sources
+### Parquet
 
-CSV and TSV are intended to be the first reference adapters. Longer-term
-candidates include XLSX, XLS, Parquet, Apache Arrow, Feather, SQLite query
-results, DuckDB query results, and third-party data sources.
+Each file exposes one table. The adapter reads the footer and metadata first,
+then only row groups and top-level projected columns intersecting a request; it
+does not stage the full file. Supported compression is uncompressed, Snappy,
+Gzip, Brotli, LZ4, LZ4_RAW, and Zstd. INT96 becomes a timezone-free nanosecond
+timestamp. LZO, encrypted Parquet, and experimental Variant/Geo types return
+`UNSUPPORTED_FEATURE`.
 
-A format should not be considered supported until a released adapter is backed
-by compatibility tests.
+All promised Parquet codecs in the official WebAssembly adapter use Rust
+implementations. Arrow/Parquet 59.1.0 calls the narrow `zstd` 0.13 bulk API
+directly, so the workspace supplies a Rust 1.85-compatible implementation of
+that API backed by pinned `ruzstd` 0.8.1. The release gate proves the official
+Arrow and Parquet WASM graphs contain neither `zstd-sys` nor `zstd-safe`.
 
-## Non-goals
+Cargo removes workspace patches when it publishes a crate. Therefore the
+experimental crates.io Rust features deliberately do not enable upstream's
+Zstd feature; Zstd is part of the stable JavaScript/WASM format contract, not
+the experimental Rust API contract. This prevents a crates.io consumer from
+silently receiving a C-backed implementation.
 
-Tabulark is not intended to be:
+### Excel
 
-- A spreadsheet editor or Excel replacement.
-- A formula calculation or workbook recalculation engine.
-- A VBA, macro, or arbitrary workbook-code runtime.
-- A pixel-perfect implementation of every Office document feature.
-- A pivot table, chart authoring, BI, or database product.
-- A mandatory all-formats bundle or complete application framework.
+Each worksheet becomes a table in workbook order with an ID such as
+`sheet-0`. Hidden and very-hidden worksheets remain addressable and preserve
+visibility. Chart, dialog, and macro sheets are skipped with a warning.
 
-Editing, analysis, and application-specific UI may be built on top of Tabulark,
-but they are outside the core project's scope.
+Columns are named A, B, …; the first row is always data; empty cells are null.
+Excel values are display strings (`typedValues=false`). Formula cells use only
+their cached result—Tabulark never executes formulas—and missing cached values
+become null with a warning. Merged cells use the top-left value as their anchor.
 
-## Development
+XLS support is deliberately limited to BIFF8. Earlier BIFF, XLSM, XLSB, ODS,
+and encrypted workbooks return `UNSUPPORTED_FEATURE`. XLS and XLSX share the
+same bounded static-presentation subset.
 
-Requirements:
+## Memory and lifecycle
 
-- Rust 1.85 or later.
-- Node.js 20 or later.
-- npm 10 or later.
+One engine-wide reservation ledger accounts for adapter runtimes, source
+staging, compressed/decompressed pages, opened worksheets, batches, and caches.
+`RESOURCE_LIMIT` errors identify the resource category and the required and
+available amounts. Excel stages one bounded workbook; Parquet performs bounded
+range reads. ZIP/CFB entry counts, decompressed bytes, worksheet dimensions,
+cells, styles, layout entries, and merged regions are capped before allocation.
 
-Run the local checks:
+Handles are nested and cleanup cascades downward:
 
-```bash
-cargo fmt --all --check
-cargo clippy --workspace --all-targets --all-features -- -D warnings
-cargo test --workspace --all-features
-cargo package --allow-dirty --locked
-npm ci
-npm run check
+```text
+Engine
+  └─ DatasetSession
+       └─ TableHandle
+            └─ TableBatch
 ```
 
-After the first registry release, consumers will be able to install the base
-packages with:
+Close operations are idempotent. Closing a dataset closes its tables; closing
+an engine closes every dataset. Cancellation and close races settle once, and
+reservations are released on success, failure, cancellation, and close.
 
-```bash
-cargo add tabulark
-npm install tabulark
+```ts
+view.destroy();
+await table.close();
+await workbook.close();
+await engine.close();
 ```
 
-## Repository layout
+## Verification
 
-```text
-tabulark/
-├── src/                  # Rust crate
-├── js/                   # Browser-facing ESM package entry point
-├── test/                 # JavaScript tests
-├── scripts/              # Repository validation scripts
-├── docs/                 # Vision and release documentation
-└── .github/workflows/    # CI and registry publication
-```
+```sh
+# Rust 1.85/stable, Clippy, all features, lifecycle, fixtures, fuzz seeds
+cargo fmt --all --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features --locked
 
-See the [project vision](docs/vision.md) for the long-term design intent and
-[release guide](docs/releasing.md) for registry setup and publishing.
+# Stable exports/declarations, clean package consumers, and Pages assembly
+npm run check
 
-## Project status
+# Real module Worker/WASM, Canvas, ARIA, keyboard, copy, forced-colors, visuals
+npm run test:browser
 
-- [ ] Validate the unified `Table` model.
-- [ ] Define the parser and Worker protocol.
-- [ ] Implement a reference CSV/TSV parser.
-- [ ] Prototype viewport-driven Canvas rendering.
-- [ ] Publish the first crates.io and npm packages.
-- [ ] Stabilize extension APIs.
+# Independent core, Arrow, Parquet, Excel, npm, and Pages delivery budgets
+npm run benchmark:size
 
-## Contributing
+# Parquet/XLS/XLSX cold-open, range-read, and Chromium memory evidence
+npm run benchmark:formats
+```
 
-Tabulark is not yet ready for broad feature contributions. Design discussion,
-representative datasets, and concrete browser-preview use cases are welcome in
-[GitHub Issues](https://github.com/Ronbb/tabulark/issues).
+Chromium is the sole formal 0.1.0 browser gate. CI records its exact version.
+The Pages post-deploy smoke opens CSV, Arrow IPC, Parquet, XLS, and XLSX and
+asserts that only used adapter artifacts were requested.
 
-## AI-assisted development
+## Stability and release
 
-Tabulark makes extensive use of generative AI throughout project design,
-implementation, testing, documentation, and code review. AI-generated output is
-treated as a draft rather than trusted work: maintainers remain responsible for
-every change, and the same review, testing, security, and licensing standards
-apply regardless of how a contribution was produced.
+The root, `/arrow`, `/parquet`, and `/excel` entry points are stable for 0.1.x:
+compatible additions are allowed, but removals and breaking changes wait for
+0.2.0. Rust APIs, the Worker protocol, adapter ABI, wire DTOs, and
+`/experimental` remain experimental/private.
 
-## License
+No `v0.1.0` tag is created until every release gate and registry/OIDC
+precondition passes. npm and crates.io publishing is serialized behind protected
+GitHub Environments with required reviewer approval. See
+[docs/releasing.md](docs/releasing.md) for the immutable-release and patch
+recovery policy.
 
-Licensed under either of:
+## Repository map
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
-- MIT License ([LICENSE-MIT](LICENSE-MIT))
+```text
+src/                         shared Rust model, protocol, and native adapters
+crates/tabulark-*-wasm/      four independently built WASM entry crates
+js/                          stable API, private Worker host, batches, and view
+examples/csv-preview/        static six-format Playground
+test/fixtures/               pinned format fixtures and provenance
+test/browser/                Chromium, accessibility, visual, and Pages smoke
+test/performance/            performance and per-artifact delivery budgets
+docs/                        architecture, testing, stability, and release policy
+```
+
+## License
 
-at your option.
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).
+Shipped third-party material is listed in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+The optional `tabulark/arrow` and `tabulark/parquet` WebAssembly artifacts use
+Apache Arrow Rust 59.1.0. This includes the `arrow-*` crates used for logical
+arrays and IPC plus the `parquet` crate. Apache Arrow Rust is distributed under
+Apache-2.0, with some Arrow component crates additionally carrying MIT terms.
+
+Arrow IPC and Parquet compression support uses `brotli` (BSD-3-Clause AND MIT),
+`flate2` (MIT OR Apache-2.0), `lz4_flex` (MIT), `snap` (BSD-3-Clause), and
+`ruzstd` 0.8.1 (MIT). A narrow in-tree compatibility crate exposes
+the `zstd` 0.13 bulk API required by Arrow/Parquet while remaining Rust-only;
+its hashing dependency is `twox-hash` (MIT). `zstd-sys` and `zstd-safe` are not
+part of the official production WebAssembly dependency graph.
+
+The optional `tabulark/excel` artifact uses `calamine` 0.35.0 (MIT) for
+workbook values, formulas, and worksheet discovery. Its bounded container and
+static-presentation readers also use `cfb` (MIT), `zip` (MIT), and `quick-xml`
+(MIT).
+
+The Arrow IPC integration fixture under `test/fixtures/arrow/v1` is copied
+byte-for-byte from `apache/arrow-testing` at the revision recorded in its
+`provenance.json`. The exact upstream Apache-2.0 license is stored next to the
+fixture.
+
+The independent Parquet fixture under `test/fixtures/parquet/v1` is copied
+byte-for-byte from `apache/parquet-testing` at the pinned revision recorded in
+its `provenance.json`. Its Apache-2.0 license is stored next to the fixture.
+
+The independent XLSX fixture under `test/fixtures/excel/v1` is copied
+byte-for-byte from the XlsxWriter comparison corpus at the pinned revision
+recorded in its `provenance.json`. XlsxWriter is distributed under BSD-2-Clause;
+the upstream license is stored next to the fixture.
+
+The complete dependency versions and checksums are locked in `Cargo.lock`.
+`cargo deny check advisories licenses` is a release gate, and the release workflow emits
+an SPDX SBOM. Nothing in this notice changes the license terms supplied by an
+upstream project.

package/dist/adapters.d.ts

@@ -0,0 +1,62 @@
+import { type OfficialAdapterId } from "./official-adapter-manifest.js";
+export type { OfficialAdapterId } from "./official-adapter-manifest.js";
+export type DelimitedDialect = "csv" | "tsv";
+export type HeaderMode = "first-row" | "none";
+export type ParseMode = "lenient" | "strict";
+/** Options understood by the built-in delimited adapter. */
+export interface DelimitedAdapterOptions {
+    /** Defaults to `csv`. No filename-based selection is performed. */
+    readonly dialect?: DelimitedDialect;
+    readonly header?: HeaderMode;
+    readonly mode?: ParseMode;
+    /** One ASCII delimiter byte. Overrides the dialect default when supplied. */
+    readonly delimiter?: string;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+export type ArrowIpcContainer = "auto" | "file" | "stream";
+/** Options understood by the built-in Arrow IPC adapter. */
+export interface ArrowIpcAdapterOptions {
+    /** Defaults to `auto`; format detection belongs to the Arrow adapter. */
+    readonly container?: ArrowIpcContainer;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+/** Options understood by the built-in Parquet adapter. */
+export interface ParquetAdapterOptions {
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+export type ExcelFormat = "auto" | "xls" | "xlsx";
+/** Options understood by the built-in Excel adapter. */
+export interface ExcelAdapterOptions {
+    /** Defaults to `auto`; the adapter identifies the file from its signature. */
+    readonly format?: ExcelFormat;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+/**
+ * A frozen descriptor for one built-in adapter.
+ *
+ * Descriptors select a named official artifact only. They are deliberately not
+ * factories and cannot carry a module URL or a third-party implementation.
+ */
+export interface AdapterDescriptor<Id extends OfficialAdapterId = OfficialAdapterId, Options = unknown> {
+    readonly id: Id;
+    readonly kind: "official";
+    /** Carries the option type without exposing a runtime extension point. */
+    readonly __options?: Options;
+}
+export interface AdapterRegistration {
+    readonly id: OfficialAdapterId;
+}
+/** The built-in RFC-style delimited text adapter. */
+export declare const delimitedAdapter: AdapterDescriptor<"tabulark:delimited", DelimitedAdapterOptions>;
+/** @internal Used by the stable `/arrow` entrypoint. */
+export declare function createArrowIpcAdapter(): AdapterDescriptor<"tabulark:arrow-ipc", ArrowIpcAdapterOptions>;
+/** @internal Used by the stable `/parquet` entrypoint. */
+export declare function createParquetAdapter(): AdapterDescriptor<"tabulark:parquet", ParquetAdapterOptions>;
+/** @internal Used by the stable `/excel` entrypoint. */
+export declare function createExcelAdapter(): AdapterDescriptor<"tabulark:excel", ExcelAdapterOptions>;
+/** @internal Validates and extracts the non-public Worker registration. */
+export declare function resolveOfficialAdapter(value: unknown): AdapterRegistration | undefined;

package/dist/arrow.d.ts

@@ -0,0 +1,3 @@
+export { type ArrowIpcAdapterOptions, type ArrowIpcContainer } from "./adapters.js";
+/** Opens Apache Arrow IPC File or Stream input through the lazy official Arrow artifact. */
+export declare const arrowIpcAdapter: import("./adapters.js").AdapterDescriptor<"tabulark:arrow-ipc", import("./adapters.js").ArrowIpcAdapterOptions>;

package/dist/arrow.js

@@ -0,0 +1,2 @@
+var OFFICIAL_ADAPTER=Symbol.for("tabulark.official-adapter.v2");function createOfficialAdapter(id){const marker=Object.freeze({id});return Object.freeze({id,kind:"official",[OFFICIAL_ADAPTER]:marker})}var delimitedAdapter=createOfficialAdapter("tabulark:delimited");function createArrowIpcAdapter(){return createOfficialAdapter("tabulark:arrow-ipc")}var arrowIpcAdapter=createArrowIpcAdapter();export{arrowIpcAdapter};
+//# sourceMappingURL=arrow.js.map

package/dist/arrow.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../js/adapters.ts", "../js/arrow.ts"],
+  "sourcesContent": ["import {\n  isOfficialAdapterId,\n  officialAdapterManifestEntry,\n  type OfficialAdapterId,\n} from \"./official-adapter-manifest.js\";\n\nexport type { OfficialAdapterId } from \"./official-adapter-manifest.js\";\n\nexport type DelimitedDialect = \"csv\" | \"tsv\";\nexport type HeaderMode = \"first-row\" | \"none\";\nexport type ParseMode = \"lenient\" | \"strict\";\n\n/** Options understood by the built-in delimited adapter. */\nexport interface DelimitedAdapterOptions {\n  /** Defaults to `csv`. No filename-based selection is performed. */\n  readonly dialect?: DelimitedDialect;\n  readonly header?: HeaderMode;\n  readonly mode?: ParseMode;\n  /** One ASCII delimiter byte. Overrides the dialect default when supplied. */\n  readonly delimiter?: string;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\nexport type ArrowIpcContainer = \"auto\" | \"file\" | \"stream\";\n\n/** Options understood by the built-in Arrow IPC adapter. */\nexport interface ArrowIpcAdapterOptions {\n  /** Defaults to `auto`; format detection belongs to the Arrow adapter. */\n  readonly container?: ArrowIpcContainer;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\n/** Options understood by the built-in Parquet adapter. */\nexport interface ParquetAdapterOptions {\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\nexport type ExcelFormat = \"auto\" | \"xls\" | \"xlsx\";\n\n/** Options understood by the built-in Excel adapter. */\nexport interface ExcelAdapterOptions {\n  /** Defaults to `auto`; the adapter identifies the file from its signature. */\n  readonly format?: ExcelFormat;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\n/**\n * A frozen descriptor for one built-in adapter.\n *\n * Descriptors select a named official artifact only. They are deliberately not\n * factories and cannot carry a module URL or a third-party implementation.\n */\nexport interface AdapterDescriptor<\n  Id extends OfficialAdapterId = OfficialAdapterId,\n  Options = unknown,\n> {\n  readonly id: Id;\n  readonly kind: \"official\";\n  /** Carries the option type without exposing a runtime extension point. */\n  readonly __options?: Options;\n}\n\ninterface InternalAdapterDescriptor<\n  Id extends OfficialAdapterId = OfficialAdapterId,\n  Options = unknown,\n> extends AdapterDescriptor<Id, Options> {\n  readonly [OFFICIAL_ADAPTER]: Readonly<{ readonly id: Id }>;\n}\n\n/**\n * A process-global symbol permits descriptors from separately bundled stable\n * entrypoints to be recognized. It conveys no capability: the manifest below\n * still owns the selected module URL and resource policy.\n */\nconst OFFICIAL_ADAPTER = Symbol.for(\"tabulark.official-adapter.v2\");\n\nexport interface AdapterRegistration {\n  readonly id: OfficialAdapterId;\n}\n\nfunction createOfficialAdapter<Id extends OfficialAdapterId, Options>(\n  id: Id,\n): AdapterDescriptor<Id, Options> {\n  const marker = Object.freeze({ id });\n  return Object.freeze({\n    id,\n    kind: \"official\" as const,\n    [OFFICIAL_ADAPTER]: marker,\n  }) as InternalAdapterDescriptor<Id, Options>;\n}\n\n/** The built-in RFC-style delimited text adapter. */\nexport const delimitedAdapter = createOfficialAdapter<\n  \"tabulark:delimited\",\n  DelimitedAdapterOptions\n>(\"tabulark:delimited\");\n\n/** @internal Used by the stable `/arrow` entrypoint. */\nexport function createArrowIpcAdapter(): AdapterDescriptor<\"tabulark:arrow-ipc\", ArrowIpcAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:arrow-ipc\", ArrowIpcAdapterOptions>(\"tabulark:arrow-ipc\");\n}\n\n/** @internal Used by the stable `/parquet` entrypoint. */\nexport function createParquetAdapter(): AdapterDescriptor<\"tabulark:parquet\", ParquetAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:parquet\", ParquetAdapterOptions>(\"tabulark:parquet\");\n}\n\n/** @internal Used by the stable `/excel` entrypoint. */\nexport function createExcelAdapter(): AdapterDescriptor<\"tabulark:excel\", ExcelAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:excel\", ExcelAdapterOptions>(\"tabulark:excel\");\n}\n\n/** @internal Validates and extracts the non-public Worker registration. */\nexport function resolveOfficialAdapter(value: unknown): AdapterRegistration | undefined {\n  if (!isRecord(value) || !Object.isFrozen(value) || !isOfficialAdapterId(value.id) || value.kind !== \"official\") {\n    return undefined;\n  }\n  const marker = value[OFFICIAL_ADAPTER];\n  if (!isRecord(marker) || marker.id !== value.id) {\n    return undefined;\n  }\n  // A marker may be recreated by another bundle, but it conveys no URL or\n  // implementation capability: it can select only a manifest-owned ID.\n  officialAdapterManifestEntry(value.id);\n  return Object.freeze({ id: value.id });\n}\n\nfunction isRecord(value: unknown): value is Record<PropertyKey, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n", "export { type ArrowIpcAdapterOptions, type ArrowIpcContainer } from \"./adapters.js\";\n\nimport { createArrowIpcAdapter } from \"./adapters.js\";\n\n/** Opens Apache Arrow IPC File or Stream input through the lazy official Arrow artifact. */\nexport const arrowIpcAdapter = createArrowIpcAdapter();\n"],
+  "mappings": "AA8EA,IAAM,iBAAmB,OAAO,IAAI,8BAA8B,EAMlE,SAAS,sBACP,GACgC,CAChC,MAAM,OAAS,OAAO,OAAO,CAAE,EAAG,CAAC,EACnC,OAAO,OAAO,OAAO,CACnB,GACA,KAAM,WACN,CAAC,gBAAgB,EAAG,MACtB,CAAC,CACH,CAGO,IAAM,iBAAmB,sBAG9B,oBAAoB,EAGf,SAAS,uBAAyF,CACvG,OAAO,sBAAoE,oBAAoB,CACjG,CCnGO,IAAM,gBAAkB,sBAAsB",
+  "names": []
+}

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import { TabularkError } from "./errors.js";
+import { type AdapterDescriptor, type OfficialAdapterId } from "./adapters.js";
+import { type RangeRequest, type PresentationRange, type TablePresentation, type TableBatch, type TableDescriptor, type TableMetadata } from "./model.js";
+export interface OpenSourceOptions<Options = unknown> {
+    /** One of the official descriptors registered when the engine was created. */
+    readonly adapter: AdapterDescriptor<OfficialAdapterId, Options>;
+    readonly adapterOptions?: Options;
+    /** Detaches an ArrayBuffer input. Defaults to false; Blob input cannot be transferred. */
+    readonly transferInput?: boolean;
+    /** Cancels opening and releases any Worker-side source created by the request. */
+    readonly signal?: AbortSignal;
+}
+export interface EngineOptions {
+    /** The engine's immutable allow-list. At least one official adapter is required. */
+    readonly adapters: readonly AdapterDescriptor[];
+    readonly memoryBudgetBytes?: number;
+    readonly workerName?: string;
+}
+export interface ReadRangeOptions {
+    readonly signal?: AbortSignal;
+}
+export interface RuntimeProgress {
+    readonly sourceHandle: string;
+    readonly tableId?: string;
+    readonly revision?: number;
+    readonly bytesScanned: number;
+    readonly rowsDiscovered: number;
+    readonly done: boolean;
+}
+export interface SourceWarning {
+    readonly handle: string;
+    readonly kind: string;
+    readonly message: string;
+    readonly byteOffset?: number;
+    readonly row?: number;
+}
+export type DatasetEvent = Readonly<{
+    type: "progress";
+    progress: RuntimeProgress;
+}> | Readonly<{
+    type: "metadata";
+    metadata: Readonly<TableMetadata>;
+}> | Readonly<{
+    type: "warning";
+    warning: SourceWarning;
+}> | Readonly<{
+    type: "closed";
+}> | Readonly<{
+    type: "runtimeError";
+    error: TabularkError;
+}>;
+export type TableEvent = Exclude<DatasetEvent, Readonly<{
+    type: "progress";
+}>>;
+export type Unsubscribe = () => void;
+export interface DatasetSession {
+    readonly tables: readonly Readonly<TableDescriptor>[];
+    openTable(tableId: string): Promise<TableHandle>;
+    subscribe(listener: (event: DatasetEvent) => void): Unsubscribe;
+    close(): Promise<void>;
+}
+export interface TableHandle {
+    readonly metadata: Readonly<TableMetadata>;
+    getPresentation(): Promise<TablePresentation | null>;
+    readPresentationRange(request: RangeRequest, options?: ReadRangeOptions): Promise<PresentationRange | null>;
+    readRange(request: RangeRequest, options?: ReadRangeOptions): Promise<TableBatch>;
+    subscribe(listener: (event: TableEvent) => void): Unsubscribe;
+    close(): Promise<void>;
+}
+export interface TabularkEngine {
+    open<Options>(source: Blob | ArrayBuffer, options: OpenSourceOptions<Options>): Promise<DatasetSession>;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Creates one dedicated Worker-backed Tabulark engine. */
+export declare function createEngine(options: EngineOptions): Promise<TabularkEngine>;

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+import type { SerializedError } from "./protocol.js";
+export type TabularkErrorCode = "INVALID_ARGUMENT" | "INVALID_RANGE" | "RANGE_NOT_INDEXED" | "RESOURCE_LIMIT" | "CANCELLED" | "HANDLE_CLOSED" | "PROTOCOL_INCOMPATIBLE" | "PARSE_FAILED" | "UNSUPPORTED_FEATURE" | "UNSUPPORTED_RUNTIME" | "RUNTIME_FAILURE" | (string & {});
+/** A stable, serializable error returned by Tabulark. */
+export declare class TabularkError extends Error {
+    readonly code: TabularkErrorCode;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+    constructor(code: TabularkErrorCode, message: string, options?: {
+        retryable?: boolean;
+        details?: unknown;
+        cause?: unknown;
+    });
+    static fromSerialized(error: SerializedError): TabularkError;
+}
+/** @internal Ensures every resource-limit error has a stable capacity shape. */
+export declare function normalizeResourceLimitDetails(details: unknown): Readonly<Record<string, unknown>>;
+export declare function cancelledError(): TabularkError;
+export declare function closedError(resource: string): TabularkError;
+export declare function invalidArgument(message: string, details?: unknown): TabularkError;

package/dist/excel.d.ts

@@ -0,0 +1,3 @@
+export { type ExcelAdapterOptions, type ExcelFormat } from "./adapters.js";
+/** Opens BIFF8 XLS or OOXML XLSX input through the lazy official Excel artifact. */
+export declare const excelAdapter: import("./adapters.js").AdapterDescriptor<"tabulark:excel", import("./adapters.js").ExcelAdapterOptions>;

package/dist/excel.js

@@ -0,0 +1,2 @@
+var OFFICIAL_ADAPTER=Symbol.for("tabulark.official-adapter.v2");function createOfficialAdapter(id){const marker=Object.freeze({id});return Object.freeze({id,kind:"official",[OFFICIAL_ADAPTER]:marker})}var delimitedAdapter=createOfficialAdapter("tabulark:delimited");function createExcelAdapter(){return createOfficialAdapter("tabulark:excel")}var excelAdapter=createExcelAdapter();export{excelAdapter};
+//# sourceMappingURL=excel.js.map