rapira: Instructions file for Claude Code

CLAUDE.md — working on this codebase

Project-level notes for future Claude sessions. The TL;DR: this is a faithful interpreter for the 1985 Agat dialect of Rapira (not the modern Rapture dialect). When in doubt about language semantics, the source of truth order is:

1. RAPIRA.md — the canonical 1985 spec, in Russian
2. SPEC.md — what this implementation actually does, including documented deviations
3. The code

Stack

• Bun for the runtime, test runner, and bundler. No Node, no Vite, no Svelte, no SvelteKit. They were ripped out — don't add them back without a strong reason.
• TypeScript with allowImportingTsExtensions so .ts extensions appear in imports (import './foo.ts'). The web tsconfig (web/tsconfig.json) inherits the same convention.
• CodeMirror 6 in the playground; the rest of the playground is plain DOM.
• just is optional — every recipe in Justfile is a thin wrapper around a bun run invocation.

Commands

Layout

src/                     interpreter core — pure, no I/O dependencies
  lexer.ts               tokeniser; Russian-only keyword table normalised to ru-RU upper-case
  parser.ts              recursive descent → AST
  ast.ts                 AST node types
  interpreter.ts         tree-walker; defines Host interface, BufferedHost
  values.ts              RValue + deep equality + arithmetic dispatch + display
  environment.ts         scope chain
  errors.ts              Pos + RapiraError subclasses
  graphics.ts            GfxEvent typed union + sinks
  fs.ts                  FileSystem capability + InMemoryFileSystem
  stdlib/gfx.ts          documented Agat graphics primitives + Чертёжник turtle
  keywords.ts            bilingual lookup table (Russian-only — "bilingual" is a misnomer left over from earlier; do not add English keywords)

cli/                     Node-backed host: stdin/stdout, NodeFileSystem, SVG renderer
                         Bundled by scripts/cli-build.ts into dist/rapira.js
                         for npm publish (`npx rapira FILE.rap`)
web/                     vanilla DOM + CodeMirror 6 playground
  worker.ts              interpreter in a Web Worker (sync sleep via Atomics.wait)
  lib/                   renderer.ts (canvas), rapira-mode.ts (CodeMirror language + light/dark highlight)

scripts/web-build.ts     Bun-only build driver (replaces Vite). Also copies tests/snippets/ → docs/examples/

tests/
  snippets/              *.rap + *.expected.txt / *.expected.svg — runner walks the directory
  *.test.ts              unit tests grouped by layer

examples/                .rap files for the CLI; not the same as tests/snippets/

RAPIRA.md                the 1985 spec
SPEC.md                  this implementation's contract