# Public SDK map

Use this as a routing map, then read the installed
`node_modules/@chasingmastery/sdk/dist/index.d.ts` and its re-exported contract
types for exact signatures. Never import another `@chasingmastery/*` package.

## Package and runtime

- `definePackage(manifest)` validates the immutable package manifest.
- `defineActivityEngine(engine)` validates deterministic `describe`,
  `initialize`, and `apply` boundaries.
- `createActivityWorkerHandler({ contributionId, engine })` exposes an activity
  engine to the isolated host runtime.
- `defineCoordinationEngine(engine)` validates deterministic multiplayer or
  multi-participant policy.
- `createCoordinationWorkerHandler({ contributionId, engine })` exposes that
  policy to the isolated host runtime.
- `defineNarrationDirector(director)` validates deterministic cue planning from
  committed broadcast facts.
- `createNarrationWorkerHandler({ contributionId, director })` exposes that
  policy to the isolated host runtime.
- `createPortablePackageUiBridge()` creates the sandbox-safe player/overlay
  message bridge.
- `parsePackageUiMessage(value)` and `parseHostUiMessage(value)` validate either
  side of the portable UI boundary.

These are the complete public SDK helpers. The SDK also re-exports public
schemas and types; it does not grant transport, speech-provider, Station, OBS,
account, or persistence authority.

The SDK re-exports public contract schemas and types, including package,
activity, progression, Story Event, presentation, coordination, narration, and
portable UI messages. Use their `.parse`/`.safeParse` methods at authored
boundaries instead of duplicating validation.

## Activity lifecycle

`describe(configuration)` declares typed measurements. `initialize(context)`
returns the first deterministic state, safe presentation projection, status,
and effects. `apply(context, priorState, input)` accepts one host-validated:

- manual `command` with actor, trusted occurrence time, elapsed host time,
  expected revision, and bounded payload;
- connector `observation` whose routing and participant were chosen by the
  host; or
- authorized `correction` targeting an existing transition.

Transitions may return these effects:

- `measurement.record` — one typed result;
- `attempt.complete` or `attempt.abandon` — the atomic terminal outcome;
- `story.emit` or `story.retract` — semantic creator/editing evidence;
- `broadcast.emit` — a safe narration fact;
- `coordination.signal` — policy output for the host coordinator.

Use only `context`, prior state, and input. Never call wall-clock, random,
network, filesystem, account, database, Station, or OBS APIs.

Correction is another immutable input, not a database update. Target a stable
accepted transition, rebuild the same Attempt deterministically, retract or
supersede invalidated Story Events and broadcast facts, and obey the activity's
declared terminal `deny` or `replay_and_reopen` policy.

## Package manifest

Artifacts declare immutable engine, schema, `web_ui`, `overlay_ui`, progression,
narration, assets, or separately reviewed Station-sidecar payloads.
Contributions connect those artifacts as:

- `activity` — engine, schemas, command types, exact accepted observation
  protocols, metrics, manual input,
  and one immutable default preset whose complete configuration is accepted by
  `describe` and matches the declared form defaults exactly;
- `progression` — one activity's transparent rank definition;
- `story_events` — declared semantic event types and schema;
- `overlay` — read-only renderer and surfaces;
- `coordination` or `narration` — deterministic policy;
- `connector` — separately reviewed Station executable contract.

Capabilities and permissions must match contributions. Portable package code
normally requests no host permissions. A connector is a distinct signed review
lane, not extra authority attached to a browser activity.

## Declarative presentation

For simple activities, use `practiceModeConfigurationFormSchema` to declare the
authoring/custom-variant contract and return a `chasingmastery.activity-form`
projection containing bounded text or typed metric-value fields plus one
declared submit command. Every ordinary package-default mode is materialized
from the contribution's complete immutable default preset; members do not fill
this form when adding an Experience Suite. Web and native hosts render the
Attempt form without package-specific code.

That form is intentionally a one-action primitive. It is not a generic dart
scorekeeper, chessboard, split editor, or other multi-action controller. Use a
rich portable UI when the player must choose among several actions, manipulate
spatial controls, see intermediate state, or correct a mistake in context.

## Rich portable UI

For boards, games, animation, timers, puzzles, or custom interaction, ship a
`web_ui` artifact and call `createPortablePackageUiBridge()` inside it.

