@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/execution/logic-calls.d.ts

@@ -0,0 +1,190 @@
+/**
+ * What every call into author logic shares, whichever resource it runs.
+ *
+ * An engine, a tick controller, a hook, a validator and an endpoint are each
+ * handed the same five things beside their own arguments: a `meta` read from
+ * one session-wide source (§10.2, §5.7), the roster as the host holds it, the
+ * callbacks their `uses` allow, a bound on how long the runtime waits for
+ * them (§11.10, §15.4), and a mark on whatever they throw saying where it came
+ * from (#639). Kept apart from the executor so that each runner built on it
+ * gets them from one place, rather than five call sites each assembling their
+ * own copy and drifting.
+ */
+import type { ApiUse, ResolvedPackageManifest, LogicMeta, Participant, RunKind, RunMeta, SignatureCallbacks } from '@seriousgaming/sdk';
+import { type ExecutorCallbacksDeps } from './executor-callbacks';
+import { type LogicOrigin, type SourceMapRegistry } from './logic-failure';
+import type { LogicKind, LogicResource } from './logic-loader';
+import type { ExecutorDependencies } from './types';
+/**
+ * Default bound on one call into author logic (§15.4, §14.4, §6.12).
+ *
+ * §11.10 bounds the tick; nothing bounded a validator, a hook chain or an
+ * endpoint, each of which runs author code on a path something is waiting on.
+ * A hung hook is the worst of the three: dispatches are serialised per team
+ * (§14.4), so one that never returns blocks every later signal for that team
+ * for the life of the session.
+ *
+ * Deployment-defined, per the spec; this is the authoring default.
+ */
+export declare const DEFAULT_LOGIC_EXECUTION_BOUND_MS = 30000;
+export declare const DEFAULT_TICK_EXECUTION_BOUND_MS = 120000;
+/**
+ * What a runner of one kind of resource needs from the executor that owns it:
+ * the package as loaded, its compiled logic, each resource's settings, and the
+ * calls every one of them shares.
+ */
+export interface LogicHost {
+    readonly calls: LogicCalls;
+    /** The loaded package, or null before the executor has loaded one. */
+    config(): ResolvedPackageManifest | null;
+    /** Whether a game is loaded: a package with no game runs nothing. */
+    initialised(): boolean;
+    load<T>(kind: LogicKind, identifier: string, resource: LogicResource | undefined, notFoundMessage: string): Promise<T>;
+    settingsFor(declaration: {
+        settings?: string[];
+    }): Record<string, Record<string, unknown>>;
+    sharedCapabilityIds(): string[];
+}
+export interface LogicCallsOptions {
+    packagePath: string;
+    /** Where `meta.now` is read from: the host's clock, so a fake one controls it. */
+    clock: {
+        now(): number;
+    };
+    deps: Pick<ExecutorDependencies, 'logicExecutionBoundMs' | 'tickExecutionBoundMs'>;
+    /** The loaded bundles' source maps, to read a thrown stack back to source. */
+    sourceMaps: SourceMapRegistry;
+    /** What the raw callbacks are built from, less what this class supplies. */
+    callbacks: Omit<ExecutorCallbacksDeps, 'readPastState' | 'getScopedTeamIndexes' | 'getAllTeamIndexes' | 'takePlatformFailure'>;
+}
+export declare class LogicCalls {
+    private readonly options;
+    /** The session locale, surfaced as `meta.locale`. */
+    locale: string;
+    /**
+     * The session's random seed, surfaced to logic as `meta.seed`. Fixed rather
+     * than drawn so a CLI run is reproducible by default: a game that wants a
+     * different world each session gets one from the host calling `setSeed`,
+     * which the dev server does and persists.
+     */
+    seed: string;
+    /**
+     * Which kind of run this executor is driving, surfaced to logic as
+     * `meta.runKind`. Host-owned like the seed and the locale: the executor
+     * carries it and changes no behaviour on it, because deciding what a
+     * walkthrough should look like is the game's business, not ours.
+     */
+    runKind: RunKind;
+    /**
+     * When the operation in progress started, or null between operations.
+     * Held so every logic call in one operation reads the same `meta.now`
+     * (§10.2). Set by {@link inOperation}, which serial callers alone use:
+     * an endpoint runs beside the queue, so it is handed its instant instead.
+     */
+    private operationStartedAt;
+    /** The session's participants, every team's, as the host holds them. */
+    private rosterSource;
+    /**
+     * Where `getPastState` reads from (§12.5). Supplied by the host after
+     * construction, because the history lives in the session's team store and
+     * that store is built around the executor.
+     */
+    private pastStateReader;
+    private teamIndexesForHistory;
+    /** Team indexes the resource now running is scoped to; null is the session. */
+    private scopedTeamIndexes;
+    /** See {@link setPlatformFailures}. */
+    private platformFailures;
+    constructor(options: LogicCallsOptions);
+    /**
+     * Run `work` as one operation: every logic call inside it reads the same
+     * `meta.now`, taken from the clock as it starts (§10.2). Nested calls join
+     * the operation already running rather than starting their own, so a
+     * cohort tick that runs each independent team separately, and the tick
+     * controller evaluated after it, all read one instant.
+     */
+    inOperation<T>(work: () => Promise<T>): Promise<T>;
+    /** The instant the current operation started, or now when there is none. */
+    operationNow(): number;
+    /** The clock's reading, outside any operation. */
+    now(): number;
+    /**
+     * The session-wide half of `meta`, which every logic call receives.
+     *
+     * One builder rather than a literal per call site: `runKind` has to read
+     * the same everywhere within a run (§5.7), and five hand-written copies is
+     * five chances for a surface to disagree with the engine beside it.
+     */
+    sessionMeta(tick: number): RunMeta;
+    /**
+     * The `meta` given to logic that runs outside the tick loop: hooks,
+     * endpoints and validators. No `tick`, because none of them runs as
+     * part of a tick.
+     */
+    meta(now?: number): LogicMeta;
+    /** See {@link GameExecutor.setRosterSource}. */
+    setRosterSource(source: () => Participant[]): void;
+    /** Every participant in the session, as the host holds them. */
+    roster(): Participant[];
+    /**
+     * The participants on `teamIds`, in team order and then join order, as a
+     * fresh copy: a call that changes its copy changes no other call's, and
+     * not the roster (§10.2).
+     */
+    participantsOn(teamIds: readonly string[]): Participant[];
+    /** See {@link GameExecutor.setHistoryAccess}. */
+    setHistoryAccess(access: {
+        read: NonNullable<ExecutorCallbacksDeps['readPastState']>;
+        allTeamIndexes: () => number[];
+    }): void;
+    /** See {@link GameExecutor.setPlatformFailures}. */
+    setPlatformFailures(take: NonNullable<ExecutorCallbacksDeps['takePlatformFailure']>): void;
+    /**
+     * Run something with `getPastState`'s notion of 'own team' pinned to
+     * `indexes`, restoring whatever was in force afterwards.
+     *
+     * Per-team work nests inside session-wide work (a tick loops over teams),
+     * so this saves and restores rather than clearing: leaving it null after a
+     * team's turn would silently widen the next read to the whole session.
+     */
+    withScopedTeams<T>(indexes: number[] | null, run: () => Promise<T>): Promise<T>;
+    /**
+     * The callbacks a resource receives: the raw runtime callbacks, built
+     * fresh so they read the live game, with every one its `uses` does not
+     * declare replaced by a throwing stub.
+     */
+    callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined): SignatureCallbacks;
+    /**
+     * Bound one call into author logic that runs as part of a tick, or of the
+     * initialisation a tick starts from (§11.10).
+     *
+     * Each call is bounded rather than the tick as a whole, because a result
+     * arriving after the bound must go nowhere: a race over one call discards
+     * it, where a race over the whole tick would let the executor carry on and
+     * commit the late result. The bound is longer than the per-call one,
+     * because an engine may make several LLM calls in one run.
+     */
+    tickBound<T>(what: string, run: () => Promise<T>, origin?: LogicOrigin): Promise<T>;
+    /**
+     * Bound one call into author logic.
+     *
+     * §11.10 bounds the tick. Nothing bounded a validator, a hook or an
+     * endpoint, and each sits on a path something is waiting on: a validator
+     * holds a participant's write, an endpoint holds a UI's promise, and a
+     * hook chain — serialised per team (§14.4) — holds every later signal for
+     * that team.
+     *
+     * **This bounds the wait, not the execution.** A promise race cannot
+     * interrupt a bare loop inside the logic realm; terminating that needs
+     * isolation the runtime may not have (§3.2). Failing the waiting path is
+     * the half that is always achievable, and it is the half that keeps the
+     * session moving.
+     */
+    bound<T>(what: string, run: () => Promise<T>, boundMs?: number, origin?: LogicOrigin): Promise<T>;
+    /**
+     * Run a call into author logic, marking anything it throws with where it
+     * came from (#639): the resource, the tick and team when there are ones,
+     * and the source line the bundle's map reads the stack back to.
+     */
+    private call;
+}

