@mpgd/tutorial 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export * from './definition.js';
+export * from './director.js';
+export * from './progress.js';
+export declare const tutorialDomAttributes: Readonly<{
+  active: "data-mpgd-tutorial-active";
+  next: "data-mpgd-tutorial-next";
+  popover: "data-mpgd-tutorial-popover";
+  skip: "data-mpgd-tutorial-skip";
+  step: "data-mpgd-tutorial-step";
+  target: "data-mpgd-tutorial-target";
+}>;
+export declare const tutorialDomSelectors: Readonly<{
+  active: "[data-mpgd-tutorial-active=\"true\"]";
+  next: "[data-mpgd-tutorial-next]";
+  popover: "[data-mpgd-tutorial-popover]";
+  skip: "[data-mpgd-tutorial-skip]";
+  step: "[data-mpgd-tutorial-step]";
+  target: "[data-mpgd-tutorial-target]";
+}>;

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from './definition.js';
+export * from './director.js';
+export * from './progress.js';
+export const tutorialDomAttributes = Object.freeze({
+    active: 'data-mpgd-tutorial-active',
+    next: 'data-mpgd-tutorial-next',
+    popover: 'data-mpgd-tutorial-popover',
+    skip: 'data-mpgd-tutorial-skip',
+    step: 'data-mpgd-tutorial-step',
+    target: 'data-mpgd-tutorial-target',
+});
+export const tutorialDomSelectors = Object.freeze({
+    active: '[data-mpgd-tutorial-active="true"]',
+    next: '[data-mpgd-tutorial-next]',
+    popover: '[data-mpgd-tutorial-popover]',
+    skip: '[data-mpgd-tutorial-skip]',
+    step: '[data-mpgd-tutorial-step]',
+    target: '[data-mpgd-tutorial-target]',
+});

package/dist/platform-storage.d.ts

@@ -0,0 +1,14 @@
+import type { StorageAdapter } from '@mpgd/platform';
+import type { TutorialDefinition } from './definition.js';
+import { type TutorialProgressOf, type TutorialProgressStore } from './progress.js';
+export declare const defaultTutorialStorageLoadTimeoutMs = 10000;
+export interface CreatePlatformTutorialProgressStoreInput<TDefinition extends TutorialDefinition> {
+  readonly definition: TDefinition;
+  readonly invalidRecord?: 'disable' | 'ignore';
+  readonly key: string;
+  readonly migrate?: (value: unknown) => unknown;
+  readonly onError?: (error: unknown) => void;
+  readonly storage: Pick<StorageAdapter, 'load' | 'save'>;
+  readonly loadTimeoutMs?: number;
+}
+export declare function createPlatformTutorialProgressStore<TDefinition extends TutorialDefinition>(input: CreatePlatformTutorialProgressStoreInput<TDefinition>): Promise<TutorialProgressStore<TutorialProgressOf<TDefinition>>>;

package/dist/platform-storage.js

