@lessonkit/core 0.9.2 → 1.0.0

package/dist/index.d.cts

@@ -143,12 +143,102 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
+type BuildTelemetryEventInput = {
+    name: TelemetryEventName;
+    courseId: CourseId;
+    lessonId?: LessonId;
+    sessionId?: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    data?: unknown;
+    timestamp?: string;
+};
+/** Reset dev-warning state (tests only). */
+declare function resetTelemetryBuilderWarningsForTests(): void;
+/**
+ * Build a typed telemetry event from a catalog event name and context.
+ * Validates lesson-scoped events require `lessonId`.
+ */
+declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
+/**
+ * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
+ */
+declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
+
+type EmitContext = {
+    courseId: string;
+    sessionId?: string;
+    attemptId?: string;
+};
+/** Pluggable telemetry output (OCP). Distinct from the legacy `TelemetrySink` function type. */
+type TelemetryPipelineSink = {
+    readonly id: string;
+    emit(event: TelemetryEvent, ctx: EmitContext): void | Promise<void>;
+};
+type TelemetryPipeline = {
+    readonly sinks: readonly TelemetryPipelineSink[];
+    emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
+};
+declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
+declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
+
+type StoragePort = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem?: (key: string) => void;
+    /** @internal Test helper to clear in-memory fallback state. */
+    resetForTests?: () => void;
+};
+type ClockPort = {
+    nowMs: () => number;
+    nowIso: () => string;
+};
+type TimerPort = {
+    setInterval: (fn: () => void, ms: number) => ReturnType<typeof globalThis.setInterval>;
+    clearInterval: (id: ReturnType<typeof globalThis.setInterval>) => void;
+};
+declare function createDefaultClock(): ClockPort;
+declare function createNoopStorage(): StoragePort;
+declare function resetStoragePortForTests(storage: StoragePort): void;
+declare function createSessionStoragePort(): StoragePort;
+declare function createGlobalTimer(): TimerPort;
+
+type ProgressState = {
+    activeLessonId?: LessonId;
+    completedLessonIds: ReadonlySet<LessonId>;
+    courseCompleted: boolean;
+};
+type ProgressController = {
+    getState: () => ProgressState;
+    setActiveLesson: (lessonId: LessonId, startedAtMs: number) => {
+        previousLessonId?: LessonId;
+    };
+    completeLesson: (lessonId: LessonId, completedAtMs: number) => {
+        durationMs?: number;
+        didComplete: boolean;
+    };
+    completeCourse: () => {
+        didComplete: boolean;
+    };
+};
+declare function createProgressController(): ProgressController;
+
+declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+declare function getTabSessionId(storage: StoragePort): string | null;
+declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
+
 /** Plugin category — aligns with roadmap extension areas. */
 type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
 type LessonkitPluginContext = {
     courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
+    user?: TelemetryUser;
 };
 type AssessmentScoreInput = {
     checkId: string;
@@ -167,43 +257,118 @@ type InteractionBlockRegistration = {
     catalogVersion?: string;
     description?: string;
 };
-/**
- * Framework plugin contract (v1). Plugins are plain objects registered on `LessonkitProvider`.
- * Marketplace / dynamic loading are out of scope until Studio post-1.0.
- */
-type LessonkitPlugin = {
+type PluginIdentity = {
     id: string;
     version: string;
     kind: LessonkitPluginKind;
     name?: string;
-    setup?: (ctx: LessonkitPluginContext) => void;
-    dispose?: () => void;
-    /**
-     * Observe or filter telemetry before tracking/xAPI. Return `null` to drop the event.
-     * Hooks run in registration order.
-     */
+};
+/** Narrow telemetry plugin contract (ISP). */
+type TelemetryPlugin = PluginIdentity & {
     onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
-    /** Optional batch observer (analytics); receives events after per-event hooks. */
     onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
-    /** Wrap the configured tracking sink (analytics plugins). First registered = innermost. */
     wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
-    /** Optional assessment scoring override (assessment plugins). */
+};
+/** Narrow lifecycle plugin contract (ISP). */
+type LifecyclePlugin = PluginIdentity & {
+    setup?: (ctx: LessonkitPluginContext) => void;
+    dispose?: () => void;
+};
+/** Narrow assessment plugin contract (ISP). */
+type AssessmentPlugin = PluginIdentity & {
+    kind: "assessment";
     scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
-    /** Declare custom interaction block types for generators/tooling. */
+};
+/** Narrow interaction metadata plugin (ISP). */
+type InteractionPlugin = PluginIdentity & {
     interactionBlocks?: InteractionBlockRegistration[];
 };
+/**
+ * Combined plugin contract (v1). Prefer segregated types for new plugins.
+ * @deprecated Prefer `TelemetryPlugin`, `AssessmentPlugin`, or `LifecyclePlugin` via `define*Plugin`.
+ */
+type LessonkitPlugin = PluginIdentity & Partial<Pick<TelemetryPlugin, "onTelemetry" | "onTelemetryBatch" | "wrapTrackingSink"> & Pick<LifecyclePlugin, "setup" | "dispose"> & Pick<AssessmentPlugin, "scoreAssessment"> & Pick<InteractionPlugin, "interactionBlocks">>;
 type PluginHost = {
     readonly plugins: readonly LessonkitPlugin[];
     setupAll: (ctx: LessonkitPluginContext) => void;
     disposeAll: () => void;
     runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
     runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    /** Invoke only `onTelemetryBatch` hooks; events were already filtered at emit time. */
     deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
     scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
-declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;
-declare function createPluginHost(plugins?: readonly LessonkitPlugin[]): PluginHost;
+/** Segregated plugin registry (ISP + SRP). */
+type PluginRegistry = PluginHost;
+
+type CourseLifecycleContext = {
+    courseId: CourseId;
+    sessionId: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    storage: StoragePort;
+    pluginHost: PluginRegistry | null;
+    lxpackBridge: "auto" | "off";
+};
+type CourseLifecycleDeps = {
+    emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
+};
+declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
+    emitted: boolean;
+    marked: boolean;
+};
+declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
+type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
+declare function completeLessonWithTelemetry(opts: {
+    progress: ProgressController;
+    lessonId: LessonId;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+}): boolean;
+declare function completeCourseWithTelemetry(opts: {
+    progress: ProgressController;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+    emitCourseCompleted: () => void;
+}): boolean;
+
+type LessonkitRuntimeVersion = "v1" | "v2";
+type HeadlessLessonkitConfig = {
+    courseId: CourseId;
+    runtimeVersion?: LessonkitRuntimeVersion;
+    session?: {
+        sessionId?: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    plugins?: PluginRegistry | null;
+};
+type HeadlessRuntimePorts = {
+    storage?: StoragePort;
+    clock?: ClockPort;
+};
+type HeadlessLessonkitRuntime = {
+    readonly config: HeadlessLessonkitConfig;
+    readonly progress: ProgressController;
+    getProgressState: () => ProgressState;
+    getSession: () => {
+        sessionId: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
+    setActiveLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    completeLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    completeCourse: (emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    track: (name: TelemetryEventName, data: unknown | undefined, emit: (event: ReturnType<typeof tryBuildTelemetryEvent>) => void, lessonId?: LessonId) => void;
+    resetForCourseChange: (courseId: CourseId) => void;
+};
+declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
+
+declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
+
+declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
+declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
+declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitUrnParts, type PluginHost, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createPluginHost, createSessionId, createTrackingClient, defineLessonkitPlugin, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };
+export { type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, markCourseStarted, markCourseStartedEmittedToTracking, migrateCourseStartedMark, nowIso, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };

package/dist/index.d.ts

@@ -143,12 +143,102 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
+type BuildTelemetryEventInput = {
+    name: TelemetryEventName;
+    courseId: CourseId;
+    lessonId?: LessonId;
+    sessionId?: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    data?: unknown;
+    timestamp?: string;
+};
+/** Reset dev-warning state (tests only). */
+declare function resetTelemetryBuilderWarningsForTests(): void;
+/**
+ * Build a typed telemetry event from a catalog event name and context.
+ * Validates lesson-scoped events require `lessonId`.
+ */
+declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
+/**
+ * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
+ */
+declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
+
+type EmitContext = {
+    courseId: string;
+    sessionId?: string;
+    attemptId?: string;
+};
+/** Pluggable telemetry output (OCP). Distinct from the legacy `TelemetrySink` function type. */
+type TelemetryPipelineSink = {
+    readonly id: string;
+    emit(event: TelemetryEvent, ctx: EmitContext): void | Promise<void>;
+};
+type TelemetryPipeline = {
+    readonly sinks: readonly TelemetryPipelineSink[];
+    emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
+};
+declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
+declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
+
+type StoragePort = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem?: (key: string) => void;
+    /** @internal Test helper to clear in-memory fallback state. */
+    resetForTests?: () => void;
+};
+type ClockPort = {
+    nowMs: () => number;
+    nowIso: () => string;
+};
+type TimerPort = {
+    setInterval: (fn: () => void, ms: number) => ReturnType<typeof globalThis.setInterval>;
+    clearInterval: (id: ReturnType<typeof globalThis.setInterval>) => void;
+};
+declare function createDefaultClock(): ClockPort;
+declare function createNoopStorage(): StoragePort;
+declare function resetStoragePortForTests(storage: StoragePort): void;
+declare function createSessionStoragePort(): StoragePort;
+declare function createGlobalTimer(): TimerPort;
+
+type ProgressState = {
+    activeLessonId?: LessonId;
+    completedLessonIds: ReadonlySet<LessonId>;
+    courseCompleted: boolean;
+};
+type ProgressController = {
+    getState: () => ProgressState;
+    setActiveLesson: (lessonId: LessonId, startedAtMs: number) => {
+        previousLessonId?: LessonId;
+    };
+    completeLesson: (lessonId: LessonId, completedAtMs: number) => {
+        durationMs?: number;
+        didComplete: boolean;
+    };
+    completeCourse: () => {
+        didComplete: boolean;
+    };
+};
+declare function createProgressController(): ProgressController;
+
+declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+declare function getTabSessionId(storage: StoragePort): string | null;
+declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
+
 /** Plugin category — aligns with roadmap extension areas. */
 type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
 type LessonkitPluginContext = {
     courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
+    user?: TelemetryUser;
 };
 type AssessmentScoreInput = {
     checkId: string;
@@ -167,43 +257,118 @@ type InteractionBlockRegistration = {
     catalogVersion?: string;
     description?: string;
 };
-/**
- * Framework plugin contract (v1). Plugins are plain objects registered on `LessonkitProvider`.
- * Marketplace / dynamic loading are out of scope until Studio post-1.0.
- */
-type LessonkitPlugin = {
+type PluginIdentity = {
     id: string;
     version: string;
     kind: LessonkitPluginKind;
     name?: string;
-    setup?: (ctx: LessonkitPluginContext) => void;
-    dispose?: () => void;
-    /**
-     * Observe or filter telemetry before tracking/xAPI. Return `null` to drop the event.
-     * Hooks run in registration order.
-     */
+};
+/** Narrow telemetry plugin contract (ISP). */
+type TelemetryPlugin = PluginIdentity & {
     onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
-    /** Optional batch observer (analytics); receives events after per-event hooks. */
     onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
-    /** Wrap the configured tracking sink (analytics plugins). First registered = innermost. */
     wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
-    /** Optional assessment scoring override (assessment plugins). */
+};
+/** Narrow lifecycle plugin contract (ISP). */
+type LifecyclePlugin = PluginIdentity & {
+    setup?: (ctx: LessonkitPluginContext) => void;
+    dispose?: () => void;
+};
+/** Narrow assessment plugin contract (ISP). */
+type AssessmentPlugin = PluginIdentity & {
+    kind: "assessment";
     scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
-    /** Declare custom interaction block types for generators/tooling. */
+};
+/** Narrow interaction metadata plugin (ISP). */
+type InteractionPlugin = PluginIdentity & {
     interactionBlocks?: InteractionBlockRegistration[];
 };
+/**
+ * Combined plugin contract (v1). Prefer segregated types for new plugins.
+ * @deprecated Prefer `TelemetryPlugin`, `AssessmentPlugin`, or `LifecyclePlugin` via `define*Plugin`.
+ */
+type LessonkitPlugin = PluginIdentity & Partial<Pick<TelemetryPlugin, "onTelemetry" | "onTelemetryBatch" | "wrapTrackingSink"> & Pick<LifecyclePlugin, "setup" | "dispose"> & Pick<AssessmentPlugin, "scoreAssessment"> & Pick<InteractionPlugin, "interactionBlocks">>;
 type PluginHost = {
     readonly plugins: readonly LessonkitPlugin[];
     setupAll: (ctx: LessonkitPluginContext) => void;
     disposeAll: () => void;
     runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
     runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    /** Invoke only `onTelemetryBatch` hooks; events were already filtered at emit time. */
     deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
     scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
-declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;
-declare function createPluginHost(plugins?: readonly LessonkitPlugin[]): PluginHost;
+/** Segregated plugin registry (ISP + SRP). */
+type PluginRegistry = PluginHost;
+
+type CourseLifecycleContext = {
+    courseId: CourseId;
+    sessionId: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    storage: StoragePort;
+    pluginHost: PluginRegistry | null;
+    lxpackBridge: "auto" | "off";
+};
+type CourseLifecycleDeps = {
+    emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
+};
+declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
+    emitted: boolean;
+    marked: boolean;
+};
+declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
+type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
+declare function completeLessonWithTelemetry(opts: {
+    progress: ProgressController;
+    lessonId: LessonId;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+}): boolean;
+declare function completeCourseWithTelemetry(opts: {
+    progress: ProgressController;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+    emitCourseCompleted: () => void;
+}): boolean;
+
+type LessonkitRuntimeVersion = "v1" | "v2";
+type HeadlessLessonkitConfig = {
+    courseId: CourseId;
+    runtimeVersion?: LessonkitRuntimeVersion;
+    session?: {
+        sessionId?: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    plugins?: PluginRegistry | null;
+};
+type HeadlessRuntimePorts = {
+    storage?: StoragePort;
+    clock?: ClockPort;
+};
+type HeadlessLessonkitRuntime = {
+    readonly config: HeadlessLessonkitConfig;
+    readonly progress: ProgressController;
+    getProgressState: () => ProgressState;
+    getSession: () => {
+        sessionId: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
+    setActiveLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    completeLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    completeCourse: (emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
+    track: (name: TelemetryEventName, data: unknown | undefined, emit: (event: ReturnType<typeof tryBuildTelemetryEvent>) => void, lessonId?: LessonId) => void;
+    resetForCourseChange: (courseId: CourseId) => void;
+};
+declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
+
+declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
+
+declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
+declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
+declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitUrnParts, type PluginHost, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createPluginHost, createSessionId, createTrackingClient, defineLessonkitPlugin, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };
+export { type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, markCourseStarted, markCourseStartedEmittedToTracking, migrateCourseStartedMark, nowIso, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };