@spacedevin/deck

Streamable .deck patch language for Tish hosts (e.g. Deckard).

Install

npm install @spacedevin/deck

import { parseProgram, registerGeneratorIdAliases, registerGenBlockDialect } from "@spacedevin/deck"

registerGeneratorIdAliases({ matrix_fm: "matrixFm" }, { matrixFm: "matrix_fm" })
// registerGenBlockDialect(...) — host supplies patch / matrix_fm parsers

let ast = parseProgram(source)

Examples

Runnable demos in examples/ (parse, host boot, helpers):

npm run examples

In scope

| Area | API | |------|-----| | Lex / parse | tokenize, isNumberToken, parseProgram | | Track / clip body | parseBodyLine, parseTrackBody, parseBoolish | | Format | formatTplBeat, formatTplFloat | | Scale | parseScaleRoot, scaleRootNames, scaleModeNames, scaleIntervals | | Bar / Euclid | parseBarSelector, barSelectorMatches, euclideanPattern | | Registries | registerGeneratorIdAliases, registerParamKeyAliases, paramKeyToCamel, … | | Host extensions | registerBodyLineDialect, registerTopLevelStatement, registerGenBlockDialect | | Macros | registerBuiltinMacros, lookupMacro, expandMacroBody | | gen_block | parseGenBlock, registerGenBlockDialect | | Highlight | classifyLine, isKeyword, registerHighlightKeywords |

Out of scope (host)

Apply/emit to project IR · session/co-DJ · audio engines · instrument catalogs · builtin macro catalogs · HTML highlight CSS · graph editor mutators.

Rust

The same src/index.tish also emits a Rust library crate, so a Rust consumer (tish-gba's build-time bake) parses .deck with this parser rather than its own:

npm run build:rust   # -> crate/  (crates.io: `deckfile`)
npm run test:rust    # the same conformance corpus, from Rust

let program = deckfile::parse(src);          // typed
let ast = deckfile::parseProgram(value);     // the raw AST, same shape as JS

One source, three targets — Tish, JS, Rust — checked against one corpus.

Docs

• Language grammar — canonical .deck surface
• gen_block extensions — dialect registration + common patch / matrix_fm
• Host integration — boot order, registries, what hosts implement
• AGENTS.md — in/out of scope for package edits

npm also exports ./grammar and ./extension to those markdown files.

Release

Matches lattish: semantic-release prerelease → promote → OIDC npm publish.

Test / coverage

npm test                 # build + API/grammar suite + conformance + tish smoke
npm run test:coverage    # c8 on dist/deck.js — 100% lines / functions / statements
npm run test:conformance # the cross-implementation corpus
npm run examples         # runnable demos

conformance/ is the contract between implementations: the same .deck inputs and expected parses are run by the JS build, the Rust crate emitted from the same Tish source, and any restricted host (via a profile). It is what makes drift a test failure rather than a surprise.

Branch % is lower (~60%) because the Tish→JS emit adds many ?? null / typeof guards that are defensive noise, not language logic. Line coverage is the gate in CI.

License

Pay It Forward (PIF) — see LICENSE. Same license as tish.