@bilig/headless 0.8.2 → 0.9.1

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm: @bilig/headless](https://img.shields.io/npm/v/@bilig/headless?label=%40bilig%2Fheadless)](https://www.npmjs.com/package/@bilig/headless)
 [![GitHub](https://img.shields.io/badge/GitHub-proompteng%2Fbilig-blue)](https://github.com/proompteng/bilig)
+[![GitHub Repo stars](https://img.shields.io/github/stars/proompteng/bilig?style=social)](https://github.com/proompteng/bilig/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
 
 `@bilig/headless` is the production-targeted WorkPaper workbook facade for
@@ -25,9 +26,12 @@ Current release posture:
 - Full local CI passed after the latest headless hardening work, including unit,
   contract, fuzz, browser, clean-diff, release-budget, runtime-publish, and
   WorkPaper competitive benchmark gates.
-- The checked-in competitive artifact generated on `2026-05-05T19:00:09.455Z`
+- The checked-in competitive artifact generated on `2026-05-06T14:54:57.091Z`
   shows `46/46` comparable WorkPaper mean wins against HyperFormula-style
   workloads: `38/38` public and `8/8` holdout.
+- The public benchmark evidence note explains the measured workload families,
+  engine metadata, exclusions, and the current p95 nuance:
+  [`docs/headless-workpaper-benchmark-evidence.md`](../../docs/headless-workpaper-benchmark-evidence.md).
 - Recently fixed and hardened P1 risks are covered by regression tests:
   - `updateConfig()` now applies `useColumnIndex` correctly when a rebuild-only
     config key changes in the same update.
@@ -42,6 +46,14 @@ Supported scope:
 - The contract is the WorkPaper/headless API exported by this package.
 - Excel-file ingestion belongs to import/export pipelines before data reaches
   `WorkPaper`; this package executes the validated WorkPaper workbook model.
+- XLSX cached-result parity investigations are covered by the repository
+  verifier, not by the published package surface. Use
+  `pnpm workpaper:xlsx-corpus:check -- <xlsx-file-or-directory>` for external
+  corpora, and `pnpm workpaper:xlsx-corpus:fixtures:check` for the checked-in
+  issue #8 reduction corpus. The verifier compares deterministic cached formula
+  results and skips volatile or environment-dependent formulas such as `NOW()`
+  and `CELL("filename")`; unsupported deterministic formulas remain visible as
+  mismatches instead of being silently accepted.
 - Custom function plugins and callback hooks are runtime registrations. Persist
   workbook data with the helpers below, then register custom behavior in
   application code before restore.
@@ -66,6 +78,8 @@ Repository:
 - npm: <https://www.npmjs.com/package/@bilig/headless>
 - runnable example:
   [`examples/headless-workpaper`](../../examples/headless-workpaper)
+- public adoption kit:
+  [`docs/public-adoption-kit.md`](../../docs/public-adoption-kit.md)
 
 Inside this monorepo:
 
@@ -144,6 +158,10 @@ npm start
 Repository CI also runs the same example against packed local runtime packages
 through `pnpm workpaper:smoke:external`.
 
+For a concise evaluator-facing summary with copy-paste npm commands, proof
+links, shareable copy, and overclaim guardrails, use the root
+[`Public Adoption Kit`](../../docs/public-adoption-kit.md).
+
 ## Core Concepts
 
 - `WorkPaper` is the top-level workbook object. Create it with
@@ -200,6 +218,39 @@ const changes = workbook.batch(() => {
 })
 ```
 
+Create and read named expressions:
+
+```ts
+import { WorkPaper, type WorkPaperCellAddress } from '@bilig/headless'
+
+const workbook = WorkPaper.buildFromSheets({
+  Plan: [
+    ['Metric', 'Value'],
+    ['Base revenue', 100],
+    ['Target revenue', null],
+  ],
+})
+
+const sheet = workbook.getSheetId('Plan')
+if (sheet === undefined) {
+  throw new Error('Plan sheet was not created')
+}
+
+const at = (row: number, col: number): WorkPaperCellAddress => ({
+  sheet,
+  row,
+  col,
+})
+
+workbook.addNamedExpression('GrowthRate', 0.15)
+workbook.setCellContents(at(2, 1), '=B2*(1+GrowthRate)')
+
+console.log(workbook.getNamedExpressionValue('GrowthRate')) // CellValue for 0.15
+console.log(workbook.getNamedExpressionFormula('GrowthRate')) // undefined for a scalar name
+console.log(workbook.getCellValue(at(2, 1))) // CellValue for 115
+console.log(workbook.getNamedExpressionValue('MissingName')) // undefined
+```
+
 Move cells inside configured bounds:
 
 ```ts
@@ -233,6 +284,39 @@ const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { inc
 const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved))
 ```
 
+Validate a persisted document before restore:
+
+```ts
+import {
+  WorkPaper,
+  createWorkPaperFromDocument,
+  exportWorkPaperDocument,
+  isPersistedWorkPaperDocument,
+  parseWorkPaperDocument,
+  serializeWorkPaperDocument,
+} from '@bilig/headless'
+
+const workbook = WorkPaper.buildFromSheets({
+  Sheet1: [[10, '=A1*2']],
+})
+
+const document = exportWorkPaperDocument(workbook, { includeConfig: true })
+const serialized = serializeWorkPaperDocument(document)
+
+const parsed = parseWorkPaperDocument(serialized)
+if (!isPersistedWorkPaperDocument(parsed)) {
+  throw new Error('Persisted WorkPaper document failed validation')
+}
+
+const restored = createWorkPaperFromDocument(parsed)
+```
+
+`parseWorkPaperDocument()` validates JSON and throws on invalid payloads.
+`isPersistedWorkPaperDocument()` is useful when a service already has an
+unknown parsed object. Custom function implementations, callback hooks, and
+other process state are not persisted; register those in application code before
+restoring the workbook.
+
 ## Persistence Contract
 
 `@bilig/headless` persists:
@@ -278,6 +362,21 @@ pnpm workpaper:bench:competitive:check
 Do not change benchmark definitions, scoring, sampling, or workload sizes to hide
 losses.
 
+For XLSX compatibility investigations with cached formula results, run the
+corpus verifier against real workbook files:
+
+```sh
+pnpm workpaper:xlsx-corpus:check -- /path/to/xlsx-corpus
+```
+
+The verifier reads `.xlsx`, `.xlsm`, and `.xls` files, builds a WorkPaper model
+with `useColumnIndex: true`, and compares formula cells against cached workbook
+results. It reports `totalFiles`, `failedTimeouts`, `comparableFormulaCells`,
+`matchingFormulaCells`, `mismatchedFormulaCells`, `matchRate`, skipped formulas,
+and actionable mismatch samples. Missing cached results and volatile or
+environment-dependent formulas such as `NOW()` and `CELL()` are counted as
+skipped instead of silently treated as parity evidence.
+
 ## Compatibility Notes
 
 - The facade follows HyperFormula-style public workbook workflows, but it is not
@@ -290,6 +389,10 @@ losses.
 - Stable compatibility adapters are available through `graph`, `rangeMapping`,
   `arrayMapping`, `sheetMapping`, `addressMapping`, `dependencyGraph`,
   `evaluator`, `columnSearch`, and `lazilyTransformingAstService`.
+- Cached XLSX result parity is a testable corpus property, not a blanket
+  package guarantee. Use `pnpm workpaper:xlsx-corpus:check -- <corpus>` for
+  supplied workbook corpora, and keep unsupported or volatile workbook functions
+  documented in the resulting report.
 
 ## For Coding Agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/headless",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Headless spreadsheet engine and WorkPaper workbook facade for Node services, coding agents, and HyperFormula-style workflows.",
   "keywords": [
     "agent",
@@ -49,9 +49,9 @@
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@bilig/core": "0.8.2",
-    "@bilig/formula": "0.8.2",
-    "@bilig/protocol": "0.8.2"
+    "@bilig/core": "0.9.1",
+    "@bilig/formula": "0.9.1",
+    "@bilig/protocol": "0.9.1"
   },
   "engines": {
     "node": ">=24.0.0"