SDK/ is the multi-runtime workspace for ManagedCode.Tps.

This folder is where TPS runtime implementations live. The goal is parity across active runtimes:

• constants catalog
• TPS validation with actionable diagnostics
• TPS parsing into a document model
• TPS compilation into a JSON-friendly state machine
• player/runtime APIs for both deterministic sampling and live timed playback

The .NET runtime is the canonical TPS implementation and source layout. TypeScript mirrors the same runtime contract as the canonical source runtime for web-focused development, and the JavaScript runtime is the consumer-facing built artifact of that TypeScript source. Flutter, Swift, and Java are independent implementations kept aligned through shared fixtures and parity tests.

Compiled TPS output is meant to be portable. The active runtimes treat the compiled state machine as the shared transport format for compile -> json -> restore -> play flows.

The root README.md is the canonical format specification. This SDK README documents the runtime contract that is implemented today.

• ts/: TypeScript runtime that mirrors the canonical .NET contract for web-oriented consumers
• js/: generated JavaScript runtime, Node tests, and package metadata
• dotnet/: canonical .NET runtime, solution, and xUnit tests
• flutter/: Dart runtime for Flutter hosts
• swift/: Swift runtime package
• java/: Java runtime package
• fixtures/: shared TPS fixtures and expected runtime behavior
• docs/: SDK ADRs and architecture notes
• manifest.json: internal runtime matrix source for CI and site generation

The format spec allows these file naming conventions:

• .tps
• .tps.md
• .md.tps

The runtimes themselves compile TPS source text, not a specific extension. If a host already has the script content in memory, it can compile it directly without depending on the original file name.

Across the active runtimes, the shared contract today includes:

• spec constants for metadata keys, keywords, emotions, archetypes, tags, and playback defaults
• actionable TPS diagnostics for malformed structure, invalid ranges, unknown tags, and unknown archetypes
• parsing into a document model with segment, block, phrase, and word scopes
• compilation into a normalized JSON-friendly state machine
• restore from compiled JSON or compiled object graphs
• deterministic playback via TpsPlayer
• timed playback via TpsPlaybackSession
• compile-and-play embedding via TpsStandalonePlayer

Archetype parsing, inheritance, recommended-WPM defaults, advisory archetype-profile mismatch warnings, and rhythm-analysis warnings are part of the current active-runtime contract and are covered by shared fixtures.

The compiled TPS state machine is organized as:

1. metadata
2. segments
3. blocks
4. phrases
5. words

Each compiled word carries timing and authoring-derived metadata such as emphasis, pause timing, highlight, breath, edit-point markers, emotion hints, articulation, energy, melody, volume, speed override or multiplier, pronunciation or phonetic guides, stress guides, speaker, and head-cue data.

Active runtimes expose three playback layers:

• TpsPlayer: pure resolver for GetState(elapsed) and deterministic sampling
• TpsPlaybackSession: stateful controller with its own timer, transport controls, speed correction, transition events, and host-controllable time sources
• TpsStandalonePlayer: compile-and-play wrapper that starts from TPS source and exposes the embeddable runtime surface in one object, including direct commands and snapshot events
• active runtimes also expose FromCompiledScript(...) and FromCompiledJson(...) helpers so hosts can restore a precompiled TPS JSON state machine instead of recompiling source on every open

Use TpsPlayer when the host already owns the clock. Use TpsPlaybackSession when the SDK should drive playback itself from an already compiled state machine. Use TpsStandalonePlayer when the host wants one SDK-owned object that compiles TPS, plays it, and exposes bindable commands and snapshots.

The standalone player/session layer is UI-framework-neutral. The SDK does not render HTML, Razor, or native buttons for you; instead it exposes the command surface a host UI binds to:

• play, pause, stop, seek
• advanceBy
• nextWord, previousWord
• nextBlock, previousBlock
• increaseSpeed, decreaseSpeed, setSpeedOffsetWpm
• snapshotChanged
• observeSnapshot / ObserveSnapshot for immediate current-state replay plus future updates

Each snapshot exposes:

• current segment, block, phrase, and focused word
• visible words with read/active/upcoming state plus word effects
• current transport status and completion progress
• tempo state: base WPM, global offset, effective base WPM, playback rate
• control availability for enabling or disabling host buttons

Keep the root README.md aligned with examples/*.tps, SDK/fixtures/invalid/*.tps, and the shared example snapshots whenever TPS syntax or playback semantics change.

On .NET, prefer wiring playback through TpsPlaybackSessionOptions.TimeProvider when a host needs deterministic or externally controlled time. On .NET UI hosts, also wire TpsPlaybackSessionOptions.EventSynchronizationContext so snapshot and state events land on the dispatcher the host actually renders from.

1. Change the TPS contract in SDK/ts first unless the work is package-specific or .NET-specific.
2. Rebuild the JS runtime from the TS source.
3. Run the runtime-specific tests for the SDK you changed.
4. If behavior changes, keep parity across active runtimes and shared fixtures.
5. Regenerate example snapshots when the compiled output or player states intentionally change.

• TypeScript: npm --prefix SDK/js run coverage:typescript
• JavaScript: npm --prefix SDK/js run coverage:js
• C#: dotnet test SDK/dotnet/ManagedCode.Tps.slnx --no-restore /p:CollectCoverage=true /p:CoverletOutputFormat=json /p:ThresholdType=line%2Cbranch%2Cmethod /p:Threshold=90
• Flutter: cd SDK/flutter && ./coverage.sh
• Swift: cd SDK/swift && ./coverage.sh
• Java: cd SDK/java && ./coverage.sh

SDK/fixtures/examples/*.snapshot.json are cross-runtime integration fixtures generated from the documented examples/*.tps files. Active runtimes must compile those examples into the same normalized state machine shape, produce the same checkpointed player states, and expose the same session/standalone playback snapshots for navigation and speed controls.

SDK/fixtures/transport/*.json are canonical compiled-wire fixtures. Active runtimes must serialize the same JSON transport shape and be able to restore playback from it.

Regenerate them with:

• npm --prefix SDK/js run generate:example-snapshots

• .github/workflows/ci.yml: compact SDK workflow with quality, runtime build/test, and coverage stages
• .github/workflows/pages.yml: static site publishing
• .github/workflows/release.yml: version-tagged GitHub releases