Bilig headless WorkPaper launch: spreadsheet engine for agents and Node services

[gregkonush]

I built @bilig/headless, a TypeScript spreadsheet engine for agents, Node services, and local-first workbook automation.

The motivating problem: useful business logic still lives in spreadsheet-shaped models, but most automation either drives a browser grid or reimplements formulas in ad hoc service code. That is brittle for coding agents and awkward for backend services.

@bilig/headless exposes a WorkPaper API for programmatic spreadsheet work:

• create workbooks from arrays or named sheets
• evaluate formulas
• edit cells, rows, columns, sheets, and named expressions
• batch related edits
• persist and restore workbook documents
• inspect values, formulas, serialized inputs, ranges, and sheets
• run without opening the browser UI

Try it from npm:

npm install @bilig/headless

Minimal example:

import { WorkPaper } from "@bilig/headless";

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

const summary = workbook.getSheetId("Summary");
console.log(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }));

The repo also includes a runnable external-consumer example:

git clone https://github.com/proompteng/bilig.git
cd bilig/examples/headless-workpaper
npm install
npm start

Performance claims are checked in rather than left as marketing copy. The current WorkPaper benchmark artifact records 46/46 mean wins on scorecard-eligible comparable workloads against HyperFormula-style workloads: 38/38 public and 8/8 holdout.

That is not a blanket "faster on every p95 row" claim. The evidence note spells out what is measured, what is excluded, and where the p95 caveat still exists:

https://github.com/proompteng/bilig/blob/main/docs/headless-workpaper-benchmark-evidence.md

Useful entry points:

• npm: https://www.npmjs.com/package/@bilig/headless
• package README: https://github.com/proompteng/bilig/tree/main/packages/headless#readme
• runnable example: https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper
• adoption kit: https://github.com/proompteng/bilig/blob/main/docs/public-adoption-kit.md
• good first issues: https://github.com/proompteng/bilig/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22

The project is still early infrastructure, not a finished Excel clone. Known open areas include deeper Excel formula parity, structured references, dynamic arrays, durable multiplayer sync, and more public release hardening.

If this solves a real problem for you, a GitHub star helps more spreadsheet-automation and agent developers find it.

[gregkonush]

Launch links are live:

• Show HN: https://news.ycombinator.com/item?id=48045427
• X launch post: https://x.com/GregKonush
• Best of JS project suggestion: Add Bilig bestofjs/bestofjs#431

If @bilig/headless is useful for a Node service, coding-agent workflow, or spreadsheet automation project, starring the repo helps more developers find it: https://github.com/proompteng/bilig

[gregkonush]

Added the second proof artifact for the headless launch: a persistence-focused article plus a runnable Node example.

• Article: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md
• Example: https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/persistence-roundtrip.mjs
• Smoke gate: pnpm workpaper:smoke:external now runs both the revenue example and the persistence round trip against packed local runtime packages.

This is the WorkPaper save/restore path I expect agent and Node-service users to care about: formulas stay formulas, named expressions survive the JSON document boundary, and restored workbooks still recalculate after a later edit.

[gregkonush]

added a short benchmark explainer for the current WorkPaper claim: https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md

it spells out what the benchmark proves, what it does not prove, and the p95 caveat around lookup-approximate-duplicates. the public claim stays precise: 46/46 mean wins on current comparable headless WorkPaper workloads, not a blanket “faster at everything” statement.

[gregkonush]

added another runnable artifact for the launch thread: a headless workpaper revenue model with formula-backed scenarios, agent-style edits, persistence, and verified readback.

article: https://github.com/proompteng/bilig/blob/main/docs/building-a-revenue-model-with-headless-workpaper.md
example: https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/revenue-scenarios.mjs

this is the shape i want agents to support by default: load workbook state, change inputs, recalc formulas, verify outputs, serialize the document, and restore it without losing the model.

[gregkonush]

added a public compatibility-boundaries note too: https://github.com/proompteng/bilig/blob/main/docs/where-bilig-is-not-excel-compatible-yet.md

short version: bilig is not a complete excel clone. native macro execution is intentionally out, formula parity claims are fixture/evidence-scoped, cached xlsx result parity is corpus-scoped, and headless workpaper benchmark claims should not be mixed with browser-ui dominance claims.

this should make the project easier to evaluate honestly instead of making people infer the boundaries from benchmark json.

[gregkonush]

added one more evaluator-facing note: https://github.com/proompteng/bilig/blob/main/docs/xlsx-corpus-verifier-walkthrough.md

it explains how to read the xlsx corpus verifier output: matched formula cells, skipped formula cells, mismatch reports, and why skipped formulas are evidence boundaries rather than successes. current checked-in corpus result is 1 file, 14 comparable formulas, 14 matches, 0 mismatches, 0 skipped.

[gregkonush]

added two more growth/support docs:

• xlookup exact fixture walkthrough: https://github.com/proompteng/bilig/blob/main/docs/formula-edge-xlookup-exact-fixture.md
• x reply growth playbook: https://github.com/proompteng/bilig/blob/main/docs/x-reply-growth-playbook.md

the reply playbook is intentionally manual and account-safe. no spam/evasion tactics; the useful shape is fewer high-fit replies, lowercase/direct tone, and a concrete artifact only when it actually helps the thread.

also kept the claim style evidence-scoped: the xlookup note proves one exact-match fixture with the verifier command, not every xlookup mode.

[gregkonush]

updated the public contributor funnel:

• labeled the open technical backlog with area: import-export, area: formula, and needs reduced fixture
• marked Workbook import dispatcher rejects MIME types with parameters or different case #29 as a code-oriented good first issue / help wanted
• updated the starter issue page with the new starter ticket and label filters: https://github.com/proompteng/bilig/blob/main/docs/starter-issues.md

this should make the repo easier to scan from github issues instead of forcing people to reverse-engineer the backlog from issue titles.

[gregkonush]

added a show hn launch pack: https://github.com/proompteng/bilig/blob/main/docs/show-hn-launch-pack.md

it includes the submission title, github repo url, first-comment draft, preflight commands, likely questions, and follow-up loop. i also linked it from the readme, package readme, adoption kit, launch post draft, growth plan, and public homepage.

external package smoke passed locally before the commit, and the current public head is green on github ci, pages, and runtime package workflows.

[gregkonush]

added a community launch pack: https://github.com/proompteng/bilig/blob/main/docs/community-launch-pack.md

it has platform-specific drafts and guardrails for reddit, dev, lobsters, and product hunt. the point is to adapt to each community instead of pasting the same launch link everywhere: manual posts, no vote asks, no fake-neutral framing, and feedback converted into issues/docs/examples.

also tightened the x reply playbook with a current lower-case tone scan and a weekly loop: ship one proof artifact, explain it publicly, reply only where the thread already fits, and convert repeated questions back into repo evidence.

[gregkonush]

added a dev-ready article draft: https://github.com/proompteng/bilig/blob/main/docs/dev-to-workbook-apis-post.md

it is shaped for a real technical post, not a thin repo link: front matter, canonical url, social preview image, a concrete node example, benchmark caveats, and feedback prompts for api friction / formula semantics / import-export cases.

also fixed the sparse xlsx import regression-test timeout that failed on the github runner after the corpus-footprint commit. local ci is green, and the pushed head is green on github actions now.