@@ -0,0 +1,74 @@
+import { parseTutorialProgress, } from './progress.js';
+export const defaultTutorialStorageLoadTimeoutMs = 10000;
+export async function createPlatformTutorialProgressStore(input) {
+    const loadTimeoutMs = resolveLoadTimeoutMs(input.loadTimeoutMs);
+    let current = null;
+    let available = true;
+    let queue = Promise.resolve();
+    try {
+        const stored = await loadWithTimeout(input.storage.load({ key: input.key }), loadTimeoutMs);
+        if (stored !== null) {
+            const migrated = input.migrate === undefined ? stored.value : input.migrate(stored.value);
+            current = parseTutorialProgress(input.definition, migrated);
+            if (current === null && (input.invalidRecord ?? 'disable') === 'disable') {
+                available = false;
+                input.onError?.(new Error(`Invalid tutorial progress: ${input.key}`));
+            }
+        }
+    }
+    catch (error) {
+        available = false;
+        input.onError?.(error);
+    }
+    return {
+        get available() {
+            return available;
+        },
+        async flush() {
+            await queue;
+        },
+        getSnapshot: () => current,
+        save(progress) {
+            if (!available) {
+                return Promise.resolve();
+            }
+            const operation = queue.then(async () => {
+                if (!available) {
+                    return;
+                }
+                await input.storage.save({ key: input.key, value: progress });
+                current = progress;
+            });
+            void (queue = operation.catch((error) => {
+                available = false;
+                input.onError?.(error);
+            }));
+            return operation;
+        },
+    };
+}
+function resolveLoadTimeoutMs(timeoutMs) {
+    const resolved = timeoutMs ?? defaultTutorialStorageLoadTimeoutMs;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        throw new TypeError('Tutorial storage loadTimeoutMs must be a positive finite number.');
+    }
+    return resolved;
+}
+async function loadWithTimeout(operation, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_resolve, reject) => {
+                timer = globalThis.setTimeout(() => {
+                    reject(new Error(`Tutorial storage load timed out after ${timeoutMs}ms.`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            globalThis.clearTimeout(timer);
+        }
+    }
+}

package/dist/progress.d.ts

@@ -0,0 +1,23 @@
+import type { TutorialDefinition, TutorialSceneOf, TutorialStepIdOf } from './definition.js';
+export type TutorialProgressStatus = 'active' | 'completed' | 'skipped';
+export interface TutorialProgress<TStepId extends string = string, TScene extends string = string> {
+  readonly checkpoint: TScene;
+  readonly completedAt: string | null;
+  readonly completedStepIds: readonly TStepId[];
+  readonly definitionRevision: number;
+  readonly schemaVersion: 1;
+  readonly skippedAt: string | null;
+  readonly status: TutorialProgressStatus;
+  readonly tutorialId: string;
+  readonly updatedAt: string;
+}
+export type TutorialProgressOf<TDefinition extends TutorialDefinition> = TutorialProgress<TutorialStepIdOf<TDefinition>, TutorialSceneOf<TDefinition>>;
+export interface TutorialProgressStore<TProgress extends TutorialProgress = TutorialProgress> {
+  readonly available: boolean;
+  flush(): Promise<void>;
+  getSnapshot(): TProgress | null;
+  save(progress: TProgress): Promise<void>;
+}
+export declare function createInitialTutorialProgress<TDefinition extends TutorialDefinition>(definition: TDefinition, now?: string): TutorialProgressOf<TDefinition>;
+export declare function createTutorialProgressAtStep<TDefinition extends TutorialDefinition>(definition: TDefinition, stepId: TutorialStepIdOf<TDefinition>, now?: string): TutorialProgressOf<TDefinition>;
+export declare function parseTutorialProgress<TDefinition extends TutorialDefinition>(definition: TDefinition, value: unknown): TutorialProgressOf<TDefinition> | null;

package/dist/progress.js

@@ -0,0 +1,80 @@
+export function createInitialTutorialProgress(definition, now = new Date().toISOString()) {
+    return {
+        checkpoint: definition.initialScene,
+        completedAt: null,
+        completedStepIds: [],
+        definitionRevision: definition.revision,
+        schemaVersion: 1,
+        skippedAt: null,
+        status: 'active',
+        tutorialId: definition.id,
+        updatedAt: now,
+    };
+}
+export function createTutorialProgressAtStep(definition, stepId, now = new Date().toISOString()) {
+    const stepIndex = definition.steps.findIndex((step) => step.id === stepId);
+    if (stepIndex < 0) {
+        throw new Error(`Unknown tutorial step: ${stepId}`);
+    }
+    const step = definition.steps[stepIndex];
+    if (step === undefined) {
+        throw new Error(`Unknown tutorial step: ${stepId}`);
+    }
+    return {
+        ...createInitialTutorialProgress(definition, now),
+        checkpoint: step.scene,
+        completedStepIds: definition.steps.slice(0, stepIndex).map((candidate) => candidate.id),
+    };
+}
+export function parseTutorialProgress(definition, value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 1
+        || value.tutorialId !== definition.id
+        || value.definitionRevision !== definition.revision
+        || !isProgressStatus(value.status)
+        || !isTimestamp(value.updatedAt)
+        || !(value.completedAt === null || isTimestamp(value.completedAt))
+        || !(value.skippedAt === null || isTimestamp(value.skippedAt))
+        || typeof value.checkpoint !== 'string'
+        || !Array.isArray(value.completedStepIds)) {
+        return null;
+    }
+    const scenes = new Set(definition.steps.map((step) => step.scene));
+    const completedStepIds = value.completedStepIds;
+    if (!scenes.has(value.checkpoint)
+        || completedStepIds.some((id) => typeof id !== 'string')
+        || new Set(completedStepIds).size !== completedStepIds.length
+        || completedStepIds.length > definition.steps.length
+        || completedStepIds.some((id, index) => definition.steps[index]?.id !== id)) {
+        return null;
+    }
+    const complete = completedStepIds.length === definition.steps.length;
+    if ((value.status === 'active'
+        && (complete || value.completedAt !== null || value.skippedAt !== null))
+        || (value.status === 'completed'
+            && (!complete || value.completedAt === null || value.skippedAt !== null))
+        || (value.status === 'skipped'
+            && (complete || value.completedAt !== null || value.skippedAt === null))) {
+        return null;
+    }
+    return {
+        checkpoint: value.checkpoint,
+        completedAt: value.completedAt,
+        completedStepIds: [...completedStepIds],
+        definitionRevision: definition.revision,
+        schemaVersion: 1,
+        skippedAt: value.skippedAt,
+        status: value.status,
+        tutorialId: definition.id,
+        updatedAt: value.updatedAt,
+    };
+}
+function isProgressStatus(value) {
+    return value === 'active' || value === 'completed' || value === 'skipped';
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/testing.d.ts

@@ -0,0 +1,59 @@
+import type { TutorialActionOf, TutorialDefinition, TutorialSignalOf, TutorialStepIdOf } from './definition.js';
+import type { TutorialDirector, TutorialReplayOptions } from './director.js';
+import type { TutorialProgress, TutorialProgressOf, TutorialProgressStore } from './progress.js';
+export interface MemoryTutorialProgressStore<TProgress extends TutorialProgress> extends TutorialProgressStore<TProgress> {
+  readonly saves: readonly TProgress[];
+}
+export declare function createMemoryTutorialProgressStore(): MemoryTutorialProgressStore<TutorialProgress>;
+export declare function createMemoryTutorialProgressStore<TDefinition extends TutorialDefinition>(input: {
+  readonly definition: TDefinition;
+  readonly available?: boolean;
+  readonly initial?: TutorialProgressOf<TDefinition> | null;
+  readonly rejectSave?: boolean;
+}): MemoryTutorialProgressStore<TutorialProgressOf<TDefinition>>;
+export declare function createMemoryTutorialProgressStore<TProgress extends TutorialProgress>(input?: {
+  readonly available?: boolean;
+  readonly definition?: TutorialDefinition;
+  readonly initial?: TProgress | null;
+  readonly rejectSave?: boolean;
+}): MemoryTutorialProgressStore<TProgress>;
+export type TutorialDebugMode = 'default' | 'off' | 'replay';
+export interface TutorialDebugLaunchPolicy<TStepId extends string = string> {
+  readonly enabled: boolean;
+  readonly mode: TutorialDebugMode;
+  readonly stepId: TStepId | null;
+}
+export declare function resolveTutorialDebugLaunchPolicy<TDefinition extends TutorialDefinition>(input: {
+  readonly definition: TDefinition;
+  readonly enabled: boolean;
+  readonly search: string;
+}): TutorialDebugLaunchPolicy<TutorialStepIdOf<TDefinition>>;
+export declare function applyTutorialDebugLaunchPolicy<TDefinition extends TutorialDefinition>(director: TutorialDirector<TDefinition>, policy: TutorialDebugLaunchPolicy<TutorialStepIdOf<TDefinition>>): Promise<void>;
+export interface TutorialDebugBridge<TDefinition extends TutorialDefinition> {
+  action(action: TutorialActionOf<TDefinition>): void;
+  getSnapshot(): ReturnType<TutorialDirector<TDefinition>['getSnapshot']>;
+  goToStep(stepId: TutorialStepIdOf<TDefinition>): Promise<void>;
+  replay(): Promise<void>;
+  scene(scene: string): void;
+  signal(signal: TutorialSignalOf<TDefinition>): void;
+  skip(): Promise<void>;
+  suspend(suspended: boolean): void;
+}
+export interface InstallTutorialDebugBridgeInput<TDefinition extends TutorialDefinition> {
+  readonly afterReplay?: (options: TutorialReplayOptions<TDefinition>) => Promise<void> | void;
+  readonly beforeReplay?: (options: TutorialReplayOptions<TDefinition>) => Promise<void> | void;
+  readonly director: TutorialDirector<TDefinition>;
+  readonly floatingReplayTrigger?: false | {
+    readonly ariaLabel?: string;
+    readonly className?: string;
+    readonly label?: string;
+    readonly parent?: HTMLElement;
+  };
+  readonly globalKey?: string;
+  readonly globalObject?: typeof globalThis;
+  readonly onError?: (error: unknown) => void;
+}
+export declare function installTutorialDebugBridge<TDefinition extends TutorialDefinition>(input: InstallTutorialDebugBridgeInput<TDefinition>): {
+  readonly bridge: TutorialDebugBridge<TDefinition>;
+  destroy(): void;
+};

package/dist/testing.js

@@ -0,0 +1,156 @@
+export function createMemoryTutorialProgressStore(input = {}) {
+    const available = input.available ?? true;
+    let current = input.initial ?? null;
+    const saves = [];
+    return {
+        available,
+        flush: () => Promise.resolve(),
+        get saves() {
+            return saves;
+        },
+        getSnapshot: () => current,
+        async save(progress) {
+            if (!available) {
+                return;
+            }
+            if (input.rejectSave === true) {
+                throw new Error('Memory tutorial progress store rejected a save.');
+            }
+            current = progress;
+            saves.push(progress);
+        },
+    };
+}
+export function resolveTutorialDebugLaunchPolicy(input) {
+    if (!input.enabled) {
+        return { enabled: false, mode: 'default', stepId: null };
+    }
+    const parameters = new URLSearchParams(input.search);
+    const requestedMode = parameters.get('mpgd-tutorial');
+    const requestedStepId = parameters.get('mpgd-tutorial-step');
+    const mode = requestedMode === 'off'
+        ? 'off'
+        : requestedMode === 'replay' || requestedStepId !== null
+            ? 'replay'
+            : 'default';
+    return {
+        enabled: true,
+        mode,
+        stepId: requestedStepId !== null && isTutorialStepId(input.definition, requestedStepId)
+            ? requestedStepId
+            : null,
+    };
+}
+export async function applyTutorialDebugLaunchPolicy(director, policy) {
+    if (!policy.enabled || policy.mode === 'default' && policy.stepId === null) {
+        return;
+    }
+    if (policy.mode === 'off') {
+        director.setSuspended(true);
+        return;
+    }
+    const options = policy.stepId === null
+        ? {}
+        : { fromStepId: policy.stepId };
+    await director.replay(options);
+}
+function isTutorialStepId(definition, stepId) {
+    return definition.steps.some((step) => step.id === stepId);
+}
+const tutorialDebugBridgeInstallations = new WeakMap();
+export function installTutorialDebugBridge(input) {
+    const globalObject = input.globalObject ?? globalThis;
+    const globalKey = input.globalKey ?? '__MPGD_TUTORIAL__';
+    const record = globalObject;
+    const previousHadOwnProperty = Object.hasOwn(record, globalKey);
+    const previous = record[globalKey];
+    const replay = async (options = {}) => {
+        await input.beforeReplay?.(options);
+        await input.director.replay(options);
+        await input.afterReplay?.(options);
+    };
+    const bridge = {
+        action: (action) => input.director.observeAction(action),
+        getSnapshot: () => input.director.getSnapshot(),
+        goToStep: (stepId) => replay({ fromStepId: stepId }),
+        replay: () => replay(),
+        scene: (scene) => input.director.observeScene(scene),
+        signal: (signal) => input.director.observeSignal(signal),
+        skip: () => input.director.skip(),
+        suspend: (suspended) => input.director.setSuspended(suspended),
+    };
+    const possiblePredecessor = typeof previous === 'object' && previous !== null
+        ? tutorialDebugBridgeInstallations.get(previous)
+        : undefined;
+    const predecessor = possiblePredecessor?.record === record
+        && possiblePredecessor.globalKey === globalKey
+        ? possiblePredecessor
+        : null;
+    const installation = {
+        bridge,
+        destroyed: false,
+        fallback: predecessor === null ? previous : predecessor.fallback,
+        fallbackHadOwnProperty: predecessor === null
+            ? previousHadOwnProperty
+            : predecessor.fallbackHadOwnProperty,
+        globalKey,
+        predecessor,
+        record,
+    };
+    tutorialDebugBridgeInstallations.set(bridge, installation);
+    record[globalKey] = bridge;
+    const destroyTrigger = createFloatingReplayTrigger(input, bridge);
+    return {
+        bridge,
+        destroy() {
+            if (installation.destroyed) {
+                return;
+            }
+            installation.destroyed = true;
+            destroyTrigger?.();
+            if (record[globalKey] !== bridge) {
+                return;
+            }
+            let restoredInstallation = installation.predecessor;
+            while (restoredInstallation?.destroyed === true) {
+                restoredInstallation = restoredInstallation.predecessor;
+            }
+            if (restoredInstallation !== null) {
+                record[globalKey] = restoredInstallation.bridge;
+            }
+            else if (installation.fallbackHadOwnProperty) {
+                record[globalKey] = installation.fallback;
+            }
+            else {
+                Reflect.deleteProperty(record, globalKey);
+            }
+        },
+    };
+}
+function createFloatingReplayTrigger(input, bridge) {
+    if (input.floatingReplayTrigger === false
+        || input.floatingReplayTrigger === undefined
+        || typeof document === 'undefined') {
+        return null;
+    }
+    const options = input.floatingReplayTrigger;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = options.label ?? '?';
+    button.setAttribute('aria-label', options.ariaLabel ?? 'Replay tutorial');
+    button.dataset.mpgdTutorialDebugReplay = 'true';
+    button.className = options.className ?? '';
+    button.style.position = 'fixed';
+    button.style.insetBlockStart = '12px';
+    button.style.insetInlineEnd = '12px';
+    button.style.zIndex = '2147483647';
+    const handleClick = () => {
+        void bridge.replay().catch((error) => input.onError?.(error));
+    };
+    button.addEventListener('click', handleClick);
+    (options.parent ?? document.body).appendChild(button);
+    return () => {
+        button.removeEventListener('click', handleClick);
+        button.remove();
+    };
+}

package/driver.css

@@ -0,0 +1,91 @@
+@import 'driver.js/dist/driver.css';
+
+.mpgd-tutorial-popover.driver-popover {
+  --mpgd-tutorial-accent: #ff8768;
+  --mpgd-tutorial-focus: #76cbd1;
+  --mpgd-tutorial-foreground: #fff0dc;
+  --mpgd-tutorial-muted: #aebbc0;
+  --mpgd-tutorial-on-accent: #24110d;
+  --mpgd-tutorial-surface: rgb(29 35 39 / 98%);
+
+  box-sizing: border-box;
+  min-width: min(280px, calc(100vw - 28px));
+  max-width: min(360px, calc(100vw - 28px));
+  padding: 16px;
+  border: 1px solid rgb(239 226 205 / 22%);
+  border-top: 3px solid var(--mpgd-tutorial-accent);
+  border-radius: 12px;
+  background: var(--mpgd-tutorial-surface);
+  box-shadow: 0 24px 70px rgb(0 0 0 / 52%);
+  color: var(--mpgd-tutorial-foreground);
+  font-family: system-ui, sans-serif;
+}
+
+.mpgd-tutorial-popover .driver-popover-title {
+  padding-inline-end: 45%;
+  color: var(--mpgd-tutorial-foreground);
+  font-size: 18px;
+  font-weight: 800;
+  line-height: 1.25;
+}
+
+.mpgd-tutorial-popover .driver-popover-description {
+  margin-top: 7px;
+  color: var(--mpgd-tutorial-muted);
+  font-size: 13px;
+  line-height: 1.55;
+}
+
+.mpgd-tutorial-popover .driver-popover-close-btn {
+  width: auto;
+  min-width: 36px;
+  height: 36px;
+  padding-inline: 8px;
+  max-width: calc(45% - 8px);
+  overflow: hidden;
+  color: var(--mpgd-tutorial-muted);
+  font-size: 11px;
+  font-weight: 700;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.mpgd-tutorial-popover .driver-popover-footer-btn {
+  min-width: 86px;
+  min-height: 42px;
+  padding: 0 14px;
+  border: 1px solid var(--mpgd-tutorial-accent);
+  border-radius: 8px;
+  background: var(--mpgd-tutorial-accent);
+  color: var(--mpgd-tutorial-on-accent);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 800;
+}
+
+.mpgd-tutorial-popover :is(button, [href]):focus-visible {
+  outline: 2px solid var(--mpgd-tutorial-focus);
+  outline-offset: 2px;
+}
+
+[data-mpgd-tutorial-active='true'] .driver-active-element {
+  outline: 2px solid var(--mpgd-tutorial-focus, #76cbd1);
+  outline-offset: 2px;
+}
+
+@supports (color: color-mix(in srgb, red, blue)) {
+  [data-mpgd-tutorial-active='true'] .driver-active-element {
+    outline: 2px solid color-mix(
+      in srgb,
+      var(--mpgd-tutorial-focus, #76cbd1) 52%,
+      transparent
+    );
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mpgd-tutorial-popover.driver-popover,
+  .driver-overlay {
+    animation: none;
+  }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@mpgd/tutorial",
+  "version": "0.1.0",
+  "description": "Headless tutorial progression, optional Driver.js presentation, and local reproduction helpers for mpgd games.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/mpgd-kit.git",
+    "directory": "packages/tutorial"
+  },
+  "bugs": {
+    "url": "https://github.com/imjlk/mpgd-kit/issues"
+  },
+  "homepage": "https://github.com/imjlk/mpgd-kit#readme",
+  "keywords": [
+    "mpgd",
+    "game-development",
+    "tutorial",
+    "onboarding",
+    "driver.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./driver.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./platform-storage": {
+      "types": "./dist/platform-storage.d.ts",
+      "default": "./dist/platform-storage.js"
+    },
+    "./driver": {
+      "types": "./dist/driver.d.ts",
+      "default": "./dist/driver.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./driver.css": "./driver.css"
+  },
+  "files": [
+    "dist",
+    "driver.css"
+  ],
+  "dependencies": {
+    "driver.js": "1.8.0",
+    "@mpgd/platform": "0.9.0"
+  },
+  "devDependencies": {
+    "jsdom": "24.1.0",
+    "ttsc": "0.18.4",
+    "typescript": "7.0.2",
+    "vitest": "^4.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "check": "ttsc --noEmit",
+    "lint": "ttsc --noEmit",
+    "test": "vitest run",
+    "format": "ttsc format",
+    "fix": "ttsc fix"
+  }
+}