@bilig/headless 0.9.0 → 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
@@ -45,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.
@@ -69,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:
 
@@ -147,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
@@ -203,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
@@ -236,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/headless",
-  "version": "0.9.0",
+  "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.9.0",
-    "@bilig/formula": "0.9.0",
-    "@bilig/protocol": "0.9.0"
+    "@bilig/core": "0.9.1",
+    "@bilig/formula": "0.9.1",
+    "@bilig/protocol": "0.9.1"
   },
   "engines": {
     "node": ">=24.0.0"