bilig - headless spreadsheet engine

Use workbook behavior as a library boundary.

A grid component is the wrong primitive for backend jobs, coding agents, and local-first sync. bilig keeps the workbook model addressable from code.

Formula-backed state

Create sheets, write cells, evaluate formulas, and inspect calculated values through a typed API.

Structural edits

Move cells, apply workbook operations, undo and redo changes, and preserve state through snapshots.

Agent-ready shape

Stable document and request shapes let tools mutate workbook state without screen scraping or hidden UI state.

Try the published package without cloning the repo.

The first evaluation path uses npm only. It builds a formula-backed workbook, edits source data, persists the document, restores it, and verifies the recalculated value.

mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless

then create eval.mjs and run node eval.mjs

expected output includes total revenue before and after an edit, the restored sheet names, and a positive serialized byte count.

import {
  WorkPaper,
  createWorkPaperFromDocument,
  exportWorkPaperDocument,
  parseWorkPaperDocument,
  serializeWorkPaperDocument,
} from "@bilig/headless";

const workbook = WorkPaper.buildFromSheets({
  Revenue: [
    ["Region", "Customers", "ARPA", "Revenue"],
    ["West", 20, 1200, "=B2*C2"],
    ["East", 30, 250, "=B3*C3"],
    ["Central", 18, 300, "=B4*C4"],
  ],
  Summary: [
    ["Metric", "Value"],
    ["Total revenue", "=SUM(Revenue!D2:D4)"],
  ],
});

const revenue = workbook.getSheetId("Revenue");
const summary = workbook.getSheetId("Summary");

if (revenue === undefined || summary === undefined) {
  throw new Error("missing sheet");
}

const before = workbook.getCellValue({ sheet: summary, row: 1, col: 1 });
workbook.setCellContents({ sheet: revenue, row: 1, col: 1 }, 32);
const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }));
const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved));
const restoredSummary = restored.getSheetId("Summary");

if (restoredSummary === undefined) {
  throw new Error("missing restored sheet");
}

const after = restored.getCellValue({ sheet: restoredSummary, row: 1, col: 1 });

console.log({ before, after, sheets: restored.getSheetNames(), bytes: saved.length });

Runtime surface

Use bilig where workbook semantics matter more than a rendered grid.

Capability	Status
Programmatic workbook creation	available
Formula evaluation and readback	available
Structural edits and undo/redo	available
Snapshot and restore	available

Current scope

For Node services, scripts, and agent-controlled workbook workflows.
For formula-backed business logic that needs deterministic readback.
Not presented as a finished Excel clone or complete formula-parity claim.
Use the checked-in examples and tests as the acceptance surface.

Evidence links

Start from artifacts, not claims. The repo includes examples, benchmark notes, and public issue threads for adoption work.

46/46 mean wins in checked-in comparable WorkPaper benchmark rows against HyperFormula-style workloads.

CI gated types, unit tests, generated-file checks, package smoke paths, and browser checks run in the repo gate.

What to review first

the external-consumer example for package shape
the agent writeback demo for formula and persistence readback
the public adoption kit for evaluation links
the workbook-api article for agent workflow positioning
the revenue-model article for a multi-sheet planning example
the benchmark explainer for the measured claim and caveat
starter issues for small contribution paths
benchmark evidence for the WorkPaper runtime path

Project links

GitHub repository source, issues, discussions Star or bookmark follow the project Feedback discussion agent and service workflow input Starter issues small contribution paths npm package @bilig/headless Technical article workbook APIs for agents Persistence article save and restore WorkPaper JSON Revenue model article formula-backed scenarios in Node Compatibility boundaries what is not Excel-compatible yet XLSX verifier walkthrough matched, skipped, and mismatched formulas XLOOKUP exact fixture one formula claim with verifier evidence Benchmark explainer 46/46 mean wins, p95 caveat Runnable example external package and agent writeback smoke paths Adoption kit proof links and listing copy X reply playbook manual, lower-case, source-backed outreach Show HN launch pack submission checklist and maintainer replies Community launch pack Reddit, DEV, Lobsters, Product Hunt DEV article draft workbook APIs instead of screenshots