@bilig/headless weekly downloads statistics

@bilig/headless

@bilig/headless is the lower-level formula and WorkPaper runtime behind the scoped @bilig/workpaper entrypoint.

If this npm page is the first thing you found, run the package proof before reading the full API docs:

It should print verified: true after editing an input cell, recalculating a dependent formula, exporting WorkPaper JSON, restoring it, and reading the same calculated value again.

Choose the narrow package by the state you own:

| You own... | Start with | First proof |

| WorkPaper state inside a service | npm install @bilig/workpaper | bilig-evaluate --door workpaper-service --json | | A new service or route | npm create @bilig/workpaper@latest pricing-workpaper | npm run smoke | | Tool or MCP integration | npm create @bilig/workpaper@latest pricing-agent -- --agent | bilig-evaluate --door agent-mcp --json | | Lower-level runtime subpaths | npm install @bilig/headless | The examples below prove WorkPaper JSON, provenance, and package weight. | | A saved workbook file remains the contract | npm install @bilig/xlsx-formula-recalc | bilig-evaluate --door workbook-compatibility --json |

Use @bilig/headless when the workbook is the business logic, but production needs API readback, tests, persistence, and deterministic proof instead of a person opening a spreadsheet app.

Your code owns a WorkPaper: build sheets, write inputs, recalculate formulas, read the cell value, and save the workbook as JSON. Product code gets reviewable workbook-shaped logic without shipping a spreadsheet UI. Tool hosts can expose narrow operations such as readRange and setInputCell instead of guessing state from screenshots.

The npm tarball also includes AGENTS.md and SKILL.md so tool hosts inspecting node_modules/@bilig/headless can find the write/read/persist loop locally. The public docs expose the same path through AGENTS.md, agent.json, skill.txt, WorkPaper agent tool, and llms-full.txt.

This package is not a browser grid or desktop Excel automation. Workbook file import/export is available from the @bilig/workpaper/xlsx and @bilig/headless/xlsx subpaths for services that need ingestion around the same WorkPaper model.

The bilig-workpaper-mcp binary still ships for hosts that specifically need an MCP stdio boundary. It is not the default evaluation path; prove the direct npm or TypeScript path first unless your tool host requires MCP. The bilig-formula-clinic binary turns a reduced XLSX into a fixture report without uploading workbook contents.

Saved workbook files are supported, but separate. Use the compatibility report or recalculation example only when the file boundary is the product contract: docs/workbook-compatibility-report.md, examples/xlsx-recalculation-node, and docs/xlsx-formula-recalculation-node.md.

Choose An Evaluation Path

| If you are evaluating... | Start here | What should be true before you adopt |

| Basic fit | Why use Bilig? | The problem is workbook-shaped business logic that needs API readback and persistence. | | Published npm package | 90-second Node quickstart | It edits one input, recalculates, persists JSON, restores, and prints verified: true. | | Backend service shape | Quote approval WorkPaper API and pnpm --dir examples/serverless-workpaper-api run hono-route | A realistic route-style workflow returns formula readback and restoredMatchesAfter: true. | | Saved workbook files | Workbook Compatibility Report and XLSX formula recalculation example | Use this only when a workbook file remains the integration contract. | | Agent or MCP tools | Headless WorkPaper agent handbook and MCP spreadsheet tool server | The agent can pick MCP, direct TypeScript, or route tools and prove write/readback/persist. | | Runtime intent contracts | Workbook runtime intent API | @bilig/workbook can describe plans, receipts, and strict runtime proof without owning state. | | Tool-owned workbook files | Workbook Compatibility Report | A tool can inspect file risks before the service trusts imported formulas. | | Technical review note | WorkPaper maintainer proof note | One compact page has the npm check, benchmark caveat, known limits, and open questions. | | Trust and performance | npm provenance and benchmark evidence | npm shows SLSA provenance, and benchmark claims match the checked artifact. | | Almost a fit | implementation gap discussion | Name the formula, import/export, persistence, framework, MCP, package, or benchmark gap. | | Formula or XLSX bug | formula bug clinic and submit a workbook fixture | Share one reduced public fixture that maintainers can turn into a test. | | Real workbook blocked | submit a workbook fixture | Use the structured form when a reduced workbook is ready. |

Reduced workbook already in hand? If the blocker is an import, formula, or persistence gap, generate the fixture report:

Handing a spreadsheet task to another coding agent?

The first command tells the agent which proof path to run. The second command proves the direct WorkPaper API. The third proves the agent tool path with tool discovery, cell mutation, formula readback, JSON export, and restart proof. Both run without cloning the repository.

Install

Requires Node 22+ and ESM imports.

For a route-shaped quote approval API today:

For a generated starter project:

That command is published through @bilig/create-workpaper. The publish gate is documented at . The --agent starter adds AGENTS.md, CLAUDE.md, project-root .mcp.json for Claude Code, Cursor and VS Code MCP configs, .junie/mcp/mcp.json for Junie, mcp/bilig-workpaper.mcp.json, npm run agent:verify, and `npm run mcp:server`.

Current checked npm footprint for @bilig/headless@0.164.11:…

Description from the npm listing.