bilig

Public APIs

Current state

• @bilig/core now implements the documented range-mutation, undo/redo, selection, and sync-state surface.
• SelectionState is additive: existing callers can keep using sheetName and address, while newer callers can use anchorAddress, range, and editMode.
• connectSyncClient is live. apps/web is already worker-first by default, but the remote sync service is not a closed durable worksheet backend yet.
• @bilig/binary-protocol is already a real wire protocol for sync frames, but the authoritative replicated workbook op family is still narrower than the full local engine surface.
• @bilig/agent-api is currently a binary envelope around JSON payloads, not yet a fully typed binary request/response/event schema.

Stable packages

@bilig/headless is the current external npm adoption path. The other package surfaces listed here are stable repository package boundaries; not every package name is provisioned on npm yet. In particular, @bilig/excel-import is still a repository package until its npm package name is configured.

• @bilig/core
• @bilig/headless
• @bilig/excel-import
• @bilig/formula
• @bilig/wasm-kernel
• @bilig/workbook-domain
• @bilig/renderer
• @bilig/grid
• @bilig/binary-protocol
• @bilig/worker-transport
• @bilig/agent-api
• @bilig/storage-browser
• @bilig/storage-server
• @bilig/excel-fixtures

Workbook DSL

@bilig/renderer keeps the declarative workbook DSL unchanged:

• <Workbook>
• <Sheet name="...">
• <Cell addr="..." value={...} />
• <Cell addr="..." formula="..." />
• <Cell addr="..." format="..." />

Core engine surface

The canonical engine surface includes:

• createSheet
• deleteSheet
• setCellValue
• setCellFormula
• setCellFormat
• clearCell
• setRangeValues
• setRangeFormulas
• clearRange
• fillRange
• copyRange
• pasteRange
• setSelection
• undo
• redo
• getCell
• getDependencies
• getDependents
• explainCell
• exportSnapshot
• importSnapshot
• exportReplicaSnapshot
• importReplicaSnapshot
• applyRemoteBatch
• subscribe
• subscribeBatches
• connectSyncClient
• disconnectSyncClient
• getSyncState

WorkPaper surface

@bilig/headless exposes WorkPaper, a HyperFormula-style headless workbook API on top of @bilig/core:

• WorkPaper.buildEmpty
• WorkPaper.buildFromArray
• WorkPaper.buildFromSheets
• WorkPaper.buildFromSnapshot
• workbook reads for cells, ranges, sheets, and named expressions
• display-value and formula-diagnostic reads for user-facing errors and structured financial validation details
• workbook mutations for cells, rows, columns, sheets, clipboard, and history
• batch, suspendEvaluation, resumeEvaluation, undo, and redo
• formula helpers such as address parsing, normalization, validation, and scratch evaluation
• static language and custom-function registration
• HyperFormula-style positional events through on, once, and off
• additive structured events through onDetailed, onceDetailed, and offDetailed
• stable internal adapter getters: graph, rangeMapping, arrayMapping, sheetMapping, addressMapping, dependencyGraph, evaluator, columnSearch, and lazilyTransformingAstService

WorkPaper is the canonical top-level contract.

Excel Import Surface

@bilig/excel-import exposes the repository CSV/XLSX boundary for WorkPaper consumers. It is not yet published as an npm package:

• importXlsx(bytes, fileName)
• importCsv(text, fileName)
• importWorkbookFile({ bytes, fileName, contentType })
• exportXlsx(snapshot)
• CSV_CONTENT_TYPE
• XLSX_CONTENT_TYPE

Use importXlsx(...).snapshot with WorkPaper.buildFromSnapshot() when a consumer needs Excel workbook metadata such as defined names, tables, and translated structured references. WorkPaper.buildFromSheets() remains a metadata-free array/sheet constructor.

Core types added in the current tranche

• CellRangeRef
• SelectionRange
• SelectionEditMode
• SyncState

Binary protocol

@bilig/binary-protocol exposes:

• PROTOCOL_VERSION
• encodeFrame(frame): Uint8Array
• decodeFrame(bytes): ProtocolFrame

The current frame families are:

• hello
• appendBatch
• ack
• snapshotChunk
• cursorWatermark
• heartbeat
• error

The protocol surface is already real for sync and snapshot traffic. The remaining architecture gap is not “do we have binary frames?” but “does the authoritative workbook mutation language fully match what the local engine can represent?”

Worker transport

@bilig/worker-transport exposes:

• createWorkerEngineHost(engine, port)
• createWorkerEngineClient({ port })

The first tranche already supports:

• method invocation
• engine events
• outbound batch subscriptions

Target state

• the core API stays source-compatible while the worker-first runtime and durable backend land under it
• the binary protocol becomes the canonical wire format for browser sync, backend relay, and agent APIs
• the agent API moves from JSON payload bodies to typed binary request/response/event frames

Exit gate

• every API documented here exists in code
• typecheck passes across all packages that import these APIs
• direct engine tests cover range mutation, history, selection state, and sync-state behavior
• the docs no longer claim a stable interface that is missing in the repo

Agent API

@bilig/agent-api exposes:

• AgentRequest
• AgentResponse
• AgentEvent
• encodeAgentFrame
• decodeAgentFrame
• encodeStdioMessage
• decodeStdioMessages

Today the package defines typed TypeScript request/response/event unions, but the transport payload is still serialized with JSON.stringify(...) inside the binary frame envelope. The target state is a true typed binary schema shared by stdio and remote network usage.

This site is open source. Improve this page.