@bilig/headless 0.11.15 → 0.11.18

package/README.md

@@ -35,7 +35,12 @@ pnpm --filter @bilig/headless build
   smoke test.
 - Try the runnable examples:
   [`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper) and
-  [`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input).
+  [`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
+  for in-process records, or
+  [`npm run json-file`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input)
+  for records already saved on disk, or
+  [`npm run http-json-summary`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary)
+  for a no-framework Node HTTP boundary.
 - Run the
   [serverless WorkPaper API example](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
   when the workbook belongs behind an HTTP or agent-tool boundary.
@@ -259,6 +264,7 @@ restores the workbook, and verifies the final result.
 cd examples/headless-workpaper
 npm install
 npm start
+npm run http-json-summary
 npm run agent:tool-call
 ```
 
@@ -332,6 +338,30 @@ npm run persistence
 - Mutation methods return WorkPaper change arrays. Empty arrays are valid when
   evaluation is suspended or a batch defers change publication.
 
+## WorkPaper Read/Write Cheat Sheet
+
+The common service and agent calls use the same zero-based address object:
+
+```ts
+const sheet = workbook.getSheetId('Sheet1')
+if (sheet === undefined) throw new Error('Sheet1 was not created')
+const at = (row: number, col: number) => ({ sheet, row, col })
+```
+
+| Operation               | Public API                                                     | Tiny snippet                                                                                          |
+| ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Create a workbook       | `WorkPaper.buildFromSheets()`                                  | `const workbook = WorkPaper.buildFromSheets({ Sheet1: [[1, '=A1*2']] })`                              |
+| Set a value             | `workbook.setCellContents()`                                   | `workbook.setCellContents(at(0, 0), 42)`                                                              |
+| Set a formula           | `workbook.setCellContents()`                                   | `workbook.setCellContents(at(0, 1), '=A1*2')`                                                         |
+| Read a calculated value | `workbook.getCellValue()`                                      | `const value = workbook.getCellValue(at(0, 1))`                                                       |
+| Read formula text       | `workbook.getCellFormula()`                                    | `const formula = workbook.getCellFormula(at(0, 1))`                                                   |
+| Export/persist state    | `exportWorkPaperDocument()` and `serializeWorkPaperDocument()` | `const json = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))` |
+| Restore persisted state | `parseWorkPaperDocument()` and `createWorkPaperFromDocument()` | `const restored = createWorkPaperFromDocument(parseWorkPaperDocument(json))`                          |
+
+Use `getCellDisplayValue()` for user-facing text, `getCellSerialized()` for the
+stored input shape, and range helpers such as `getRangeValues()` when an API
+response needs more than one cell.
+
 ## Common API Recipes
 
 Create an empty workbook:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/headless",
-  "version": "0.11.15",
+  "version": "0.11.18",
   "description": "Headless spreadsheet engine for Node.js formulas, workbook JSON persistence, and service-side spreadsheet automation.",
   "keywords": [
     "agent",
@@ -66,9 +66,9 @@
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@bilig/core": "0.11.15",
-    "@bilig/formula": "0.11.15",
-    "@bilig/protocol": "0.11.15"
+    "@bilig/core": "0.11.18",
+    "@bilig/formula": "0.11.18",
+    "@bilig/protocol": "0.11.18"
   },
   "engines": {
     "node": ">=24.0.0"