@mpgd/tutorial 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imjlk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @mpgd/tutorial
+
+Reusable tutorial engine for mpgd games. It provides a DOM-free tutorial
+director, platform storage adapter, optional Driver.js presenter, and opt-in
+local reproduction helpers. Games keep ownership of tutorial content, gameplay
+signals, simulation blocking, localization, and any production replay button.
+
+See the [Tutorial Engine guide](https://github.com/imjlk/mpgd-kit/blob/main/docs/TUTORIAL_ENGINE.md)
+for boundaries, API usage, optional replay UI, and the local browser harness.

package/dist/definition.d.ts

@@ -0,0 +1,38 @@
+export type TutorialInteraction = 'blocked' | 'target' | 'gameplay' | 'hidden';
+export type TutorialAdvance<TAction extends string = string, TSignal extends string = string> = {
+  readonly kind: 'acknowledge';
+} | {
+  readonly action: TAction;
+  readonly kind: 'action';
+} | {
+  readonly kind: 'signal';
+  readonly signal: TSignal;
+};
+export interface TutorialStep<TStepId extends string = string, TScene extends string = string, TTarget extends string = string, TAction extends string = string, TSignal extends string = string, TContent = unknown, TMeta = unknown> {
+  readonly advance: TutorialAdvance<TAction, TSignal>;
+  readonly align?: 'start' | 'center' | 'end';
+  readonly content?: TContent;
+  readonly id: TStepId;
+  readonly interaction: TutorialInteraction;
+  readonly meta?: TMeta;
+  readonly scene: TScene;
+  readonly side?: 'top' | 'right' | 'bottom' | 'left';
+  readonly target: TTarget | null;
+}
+export interface TutorialDefinition<TStep extends TutorialStep = TutorialStep> {
+  readonly id: string;
+  readonly initialScene: TStep['scene'];
+  readonly revision: number;
+  readonly steps: readonly TStep[];
+}
+export type TutorialStepOf<TDefinition extends TutorialDefinition> = TDefinition['steps'][number];
+export type TutorialStepIdOf<TDefinition extends TutorialDefinition> = TutorialStepOf<TDefinition>['id'];
+export type TutorialSceneOf<TDefinition extends TutorialDefinition> = TutorialStepOf<TDefinition>['scene'];
+export type TutorialActionOf<TDefinition extends TutorialDefinition> = Extract<TutorialStepOf<TDefinition>['advance'], {
+  readonly kind: 'action';
+}>['action'];
+export type TutorialSignalOf<TDefinition extends TutorialDefinition> = Extract<TutorialStepOf<TDefinition>['advance'], {
+  readonly kind: 'signal';
+}>['signal'];
+export declare function defineTutorial<const TDefinition extends TutorialDefinition>(definition: TDefinition): TDefinition;
+export declare function findTutorialStep<TDefinition extends TutorialDefinition>(definition: TDefinition, stepId: TutorialStepIdOf<TDefinition>): TutorialStepOf<TDefinition> | null;

package/dist/definition.js

@@ -0,0 +1,33 @@
+export function defineTutorial(definition) {
+    if (definition.id.trim().length === 0) {
+        throw new Error('Tutorial id must not be empty.');
+    }
+    if (!Number.isSafeInteger(definition.revision) || definition.revision <= 0) {
+        throw new Error('Tutorial revision must be a positive safe integer.');
+    }
+    if (definition.steps.length === 0) {
+        throw new Error('Tutorial must define at least one step.');
+    }
+    const stepIds = new Set();
+    const scenes = new Set();
+    for (const step of definition.steps) {
+        if (step.id.trim().length === 0) {
+            throw new Error('Tutorial step id must not be empty.');
+        }
+        if (stepIds.has(step.id)) {
+            throw new Error(`Duplicate tutorial step id: ${step.id}`);
+        }
+        if (step.scene.trim().length === 0) {
+            throw new Error(`Tutorial step scene must not be empty: ${step.id}`);
+        }
+        stepIds.add(step.id);
+        scenes.add(step.scene);
+    }
+    if (!scenes.has(definition.initialScene)) {
+        throw new Error(`Tutorial initial scene is not used by any step: ${definition.initialScene}`);
+    }
+    return definition;
+}
+export function findTutorialStep(definition, stepId) {
+    return definition.steps.find((step) => step.id === stepId) ?? null;
+}

package/dist/director.d.ts

@@ -0,0 +1,39 @@
+import type { TutorialActionOf, TutorialDefinition, TutorialSceneOf, TutorialSignalOf, TutorialStepIdOf, TutorialStepOf } from './definition.js';
+import { type TutorialProgressOf, type TutorialProgressStatus, type TutorialProgressStore } from './progress.js';
+export interface TutorialDirectorSnapshot<TDefinition extends TutorialDefinition> {
+  readonly active: boolean;
+  readonly currentScene: string;
+  readonly currentStep: TutorialStepOf<TDefinition> | null;
+  readonly currentStepId: TutorialStepIdOf<TDefinition> | null;
+  readonly presentedStep: TutorialStepOf<TDefinition> | null;
+  readonly replaying: boolean;
+  readonly requiredScene: TutorialSceneOf<TDefinition> | null;
+  readonly status: TutorialProgressStatus | 'inactive';
+  readonly suspended: boolean;
+}
+export interface TutorialReplayOptions<TDefinition extends TutorialDefinition> {
+  readonly fromStepId?: TutorialStepIdOf<TDefinition>;
+}
+export interface TutorialDirector<TDefinition extends TutorialDefinition> {
+  acknowledge(stepId: TutorialStepIdOf<TDefinition>): void;
+  destroy(): void;
+  flush(): Promise<void>;
+  getSnapshot(): TutorialDirectorSnapshot<TDefinition>;
+  observeAction(action: TutorialActionOf<TDefinition>): void;
+  observeScene(scene: string): void;
+  observeSignal(signal: TutorialSignalOf<TDefinition>): void;
+  replay(options?: TutorialReplayOptions<TDefinition>): Promise<void>;
+  setSuspended(suspended: boolean): void;
+  skip(): Promise<void>;
+  subscribe(listener: (snapshot: TutorialDirectorSnapshot<TDefinition>) => void): () => void;
+}
+export interface CreateTutorialDirectorInput<TDefinition extends TutorialDefinition> {
+  readonly autoStart: boolean;
+  readonly clock?: () => Date;
+  readonly definition: TDefinition;
+  readonly initialScene?: string;
+  readonly onError?: (error: unknown) => void;
+  readonly progressStore: TutorialProgressStore<TutorialProgressOf<TDefinition>>;
+  readonly suspended?: boolean;
+}
+export declare function createTutorialDirector<TDefinition extends TutorialDefinition>(input: CreateTutorialDirectorInput<TDefinition>): TutorialDirector<TDefinition>;

package/dist/director.js

@@ -0,0 +1,230 @@
+import { createInitialTutorialProgress, createTutorialProgressAtStep, } from './progress.js';
+export function createTutorialDirector(input) {
+    const { definition, progressStore } = input;
+    const listeners = new Set();
+    const clock = input.clock ?? (() => new Date());
+    const stored = progressStore.getSnapshot();
+    let durableBeforeReplay = null;
+    let replayRestorePending = false;
+    let progress = stored ?? (input.autoStart && progressStore.available
+        ? createInitialTutorialProgress(definition, now())
+        : null);
+    let replaying = false;
+    let durableFallbackDuringPublish;
+    let suspended = input.suspended ?? false;
+    let destroyed = false;
+    let currentScene = input.initialScene ?? definition.initialScene;
+    let publishing = false;
+    const pendingSnapshots = [];
+    if (stored === null && progress !== null) {
+        persist(progress);
+    }
+    let snapshot = createSnapshot(definition, progress, replaying, suspended, currentScene);
+    function now() {
+        return clock().toISOString();
+    }
+    function persist(next) {
+        if (destroyed || replaying) {
+            return;
+        }
+        void progressStore.save(next).catch((error) => {
+            input.onError?.(error);
+        });
+    }
+    function publish() {
+        const publishedSnapshot = createSnapshot(definition, progress, replaying, suspended, currentScene);
+        pendingSnapshots.push(publishedSnapshot);
+        if (publishing) {
+            return;
+        }
+        publishing = true;
+        try {
+            while (pendingSnapshots.length > 0) {
+                const pendingSnapshot = pendingSnapshots.shift();
+                if (pendingSnapshot === undefined) {
+                    continue;
+                }
+                snapshot = pendingSnapshot;
+                const recipients = [...listeners];
+                for (const subscription of recipients) {
+                    if (listeners.has(subscription)) {
+                        subscription.listener(pendingSnapshot);
+                    }
+                }
+            }
+        }
+        finally {
+            publishing = false;
+        }
+    }
+    function getCurrentStep() {
+        if (progress?.status !== 'active') {
+            return null;
+        }
+        return definition.steps[progress.completedStepIds.length] ?? null;
+    }
+    function canAdvance(step) {
+        return !suspended
+            && progress?.status === 'active'
+            && step !== null
+            && step.scene === currentScene;
+    }
+    function advanceCurrent() {
+        const current = getCurrentStep();
+        if (!canAdvance(current) || progress === null) {
+            return;
+        }
+        const completedStepIds = [...progress.completedStepIds, current.id];
+        const timestamp = now();
+        const complete = completedStepIds.length === definition.steps.length;
+        progress = {
+            ...progress,
+            checkpoint: current.scene,
+            completedAt: complete ? timestamp : null,
+            completedStepIds,
+            skippedAt: null,
+            status: complete ? 'completed' : 'active',
+            updatedAt: timestamp,
+        };
+        if (complete && replaying && replayRestorePending) {
+            progress = durableBeforeReplay;
+            replaying = false;
+            replayRestorePending = false;
+            durableBeforeReplay = null;
+            publish();
+            return;
+        }
+        if (complete) {
+            replaying = false;
+            replayRestorePending = false;
+            durableBeforeReplay = null;
+        }
+        persist(progress);
+        publish();
+    }
+    return {
+        acknowledge(stepId) {
+            const step = getCurrentStep();
+            if (step?.id === stepId && step.advance.kind === 'acknowledge') {
+                advanceCurrent();
+            }
+        },
+        destroy() {
+            destroyed = true;
+            listeners.clear();
+        },
+        flush: () => progressStore.flush(),
+        getSnapshot: () => snapshot,
+        observeAction(action) {
+            const step = getCurrentStep();
+            if (canAdvance(step) && step.advance.kind === 'action' && step.advance.action === action) {
+                advanceCurrent();
+            }
+        },
+        observeScene(scene) {
+            currentScene = scene;
+            const step = getCurrentStep();
+            if (progress?.status === 'active' && step?.scene === scene && progress.checkpoint !== scene) {
+                progress = { ...progress, checkpoint: scene, updatedAt: now() };
+                persist(progress);
+            }
+            publish();
+        },
+        observeSignal(signal) {
+            const step = getCurrentStep();
+            if (canAdvance(step) && step.advance.kind === 'signal' && step.advance.signal === signal) {
+                advanceCurrent();
+            }
+        },
+        async replay(options = {}) {
+            const replayProgress = options.fromStepId === undefined
+                ? createInitialTutorialProgress(definition, now())
+                : createTutorialProgressAtStep(definition, options.fromStepId, now());
+            if (!replaying) {
+                durableBeforeReplay = durableFallbackDuringPublish === undefined
+                    ? progress
+                    : durableFallbackDuringPublish;
+                replayRestorePending = true;
+            }
+            replaying = true;
+            suspended = false;
+            progress = replayProgress;
+            publish();
+        },
+        setSuspended(nextSuspended) {
+            if (suspended === nextSuspended) {
+                return;
+            }
+            suspended = nextSuspended;
+            publish();
+        },
+        async skip() {
+            if (progress === null) {
+                return;
+            }
+            if (replaying && replayRestorePending) {
+                progress = durableBeforeReplay;
+                durableBeforeReplay = null;
+                replayRestorePending = false;
+                replaying = false;
+                publish();
+                return;
+            }
+            if (progress.status !== 'active') {
+                return;
+            }
+            const progressBeforeSkip = progress;
+            const timestamp = now();
+            progress = {
+                ...progress,
+                completedAt: null,
+                skippedAt: timestamp,
+                status: 'skipped',
+                updatedAt: timestamp,
+            };
+            replaying = false;
+            durableBeforeReplay = null;
+            replayRestorePending = false;
+            durableFallbackDuringPublish = progressBeforeSkip;
+            try {
+                publish();
+            }
+            finally {
+                durableFallbackDuringPublish = undefined;
+            }
+            if (destroyed || replaying) {
+                return;
+            }
+            try {
+                await progressStore.save(progress);
+            }
+            catch (error) {
+                input.onError?.(error);
+            }
+        },
+        subscribe(listener) {
+            const subscription = { listener };
+            listeners.add(subscription);
+            listener(snapshot);
+            return () => listeners.delete(subscription);
+        },
+    };
+}
+function createSnapshot(definition, progress, replaying, suspended, currentScene) {
+    const currentStep = progress?.status === 'active'
+        ? (definition.steps[progress.completedStepIds.length] ?? null)
+        : null;
+    const active = !suspended && currentStep !== null;
+    const inCurrentScene = active && currentStep.scene === currentScene;
+    return {
+        active,
+        currentScene,
+        currentStep,
+        currentStepId: currentStep?.id ?? null,
+        presentedStep: inCurrentScene && currentStep.interaction !== 'hidden' ? currentStep : null,
+        replaying,
+        requiredScene: currentStep?.scene ?? null,
+        status: progress?.status ?? 'inactive',
+        suspended,
+    };
+}

package/dist/driver.d.ts

@@ -0,0 +1,50 @@
+import type { TutorialDefinition, TutorialStep } from './definition.js';
+import type { TutorialDirector } from './director.js';
+export interface DriverTutorialCopy {
+  readonly description: string;
+  readonly done: string;
+  readonly next: string;
+  readonly skip: string;
+  readonly title: string;
+}
+export interface DriverTutorialPresentation<TStep extends TutorialStep = TutorialStep> {
+  readonly acknowledgeOnTargetClick?: boolean;
+  readonly allowTargetInteraction?: boolean;
+  readonly copy: DriverTutorialCopy;
+  readonly finalStep?: boolean;
+  readonly step: TStep;
+}
+export interface DriverTutorialPresenterInput<TStep extends TutorialStep = TutorialStep> {
+  readonly missingTarget?: 'error' | 'unanchored' | 'wait';
+  readonly modalSelector?: string;
+  readonly onAcknowledge: (stepId: TStep['id']) => void;
+  readonly onActiveChange?: (active: boolean) => void;
+  readonly onError?: (error: unknown) => void;
+  readonly onSkip: () => Promise<void> | void;
+  readonly resolveTarget?: (target: TStep['target'], root: Document | HTMLElement) => HTMLElement | null;
+  readonly root?: Document | HTMLElement;
+  readonly stateHost?: HTMLElement;
+  readonly targetAttribute?: string;
+}
+export interface DriverTutorialPresenter<TStep extends TutorialStep = TutorialStep> {
+  destroy(): void;
+  present(presentation: DriverTutorialPresentation<TStep> | null): void;
+  refresh(): void;
+  resetForReplay(): void;
+  waitForPendingSkip(): Promise<void>;
+}
+export declare function createDriverTutorialPresenter<TStep extends TutorialStep>(input: DriverTutorialPresenterInput<TStep>): DriverTutorialPresenter<TStep>;
+export declare function resolveVisibleTutorialTarget(input: {
+  readonly root?: Document | HTMLElement;
+  readonly target: string;
+  readonly targetAttribute?: string;
+  readonly view?: Window;
+}): HTMLElement | null;
+export declare function isVisibleTutorialTarget(element: HTMLElement, view?: Window): boolean;
+export declare function bindTutorialReplayTrigger<TDefinition extends TutorialDefinition>(input: {
+  readonly beforeReplay?: () => Promise<void> | void;
+  readonly director: TutorialDirector<TDefinition>;
+  readonly element: HTMLElement;
+  readonly onError?: (error: unknown) => void;
+  readonly presenter: Pick<DriverTutorialPresenter, 'resetForReplay' | 'waitForPendingSkip'>;
+}): () => void;