@portel/csv 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-01
+
+### Added
+
+- `CsvEngine` class — stateful CSV engine with formula evaluation
+- `CsvEngine.fromCSV()` — parse CSV text including format rows
+- Formula engine: SUM, AVG, MAX, MIN, COUNT, IF, LEN, ABS, ROUND, CONCAT
+- Visual formula descriptors: PIE, BAR, LINE, SPARKLINE, GAUGE
+- Cell references in A1 notation, ranges (A1:B5), column ranges (A:C)
+- Format row parsing and building (Photon CSV Format v1.0)
+- Column metadata: type, alignment, width, wrap, required, sort
+- Simple query conditions: `>`, `<`, `=`, `!=`, `>=`, `<=`, `contains`
+- SQL queries via optional `alasql` peer dependency
+- Serialization: `toCSV()`, `toObjects()`, `toTable()`, `snapshot()`, `schema()`
+- Data mutation: `set`, `add`, `remove`, `update`, `push`, `fill`, `clear`, `resize`, `rename`, `sort`, `format`
+- `columnMeta` included in `query()` and `sql()` results for display formatting
+- Standalone exports for all internal modules (csv, cells, format, query, formulas, charts, table)
+- 146 tests across 8 test suites

package/FORMAT.md

@@ -0,0 +1,199 @@
+# Photon CSV Format Specification
+
+**Version 1.0** — A backward-compatible extension to standard CSV that embeds column metadata in an optional format row.
+
+## Overview
+
+Photon CSV is standard RFC 4180 CSV with one addition: an optional **format row** as the first line that encodes column types, alignment, width, wrapping, and sort hints using a compact dash-based syntax inspired by Markdown table separators.
+
+Any tool that reads standard CSV will simply see the format row as a regular data row with dashes — it degrades gracefully. Tools that understand the format row can extract rich column metadata without external schema files.
+
+```
+:---#:,:---:,:---M+:,:---$:
+ID,Name,Description,Price
+1,Widget,"A **useful** widget",9.99
+2,Gadget,"A _fancy_ gadget",19.99
+```
+
+## Format Row Syntax
+
+The format row is **row 0** (the very first line). The header row follows as **row 1**. If no format row is present, row 0 is treated as headers (standard CSV behavior).
+
+### Detection
+
+A row is a format row if **every cell** matches this pattern:
+
+```
+[<>]? :? -{2,} [type]? [modifiers]* :?
+```
+
+In regex: `/^[<>]?:?-{2,}[^,]*:?$/` (after stripping `+` modifiers)
+
+### Cell Anatomy
+
+```
+  :---#w120+*:
+  │ │  ││   ││
+  │ │  ││   │└─ right/center align marker
+  │ │  ││   └── required field
+  │ │  ││ └──── wrap enabled
+  │ │  │└────── width in pixels
+  │ │  └─────── type indicator
+  │ └────────── dashes (minimum 2)
+  └──────────── left/center align marker
+```
+
+### Alignment
+
+| Pattern | Alignment | Example |
+|---------|-----------|---------|
+| `:---` | Left (default) | `:---` |
+| `---:` | Right | `---:` |
+| `:---:` | Center | `:---:` |
+| `---` | Left | `---` |
+
+### Type Indicators
+
+| Indicator | Type | Description |
+|-----------|------|-------------|
+| *(none)* | `text` | Plain text (default) |
+| `#` | `number` | Numeric values |
+| `$` | `currency` | Currency values |
+| `%` | `percent` | Percentage values |
+| `D` | `date` | Date values |
+| `?` | `bool` | Boolean/checkbox |
+| `=` | `select` | Single select from options |
+| `~` | `formula` | Formula column |
+| `M` | `markdown` | Inline markdown rendering |
+| `T` | `longtext` | Long text with wrapping |
+
+### Modifiers
+
+| Modifier | Meaning | Example |
+|----------|---------|---------|
+| `w{N}` | Column width in pixels | `---#w120` = number, 120px wide |
+| `+` | Enable text wrapping | `---M+` = markdown with wrap |
+| `*` | Required field | `---#*` = required number |
+| `>` (prefix) | Sort ascending | `>---#` = number, sort asc |
+| `<` (prefix) | Sort descending | `<---$` = currency, sort desc |
+
+Modifiers can be combined: `:---M+w200*:` = centered, markdown, wrapped, 200px, required.
+
+## Examples
+
+### Basic — Numbers and Currency
+
+```csv
+:---,:---#:,:---$:
+Product,Quantity,Price
+Widget,42,9.99
+Gadget,17,24.50
+```
+
+### Rich — Mixed Types with Wrapping
+
+```csv
+:---,:---?,:---M+w300:,:---$:
+Task,Done,Notes,Budget
+Design,true,"**Phase 1** complete\nMoving to _phase 2_",5000
+Backend,false,"`API` endpoints [spec](https://...)",8000
+```
+
+### Sorted — Pre-sorted Data
+
+```csv
+>---,:---#:
+Name,Score
+Alice,95
+Bob,87
+Charlie,72
+```
+
+## Visual Formulas
+
+Cells can contain formula functions that render as visualizations instead of scalar values. These are standard cell values starting with `=`:
+
+| Formula | Renders | Example |
+|---------|---------|---------|
+| `=PIE(labels, values)` | Pie chart overlay | `=PIE(A1:A5, B1:B5)` |
+| `=BAR(labels, values)` | Bar chart overlay | `=BAR(A1:A5, B1:B5)` |
+| `=LINE(labels, values)` | Line chart overlay | `=LINE(A1:A10, B1:B10)` |
+| `=SPARKLINE(range)` | Inline sparkline | `=SPARKLINE(B1:B10)` |
+| `=GAUGE(value, min, max)` | Gauge meter | `=GAUGE(B1, 0, 100)` |
+
+Visual formulas are evaluated by the host application. In plain CSV readers, they appear as text (e.g., `=PIE(A1:A5, B1:B5)`).
+
+## Scalar Formulas
+
+Standard formulas evaluate to scalar values and are stored in cells with a `=` prefix:
+
+| Formula | Description | Example |
+|---------|-------------|---------|
+| `=SUM(range)` | Sum of numbers | `=SUM(B1:B10)` |
+| `=AVG(range)` | Average | `=AVG(B1:B10)` |
+| `=MAX(range)` | Maximum | `=MAX(B1:B10)` |
+| `=MIN(range)` | Minimum | `=MIN(B1:B10)` |
+| `=COUNT(range)` | Count of numbers | `=COUNT(B1:B10)` |
+| `=IF(cond, true, false)` | Conditional | `=IF(A1>10, "high", "low")` |
+| `=LEN(text)` | String length | `=LEN(A1)` |
+| `=ABS(number)` | Absolute value | `=ABS(A1)` |
+| `=ROUND(number, digits)` | Round | `=ROUND(A1, 2)` |
+| `=CONCAT(a, b, ...)` | Join strings | `=CONCAT(A1, " ", B1)` |
+
+Cell references use A1 notation. Ranges use `A1:B2` notation. Column-only ranges (`A:B`) span all rows.
+
+## Markdown in Cells
+
+Cells in `markdown` (`M`) columns support inline Markdown:
+
+| Syntax | Renders |
+|--------|---------|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `` `code` `` | `code` |
+| `[text](url)` | [text](url) |
+| `\n` | Line break |
+
+Full block-level Markdown (headings, lists, tables) is not supported — cells use inline rendering only.
+
+## Streaming
+
+CSV files can be streamed append-only. The format row and header row are written once at the top; subsequent rows are appended. Consumers that understand the format can:
+
+1. Read the format row to learn column metadata
+2. Read the header row for column names
+3. Tail the file for new rows (`tail -f` or `fs.watch`)
+
+The `appendCSVLines()` method in `@portel/csv` handles this: it parses incoming lines, skips duplicate headers and format rows, and appends only data rows.
+
+## Compatibility
+
+| Reader | Behavior |
+|--------|----------|
+| Standard CSV parser | Sees format row as data row with dashes — harmless |
+| Excel / Google Sheets | Ignores format row (shows as text) |
+| `@portel/csv` | Full metadata extraction and round-trip preservation |
+| pandas `read_csv` | `skiprows=[0]` to skip format row |
+
+The format is designed to be **zero-cost to ignore** — any tool that doesn't understand it simply sees an extra row of dashes.
+
+## MIME Type
+
+Photon CSV files use the standard `text/csv` MIME type. The format row is detectable by content inspection, not by file extension or MIME type.
+
+## Grammar (ABNF)
+
+```abnf
+format-row   = format-cell *("," format-cell)
+format-cell  = [sort-prefix] [left-align] dashes [type] *modifier [right-align]
+
+sort-prefix  = ">" / "<"
+left-align   = ":"
+right-align  = ":"
+dashes       = 2*"-"
+type         = "#" / "$" / "%" / "D" / "?" / "=" / "~" / "M" / "T"
+modifier     = wrap / width / required
+wrap         = "+"
+width        = "w" 1*DIGIT
+required     = "*"
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Portel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,408 @@
+# @portel/csv
+
+CSV is the one format every AI already speaks. When an LLM needs structured data, it doesn't reach for Protocol Buffers. It writes a comma-separated table. When a tool returns rows to an agent, it's CSV, or something that wishes it were.
+
+And yet most CSV libraries give you a pile of string arrays and wave goodbye. Here's your data, good luck.
+
+`@portel/csv` is different. It's a **stateful engine** that actually understands what's inside the cells. Formulas evaluate. Columns know they hold currency. Queries work without loading pandas. You get a spreadsheet brain in a 30KB package, with zero dependencies and no I/O.
+
+```
+:---,:---#:,:---$:
+Product,Quantity,Price
+Widget,42,9.99
+Gadget,17,24.50
+```
+
+That first row? It's a **format row**. Any CSV reader that doesn't understand it just sees dashes. But tools that *do* understand it know that Quantity is a number (right-aligned) and Price is currency. The schema lives inside the file. No sidecar JSON. No separate config. Just CSV that knows what it is.
+
+## Built for AI Tool Chains
+
+If you're building agents, MCP servers, or tool-calling pipelines, this is your CSV layer.
+
+**The problem:** An LLM asks your tool for sales data. You read a CSV, return string arrays, and the model has to guess that column 3 is currency. It formats `1234.5` as plain text. The user sees a wall of numbers with no structure. You end up writing formatting hints into system prompts.
+
+**With `@portel/csv`:**
+
+```typescript
+import { CsvEngine } from '@portel/csv';
+
+const engine = CsvEngine.fromCSV(csvText);
+const snap = engine.snapshot('Sales data for Q1');
+
+// snap.data        → evaluated values (formulas resolved)
+// snap.columnMeta  → [{type:'text'}, {type:'number'}, {type:'currency'}]
+// snap.charts      → any visual formulas, pre-resolved
+// snap.table       → ASCII markdown table, ready to return
+```
+
+Your tool returns structured data *and* the metadata to render it. The client knows column 3 is currency and can format `1234.5` as `$1,234.50` in whatever locale it wants. The AI doesn't have to guess. Neither does the UI.
+
+**Agents that mutate data** get synchronous operations. No async, no file I/O, no "await the save." Just change the data and serialize when you're done.
+
+```typescript
+engine.add({ Product: 'Thingamajig', Quantity: '100', Price: '4.99' });
+engine.sort('Price', 'desc');
+engine.set('D1', '=SUM(C1:C3)');
+
+const csv = engine.toCSV();  // ready to write, with formulas preserved
+```
+
+**SQL without the database.** Need to answer "which products cost more than $10"? Your agent can query in plain SQL:
+
+```typescript
+const result = engine.sql('SELECT Product, Price FROM data WHERE Price > 10');
+// result.result     → [{ Product: 'Gadget', Price: 24.50 }]
+// result.columnMeta → knows Price is currency
+```
+
+No database. No connection string. Just a CSV file and a question. (SQL needs `alasql` as a peer dep. Everything else works with zero dependencies.)
+
+## Install
+
+```bash
+npm install @portel/csv
+```
+
+For SQL queries:
+
+```bash
+npm install @portel/csv alasql
+```
+
+## The Basics
+
+### Parse and explore
+
+```typescript
+import { CsvEngine } from '@portel/csv';
+
+const engine = CsvEngine.fromCSV(`
+Name,Age,Score
+Alice,30,95
+Bob,25,87
+Charlie,35,72
+`);
+
+engine.getHeaders();       // ['Name', 'Age', 'Score']
+engine.rowCount;           // 3
+engine.evaluate(0, 1);     // '30'
+engine.toTable();          // ASCII markdown table
+engine.toObjects();        // [{ Name: 'Alice', Age: 30, Score: 95 }, ...]
+```
+
+`toObjects()` auto-coerces numbers. `Age` comes back as `30`, not `"30"`. If you've set column metadata (or the CSV has a format row), currency columns strip `$` and `%` before converting. The type information travels with the data.
+
+### Mutate
+
+Every mutation is synchronous. No promises, no callbacks, no waiting for disk. The engine is pure in-memory state. You persist it when and how you want.
+
+```typescript
+engine.set('D1', '=SUM(B1:B3)');                          // formulas just work
+engine.add({ Name: 'Diana', Age: '28', Score: '91' });    // add by column name
+engine.push([['Eve', '22', '88'], ['Frank', '40', '76']]); // batch append
+engine.update(2, { Score: '90' });                         // update row 2
+engine.remove(3);                                          // remove row 3
+engine.sort('Score', 'desc');                              // sort descending
+engine.rename('A', 'FullName');                            // rename column
+engine.fill('C1:C5', '0');                                 // fill a range
+engine.clear('B:B');                                       // clear entire column
+engine.resize(10, 5);                                      // grow or shrink the grid
+```
+
+### Query
+
+Two ways to ask questions. Simple conditions for the common case, SQL for everything else.
+
+```typescript
+// Simple: column, operator, value
+const result = engine.query('Age > 25');
+result.matchCount;    // 2
+result.data;          // [['Alice','30','95'], ['Charlie','35','72']]
+result.columnMeta;    // metadata for each column, so you can format the output
+
+// SQL: full power when you need it
+const sql = engine.sql('SELECT Name, Score FROM data WHERE Score > 85 ORDER BY Score DESC');
+sql.result;           // [{ Name: 'Alice', Score: 95 }, { Name: 'Bob', Score: 87 }]
+sql.columnMeta;       // still there, still useful
+```
+
+Both `query()` and `sql()` return `columnMeta` alongside the results. This is intentional. When your agent returns a table to the user, the rendering layer needs to know that Score is a number and Price is currency. The metadata is *always* available. You never have to ask for it separately.
+
+### Serialize
+
+```typescript
+engine.toCSV();                        // CSV text, format row included if present
+engine.toCSV({ formatRow: true });     // force the format row in
+engine.toCSV({ formatRow: false });    // strip it out
+engine.toObjects();                    // typed objects with number coercion
+engine.toTable();                      // ASCII markdown table
+engine.toTable('A1:B3');               // just a range
+engine.snapshot('Quarterly report');    // everything: data, formulas, charts, metadata
+engine.schema();                       // column types and fill statistics
+```
+
+`snapshot()` is the one you want for AI tool responses. It bundles evaluated data, raw formulas, chart descriptors, column metadata, and a message string into a single object. Hand it to your UI layer and it has everything it needs.
+
+## Formulas
+
+Cells starting with `=` evaluate when read. The formula engine handles A1 references, ranges, and these functions:
+
+| Formula | What it does | Example |
+|---------|-------------|---------|
+| `=SUM(range)` | Add up numbers | `=SUM(A1:A10)` |
+| `=AVG(range)` | Average (alias: `AVERAGE`) | `=AVG(B1:B5)` |
+| `=MAX(range)` | Largest value | `=MAX(C1:C10)` |
+| `=MIN(range)` | Smallest value | `=MIN(C1:C10)` |
+| `=COUNT(range)` | How many numbers | `=COUNT(A:A)` |
+| `=IF(cond, t, f)` | Pick one or the other | `=IF(A1>10,"high","low")` |
+| `=LEN(value)` | String length | `=LEN(A1)` |
+| `=ABS(number)` | Absolute value | `=ABS(A1)` |
+| `=ROUND(n, digits)` | Round to N places | `=ROUND(A1, 2)` |
+| `=CONCAT(a, b, ...)` | Stick strings together | `=CONCAT(A1, " ", B1)` |
+
+Formulas are stored as-is in the CSV. `toCSV()` preserves them. `evaluate()` resolves them. Round-trip safe.
+
+### Visual formulas
+
+Some formulas don't produce numbers. They describe charts. The engine resolves the data ranges and gives you a `ChartDescriptor`. Your UI picks the charting library.
+
+| Formula | Produces | Example |
+|---------|----------|---------|
+| `=PIE(labels, values)` | Pie chart descriptor | `=PIE(A1:A5, B1:B5)` |
+| `=BAR(labels, values)` | Bar chart descriptor | `=BAR(A1:A5, B1:B5)` |
+| `=LINE(labels, values)` | Line chart descriptor | `=LINE(A1:A10, B1:B10)` |
+| `=SPARKLINE(range)` | Sparkline descriptor | `=SPARKLINE(B1:B10)` |
+| `=GAUGE(val, min, max)` | Gauge descriptor | `=GAUGE(B1, 0, 100)` |
+
+```typescript
+const snap = engine.snapshot();
+snap.charts;
+// [{ cell: 'C1', type: 'pie', resolvedLabels: ['Q1','Q2'], resolvedValues: [40,60] }]
+```
+
+The data is resolved. The labels are resolved. The UI just draws.
+
+## The Format Row
+
+This is the interesting part. Here's a normal CSV:
+
+```csv
+Product,Quantity,Price
+Widget,42,9.99
+```
+
+And here's the same CSV with a format row:
+
+```csv
+:---,---#:,:---$:
+Product,Quantity,Price
+Widget,42,9.99
+```
+
+That first line tells any format-aware reader: column 1 is left-aligned text, column 2 is a right-aligned number, column 3 is right-aligned currency. Open this in Excel and you'll see a harmless row of dashes. Open it in `@portel/csv` and you get typed column metadata for free.
+
+```
+  :---#w120+*:
+  │ │  ││   ││
+  │ │  ││   │└─ right/center align marker
+  │ │  ││   └── required field
+  │ │  ││ └──── text wrapping
+  │ │  │└────── width in pixels
+  │ │  └─────── type indicator
+  │ └────────── dashes (minimum 2)
+  └──────────── left/center align marker
+```
+
+The syntax is inspired by Markdown table separators. If you've written `|:---|---:|` in a Markdown table, you already know how this works.
+
+| Alignment | Pattern | Types | Char | Modifiers | Syntax |
+|-----------|---------|-------|------|-----------|--------|
+| Left | `:---` | number | `#` | width | `w120` |
+| Right | `---:` | currency | `$` | wrap | `+` |
+| Center | `:---:` | percent | `%` | required | `*` |
+| | | date | `D` | sort asc | `>` prefix |
+| | | bool | `?` | sort desc | `<` prefix |
+| | | markdown | `M` | | |
+| | | longtext | `T` | | |
+
+Full specification with ABNF grammar: **[FORMAT.md](./FORMAT.md)**
+
+### Compatibility
+
+The format was designed around one principle: **zero cost to ignore.**
+
+| Reader | What happens |
+|--------|-------------|
+| Standard CSV parser | Sees a data row with dashes. Harmless. |
+| Excel / Google Sheets | Shows dashes as text. Ignore or delete the row. |
+| pandas | `skiprows=[0]` and carry on. |
+| `@portel/csv` | Full metadata extraction. Types, alignment, width, the works. |
+
+### Metadata, not rendering
+
+Worth repeating: the library stores column metadata but never formats output. `type: 'currency'` is a hint that says "this column holds money." Your UI decides whether to show `$9.99` or `€9,99` or `9.99 USD`. The engine stays locale-agnostic and opinion-free.
+
+```typescript
+const engine = CsvEngine.fromCSV(csvWithFormatRow);
+const meta = engine.getColumnMeta();
+// meta[2] = { align: 'right', type: 'currency' }
+
+// Every result carries this metadata
+const query = engine.query('Price > 5');
+query.columnMeta[2].type;  // 'currency'
+// Your formatter does: new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
+```
+
+## Standalone Utilities
+
+You don't have to use `CsvEngine`. Every module is exported individually:
+
+```typescript
+import {
+  escapeCSV, parseCSVLine,                          // CSV primitives
+  numberToColumnName, columnNameToNumber,            // A ↔ 0, Z ↔ 25, AA ↔ 26
+  cellToIndex, rangeToIndices,                       // A1 → {row:0, col:0}
+  isFormatRow, parseFormatCell, buildFormatCell,     // format row handling
+  parseCondition, matchCondition,                    // query conditions
+  evaluateFormula, isVisualFormula, parseVisualFormula, // formula engine
+} from '@portel/csv';
+```
+
+Building your own CSV viewer? Just pull `parseCSVLine` and `isFormatRow`. Writing a data pipeline? Use `parseFormatCell` to extract types and ignore the rest. The engine is convenient. The parts are flexible.
+
+## API Reference
+
+### `CsvEngine`
+
+#### Construction
+
+```typescript
+new CsvEngine()                                          // 10 empty columns
+new CsvEngine({ headers: ['Name', 'Age'] })              // custom headers
+new CsvEngine({ headers, columnMeta, defaultCols: 5 })   // full control
+
+CsvEngine.fromCSV(csvText: string): CsvEngine             // parse CSV text
+```
+
+#### Read
+
+| Property / Method | Returns | Description |
+|-------------------|---------|-------------|
+| `rowCount` | `number` | Data rows |
+| `colCount` | `number` | Columns |
+| `getHeaders()` | `string[]` | Column headers (copy) |
+| `getColumnMeta()` | `ColumnMeta[]` | Column metadata (copy) |
+| `evaluate(row, col)` | `string` | Evaluated cell value |
+| `evaluateAll()` | `string[][]` | Full evaluated grid |
+| `getRawCell(row, col)` | `string` | Raw content (formula string if any) |
+
+#### Mutate
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `set` | `(cell: string, value: string)` | `void` |
+| `add` | `(values: Record<string, string>)` | `number` (1-indexed row) |
+| `remove` | `(row: number)` | `void` |
+| `update` | `(row: number, values: Record<string, string>)` | `string[]` (change descriptions) |
+| `push` | `(rows: (string[] \| Record<string, string>)[])` | `number` (rows added) |
+| `fill` | `(range: string, pattern: string)` | `void` |
+| `clear` | `(range?: string)` | `void` |
+| `resize` | `(rows?: number, cols?: number)` | `void` |
+| `rename` | `(column: string, name: string)` | `string` (old name) |
+| `sort` | `(column: string, order?: 'asc' \| 'desc')` | `void` |
+| `format` | `(column: string, opts)` | `void` |
+
+#### Query
+
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `query(where, limit?)` | `QueryResult` | Conditions: `>`, `<`, `=`, `!=`, `>=`, `<=`, `contains` |
+| `sql(query)` | `SqlResult` | Full SQL. Requires `alasql`. |
+
+#### Serialize
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `toCSV(options?)` | `string` | CSV text. `{ formatRow: true/false }` controls format row. |
+| `toObjects()` | `Record[]` | Type-coerced objects |
+| `toTable(range?)` | `string` | ASCII markdown table |
+| `snapshot(msg?)` | `EngineSnapshot` | Full state for UIs |
+| `schema()` | `SchemaColumn[]` | Column types and stats |
+
+#### Data Loading
+
+| Method | Description |
+|--------|-------------|
+| `loadCSV(csvText)` | Replace state from CSV text |
+| `appendCSVLines(lines)` | Append lines, skipping headers/format rows |
+
+### Types
+
+<details>
+<summary>Full TypeScript interfaces</summary>
+
+```typescript
+interface ColumnMeta {
+  align: string;           // 'left' | 'right' | 'center'
+  type: string;            // 'text' | 'number' | 'currency' | 'percent' | 'date'
+                           // | 'bool' | 'select' | 'formula' | 'markdown' | 'longtext'
+  width?: number;          // pixels
+  required?: boolean;
+  sort?: string;           // 'asc' | 'desc'
+  wrap?: boolean;
+}
+
+interface EngineSnapshot {
+  table: string;                       // ASCII table
+  data: string[][];                    // evaluated values (non-empty rows)
+  formulas: Record<string, string>;    // cell ref → raw formula
+  headers: string[];
+  columnMeta: ColumnMeta[];
+  charts: ChartDescriptor[];
+  message: string;
+  rows: number;
+  cols: number;
+}
+
+interface QueryResult {
+  table: string;
+  data: string[][];
+  headers: string[];
+  columnMeta: ColumnMeta[];
+  message: string;
+  matchCount: number;
+}
+
+interface SqlResult {
+  result: any;
+  columnMeta: ColumnMeta[];
+  count: number;
+  message: string;
+}
+
+interface ChartDescriptor {
+  cell: string;
+  type: 'pie' | 'bar' | 'line' | 'sparkline' | 'gauge';
+  labelRange?: string;
+  valueRange?: string;
+  resolvedLabels: string[];
+  resolvedValues: number[];
+  min?: number;
+  max?: number;
+}
+```
+</details>
+
+## Design Decisions
+
+**Pure library.** No `fs`, no `fetch`, no async. Strings in, strings out. You bring the persistence layer. This means it works in browsers, workers, edge functions, Deno, Bun, wherever JavaScript runs.
+
+**Metadata, not opinions.** Column types and alignment are stored and returned, never rendered. The engine is intentionally locale-agnostic. A `currency` column in Tokyo and Toronto should look different, and that's your formatter's job, not ours.
+
+**alasql is optional.** Most people just need CSV parsing and formulas. SQL is powerful but heavy. It lives behind an optional peer dependency. If you call `sql()` without installing alasql, you get a clear error message telling you exactly what to do. Not a cryptic module resolution failure.
+
+**Format rows round-trip.** Load a CSV with a format row, mutate the data, save it back. The format row survives. If you set column formatting programmatically, `toCSV()` auto-includes a format row even if the original didn't have one.
+
+## License
+
+MIT

package/dist/cells.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cell addressing — A1 notation, column naming, range resolution.
+ */
+import type { CellIndex, RangeBounds } from './types.js';
+/** Convert a 0-based column index to a letter name (0 → A, 25 → Z, 26 → AA). */
+export declare function numberToColumnName(num: number): string;
+/** Convert a column letter name to a 0-based index (A → 0, Z → 25, AA → 26). */
+export declare function columnNameToNumber(name: string): number;
+/** Parse an A1-style cell reference into row/col indices (both 0-based). */
+export declare function cellToIndex(cell: string): CellIndex;
+/**
+ * Parse a range reference into start/end row/col indices.
+ * Supports cell ranges (A1:C3) and column-only ranges (A:C).
+ * For column-only ranges, `maxRow` determines the end row.
+ */
+export declare function rangeToIndices(range: string, maxRow: number): RangeBounds;
+/**
+ * Resolve a column name or letter to a 0-based index.
+ * Tries exact header match first, then case-insensitive, then letter conversion.
+ */
+export declare function resolveColumnIndex(name: string, headers: string[]): number;
+//# sourceMappingURL=cells.d.ts.map

package/dist/cells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../src/cells.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAStD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAOnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAezE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAO1E"}