tabulark 0.0.4 → 0.1.0

package/dist/model.d.ts

@@ -0,0 +1,389 @@
+import { BATCH_LAYOUT_VERSION } from "./protocol.js";
+export declare const DEFAULT_MEMORY_BUDGET_BYTES: number;
+export declare const MAX_ARRAY_BUFFER_BYTES: number;
+export declare const MAX_RANGE_CELLS = 250000;
+export declare const DEFAULT_TO_ROWS_CELL_LIMIT = 10000;
+export declare const MAX_NESTING_DEPTH = 64;
+export declare const MAX_SOURCES = 2;
+export declare const MAX_ACTIVE_RANGES = 2;
+export declare const MAX_RANGE_WAITERS = 8;
+export interface MemoryBudgetLimits {
+    readonly memoryBudgetBytes: number;
+    /** Shared retained capacity allocated among the adapters actually registered. */
+    readonly adapterRuntimePoolBytes: number;
+    /** Maximum transient/decoded budget retained by one active adapter operation. */
+    readonly operationBudgetBytes: number;
+    readonly indexBudgetBytes: number;
+    readonly adapterTileCacheBudgetBytes: number;
+    readonly workerRangeCacheBytes: number;
+    readonly workerDatasetRangeCacheBytes: number;
+    readonly mainThreadRangeCacheBytes: number;
+    readonly maxFieldBytes: number;
+    readonly maxBatchBytes: number;
+    readonly maxArrayBufferBytes: number;
+    readonly maxSources: number;
+    readonly maxActiveRanges: number;
+    readonly maxRangeWaiters: number;
+}
+/** Derives every bounded runtime allocation from one engine-wide budget. */
+export declare function deriveMemoryBudgetLimits(memoryBudgetBytes: number): MemoryBudgetLimits;
+export type MemoryResourceKind = "adapter-runtime" | "source-staging" | "compressed-page" | "decompression" | "opened-worksheet" | "batch" | "range-cache";
+export interface MemoryReservation {
+    readonly resource: MemoryResourceKind;
+    readonly bytes: number;
+    release(): void;
+}
+/**
+ * Single-accounting ledger for Worker-owned bounded allocations.
+ *
+ * A reservation is deliberately idempotent so cancellation, close and failure
+ * races can all execute their normal cleanup paths without double accounting.
+ */
+export declare class MemoryReservationLedger {
+    #private;
+    constructor(capacityBytes: number);
+    get capacityBytes(): number;
+    get usedBytes(): number;
+    get availableBytes(): number;
+    reserve(resource: MemoryResourceKind, bytes: number): MemoryReservation;
+}
+export type AxisExtent = Readonly<{
+    kind: "exact";
+    value: number;
+}> | Readonly<{
+    kind: "at-least";
+    value: number;
+}> | Readonly<{
+    kind: "unknown";
+}>;
+export interface TableExtent {
+    readonly rows: AxisExtent;
+    readonly columns: AxisExtent;
+}
+export type TimeUnit = "second" | "millisecond" | "microsecond" | "nanosecond";
+export type IntervalUnit = "year-month" | "day-time" | "month-day-nano";
+export interface ArrowField {
+    readonly name: string;
+    readonly nullable: boolean;
+    readonly dataType: ArrowDataType;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+interface SimpleDataType<Type extends string> {
+    readonly type: Type;
+}
+/** A recursive representation of every arrow-schema 59.1.0 built-in DataType. */
+export type ArrowDataType = SimpleDataType<"null" | "unknown" | "boolean" | "int8" | "int16" | "int32" | "int64" | "uint8" | "uint16" | "uint32" | "uint64" | "float16" | "float32" | "float64" | "date32" | "date64" | "binary" | "large-binary" | "binary-view" | "utf8" | "large-utf8" | "utf8-view"> | Readonly<{
+    type: "timestamp";
+    unit: TimeUnit;
+    timezone?: string;
+}> | Readonly<{
+    type: "time32" | "time64" | "duration";
+    unit: TimeUnit;
+}> | Readonly<{
+    type: "interval";
+    unit: IntervalUnit;
+}> | Readonly<{
+    type: "fixed-size-binary";
+    byteWidth: number;
+}> | Readonly<{
+    type: "decimal32" | "decimal64" | "decimal128" | "decimal256";
+    precision: number;
+    scale: number;
+}> | Readonly<{
+    type: "list" | "large-list" | "list-view" | "large-list-view";
+    field: ArrowField;
+}> | Readonly<{
+    type: "fixed-size-list";
+    field: ArrowField;
+    listSize: number;
+}> | Readonly<{
+    type: "struct";
+    fields: readonly ArrowField[];
+}> | Readonly<{
+    type: "union";
+    mode: "sparse" | "dense";
+    fields: readonly Readonly<{
+        typeId: number;
+        field: ArrowField;
+    }>[];
+}> | Readonly<{
+    type: "dictionary";
+    indexType: ArrowDataType;
+    valueType: ArrowDataType;
+    ordered?: boolean;
+}> | Readonly<{
+    type: "map";
+    entries: ArrowField;
+    keysSorted: boolean;
+}> | Readonly<{
+    type: "run-end-encoded";
+    runEnds: ArrowField;
+    values: ArrowField;
+}> | Readonly<{
+    type: "extension";
+    name: string;
+    metadata?: string;
+    storageType: ArrowDataType;
+}>;
+export interface ColumnSchema {
+    readonly id: string;
+    readonly name: string;
+    readonly index: number;
+    readonly dataType: ArrowDataType;
+    readonly nullable: boolean;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface TableCapabilities {
+    readonly randomAccess: "indexed-prefix" | "full";
+    readonly typedValues: boolean;
+    readonly search: boolean;
+    readonly sort: boolean;
+    readonly filter: boolean;
+    readonly multiTable: boolean;
+    readonly [name: string]: unknown;
+}
+export interface TableMetadata {
+    readonly tableId: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly extent: Readonly<TableExtent>;
+    readonly schema: Readonly<{
+        readonly version: number;
+        readonly columns: readonly Readonly<ColumnSchema>[];
+    }>;
+    readonly capabilities: Readonly<TableCapabilities>;
+}
+export type WorksheetVisibility = "visible" | "hidden" | "very-hidden";
+/** One sparse row or column override supplied by a spreadsheet presentation. */
+export interface PresentationAxisEntry {
+    readonly index: number;
+    /** CSS pixel extent when the source supplies an explicit dimension. */
+    readonly size?: number;
+    readonly hidden?: boolean;
+}
+export interface PresentationColor {
+    /** CSS-compatible resolved color, when the workbook supplied one. */
+    readonly css?: string;
+}
+export interface PresentationFont {
+    readonly family?: string;
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly color?: PresentationColor;
+}
+export interface PresentationBorderSide {
+    readonly style?: "none" | "thin" | "medium" | "thick" | "dashed" | "dotted" | "double";
+    readonly color?: PresentationColor;
+}
+/** Static cell styling that 0.1 preserves from spreadsheet input. */
+export interface PresentationStyle {
+    readonly numberFormat?: string;
+    readonly font?: PresentationFont;
+    readonly foregroundColor?: PresentationColor;
+    readonly backgroundColor?: PresentationColor;
+    readonly fillColor?: PresentationColor;
+    readonly borders?: Readonly<{
+        readonly top?: PresentationBorderSide;
+        readonly right?: PresentationBorderSide;
+        readonly bottom?: PresentationBorderSide;
+        readonly left?: PresentationBorderSide;
+    }>;
+    readonly horizontalAlignment?: "general" | "left" | "center" | "right" | "justify";
+    readonly verticalAlignment?: "top" | "center" | "bottom" | "justify";
+    readonly wrapText?: boolean;
+}
+export interface MergedCellRegion {
+    readonly rowStart: number;
+    readonly rowEnd: number;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+}
+/**
+ * Presentation metadata for a worksheet. It is intentionally static: formula
+ * calculation and document round-tripping are outside the 0.1 contract.
+ */
+export interface SpreadsheetPresentation {
+    readonly kind: "spreadsheet-v1";
+    readonly tableId: string;
+    readonly revision: number;
+    readonly visibility: WorksheetVisibility;
+    readonly frozenRows: number;
+    readonly frozenColumns: number;
+    readonly rows: readonly PresentationAxisEntry[];
+    readonly columns: readonly PresentationAxisEntry[];
+    /** Deduplicated styles addressed by `SpreadsheetPresentationRange.styleIds`. */
+    readonly styles: readonly PresentationStyle[];
+}
+export type TablePresentation = SpreadsheetPresentation;
+export interface SpreadsheetPresentationRange {
+    readonly kind: "spreadsheet-v1";
+    readonly tableId: string;
+    readonly revision: number;
+    readonly range: Readonly<ReturnedRange>;
+    /** Rows and columns are exactly aligned with `range`; null means no style. */
+    readonly styleIds: readonly (readonly (number | null)[])[];
+    readonly mergedCells: readonly MergedCellRegion[];
+    /** Sparse layout entries that intersect this requested range. */
+    readonly rows: readonly PresentationAxisEntry[];
+    readonly columns: readonly PresentationAxisEntry[];
+}
+export type PresentationRange = SpreadsheetPresentationRange;
+export interface TableDescriptor {
+    readonly id: string;
+    readonly name: string;
+}
+export interface RangeRequest {
+    readonly rowStart: number;
+    readonly rowCount: number;
+    readonly columnStart: number;
+    readonly columnCount: number;
+}
+export interface ReturnedRange extends RangeRequest {
+}
+/** A byte region in the batch's deduplicated buffer pool. */
+export interface BatchBufferRegion {
+    readonly buffer: number;
+    readonly byteOffset?: number;
+    readonly byteLength?: number;
+    /** First bit for bitmap regions; ignored for byte-oriented regions. */
+    readonly bitOffset?: number;
+}
+/** UTF-8 text generated by Rust for rendering, ARIA, width measurement and copy. */
+export interface DisplayColumnDescriptor {
+    readonly encoding: "utf8";
+    readonly data: BatchBufferRegion;
+    readonly offsets: BatchBufferRegion;
+    readonly validity?: BatchBufferRegion;
+    /** Logical offset into the display arrays, for sliced batches. */
+    readonly offset?: number;
+}
+/**
+ * Recursive Arrow ArrayData layout. Buffer regions always point into the
+ * enclosing TableBatch buffer pool; encoded dictionaries and run ends remain
+ * visible in this descriptor even though `toRows()` returns logical values.
+ */
+export interface NativeColumnDescriptor {
+    /** Rust ArrayData layout encoding (for example `dictionary` or `run-end-encoded`). */
+    readonly encoding?: string;
+    readonly dataType: ArrowDataType;
+    readonly length: number;
+    readonly offset?: number;
+    readonly validity?: BatchBufferRegion;
+    readonly values?: BatchBufferRegion;
+    readonly offsets?: BatchBufferRegion;
+    readonly sizes?: BatchBufferRegion;
+    readonly data?: BatchBufferRegion;
+    readonly typeIds?: BatchBufferRegion;
+    readonly unionOffsets?: BatchBufferRegion;
+    readonly variadicBuffers?: readonly BatchBufferRegion[];
+    readonly children?: readonly NativeColumnDescriptor[];
+    readonly dictionary?: NativeColumnDescriptor;
+    readonly runEnds?: NativeColumnDescriptor;
+    readonly typeId?: number;
+}
+/** @internal Layout-v1 column descriptor received from an official WASM runtime. */
+export interface WireTableBatchColumn {
+    readonly columnId: string;
+    readonly native: NativeColumnDescriptor;
+    readonly display: DisplayColumnDescriptor;
+}
+export interface DecimalValue {
+    readonly kind: "decimal";
+    readonly unscaled: bigint;
+    readonly precision: number;
+    readonly scale: number;
+}
+export interface TemporalValue {
+    readonly kind: "date32" | "date64" | "time32" | "time64" | "timestamp" | "duration";
+    readonly value: number | bigint;
+    readonly unit?: TimeUnit;
+    readonly timezone?: string;
+}
+export interface IntervalValue {
+    readonly kind: "interval";
+    readonly unit: IntervalUnit;
+    readonly months?: number;
+    readonly days?: number;
+    readonly milliseconds?: number;
+    readonly nanoseconds?: bigint;
+}
+export interface UnionValue {
+    readonly kind: "union";
+    readonly typeId: number;
+    readonly value: NativeValue | null;
+}
+export interface MapEntryValue {
+    readonly key: NativeValue | null;
+    readonly value: NativeValue | null;
+}
+export interface NativeListValue extends ReadonlyArray<NativeValue | null> {
+}
+export interface NativeStructValue {
+    readonly [name: string]: NativeValue | null;
+}
+export interface NativeMapValue extends ReadonlyArray<Readonly<MapEntryValue>> {
+}
+export type NativeValue = boolean | number | bigint | string | Uint8Array | DecimalValue | TemporalValue | IntervalValue | UnionValue | NativeListValue | NativeStructValue | NativeMapValue;
+export interface ToRowsOptions {
+    /** Maximum decoded cells. Defaults to 10,000. */
+    readonly maxCells?: number;
+}
+/**
+ * Logical, column-oriented access to one returned batch column.
+ *
+ * Values are indexed relative to `TableBatch.range.rowStart`; physical buffer
+ * regions and adapter transport details intentionally remain private.
+ */
+export interface TableBatchColumn {
+    readonly columnId: string;
+    readonly columnIndex: number;
+    readonly rowCount: number;
+    getValue(rowOffset: number): NativeValue | null;
+    getDisplayValue(rowOffset: number): string | null;
+    toValues(options?: ToRowsOptions): (NativeValue | null)[];
+    toDisplayValues(options?: ToRowsOptions): (string | null)[];
+}
+/** Stable logical batch contract. Wire buffers and ABI layout stay private. */
+export interface TableBatch {
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: Readonly<ReturnedRange>;
+    readonly columns: readonly TableBatchColumn[];
+    readonly complete: boolean;
+    toRows(options?: ToRowsOptions): (NativeValue | null)[][];
+    toDisplayRows(options?: ToRowsOptions): (string | null)[][];
+}
+export type WireBatchBuffer = ArrayBuffer | ArrayBufferView;
+export interface WireTableBatch {
+    readonly layoutVersion: typeof BATCH_LAYOUT_VERSION;
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: ReturnedRange;
+    readonly buffers: readonly WireBatchBuffer[];
+    readonly columns: readonly WireTableBatchColumn[];
+    readonly complete: boolean;
+}
+/** Owns and validates one generic layout-v1 batch received from the Worker. */
+export declare class ColumnarTableBatch implements TableBatch {
+    #private;
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: Readonly<ReturnedRange>;
+    readonly columns: readonly TableBatchColumn[];
+    readonly complete: boolean;
+    constructor(value: WireTableBatch);
+    toRows(options?: ToRowsOptions): (NativeValue | null)[][];
+    toDisplayRows(options?: ToRowsOptions): (string | null)[][];
+}
+export declare function validateRange(request: RangeRequest): RangeRequest;
+export declare function normalizeMetadata(value: TableMetadata): Readonly<TableMetadata>;
+/** Normalizes a protocol DataType and rejects cycles or excessive nesting. */
+export declare function normalizeDataType(value: unknown, depth?: number): ArrowDataType;
+export declare function assertNonNegativeSafeInteger(value: unknown, name: string): asserts value is number;
+export declare function assertPositiveSafeInteger(value: unknown, name: string): asserts value is number;
+export {};

package/dist/official-adapter-manifest.d.ts

@@ -0,0 +1,31 @@
+export type OfficialAdapterId = "tabulark:delimited" | "tabulark:arrow-ipc" | "tabulark:parquet" | "tabulark:excel";
+export type OfficialSourceAccess = "streaming" | "range" | "staged";
+export interface OfficialAdapterManifestEntry {
+    readonly id: OfficialAdapterId;
+    readonly entrypoint: "." | "./arrow" | "./parquet" | "./excel";
+    readonly exportName: string;
+    readonly wasm: Readonly<{
+        readonly packageName: string;
+        readonly crateArtifact: string;
+        readonly outputName: string;
+        readonly outputDirectory: string;
+        readonly modulePath: string;
+        readonly runtimeExport: "WasmRuntime";
+    }>;
+    readonly options: Readonly<{
+        readonly allowedKeys: readonly string[];
+    }>;
+    readonly resources: Readonly<{
+        readonly sourceAccess: OfficialSourceAccess;
+        readonly supportsPresentation: boolean;
+        readonly runtimeWeight: number;
+    }>;
+}
+/** Runtime IDs are derived from the manifest rather than repeated in code. */
+export declare const OFFICIAL_ADAPTER_IDS: readonly OfficialAdapterId[];
+/** The sole internal source of truth for built-in IDs, artifacts and host policy. */
+export declare const OFFICIAL_ADAPTER_MANIFEST: readonly OfficialAdapterManifestEntry[];
+export declare function isOfficialAdapterId(value: unknown): value is OfficialAdapterId;
+export declare function officialAdapterManifestEntry(id: OfficialAdapterId): OfficialAdapterManifestEntry;
+/** Resolves an official wrapper relative to the bundle that hosts this code. */
+export declare function officialAdapterModuleUrl(id: OfficialAdapterId): string;

package/dist/parquet.d.ts

@@ -0,0 +1,3 @@
+export { type ParquetAdapterOptions } from "./adapters.js";
+/** Opens Apache Parquet input through the lazy official Parquet WASM artifact. */
+export declare const parquetAdapter: import("./adapters.js").AdapterDescriptor<"tabulark:parquet", import("./adapters.js").ParquetAdapterOptions>;

package/dist/parquet.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 createParquetAdapter(){return createOfficialAdapter("tabulark:parquet")}var parquetAdapter=createParquetAdapter();export{parquetAdapter};
+//# sourceMappingURL=parquet.js.map

package/dist/parquet.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../js/adapters.ts", "../js/parquet.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 ParquetAdapterOptions } from \"./adapters.js\";\n\nimport { createParquetAdapter } from \"./adapters.js\";\n\n/** Opens Apache Parquet input through the lazy official Parquet WASM artifact. */\nexport const parquetAdapter = createParquetAdapter();\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,EAQf,SAAS,sBAAqF,CACnG,OAAO,sBAAiE,kBAAkB,CAC5F,CCxGO,IAAM,eAAiB,qBAAqB",
+  "names": []
+}

