Spyret

Spyret connects Pyret values to Spytial diagrams. toDataInstance(value, runtime) turns a Pyret value into relational data for Spytial; await getSpytialSpec(value, runtime) walks its reachable values and collects one YAML string per distinct _spytial hook. Hooks can return typed Pyret rules or raw YAML; values without hooks return []. The JavaScript API runs without an IDE, and the browser library lets Pyret programs display diagrams in CPO through an import.

JavaScript

npm install spyret

import { toDataInstance, getSpytialSpec } from 'spyret';

// Use the Pyret runtime that owns the value, while it is idle or paused.
const instance = toDataInstance(pyretValue, runtime);
const specs = await getSpytialSpec(pyretValue, runtime); // string[]
// Pass the data and layout specs to Spytial-Core.

toDataInstance returns an IDataInstance and never invokes hooks. The collector handles cycles and calls each distinct hook once. See the hook contract and typed rules for composition, errors and runtime requirements. For portable snapshots and reconstruction, see the capture API.

Pyret: import, describe, display

A maintainer runs npm run release:drive and follows the CPO-save and Drive publishing instructions. The native JavaScript file needs CPO per-file authorization; a public Drive upload alone is insufficient. Verify access with a second account before distributing the versioned wrapper, which combines typed rule constructors and diagram functions:

# Use the import line supplied by the library maintainer.
import shared-gdrive("spyret-vVERSION.arr", "WRAPPER_DRIVE_FILE_ID") as S

data Tree:
  | leaf(value)
  | branch(left, right)
sharing:
  method _spytial(self):
    [list: S.orientation("left + right", [list: S.below])]
  end
end

S.diagram(branch(leaf(1), leaf(2)))

diagram collects the reachable types' rules, relationalizes the value and displays a diagram. Compose rules with ordinary Pyret lists; constructors such as orientation, align and group handle their constraint/directive category. S.diagram([list: 1, 2, 3]) also works without any hooks. To supply rules explicitly, use S.diagram-with-rules(value, rules), or S.diagram(value, yaml) for YAML. See the layout rule guide for examples and meaning, and the rule reference for every constructor. These examples use the 0.3.0 source API. The published v0.2.0 release wrapper uses names such as S.direction-below; release:drive prints an example matching the release it downloads. Version 0.3.0 also replaces fluent .with-* style options with named records and typed style blocks.

The import form depends on the host and file:

| Import | What it loads | | --- | --- | | shared-gdrive("spyret-vVERSION.arr", "WRAPPER_DRIVE_FILE_ID") | The versioned release wrapper in CPO: typed rules and diagram functions in one import. | | url("https://raw.githubusercontent.com/…/spyret-vVERSION.arr") | A GitHub-hosted Pyret wrapper: typed rules and diagram functions in one import. It imports the native module from Drive internally. | | gdrive-js("spyret-vVERSION.js", "NATIVE_DRIVE_FILE_ID") | The versioned native JavaScript module in CPO, providing diagram functions. | | js-file("path/to/spyret") | The same native module in a browser host with a filesystem bridge. |

A plain url(...) import cannot load native JavaScript. The packaged renderer supports CPO; other browser hosts need an adapter. No changes to CPO itself are required, although the library uses private CPO display APIs. See the hosting and import guide for details about published imports.

Spyret owns Pyret adaptation and display integration; Core owns layout semantics and graph rendering. Spyret-IDE can consume this library through a small wrapper; its migration is a separate companion change.

Development

Requires Node 22 or later. The development dependency on released Core 6.3.2 provides its public interface types and tests layout/query compatibility. Published Spyret builds include those type declarations and have no Core runtime dependency.

npm ci
npm run typecheck
npm run build
npm test

To run against an unmodified brownplt/pyret-lang checkout, build its lang/ directory with npm ci --ignore-scripts && make phaseA, then run:

npm run test:upstream -- /path/to/pyret-lang/lang
npm run test:program -- /path/to/pyret-lang/lang
npm run test:spytial -- /path/to/pyret-lang/lang
REIFY_SEED=1 npm run test:pbt -- /path/to/pyret-lang/lang
REIFY_SEED=2 npm run test:pbt -- /path/to/pyret-lang/lang

CI pins upstream revision 6e62dcda5298606aa0abe66a372c4eb17a38db85. The unit suite includes 2,000 generated graphs across two seeds. Each upstream PBT job compiles actual Pyret programs: fixed value/constructor cases, 100 generated values and 20 generated datatype declarations. Producer and decoder run in separate processes; reconstruction receives only JSON snapshots. Actual Pyret check blocks compare inspection strings. No browser or IDE is involved.

CommonJS and ES modules import spyret. The browser bundle is dist/spyret.global.js, which defines Spyret.

npm releases

Published builds contain Spyret's adapter and bundled interface declarations. The standalone browser module loads Core 6.3.2; headless consumers do not need a Core runtime. npm run test:package verifies the actual tarball in an isolated consumer. Version tags trigger the unit/package suite and both upstream PBT seeds before publishing to npm and GitHub. To prepare the latest release for Google Drive, run npm run release:drive and follow the upload prompts. See manual release instructions.

Migration and provenance

The adapters and structural tests were extracted from Spytial-Core, including the capture work in PR #618. Runtime fixture generators came from Spyret-IDE. Both are maintained by Siddhartha Prasad. Core retains its existing Pyret exports temporarily for compatibility; new Pyret functionality belongs here.