spytial-core

The host-agnostic engine behind Spytial. Integrate spatial diagramming into your language.

spytial-core is the browser-side engine that turns relational data + a YAML spec of spatial constraints into a rendered diagram. It is not a tool for end users — it is the piece you embed when you want Spytial in a new host (a language, an IDE, a notebook, a debugger).

If you want to render Python objects, use sPyTial. If you want to render Rust values, use Caraspace. If you want to render Pyret values, use Spyret. If you want to add a new host to that list — read on.

---

The integration guide

The full guide is published from site/ and rendered with Docsify.

The structure mirrors the integrator's job:

• Overview — What is spytial-core? · The Integration Pipeline · Quick Start
• Integrating Spytial Into a Language — New Language Integration · Custom Data Instances
• Data — JSON Data Format · Built-in Adapters
• The YAML Spec Language — YAML Reference · Constraints · Directives · Selector Syntax
• Sequences of States — Sequence Layouts
• API Reference — Exported API
• Cookbook — Examples

To browse the guide locally:

npm run serve   # python3 -m http.server 8080
# open http://localhost:8080/site/

---

Installation

NPM:

npm install spytial-core

CDN:

<script src="https://cdn.jsdelivr.net/npm/spytial-core/dist/browser/spytial-core-complete.global.js"></script>

For reproducibility, pin a version (e.g. spytial-core@2.5.2).

---

The five-line integration

import {
  JSONDataInstance,
  parseLayoutSpec,
  SGraphQueryEvaluator,
  LayoutInstance,
} from 'spytial-core';

const instance  = new JSONDataInstance(jsonPayload);
const spec      = parseLayoutSpec(yamlSpec);
const evaluator = new SGraphQueryEvaluator();
evaluator.initialize({ sourceData: instance });

const layout = new LayoutInstance(spec, evaluator).generateLayout(instance);
document.querySelector('webcola-cnd-graph').renderLayout(layout);

That's the entire core pipeline. Where jsonPayload and yamlSpec come from is the host integrator's job — see the Quick Start for a self-contained HTML example, and New Language Integration for the principled framing.

---

What spytial-core ships

Layer	Highlights
Data instances	JSONDataInstance, AlloyDataInstance, DotDataInstance, PyretDataInstance, TlaDataInstance, plus the IDataInstance interface for custom adapters.
Spec language	YAML constraints (orientation, align, cyclic, group, size, hideAtom) and directives (atomColor, edgeColor, icon, attribute, tag, inferredEdge, flag, …).
Selector engine	SGraphQueryEvaluator (Forge-style relational expressions) plus optional Forge / SQL evaluators.
Layout solver	LayoutInstance + QualitativeConstraintValidator — qualitative spatial constraints with IIS reporting.
Renderers	<webcola-cnd-graph> (visual), <spytial-explorer> (a11y + spatial REPL), AccessibleTranslator (semantic HTML / alt-text).
Sequence support	Pairwise policies (stability, changeEmphasis, randomPositioning, …) for inter-frame continuity. Custom policies via registerSequencePolicy.
Selector synthesis	Generate CnD selectors from positive/negative atom or pair examples.
React components	InstanceBuilder, ReplInterface, ProjectionControls, ProjectionOrchestrator, ErrorMessageContainer, ReplWithVisualization.

Full export surface: API Reference.

---

Stable references

The YAML spec is mirrored to a CDN-stable URL for use by integrators / agents that want to pin a copy:

https://cdn.jsdelivr.net/gh/sidprasad/spytial-core@<tag-or-sha>/docs/YAML_SPECIFICATION.md

---

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/...)
3. Run npm run build:all and npm run test:run
4. Open a Pull Request

The dev-loop reference is in docs/DEV_GUIDE.md.

---

MIT