ball2d 0.3.0 → 0.3.2-next.0

package/dist/types/browser.d.ts

@@ -14,3 +14,7 @@ export declare class RoomAdmissionError extends Error {
 export declare function createRoom(config?: RoomConfig, options?: CreateRoomOptions): Promise<Room>;
 export declare function readReplay(blob: Blob): Promise<Replay>;
 export declare function validateStadium(source: string): StadiumValidation;
+export type { AtmospherePolicy, AtmospherePack, AtmosphereCue, CommentaryCue, CommentaryWordTiming, MatchFact, CommentaryPolicy, CommentaryPolicyPatch, CommentaryPlayerFact, CommentaryPlayerFactInput, CommentaryConfiguration, CommentaryObservation, CommentaryGoalGeometry, } from './commentary.js';
+export type { MatchIntelligencePolicy, MatchIntelligencePolicyPatch, MatchIntelligenceRole, MatchIntelligenceRoleInput, MatchIntelligenceRoleAssignment, MatchIntelligenceEvent, MatchIntelligenceEventKind, MatchIntelligenceSnapshot, MatchIntelligenceTeamTotals, MatchShotQuality, } from './match-intelligence.js';
+export type { MatchXgFeatures, MatchXgVector, MatchXgDomain, MatchXgModel, MatchXgUnavailableReason, MatchXgEstimate, MatchXgTrust, } from './match-xg.js';
+export type { MatchXgCollectionPolicy, MatchXgRuntimeConfig, MatchXgRuntimeReason, MatchXgRuntimeStatus, MatchKickEstimateEvent, } from './match-xg-runtime.js';

package/dist/types/commentary.d.ts

@@ -0,0 +1,276 @@
+/** Presentation facts are independent of physics, account state, and sound assets. */
+export type CommentaryLocale = 'tr' | 'en';
+export type CommentaryTeam = 1 | 2;
+export type CommentaryDose = 'off' | 'minimal' | 'balanced' | 'rich';
+export type CommentaryIntentKind = 'kickoff' | 'restart' | 'goal.neutral' | 'goal.first' | 'goal.equalizer' | 'goal.lead' | 'goal.late-winner' | 'goal.consolation' | 'goal.own-goal' | 'post' | 'near-miss' | 'pressure' | 'pass' | 'pass-chain' | 'turnover' | 'assist' | 'save' | 'shot' | 'block' | 'counterattack' | 'attack-progress' | 'sustained-pressure' | 'tactical-summary' | 'match-end.win' | 'match-end.draw' | 'match-stop' | 'pause' | 'resume' | 'context.fact';
+export interface CommentaryPlayerIdentity {
+    /** Room/connection generation qualified; never reuse for a new occupant of a slot. */
+    readonly sessionId: string;
+    readonly playerId: number;
+    readonly team: CommentaryTeam;
+    readonly name?: string;
+}
+export interface CommentaryMatchContext {
+    readonly phase: 'lobby' | 'playing' | 'goal' | 'finished';
+    readonly paused?: boolean;
+    /** Simulation seconds, not wall-clock time and not ticks. Zero limit means unlimited. */
+    readonly elapsed: number;
+    readonly timeLimit: number;
+    readonly scoreLimit: number;
+    readonly score: {
+        readonly red: number;
+        readonly blue: number;
+    };
+}
+export interface MatchFact {
+    readonly eventId: string;
+    /** Explicitly reset/baseline the consumer when joining a new stream. */
+    readonly streamId: string;
+    readonly sequence: number;
+    readonly tick: number;
+    readonly epoch: number;
+    readonly kind: 'kickoff' | 'restart' | 'goal' | 'pause' | 'resume' | 'end' | 'stop';
+    readonly context: CommentaryMatchContext;
+    readonly goal?: {
+        readonly team: CommentaryTeam;
+        readonly scorer: CommentaryPlayerIdentity | null;
+        readonly ownGoal: boolean;
+    };
+    readonly endReason?: 'time-limit' | 'score-limit' | 'draw' | 'script';
+}
+/** Optional human-supplied alignment; binding validation is not artistic or rights approval. */
+export interface CommentaryWordTiming {
+    readonly schemaVersion: 1;
+    readonly audioSha256: string;
+    readonly textSha256: string;
+    readonly durationMs: number;
+    readonly words: readonly {
+        /** Exact UTF-16 offsets of each complete whitespace-delimited token. */
+        readonly startChar: number;
+        readonly endChar: number;
+        readonly startMs: number;
+        readonly endMs: number;
+    }[];
+    readonly annotation: {
+        readonly source: string;
+        readonly reviewer: string;
+        readonly reference: string;
+    };
+}
+export interface CommentaryCue {
+    readonly id: string;
+    readonly locale: CommentaryLocale;
+    readonly role: 'play-by-play' | 'analyst';
+    readonly family: CommentaryIntentKind;
+    /** Same idea/opening across different recordings: anti-repeat follows meaning. */
+    readonly semanticKey: string;
+    readonly openingKey: string;
+    readonly text: string;
+    readonly intensity: readonly [number, number];
+    readonly durationMs: number;
+    readonly onsetMs: number;
+    readonly interruptibleAtMs: readonly number[];
+    readonly cooldownMs: number;
+    readonly audio: {
+        readonly url: string;
+        readonly sha256: string;
+    } | null;
+    readonly wordTiming?: CommentaryWordTiming;
+    readonly provenance: {
+        readonly source: string;
+        readonly license: string;
+        readonly status: 'draft' | 'approved';
+    };
+    readonly fallbackId?: string;
+    /** No arbitrary runtime interpolation; a recorded full sentence must name its fact. */
+    readonly contextFactKey?: string;
+    readonly contextFactValue?: string | number;
+}
+export interface CommentaryFamilyPolicy {
+    readonly enabled?: boolean;
+    readonly cooldownMs?: number;
+    readonly priority?: number;
+    readonly ttlMs?: number;
+}
+export interface CommentaryPolicy {
+    readonly locale: CommentaryLocale;
+    readonly dose: CommentaryDose;
+    readonly reactionIntensity: number;
+    readonly maxDurationMs: number;
+    readonly minGapMs: number;
+    readonly semanticCooldownMs: number;
+    readonly historySize: number;
+    readonly traceSize: number;
+    readonly seed: number;
+    readonly families: Readonly<Partial<Record<CommentaryIntentKind, CommentaryFamilyPolicy>>>;
+    readonly contextFactsEnabled: boolean;
+    /** Host presentation ceilings. Omitted channels allow delivery; local consent still applies. */
+    readonly channels?: {
+        readonly audio?: boolean;
+        readonly caption?: boolean;
+        readonly chat?: boolean;
+    };
+}
+/** An optional pre-fetched annotation; this is never a gameplay authority or a fetch command. */
+export interface CommentaryPlayerFact {
+    readonly id: string;
+    readonly player: CommentaryPlayerIdentity;
+    /** Stable key identifies a fully authored/recorded compatible cue. */
+    readonly key: string;
+    readonly value: string | number;
+    readonly source: string;
+    /** Provider trust is granted by the host integration, never by a client's payload. */
+    readonly trusted: boolean;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface CommentaryPlan {
+    readonly id: string;
+    readonly eventId: string;
+    readonly streamId: string;
+    readonly epoch: number;
+    readonly family: CommentaryIntentKind;
+    readonly cueId: string;
+    readonly text: string;
+    readonly locale: CommentaryLocale;
+    readonly role: CommentaryCue['role'];
+    readonly intensity: number;
+    readonly priority: number;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+    readonly durationMs: number;
+    readonly wordTiming?: CommentaryWordTiming;
+    readonly canInterrupt: boolean;
+    readonly interruptibleAtMs: readonly number[];
+    readonly context: CommentaryMatchContext;
+    readonly confidence: 'authoritative' | 'supported';
+    readonly explanation: readonly string[];
+    readonly playerFact?: CommentaryPlayerFact;
+    /** Correlation never invents a result; it prevents retelling the same observed attack. */
+    readonly attackId?: string;
+}
+export interface CommentarySelectionAudit {
+    readonly catalog: number;
+    readonly eligible: number;
+    readonly ready: number;
+    readonly considered: number;
+    readonly outsideWindow: number;
+    readonly fallback: boolean;
+    readonly rejected: Readonly<Partial<Record<'language' | 'duration' | 'intensity' | 'context-fact' | 'not-ready' | 'cooldown', number>>>;
+    /** At most eight considered candidates; counts above describe the rest. */
+    readonly candidates: readonly {
+        readonly cueId: string;
+        readonly score: number;
+        readonly repetitionPenalty: number;
+        readonly tieBreaker: number;
+        readonly cooling: boolean;
+    }[];
+}
+export interface CommentaryTrace {
+    readonly atMs: number;
+    readonly eventId: string;
+    readonly action: 'reject' | 'silence' | 'plan' | 'played' | 'previewed' | 'displayed' | 'cancel' | 'defer';
+    readonly reason: string;
+    readonly cueId?: string;
+    readonly family?: CommentaryIntentKind;
+    readonly fact?: {
+        readonly kind: string;
+        readonly tick: number;
+        readonly epoch: number;
+        readonly context: CommentaryMatchContext;
+    };
+    readonly evidence?: readonly string[];
+    readonly selection?: CommentarySelectionAudit;
+}
+export interface CommentaryBaseline {
+    readonly streamId: string;
+    readonly sequence: number;
+    readonly epoch: number;
+}
+export type CommentaryPolicyPatch = Partial<CommentaryPolicy>;
+export type CommentaryPlayerFactInput = Omit<CommentaryPlayerFact, 'player' | 'trusted'>;
+export interface CommentaryGoalGeometry {
+    readonly id: string;
+    readonly p0: readonly [number, number];
+    readonly p1: readonly [number, number];
+    readonly defendingTeam: CommentaryTeam;
+    /** A known playable point on the field side. Off-centre/rotated stadiums need no origin assumption. */
+    readonly pitchPoint: readonly [number, number];
+}
+export interface CommentaryAnalysisFrame {
+    readonly streamId: string;
+    readonly epoch: number;
+    readonly tick: number;
+    readonly context: CommentaryMatchContext;
+    readonly ball: {
+        readonly x: number;
+        readonly y: number;
+        /** Units/second in world coordinates. The adapter converts native per-tick velocity. */
+        readonly vx: number;
+        readonly vy: number;
+        readonly radius: number;
+    };
+    readonly goals: readonly CommentaryGoalGeometry[];
+    readonly contact?: {
+        readonly kind: 'kick' | 'post' | 'player' | 'wall' | 'net';
+        readonly player?: CommentaryPlayerIdentity;
+        readonly goalId?: string;
+    };
+}
+export interface CommentaryObservation {
+    readonly eventId: string;
+    readonly streamId: string;
+    readonly epoch: number;
+    readonly tick: number;
+    readonly kind: 'directed-shot' | 'post' | 'near-miss' | 'pressure' | 'block';
+    readonly context: CommentaryMatchContext;
+    readonly confidence: 'supported';
+    readonly evidence: readonly string[];
+    readonly attackingTeam: CommentaryTeam;
+    readonly intensity: number;
+    readonly player?: CommentaryPlayerIdentity;
+    readonly attackId?: string;
+}
+export interface CommentaryConfiguration {
+    readonly policy: CommentaryPolicy;
+    readonly playerFacts: readonly CommentaryPlayerFact[];
+    /** Configuration transport converts expiry durations to the receiver's clock domain. */
+    readonly hostNowMs: number;
+    /** Omitted means unchanged; null restores the built-in catalog. */
+    readonly catalog?: readonly CommentaryCue[] | null;
+    readonly atmosphere: AtmospherePolicy;
+    /** Omitted means unchanged; null restores the built-in atmosphere assets. */
+    readonly atmospherePack?: AtmospherePack | null;
+}
+export interface AtmospherePolicy {
+    readonly enabled: boolean;
+    readonly bedIntensity: number;
+    readonly reactionIntensity: number;
+    readonly chantIntensity: number;
+    readonly chantCooldownMs: number;
+    /** Neutral is the default; the room must explicitly declare a supporter preference. */
+    readonly preferredTeam: 'neutral' | CommentaryTeam;
+}
+export interface AtmosphereCue {
+    readonly id: string;
+    readonly kind: 'bed' | 'tension' | 'goal' | 'disappointment' | 'chant' | 'post' | 'near-miss' | 'release';
+    readonly team: 'neutral' | CommentaryTeam;
+    readonly intensity: readonly [number, number];
+    /** Complete decoded recording duration, from 100 to 60,000 milliseconds. */
+    readonly durationMs: number;
+    /** Bed/tension/chant only; at least 100 ms, wholly inside the recording. */
+    readonly loop: {
+        readonly startMs: number;
+        readonly endMs: number;
+    } | null;
+    readonly audio: {
+        readonly url: string;
+        readonly sha256: string;
+    };
+    readonly provenance: CommentaryCue['provenance'];
+}
+export interface AtmospherePack {
+    readonly id: string;
+    readonly version: string;
+    readonly cues: readonly AtmosphereCue[];
+}

package/dist/types/creation.d.ts

@@ -1,4 +1,7 @@
+import type { MatchXgTrust } from './match-xg.js';
 export interface CreateRoomOptions {
     /** Cancels startup only. Close the returned room explicitly after it opens. */
     signal?: AbortSignal;
+    /** Host-operator reviewed descriptor allowlist, captured at startup. Never supplied by guests. */
+    matchXgTrust?: MatchXgTrust;
 }

package/dist/types/match-intelligence.d.ts

@@ -0,0 +1,128 @@
+import type { CommentaryAnalysisFrame, CommentaryMatchContext, CommentaryPlayerIdentity, CommentaryTeam } from './commentary.js';
+/** Roles are explicit host assignments. Being the player nearest a goal is not a role. */
+export type MatchIntelligenceRole = 'goalkeeper' | 'outfield';
+export interface MatchIntelligenceRoleAssignment {
+    readonly player: CommentaryPlayerIdentity;
+    readonly role: MatchIntelligenceRole;
+}
+export interface MatchIntelligenceRoleInput {
+    readonly playerId: number;
+    readonly role: MatchIntelligenceRole;
+}
+export interface MatchIntelligencePlayer {
+    readonly identity: CommentaryPlayerIdentity;
+    readonly x: number;
+    readonly y: number;
+    /** World units per simulation second, as for the ball. */
+    readonly vx: number;
+    readonly vy: number;
+    readonly radius: number;
+    readonly role?: MatchIntelligenceRole;
+}
+export interface MatchIntelligenceContact {
+    /** Unique within the stream; repeated delivery does not create another action. */
+    readonly id: string;
+    readonly tick: number;
+    readonly kind: 'kick' | 'player' | 'wall' | 'post';
+    readonly player?: CommentaryPlayerIdentity;
+    readonly goalId?: string;
+}
+export interface MatchIntelligenceFrame extends Omit<CommentaryAnalysisFrame, 'contact'> {
+    /** Authoritative active roster, at most 32. Overflow/invalid input produces unknown. */
+    readonly players: readonly MatchIntelligencePlayer[];
+    /** Physical contacts for this sampled interval, at most 32, oldest first. */
+    readonly contacts: readonly MatchIntelligenceContact[];
+    /** False when the adapter cannot prove complete contact coverage since its last frame.
+     * Control geometry may still be observed; pass/assist/shot continuity becomes unknown. */
+    readonly contactsComplete: boolean;
+}
+export interface MatchIntelligencePolicy {
+    readonly enabled: boolean;
+    readonly maxGapMs: number;
+    readonly controlHoldMs: number;
+    /** Extra distance beyond player radius + ball radius, in ball radii. */
+    readonly controlExtraRadii: number;
+    readonly controlRelativeSpeedRadii: number;
+    readonly passWindowMs: number;
+    readonly passMinTravelRadii: number;
+    readonly chainWindowMs: number;
+    readonly assistWindowMs: number;
+    readonly shotWindowMs: number;
+    readonly shotMinSpeedRadii: number;
+    readonly shotHorizonMs: number;
+    readonly saveAreaGoalWidths: number;
+    readonly progressGoalWidths: number;
+    readonly counterWindowMs: number;
+    readonly pressureHoldMs: number;
+    readonly pressureAreaGoalWidths: number;
+    readonly summaryWindowMs: number;
+}
+export type MatchIntelligencePolicyPatch = Partial<MatchIntelligencePolicy>;
+/** Descriptive features only. None of these values is calibrated xG or a goal probability. */
+export interface MatchShotQuality {
+    readonly distanceGoalWidths: number;
+    readonly openingAngleRadians: number;
+    readonly speedBallRadiiPerSecond: number;
+    readonly defendersInLane: number;
+}
+export type MatchIntelligenceEventKind = 'control-established'
+/** Silent authority barrier for a departed/reassigned field identity. Does not assert
+ * a kick, lost possession or an opponent takeover; only retires matching live control. */
+ | 'player-retired'
+/** Silent, positively observed controller kick/release. Carries player + attackId;
+ * distance/speed evidence must exceed the measured control boundary. No opponent takeover. */
+ | 'control-ended' | 'pass-completed' | 'pass-failed' | 'pass-chain' | 'assist-confirmed' | 'turnover' | 'directed-shot' | 'block' | 'goalkeeper-save' | 'attack-progress' | 'counterattack' | 'sustained-pressure' | 'tactical-summary';
+export interface MatchIntelligenceEvent {
+    readonly eventId: string;
+    readonly streamId: string;
+    readonly epoch: number;
+    readonly tick: number;
+    readonly kind: MatchIntelligenceEventKind;
+    readonly team: CommentaryTeam;
+    readonly player?: CommentaryPlayerIdentity;
+    readonly otherPlayer?: CommentaryPlayerIdentity;
+    readonly goalId?: string;
+    readonly attackId?: string;
+    readonly context: CommentaryMatchContext;
+    readonly confidence: 'supported' | 'authoritative';
+    readonly evidence: readonly string[];
+    /** Bounded descriptive values, never arbitrary prose or a probability. */
+    readonly metrics: Readonly<Record<string, number>>;
+    readonly shotQuality?: MatchShotQuality;
+}
+export interface MatchIntelligenceTeamTotals {
+    readonly controlledMs: number;
+    readonly completedPasses: number;
+    readonly failedPasses: number;
+    readonly turnoversWon: number;
+    readonly directedShots: number;
+    readonly blocks: number;
+    readonly saves: number;
+    readonly confirmedAssists: number;
+}
+export interface MatchIntelligenceSnapshot {
+    readonly streamId: string | null;
+    readonly epoch: number | null;
+    readonly tick: number | null;
+    readonly status: 'uninitialized' | 'tracking' | 'paused' | 'unknown' | 'disabled';
+    readonly unknownReasons: readonly string[];
+    /** Observed control only; free/contested balls remain unassigned. */
+    readonly controller: CommentaryPlayerIdentity | null;
+    readonly passChain: {
+        readonly team: CommentaryTeam | null;
+        readonly completed: number;
+    };
+    readonly attack: {
+        readonly id: string;
+        readonly team: CommentaryTeam;
+        readonly goalId: string;
+    } | null;
+    readonly observedMs: number;
+    readonly uncontrolledMs: number;
+    readonly teams: {
+        readonly red: MatchIntelligenceTeamTotals;
+        readonly blue: MatchIntelligenceTeamTotals;
+    };
+    readonly emittedEvents: number;
+    readonly droppedEvents: number;
+}

package/dist/types/match-xg-runtime.d.ts

@@ -0,0 +1,37 @@
+import type { CommentaryPlayerIdentity } from './commentary.js';
+import type { MatchXgDomain, MatchXgEstimate, MatchXgFeatures, MatchXgModel, MatchXgUnavailableReason } from './match-xg.js';
+/** Must match the independently reviewed offline collection population and feature stage. */
+export interface MatchXgCollectionPolicy {
+    readonly featureStage: 'pre-kick' | 'post-kick';
+    readonly population: 'all-kicks-v1' | 'goalward-release-v1';
+    /** Integer simulation milliseconds, 100 through 60,000. */
+    readonly outcomeHorizonMs: number;
+}
+/** Host-local configuration. null disables inference; no model or approval is bundled. */
+export interface MatchXgRuntimeConfig {
+    readonly model: MatchXgModel;
+    readonly policy: MatchXgCollectionPolicy;
+}
+export type MatchXgRuntimeReason = MatchXgUnavailableReason | 'disabled' | 'preparing' | 'ready' | 'closed' | 'physics-edit' | 'unsupported-geometry' | 'domain-change' | 'capture-discontinuity';
+export interface MatchXgRuntimeStatus {
+    readonly state: 'disabled' | 'preparing' | 'ready' | 'unavailable' | 'invalidated';
+    readonly reason: MatchXgRuntimeReason;
+    readonly domain: MatchXgDomain | null;
+    readonly modelId: string | null;
+    /** Approval is the host operator's explicit assertion, not platform certification. */
+    readonly trustScope: 'host-configuration';
+}
+/** Frozen kick-time input and estimate. Host-local only; never a confirmed goal or spoken probability. */
+export interface MatchKickEstimateEvent {
+    readonly eventId: string;
+    readonly streamId: string;
+    readonly epoch: number;
+    readonly tick: number;
+    readonly order: number;
+    readonly player: CommentaryPlayerIdentity;
+    readonly goalId: string;
+    readonly features: MatchXgFeatures;
+    readonly estimate: MatchXgEstimate;
+    readonly domain: MatchXgDomain;
+    readonly trustScope: 'host-configuration';
+}

package/dist/types/match-xg.d.ts

@@ -0,0 +1,88 @@
+/** Feature units are bound by MatchXgDomain; end-step observations are not frozen kick inputs. */
+export interface MatchXgFeatures {
+    /** Perpendicular playable-side distance to the goal line / mouth width. */
+    readonly distanceGoalWidths: number;
+    /** Smaller absolute angle between rays from the ball to the two posts, in [0, pi]. */
+    readonly openingAngleRadians: number;
+    /** Ball speed at domain.featureStage / current ball radius. Pre-kick is incoming speed;
+     * post-kick is immediately after the impulse, before clamp, gravity, damping or collisions.
+     * These are distinct feature definitions, never interchangeable. */
+    readonly speedBallRadiiPerSecond: number;
+    /** Opponents intersecting the ball-to-goal-center corridor; not a block probability. */
+    readonly defendersInLane: number;
+}
+export type MatchXgVector = readonly [
+    distance: number,
+    angle: number,
+    speed: number,
+    defenders: number
+];
+/** Supplied from the authoritative match configuration, never from the candidate model alone. */
+export interface MatchXgDomain {
+    readonly engineId: string;
+    /** SHA-256 of the integration's canonical stadium physics/goal geometry. */
+    readonly geometrySha256: string;
+    /** SHA-256 of the exact eligibility, attribution and analysis policy used to collect samples. */
+    readonly policySha256: string;
+    readonly featuresRevision: string;
+    readonly featureStage: 'pre-kick' | 'post-kick' | 'end-step';
+    /** Game action populations, not a claim that a kick was an intentional football shot. */
+    readonly population: 'all-kicks-v1' | 'goalward-release-v1' | 'legacy-end-step-on-target-v1';
+    readonly shotDefinitionRevision: string;
+    /** Prediction target: a goal attributable to this shot within this simulation-time horizon. */
+    readonly outcomeHorizonMs: number;
+}
+/** Offline descriptor only. No bundled/trained model or telemetry is implied by this contract. */
+export interface MatchXgModel {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly purpose: 'production' | 'technical-fixture';
+    readonly kind: 'logistic';
+    readonly domain: MatchXgDomain;
+    /** logit = intercept + sum(weights[i] * (feature[i] - means[i]) / scales[i]). */
+    readonly intercept: number;
+    readonly weights: MatchXgVector;
+    readonly means: MatchXgVector;
+    readonly scales: MatchXgVector;
+    /** Explicit evaluated support. Outside this box inference returns null, never extrapolates. */
+    readonly minimums: MatchXgVector;
+    readonly maximums: MatchXgVector;
+    /** Structural metric ranges are not an acceptance threshold; offline review owns calibration quality. */
+    readonly evaluation: {
+        readonly trainingDatasetSha256: string;
+        readonly evaluationDatasetSha256: string;
+        readonly evaluationReportSha256: string;
+        readonly splitUnit: 'match';
+        readonly heldOutSamples: number;
+        readonly heldOutGoals: number;
+        readonly brier: number;
+        readonly logLoss: number;
+        readonly ece: number;
+        readonly eceBins: number;
+    };
+    /** References to reviewed evidence, not self-authenticating approval or scientific proof. */
+    readonly provenance: {
+        readonly provider: string;
+        readonly source: string;
+        readonly license: string;
+        readonly reviewedBy: string;
+        readonly reviewReference: string;
+    };
+}
+export type MatchXgUnavailableReason = 'missing-model' | 'invalid-domain' | 'invalid-descriptor' | 'domain-mismatch' | 'technical-fixture' | 'untrusted-model' | 'invalid-features' | 'outside-model-support';
+export type MatchXgEstimate = {
+    readonly xG: null;
+    readonly status: 'uncalibrated';
+    readonly reason: MatchXgUnavailableReason;
+    readonly modelId?: string;
+} | {
+    readonly xG: number;
+    /** Explicit integration approval; validation/inference do not prove scientific calibration. */
+    readonly status: 'reviewed-model';
+    readonly reason: 'trusted-offline-model';
+    readonly modelId: string;
+};
+export interface MatchXgTrust {
+    /** Separate integration-owned allowlist. Never accept this list from the candidate descriptor. */
+    readonly trustedModels?: readonly MatchXgModel[];
+}

package/dist/types/node.d.ts

@@ -13,3 +13,7 @@ export type NodeRoom = Room & {
     readonly closed: Promise<void>;
 };
 export declare function createRoom(config: NodeRoomConfig, creation?: CreateRoomOptions): Promise<NodeRoom>;
+export type { AtmospherePolicy, AtmospherePack, AtmosphereCue, CommentaryCue, CommentaryWordTiming, MatchFact, CommentaryPolicy, CommentaryPolicyPatch, CommentaryPlayerFact, CommentaryPlayerFactInput, CommentaryConfiguration, CommentaryObservation, CommentaryGoalGeometry, } from './commentary.js';
+export type { MatchIntelligencePolicy, MatchIntelligencePolicyPatch, MatchIntelligenceRole, MatchIntelligenceRoleInput, MatchIntelligenceRoleAssignment, MatchIntelligenceEvent, MatchIntelligenceEventKind, MatchIntelligenceSnapshot, MatchIntelligenceTeamTotals, MatchShotQuality, } from './match-intelligence.js';
+export type { MatchXgFeatures, MatchXgVector, MatchXgDomain, MatchXgModel, MatchXgUnavailableReason, MatchXgEstimate, MatchXgTrust, } from './match-xg.js';
+export type { MatchXgCollectionPolicy, MatchXgRuntimeConfig, MatchXgRuntimeReason, MatchXgRuntimeStatus, MatchKickEstimateEvent, } from './match-xg-runtime.js';

package/dist/types/replay.d.ts

@@ -3,7 +3,7 @@ import type { TeamStyles } from './team.js';
 import type { MatchState } from './match-state.js';
 export type ReplayCommand = {
     tick: number;
-    kind: 'input' | 'team' | 'start' | 'stop' | 'pause' | 'scoreLimit' | 'timeLimit' | 'kickRate' | 'join' | 'disc' | 'finishDraw';
+    kind: 'input' | 'team' | 'start' | 'stop' | 'pause' | 'scoreLimit' | 'timeLimit' | 'kickRate' | 'join' | 'disc';
     properties?: DiscPropertyPatch;
     slot: number;
     value: number;

package/dist/types/room-hooks.d.ts

@@ -0,0 +1,48 @@
+import type { MatchKickEstimateEvent } from './match-xg-runtime.js';
+import type { HostPlayer, HostScores } from './player.js';
+import type { CommentaryObservation, MatchFact } from './commentary.js';
+import type { MatchIntelligenceEvent } from './match-intelligence.js';
+/**
+ * Application callbacks a host room invokes. All are optional and run with the room
+ * as `this`; they observe the room and may call its commands.
+ */
+export interface RoomHooks {
+    /** Immutable event-time context captured before legacy match callbacks. */
+    onMatchFact?: (fact: MatchFact) => void;
+    /** Conservative geometry evidence; never a confirmed goal, pass, save, or player rank. */
+    onMatchObservation?: (observation: CommentaryObservation) => void;
+    /** Bounded authoritative-derived analysis, copied before application callbacks. No persisted statistics. */
+    onMatchIntelligenceEvent?: (event: MatchIntelligenceEvent) => void;
+    /** Host-local frozen kick estimate; trust is an operator assertion, never platform certification. */
+    onMatchKickEstimate?: (event: MatchKickEstimateEvent) => void;
+    onRecordingComplete?: (blob: Blob, reason: string) => void;
+    onRoomLink?: (url: string) => void;
+    onPlayerJoin?: (p: HostPlayer) => void;
+    onPlayerTeamChange?: (p: HostPlayer, byPlayer: HostPlayer | null) => void;
+    onPlayerMuteChange?: (p: HostPlayer, byPlayer: HostPlayer | null) => void;
+    onPlayerAdminChange?: (p: HostPlayer, byPlayer: HostPlayer | null) => void;
+    onGameStart?: (byPlayer: HostPlayer | null) => void;
+    onGameStop?: (byPlayer: HostPlayer | null) => void;
+    onTeamVictory?: (scores: HostScores) => void;
+    /** Legacy Ball2D callback; prefer onTeamVictory. */
+    onGameVictory?: (scores: HostScores) => void;
+    onGamePauseChange?: (paused: boolean) => void;
+    onGamePause?: (byPlayer: HostPlayer | null) => void;
+    onGameUnpause?: (byPlayer: HostPlayer | null) => void;
+    onPlayerLeave?: (p: HostPlayer) => void;
+    onPlayerKicked?: (p: HostPlayer, reason: string, ban: boolean, byPlayer: HostPlayer | null) => void;
+    onPlayerActivity?: (p: HostPlayer) => void;
+    /** Runs only when a peer changes its accepted key state; prevInput is the previous authoritative bitmask. */
+    onPlayerInput?: (p: HostPlayer, prevInput: number) => void;
+    onPlayerChat?: (p: HostPlayer, text: string) => boolean | void;
+    /** Host-visible direct chat; return false to suppress delivery to both participants. */
+    onPlayerDirectChat?: (p: HostPlayer, recipient: HostPlayer, text: string) => boolean | void;
+    onPlayerBallKick?: (p: HostPlayer) => void;
+    onTeamGoal?: (team: 1 | 2) => void;
+    onPositionsReset?: () => void;
+    onStadiumChange?: (name: string, byPlayer: HostPlayer | null) => void;
+    onTeamsLockChange?: (locked: boolean, byPlayer: HostPlayer | null) => void;
+    onKickRateLimitSet?: (min: number, rate: number, burst: number, byPlayer: HostPlayer | null) => void;
+    onGameTick?: () => void;
+    onError?: (message: string) => void;
+}