package/dist/protocol.d.ts

@@ -0,0 +1,54 @@
+/** Version 3 introduces multi-table presentation and discriminated adapter steps. */
+export declare const PROTOCOL_VERSION: 3;
+/** Version of the private, built-in Rust adapter contract. */
+export declare const ADAPTER_API_VERSION: 2;
+/** Version of the descriptor + deduplicated-buffer batch transport. */
+export declare const BATCH_LAYOUT_VERSION: 1;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+export type Operation = "hello" | "openSource" | "listTables" | "openTable" | "getMetadata" | "getPresentation" | "readPresentationRange" | "readRange" | "cancel" | "closeTable" | "closeSource" | "shutdown";
+export interface ProtocolRequest<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly op: Operation;
+    readonly payload: T;
+}
+export type ResponseKind = "hello" | "dataset" | "tables" | "table" | "metadata" | "presentation" | "presentationRange" | "batch" | "acknowledged";
+export interface ProtocolResult<T = unknown> {
+    readonly kind: ResponseKind;
+    readonly data?: T;
+}
+export interface ProtocolSuccess<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly status: "success";
+    readonly result: ProtocolResult<T>;
+}
+export interface SerializedError {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+}
+export interface ProtocolFailure {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly status: "failure";
+    readonly error: SerializedError;
+}
+export type ProtocolResponse<T = unknown> = ProtocolSuccess<T> | ProtocolFailure;
+export type RuntimeEventName = "progress" | "metadata" | "warning" | "closed" | "runtimeError";
+export interface ProtocolEvent<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId?: string;
+    readonly event: RuntimeEventName;
+    /** Required for dataset/table events; omitted only by a process-wide runtimeError. */
+    readonly datasetHandle?: string;
+    readonly tableHandle?: string;
+    readonly tableId?: string;
+    /** Revision associated with a table-scoped event, when known. */
+    readonly revision?: number;
+    readonly payload: T;
+}
+export declare function isProtocolResponse(value: unknown): value is ProtocolResponse;
+export declare function isProtocolEvent(value: unknown): value is ProtocolEvent;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/range-cache.d.ts