package/dist/execution/logic-failure.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Where game logic threw (#639).
+ *
+ * The dev server runs each logic bundle compiled from the author's TypeScript,
+ * so a stack names a line in the bundle, not in anything the author wrote. The
+ * loader keeps each bundle's source map, and a failure is read back through it
+ * to the file, line and column of the source, plus the tick and team it threw
+ * for. Runtime-internal: nothing here is part of the specification, and a
+ * surface is never shown it.
+ */
+import { LLM_NOT_CONFIGURED } from '../utils/llm-client';
+/** One resource's logic, by type and identifier. */
+export interface LogicOrigin {
+    resource: {
+        type: string;
+        identifier: string;
+    };
+    tick?: number;
+    team?: {
+        teamId: string;
+        index: number;
+    };
+}
+/** What a session result carries about logic that threw. */
+export interface LogicFailure extends LogicOrigin {
+    message: string;
+    /** The source file, relative to the package root, with forward slashes. */
+    file?: string;
+    /** 1-based. */
+    line?: number;
+    /** 1-based. */
+    column?: number;
+    /**
+     * Set when what logic threw is the environment's failure rather than the
+     * game's, so the command reports it as one.
+     */
+    errorCode?: typeof LLM_NOT_CONFIGURED;
+}
+/** A position in a source file. */
+export interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Mark `error` as thrown by game logic. A thrown value that is not an object
+ * cannot carry the mark, so it is wrapped in an Error first; the value to
+ * rethrow is returned either way.
+ */
+export declare function markLogicFailure(error: unknown, failure: LogicFailure): unknown;
+/** The logic failure `error` was marked with, if it was thrown by game logic. */
+export declare function logicFailureOf(error: unknown): LogicFailure | undefined;
+/** Carry a mark from one error to the error that replaces it, such as a wrapper. */
+export declare function carryLogicFailure<T>(from: unknown, to: T): T;
+/** The logic failure a session result carries beside its outcome, if any. */
+export declare function logicErrorOf(result: unknown): LogicFailure | undefined;
+/** A thrown value's message, read structurally: logic throws from another realm. */
+export declare function thrownMessage(error: unknown): string;
+/**
+ * The source maps of the bundles the dev server has evaluated, keyed by the
+ * filename each was compiled under, which is what its stack frames name.
+ */
+export declare class SourceMapRegistry {
+    private readonly maps;
+    /**
+     * Remember the inline source map at the end of `code`, compiled under
+     * `filename`. Its sources are relative to the bundle's directory, which is
+     * the directory of the entrypoint (see `Transpile`).
+     */
+    register(filename: string, code: string): void;
+    clear(): void;
+    /**
+     * Where `error` was thrown in source: the first stack frame inside a
+     * registered bundle that maps to the author's own code, or failing that to
+     * anything (such as a bundled dependency). Undefined when no frame is in a
+     * bundle, or the error carries no stack.
+     */
+    locate(error: unknown): SourceLocation | undefined;
+}
+/**
+ * The failure for logic that threw `error`: its message, its origin, and the
+ * source location `maps` finds, relative to `packagePath`.
+ */
+export declare function describeLogicFailure(error: unknown, origin: LogicOrigin, maps: SourceMapRegistry, packagePath: string): LogicFailure;

package/dist/execution/logic-loader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * LogicLoader - loads and caches the compiled logic bundles the executor runs.
+ *
+ * Every resource kind that carries logic (the engine, tick controllers, hooks,
+ * validators, endpoints) is transpiled once, evaluated in the shared bare-V8
+ * context, and cached by identifier. The executor owns *which* resource maps to
+ * an identifier; this class owns the caches, the transpile/evaluate step, and
+ * the sandbox context.
+ */
+import { SourceMapRegistry } from './logic-failure';
+import type { ExecutorDependencies } from './types';
+/** The resource kinds that carry loadable logic. Each has its own cache. */
+export type LogicKind = 'engine' | 'tickController' | 'hook' | 'validator' | 'endpoint';
+/** The subset of a resource bundle the loader needs to locate its logic. */
+export interface LogicResource {
+    rootDirectory: string;
+    logic: {
+        directory: string;
+        entrypoint: string;
+    };
+}
+/** The dependencies the loader needs: a transpiler and a file reader. */
+export type LogicLoaderDeps = Pick<ExecutorDependencies, 'transpile' | 'fs'>;
+export declare class LogicLoader {
+    private readonly packagePath;
+    private readonly deps;
+    private readonly caches;
+    private logicContext?;
+    /** Each evaluated bundle's source map, to read a thrown stack back to source. */
+    readonly sourceMaps: SourceMapRegistry;
+    constructor(packagePath: string, deps: LogicLoaderDeps);
+    /**
+     * Load the logic exports for `identifier` of the given `kind`, from cache
+     * when present. `resource` is the bundle whose logic to compile; a missing
+     * resource throws `notFoundMessage`.
+     */
+    load<T>(kind: LogicKind, identifier: string, resource: LogicResource | undefined, notFoundMessage: string): Promise<T>;
+    /** Drop every cached bundle (used when configuration or code reloads). */
+    clearAll(): void;
+    /** Drop a single cached bundle so its next load re-transpiles it. */
+    invalidate(kind: LogicKind, identifier: string): void;
+    /**
+     * The shared bare-V8 global scope every logic bundle is evaluated in.
+     *
+     * A fresh vm context exposes only the ECMAScript intrinsics — the
+     * environment the production runtime guarantees (SPECIFICATION.md §3.2).
+     * Host globals such as `structuredClone`, `fetch`, `setTimeout`,
+     * `TextEncoder`, and `process` are absent, so logic that reaches for one
+     * throws a `ReferenceError` here exactly as it would in production, instead
+     * of silently working against Node's globals and only failing on deploy.
+     * (`console` is provided by a shim the transpiler compiles into each bundle.)
+     */
+    private getLogicContext;
+}

package/dist/execution/logic-result.d.ts

@@ -0,0 +1,76 @@
+import type { ContextDeletePath, TickControllerResult } from '@seriousgaming/sdk';
+import type { GameContext } from './types';
+/**
+ * Read the capabilities patch out of a logic result (`{ capabilities }`).
+ *
+ * A top-level key other than those in `allowed` fails the call. The one a game
+ * written for the flat shape returns is a capability identifier, so without
+ * this its writes would be discarded without a word; the message says how to
+ * wrap them instead.
+ */
+export declare function readCapabilities(label: string, result: unknown, allowed?: readonly string[]): GameContext;
+/**
+ * Read the paths a logic result removes (`deletes`), beside its capabilities.
+ *
+ * Each path is a `ContextDeletePath`, as a UI's `deletes` is (§9.5): segments
+ * joined by `.`, or an array of segments where a key could contain one. An
+ * absent `deletes` removes nothing. Anything else fails the call, because a
+ * malformed delete that was skipped would leave the entry the author meant to
+ * remove in place without a word.
+ */
+export declare function readDeletes(label: string, result: unknown): ContextDeletePath[];
+/** A delete path as an author would read it in a message. */
+export declare function describeDeletePath(path: ContextDeletePath): string;
+/** The capability a delete path removes something from: its first segment. */
+export declare function deleteHead(path: ContextDeletePath): string;
+/**
+ * Hold a logic result's `deletes` to what the resource may change (§7.4,
+ * §10.5), before anything is applied.
+ *
+ * A delete is a write, so the capability at the head of every path must be in
+ * `writes`. The test is the declaration, not a change of value: unlike a
+ * returned capability, a delete is never an echo of what the resource was
+ * handed, so there is no spread idiom to tolerate, and a delete under a
+ * capability the resource only reads is a mistake even when the path happens
+ * not to resolve. `target` says whose board the deletes land on: per-team logic
+ * may not reach a shared capability (§7.5), and an aggregate's or a
+ * session-scoped endpoint's `shared` result may reach nothing else.
+ */
+export declare function assertDeletesDeclared(label: string, deletes: readonly ContextDeletePath[], declaration: {
+    reads?: readonly string[];
+    writes?: readonly string[];
+}, shared: ReadonlySet<string>, target: 'team' | 'shared'): void;
+/**
+ * An engine result: its capabilities patch, the paths it removes, and its
+ * `state` when it returned one. `state` is `undefined` when the result left it
+ * out, which keeps the previous state; `null` is a value like any other.
+ */
+export interface EngineResultRead {
+    capabilities: GameContext;
+    /** Paths removed after the capabilities fold (§7.4). */
+    deletes: ContextDeletePath[];
+    state: unknown;
+    /** Whether a tick's result reported the game complete (§11). */
+    complete: boolean;
+}
+/**
+ * Read an engine result (`{ capabilities, deletes?, state? }`, and `complete?` from a
+ * tick's `Run` or `RunAggregate`). `Init` closes no round, so it has nothing to
+ * complete and `complete` there is an unknown key like any other.
+ */
+export declare function readEngineResult(label: string, result: unknown, phase?: 'init' | 'tick'): EngineResultRead;
+/**
+ * Read an aggregate result (`{ shared: { capabilities }, teams: [{ capabilities }] }`)
+ * into the shared patch and one patch per team.
+ */
+export declare function readAggregateResult(label: string, result: unknown, teamCount: number, phase?: 'init' | 'tick'): {
+    shared: EngineResultRead;
+    teams: EngineResultRead[];
+};
+/**
+ * Read a tick controller's result, whose shape is closed (§11.12). An unknown
+ * key, or an `enabled` or `complete` that is not a boolean, fails the
+ * evaluation. A malformed `intervalMs` or `nextTickAt` is not refused here:
+ * §11.9 has the runtime clamp those instead.
+ */
+export declare function readTickControllerResult(label: string, result: unknown): TickControllerResult;

package/dist/execution/tick-controller-call.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One evaluation of the game's tick controller (§11): what it is handed and
+ * how long the runtime waits for it.
+ *
+ * The controller is the one logic resource that judges several teams at once
+ * without writing anything, so its arguments are its own shape: the board of
+ * the team the host swapped in, each team's board projected as the
+ * controller's own is, and the waiting-room flag. What its answer means for
+ * the timers is the session's business; this module only asks the question.
+ */
+import type { TickControllerResult } from '@seriousgaming/sdk';
+import type { LogicHost } from './logic-calls';
+import type { GameContext } from './types';
+export interface TickControllerHost extends LogicHost {
+    /** The board of the team the host swapped in before calling. */
+    board(): GameContext;
+    /** The tick last run, which `meta.tick` reports. */
+    lastTick(): number;
+    waitingRoomOpen(): boolean;
+}
+/**
+ * Execute the tick controller for the current game and return its result.
+ * Returns null if no tick controller is configured.
+ */
+export declare function callTickController(host: TickControllerHost, teams: {
+    teamId: string;
+    index: number;
+    context: Record<string, unknown>;
+}[], identity: {
+    teamId: string;
+    index: number;
+}): Promise<TickControllerResult | null>;

package/dist/execution/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared types for game execution
+ */
+import type { ResolvedPackageManifest } from '@seriousgaming/sdk';
+import type { ResolvedSettings, SessionSettingsOverrides } from './configuration-builder';
+export type { ResolvedSettings, SessionSettingsOverrides };
+export type GameContext = Record<string, unknown>;
+/**
+ * Injectable dependencies for GameExecutor.
+ * All I/O-heavy operations are abstracted behind this interface
+ * so that tests can substitute lightweight mocks.
+ */
+export interface ExecutorDependencies {
+    /** Transpile a TypeScript entrypoint into a CommonJS bundle string */
+    transpile: (options: {
+        entrypoint: string;
+        sourcemap?: boolean;
+        packageRoot?: string;
+    }) => Promise<string>;
+    /** Load and resolve the SDK configuration from a JSON path */
+    loadConfig: (configPath: string) => Promise<ResolvedPackageManifest>;
+    /** File-system read operations */
+    fs: {
+        existsSync: (path: string) => boolean;
+        readFile: (path: string, encoding: BufferEncoding) => Promise<string>;
+    };
+    /** Persistence for session-override layer */
+    configStore: {
+        save: (packagePath: string, configuration: SessionSettingsOverrides) => Promise<void>;
+        getPath: (packagePath: string) => string;
+        /** Record which scenario the saved configuration was built for (#439). */
+        saveScenario: (packagePath: string, scenarioId: string | null) => Promise<void>;
+        /** The recorded scenario, or `undefined` when nothing was recorded. */
+        readScenario: (packagePath: string) => string | null | undefined;
+    };
+    /**
+     * How long one call into author logic may take before the runtime stops
+     * waiting on it (SPECIFICATION.md §15.4, §14.4, §6.12). Deployment-defined;
+     * omit for the default.
+     */
+    logicExecutionBoundMs?: number;
+    /**
+     * How long one engine or tick-controller call may take before the tick is
+     * abandoned (SPECIFICATION.md §11.10). Deployment-defined; omit for the
+     * default.
+     */
+    tickExecutionBoundMs?: number;
+}

package/dist/generation/ts-type.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `tsType` on a capability's `variablesSchema` (#601): a property names a real
+ * TypeScript type, which the generated `types.ts` uses in place of what the
+ * schema alone would give (`{ [k: string]: unknown }` for a loose object).
+ *
+ * `json-schema-to-typescript` emits a `tsType` verbatim, so the only work is
+ * the path in an `import('…')` type. An author writes it relative to the
+ * capability's own directory, as any import in a file beside the bundle would
+ * be. The same capability is compiled into many `types.ts` files, each in a
+ * different directory, so the path is resolved to an absolute one when the
+ * capabilities are loaded and made relative to each output as it is written.
+ *
+ * A bare specifier (`import('some-package').Thing`) and a `tsType` with no
+ * import at all (`'low' | 'high'`) pass through unchanged.
+ */
+import type { SDKCapability } from '@seriousgaming/sdk';
+/** Where a capability's bundle, and so the base of its `tsType` paths, lives. */
+export declare function capabilityDirectory(workingDir: string, identifier: string): string;
+/**
+ * The capabilities with every relative `tsType` import resolved to an
+ * absolute path, from the capability's own directory. Capabilities with none
+ * are returned as they are.
+ */
+export declare function absolutiseTsTypes(capabilities: readonly SDKCapability[], workingDir: string): SDKCapability[];
+/**
+ * A schema fragment with every absolute `tsType` import made relative to the
+ * file it is about to be written into.
+ */
+export declare function relativiseTsTypes<T>(schema: T, outputPath: string): T;
+/**
+ * Check every `tsType` import a package's capabilities make: the module
+ * exists, and exports the name the type reads from it.
+ *
+ * A textual check rather than a compile, which is enough to catch the two
+ * mistakes worth catching before a whole-package `tsc` does: a path written
+ * relative to the wrong directory, and a misspelt or unexported name. The
+ * message names the capability, the `tsType` and where it looked.
+ */
+export declare function validateTsTypes(capabilities: readonly SDKCapability[], workingDir: string): string[];

package/dist/guide/locale.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Locale helpers for facilitator guides.
+ *
+ * This module is browser-safe: it is imported by both the CLI content
+ * validator and the dev server UI.
+ */
+/**
+ * Pick the locale whose chapter set the others are measured against and
+ * fall back to (§18.2: 'en' when declared, otherwise the first declared
+ * locale).
+ */
+export declare function referenceLocale(locales: Record<string, unknown>): string;

package/dist/guide/video-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Closed provider registry for facilitator guide video embeds.
+ *
+ * A video embed is a fenced code block with language `video` and a YAML-style
+ * body, validated against this registry:
+ *
+ * ```video
+ * provider: youtube
+ * id: dQw4w9WgXcQ
+ * ```
+ *
+ * IDs are validated against a strict per-provider regex and never
+ * interpolated raw into a URL. Unknown providers or malformed blocks must
+ * render as an inert error block, never a passthrough.
+ *
+ * This module is browser-safe: it is imported by both the CLI content
+ * validator and the dev server UI renderer.
+ */
+export interface VideoProvider {
+    /** Strict pattern a video id must match before any URL is built */
+    idPattern: RegExp;
+    /** Embed URL template, only ever called with a pattern-validated id */
+    embedUrl: (id: string) => string;
+    /** Hosts the embed iframe may load from (for frame-src CSP) */
+    embedHosts: string[];
+}
+export declare const VIDEO_PROVIDERS: Record<string, VideoProvider>;
+export type ParsedVideoBlock = {
+    ok: true;
+    provider: string;
+    id: string;
+    embedUrl: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse and validate the body of a `video` fenced block. Returns a typed
+ * error (never throws) so renderers can show an inert error block and
+ * validators can surface the message.
+ */
+export declare function parseVideoBlock(body: string): ParsedVideoBlock;