- Send `ui.ready`, snapshot requests, declared command intents, or correction
  intents.
- Subscribe to host context, committed snapshots, request results, connection,
  and lifecycle messages.
- Treat request IDs as correlation only; the host supplies actor, run, clock,
  routing, and idempotency authority.
- Support browser iframe and native WebView delivery, reduced motion, reconnect,
  and terminal states. The same artifact must work in Workbench.

An `overlay_ui` uses the same safe host-provided presentation but must remain
read-only. Map the package's real committed projection into
`activityPresentationSchema` before rendering it. Activity Presentation v1 is
the fixed viewer vocabulary: identity, lifecycle, connection, goal, primary
result, optional change/stakes, and optional next milestone. It is not a place
for arbitrary package JSON, markup, URLs, history queries, ranking logic, or
unbounded collections.

The exact `@chasingmastery/presentation-kit` Domain Kit provides pure tokens,
duration/delta formatting, escaping, fixed display slots, and a safe compact or
16:9 overlay shell. The package still owns the domain-to-presentation mapping
and its visual accent. Assign all dynamic copy with `textContent`; never
interpolate package values into HTML. Exercise ready, live, terminal, stale,
unavailable, compact, broadcast, and reduced-motion states in Workbench.

## Manual and automatic input

An activity may accept both declared command types and exact namespaced
observation protocols. Each protocol declaration points to a package-owned JSON
payload schema; the packer resolves its RFC 8785 SHA-256 digest over canonical
UTF-8 JSON plus one trailing newline. Keep transport details out of the activity.
Normalize equivalent manual
and automatic input through one package-owned rule path so they produce the
same state, measurements, completion, and Story Events. For example, a Darts
package could map a manual `darts.throw` command and an `autodarts.throw`
observation to one internal `applyThrow` policy.

Workbench executes portable UI commands against the real reducer and can inject
declared observations into the same live Attempt. This tests the activity-side
contract only. Native connector executables, network/device access, source
binding, credentials, signing, installation, and Station diagnostics belong to
the separate connector authoring and review lane.

## Progression and creator evidence

A progression definition selects one directed numeric metric, `best`, `latest`,
or bounded rolling `average`, minimum evidence, accepted provenance, and
strictly monotonic package-owned levels. Binary/text metrics may correctly have
no progression.

Emit Story Events only for editorially meaningful committed moments. Include a
stable event key/type, title, structured facts, significance, and an optional
suggested media window or personal-best commit condition. The host commits and
anchors them to capture time; the package never touches recording media.

## Coordination and narration

A `coordination` contribution governs a Live Run around independently committed
Attempts. Its engine receives a participant roster, bounded configuration,
input topology, prior coordination state, and host-validated signals. It returns
safe projection, phase/directives, and effects such as opening activity Attempts,
forwarding an activity signal, completing a round, emitting/retracting a Story
Event, or completing a match. It never mutates an Attempt or becomes an
enclosing practice-history session. Export deterministic scenarios covering
ready/start, input arbitration, terminal outcome, correction, disconnect, and
round/team behavior that the brief promises.

A `narration` contribution maps bounded committed broadcast facts plus active
cue identity into planned cues and cancellations. Cues carry a stable fact and
cancel key, voice role, text/caption, priority, interruptibility, and expiry.
The host owns provider selection and synthesis. The director must remain silent
when facts are incomplete, cancel superseded active cues after correction, and
leave visual state authoritative when speech fails.

## Working examples

When operating inside the platform checkout, inspect these public-SDK-only
packages selectively:

- `packages/manual-metric` — host-rendered single submission;
- `packages/split-timer` — multi-step host-timed activity whose manual commands
  and connector observations converge on one reducer policy, plus a real
  Activity Presentation overlay;
- `packages/reaction-suite` — independently configured modes sharing a
  presentation primitive while retaining distinct domain mappings;
- `packages/typing-lab` — rich player UI, progression, Story Events, overlay.
- `packages/darts-core` — the demanding reference: eight modes, rich manual UI,
  exact automatic observations, correction/reopen, progression, overlays,
  three coordination policies, and two correction-safe narration directors.

Use examples to learn public patterns, never to import their source or private
host modules into a new package.