@@ -0,0 +1,28 @@
+import type { RangeRequest, WireTableBatch } from "./model.js";
+export declare class PermitQueueFullError extends Error {
+    readonly maxWaiters: number;
+    constructor(maxWaiters: number);
+}
+/** A small FIFO permit queue whose pending acquisitions can be cancelled by key. */
+export declare class AsyncPermitQueue {
+    #private;
+    constructor(maxActive: number, maxWaiters: number);
+    acquire(key: string): Promise<() => void>;
+    cancel(key: string, reason: unknown): boolean;
+}
+/** A byte-bounded least-recently-used cache. */
+export declare class ByteLruCache<T> {
+    #private;
+    constructor(maxBytes: number, options?: Readonly<{
+        onRemove?: (key: string, value: T, byteLength: number) => void;
+    }>);
+    get maxBytes(): number;
+    get(key: string): T | undefined;
+    set(key: string, value: T, byteLength: number): void;
+    deleteWhere(predicate: (key: string, value: T) => boolean): void;
+    clear(): void;
+}
+export declare function rangeCacheKey(owner: string, revision: number, schemaVersion: number, range: RangeRequest): string;
+export declare function rangeCacheKeyBelongsTo(key: string, owner: string): boolean;
+export declare function cloneWireTableBatch(batch: WireTableBatch): WireTableBatch;
+export declare function wireBatchByteLength(batch: WireTableBatch): number;

