@rashidazarang/subframe-core

Framework-agnostic TypeScript parser, validator, and types for the subframe-v1 composition format and the subframe-book-v1 book manifest. Runs in Node and in the browser; zero browser-only dependencies.

This package is the substrate for every other Resonant package (subframe-engine-live, resonant-import-markdown, the conformance suite, the reference reader app). If a tool needs to read, validate, or type a subframe-v1 document, it depends on this package.

Install

pnpm add @rashidazarang/subframe-core

Usage

import {
  parseComposition,
  parseBook,
  validateComposition,
  negotiateCapability,
  SubframeValidationError
} from '@rashidazarang/subframe-core';

// Parse + validate a composition document.
const composition = parseComposition(json);
//      ^? Composition
console.log(composition.text_flow.paragraphs.length);

// Validate without throwing.
const result = validateComposition(json);
if (!result.valid) {
  for (const err of result.errors) {
    console.error(err.path, err.message);
  }
}

// Negotiate against a reader implementation's capability manifest.
const decision = negotiateCapability(composition, {
  accepts_anchors: ['reader', 'continuous'],
  rejects_anchors: ['clock']
});
if (!decision.ok) throw new Error(decision.reason);

API

| Symbol | Description | |---|---| | parseComposition(json: unknown): Composition | Validate then return the inner composition object. Throws SubframeValidationError on schema failure. | | parseBook(json: unknown): BookManifest | Validate then return a typed book manifest. | | parseFromString(text: string): CompositionDocument | JSON.parse + parseComposition. | | parseFromUrl(url, fetch?): Promise<CompositionDocument> | Fetch + parse. Pass a fetch implementation explicitly in Node ≤ 17. | | validateComposition(json: unknown): ValidationResult | Pure validation; returns {valid:true} or {valid:false, errors}. | | validateBook(json: unknown): ValidationResult | Same shape for book manifests. | | negotiateCapability(composition, manifest): {ok:true} \| {ok:false, reason} | Walks anchor uses; rejects per § 4.5 of the spec. | | SubframeParseError | Thrown on non-JSON input or transport failure. | | SubframeValidationError | Thrown on schema failure; carries an errors array with JSON-Pointer paths. |

All types from types.ts are re-exported: Composition, BookManifest, Paragraph, AudioTrack, AudioSegment, MixBlock, AnchorMode, BlockKind, ParagraphKind, CapabilityManifest, and friends.

Conformance

The bundled JSON Schemas under src/schemas/ are mirrors of the canonical specs in spec/. The conformance suite consumes the canonical copies; this package consumes the mirrors so it remains self-contained when published.

License

Apache-2.0 — see LICENSE at the repository root.