open-sheet AGENTS.md

open-sheet — repository guide

This file describes the framework repo. If you are authoring workbooks in a scaffolded workspace, you want the sheet-authoring skill instead.

Repo layout

pnpm + Turbo monorepo.

Path	Package	Purpose
packages/core	@open-sheet/core	Compiler, placement, references, formula engine, style bridge, export, viewer, Vite plugin, open-sheet CLI
packages/cli	@open-sheet/cli	Scaffolder and project template
packages/mcp	@open-sheet/mcp	MCP server over Streamable HTTP
apps/demo	private	Local framework consumer, dogfood target

Shared config at the root: biome.json, turbo.json, pnpm-workspace.yaml, tsconfig.base.json.

Commands

pnpm dev          # run the demo against local core
pnpm build        # build all packages
pnpm typecheck    # tsc across the monorepo
pnpm check        # biome: format, lint, organize imports
pnpm check:fix    # auto-fix
pnpm test         # vitest

Filter to one package: pnpm core <script>, pnpm cli <script>, pnpm mcp <script>.

The one invariant

No A1 address is ever authored by hand — not in apps/demo, not in fixtures, not in tests that represent user code.

The whole premise of open-sheet is that the framework owns every coordinate. A test fixture containing =SUM(B2:B13) written by a human is a fixture that stops testing the thing that matters. Tests may assert on A1 output; they must not author it.

The one exception is raw(), the deliberate escape hatch. It is expected to show #NOT_EVALUATED in the viewer.

Core pipeline

Understand this before touching packages/core:

sheets/<id>/index.tsx
  → (1) evaluate JSX via our own jsx-runtime (no react-dom, no DOM at all)
  → Block tree
  → (2) measure   each block reports its intrinsic { rows, cols }
  → (3) place     assign every block an origin; collisions are a bug
  → Grid model + anchor registry
  → (4) resolve   Refs → concrete A1 / defined names
  → (5) evaluate  topological evaluation → the numbers the viewer shows
  → emit: viewer | .xlsx | .csv | .html | .pdf