package/dist/rpc-client.d.ts

@@ -0,0 +1,18 @@
+import { TabularkError } from "./errors.js";
+import { type Operation, type ProtocolEvent, type ResponseKind } from "./protocol.js";
+type EventListener = (event: ProtocolEvent) => void;
+type FailureListener = (error: TabularkError) => void;
+interface RequestOptions {
+    readonly transfer?: Transferable[];
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+/** Main-thread request multiplexer for one dedicated Worker. */
+export declare class WorkerRpcClient {
+    #private;
+    constructor(worker: Worker, onEvent: EventListener, onFailure?: FailureListener);
+    request<T>(op: Operation, payload: unknown, expectedKind: ResponseKind, options?: RequestOptions): Promise<T>;
+    shutdown(timeoutMs?: number): Promise<void>;
+    terminate(error?: TabularkError, notifyFailure?: boolean): void;
+}
+export {};

package/dist/view/accessible-grid.d.ts

@@ -0,0 +1,36 @@
+export interface AccessibleGridColumn {
+    readonly index: number;
+    readonly name: string;
+}
+export interface AccessibleGridCell {
+    readonly rowIndex: number;
+    readonly columnIndex: number;
+    readonly value: string | null | undefined;
+    readonly selected: boolean;
+    readonly active: boolean;
+    readonly rowSpan?: number;
+    readonly columnSpan?: number;
+}
+export interface AccessibleGridRow {
+    readonly index: number;
+    readonly cells: readonly AccessibleGridCell[];
+}
+export interface AccessibleGridSnapshot {
+    readonly label: string;
+    readonly exactRowCount?: number;
+    readonly columnCount: number;
+    readonly columns: readonly AccessibleGridColumn[];
+    readonly rows: readonly AccessibleGridRow[];
+    readonly busy: boolean;
+    readonly status?: string;
+}
+/** A viewport-bounded semantic counterpart to the visual Canvas table. */
+export declare class AccessibleViewportGrid {
+    #private;
+    readonly element: HTMLDivElement;
+    readonly statusElement: HTMLDivElement;
+    constructor(ownerDocument: Document, label?: string);
+    update(snapshot: AccessibleGridSnapshot): void;
+    focus(options?: FocusOptions): void;
+    destroy(): void;
+}

package/dist/view/canvas-painter.d.ts

@@ -0,0 +1,91 @@
+import type { MergedCellRegion, PresentationStyle } from "../model.js";
+export interface CanvasPaintColumn {
+    readonly index: number;
+    readonly name: string;
+    /** Viewport-relative x coordinate, including the pinned row gutter offset. */
+    readonly x: number;
+    readonly width: number;
+    readonly frozen?: boolean;
+}
+export interface CanvasPaintCell {
+    readonly columnIndex: number;
+    readonly value: string | null | undefined;
+    readonly style?: PresentationStyle;
+    /** The cell is painted by its merge anchor rather than its own grid slot. */
+    readonly coveredByMerge?: boolean;
+}
+export interface CanvasPaintRow {
+    readonly index: number;
+    /** Viewport-relative y coordinate, including the pinned header offset. */
+    readonly y: number;
+    readonly height: number;
+    readonly frozen?: boolean;
+    readonly cells: readonly CanvasPaintCell[];
+}
+export interface CanvasPaintMergedCell {
+    readonly region: Readonly<MergedCellRegion>;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly value: string | null | undefined;
+    readonly style?: PresentationStyle;
+    /** A pane-clipped continuation; only the anchor fragment paints the value. */
+    readonly continuation?: boolean;
+}
+export interface CanvasPaintSelection {
+    readonly rowStart: number;
+    /** Exclusive table row bound. */
+    readonly rowEnd: number;
+    readonly columnStart: number;
+    /** Exclusive table column bound. */
+    readonly columnEnd: number;
+}
+export interface CanvasPaintActiveCell {
+    readonly rowIndex: number;
+    readonly columnIndex: number;
+}
+export interface CanvasPaintSnapshot {
+    readonly width: number;
+    readonly height: number;
+    readonly headerHeight: number;
+    readonly rowGutterWidth: number;
+    readonly columns: readonly CanvasPaintColumn[];
+    readonly rows: readonly CanvasPaintRow[];
+    readonly mergedCells?: readonly CanvasPaintMergedCell[];
+    readonly selection?: CanvasPaintSelection;
+    readonly activeCell?: CanvasPaintActiveCell;
+    readonly busy: boolean;
+}
+export interface CanvasTableTheme {
+    readonly background: string;
+    readonly foreground: string;
+    readonly mutedForeground: string;
+    readonly headerBackground: string;
+    readonly headerForeground: string;
+    readonly alternateRowBackground: string;
+    readonly gridLine: string;
+    readonly selectionBackground: string;
+    readonly selectionBorder: string;
+    readonly activeCellBorder: string;
+    readonly loadingBackground: string;
+    readonly font: string;
+    readonly headerFont: string;
+}
+export declare const DEFAULT_CANVAS_TABLE_THEME: Readonly<CanvasTableTheme>;
+/** Resolves author-independent system colors for Windows High Contrast and other forced palettes. */
+export declare function forcedColorsCanvasTableTheme(base?: Readonly<CanvasTableTheme>): Readonly<CanvasTableTheme>;
+/** Paints one viewport frame and keeps the backing store device-pixel aware. */
+export declare class CanvasTablePainter {
+    #private;
+    readonly canvas: HTMLCanvasElement;
+    constructor(canvas: HTMLCanvasElement, options?: {
+        readonly theme?: Partial<CanvasTableTheme>;
+        readonly maxDevicePixelRatio?: number;
+        readonly forcedColors?: boolean;
+    });
+    setTheme(theme: Readonly<CanvasTableTheme>, options?: {
+        readonly forcedColors?: boolean;
+    }): void;
+    paint(snapshot: CanvasPaintSnapshot): void;
+}