@futdevpro/fsm-dynamo 1.20.101 → 1.20.103

package/build-esm/_modules/game/_models/guided-onboarding.control-model.js

@@ -0,0 +1,486 @@
+import { DyFM_Log } from '../../../_collections/utils/log.util';
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+const ISSUER = 'DyFM_GuidedOnboarding_ControlModel';
+/**
+ * BFR-WARFACTORY-014 — content-agnostic guided onboarding: chapters of steps with STABLE ids, declarative commands and
+ * predicates resolved against the game's capability surface, state-regression recovery, bounded timeouts,
+ * skip / restart / resume, and a versioned, migratable progress state.
+ *
+ * It owns no timer and no DOM: the driver (a game loop tick, a state-change event, an Angular effect) calls
+ * `evaluate()`; the UI layer renders `position()` and listens to `onEvent()`. The clock is injectable, so timeouts are
+ * deterministic in tests.
+ */
+export class DyFM_GuidedOnboarding_ControlModel {
+    catalog;
+    capabilities;
+    now;
+    steps = [];
+    chapterCount;
+    status = 'not-started';
+    currentIndex = -1;
+    enteredAtMs = 0;
+    completed = new Set();
+    skipped = new Set();
+    listeners = [];
+    /** `importState` restored an active step, but it was not entered yet (`resume`). */
+    pendingResume = false;
+    /** A transition (with a possibly async command) is running — a re-entrant `evaluate` waits it out. */
+    transitioning = false;
+    /** Validates the catalog against the capabilities; any finding throws `DYFM-ONBOARDING-CATALOG` listing them all. */
+    constructor(catalog, capabilities, now = () => Date.now()) {
+        this.catalog = catalog;
+        this.capabilities = capabilities;
+        this.now = now;
+        const findings = DyFM_GuidedOnboarding_ControlModel.validateCatalog(catalog, capabilities);
+        if (findings.length) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: invalid catalog — ${findings.map((f) => `[${f.code}] ${f.path}: ${f.message}`).join(' · ')}`,
+                errorCode: 'DYFM-ONBOARDING-CATALOG',
+                issuerService: ISSUER,
+            });
+        }
+        catalog.chapters.forEach((chapter, chapterIndex) => {
+            chapter.steps.forEach((step) => {
+                this.steps.push({ chapterId: chapter.chapterId, chapterIndex: chapterIndex, step: step });
+            });
+        });
+        this.chapterCount = catalog.chapters.length;
+    }
+    /**
+     * Every problem of a catalog, as data (never throws). With `capabilities`, each ref must name a registered command /
+     * predicate — a typo is caught when the game boots, not when a player reaches that step.
+     */
+    static validateCatalog(catalog, capabilities) {
+        const findings = [];
+        const add = (code, path, message) => findings.push({ code: code, path: path, message: message });
+        if (!catalog || !Array.isArray(catalog.chapters) || !catalog.chapters.length) {
+            add('ONB-EMPTY', 'chapters', 'a catalog needs at least one chapter');
+            return findings;
+        }
+        if (catalog.catalogVersion === undefined || catalog.catalogVersion === null || catalog.catalogVersion === '') {
+            add('ONB-VERSION', 'catalogVersion', 'required — saves are migrated by it');
+        }
+        const chapterIds = new Set();
+        const stepIds = new Set();
+        catalog.chapters.forEach((chapter, c) => {
+            if (!chapter?.chapterId || chapterIds.has(chapter.chapterId)) {
+                add('ONB-CHAPTER-ID', `chapters[${c}]`, `chapter id must be non-empty and unique (${chapter?.chapterId})`);
+            }
+            chapterIds.add(chapter?.chapterId);
+            if (!Array.isArray(chapter?.steps) || !chapter.steps.length) {
+                add('ONB-CHAPTER-EMPTY', `chapters[${c}]`, `chapter '${chapter?.chapterId}' has no steps`);
+                return;
+            }
+            chapter.steps.forEach((step, s) => {
+                if (!step?.stepId || stepIds.has(step.stepId)) {
+                    add('ONB-STEP-ID', `chapters[${c}].steps[${s}]`, `step id must be non-empty and unique across the catalog (${step?.stepId})`);
+                }
+                stepIds.add(step?.stepId);
+            });
+        });
+        const checkRef = (ref, kind, path) => {
+            if (ref === undefined) {
+                return;
+            }
+            if (!ref || typeof ref.name !== 'string' || !ref.name) {
+                add('ONB-REF', path, 'a ref needs a non-empty name');
+            }
+            else if (capabilities && typeof capabilities[kind]?.[ref.name] !== 'function') {
+                add('ONB-REF-UNKNOWN', path, `'${ref.name}' is not a registered ${kind === 'commands' ? 'command' : 'predicate'}`);
+            }
+        };
+        catalog.chapters.forEach((chapter, c) => {
+            (chapter?.steps ?? []).forEach((step, s) => {
+                const path = `chapters[${c}].steps[${s}]`;
+                checkRef(step?.command, 'commands', `${path}.command`);
+                checkRef(step?.completion, 'predicates', `${path}.completion`);
+                checkRef(step?.stateValidator, 'predicates', `${path}.stateValidator`);
+                (step?.fallbackStepIds ?? []).forEach((fallback) => {
+                    if (fallback === step.stepId || !stepIds.has(fallback)) {
+                        add('ONB-FALLBACK', `${path}.fallbackStepIds`, `'${fallback}' is not another step of the catalog`);
+                    }
+                });
+                if (step?.timeoutMs !== undefined && !(Number.isFinite(step.timeoutMs) && step.timeoutMs > 0)) {
+                    add('ONB-TIMEOUT', `${path}.timeoutMs`, `must be a positive number (${step.timeoutMs})`);
+                }
+            });
+        });
+        for (const source of Object.keys(catalog.migrations ?? {})) {
+            if (stepIds.has(source)) {
+                add('ONB-MIGRATION-SOURCE-LIVE', `migrations.${source}`, 'the source id still exists — a rule for a live step would hijack it');
+                continue;
+            }
+            const seen = new Set([source]);
+            let target = (catalog.migrations)[source];
+            while (target !== undefined && !stepIds.has(target) && (catalog.migrations)[target] !== undefined) {
+                if (seen.has(target)) {
+                    add('ONB-MIGRATION-CYCLE', `migrations.${source}`, `cycle through '${target}'`);
+                    target = undefined;
+                    break;
+                }
+                seen.add(target);
+                target = (catalog.migrations)[target];
+            }
+            if (target !== undefined && !stepIds.has(target)) {
+                add('ONB-MIGRATION-TARGET', `migrations.${source}`, `resolves to '${target}', which is not a step of the catalog`);
+            }
+        }
+        return findings;
+    }
+    /** Subscribe; returns the unsubscribe. A throwing listener is logged and isolated — it never breaks the runtime. */
+    onEvent(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    getStatus() {
+        return this.status;
+    }
+    /** Where the player is; `null` unless active. */
+    position() {
+        if (this.status !== 'active' || this.currentIndex < 0) {
+            return null;
+        }
+        const current = this.steps[this.currentIndex];
+        const chapterSteps = this.steps
+            .filter((s) => s.chapterIndex === current.chapterIndex);
+        return {
+            chapterId: current.chapterId,
+            chapterIndex: current.chapterIndex,
+            chapterCount: this.chapterCount,
+            step: current.step,
+            stepIndexInChapter: chapterSteps.indexOf(current),
+            chapterStepCount: chapterSteps.length,
+            doneCount: this.completed.size + this.skipped.size,
+            totalCount: this.steps.length,
+            manual: !current.step.completion,
+        };
+    }
+    /** Starts a not-yet-started onboarding at its first step (no-op otherwise — a finished one is `restart`ed). */
+    async start(context) {
+        if (this.status !== 'not-started') {
+            return;
+        }
+        this.status = 'active';
+        await this.transition(async () => this.enter(0, context, true, false));
+    }
+    /**
+     * One check of the active step: state regression → fallback · completion → next step · timeout → recorded and left.
+     * Call it from whatever drives the game (tick, state event); it never waits by itself.
+     */
+    async evaluate(context) {
+        if (this.status !== 'active' || this.transitioning) {
+            return this.status === 'active' ? 'waiting' : 'inactive';
+        }
+        this.assertResumed();
+        const step = this.steps[this.currentIndex].step;
+        if (step.stateValidator && !this.predicate(step.stateValidator, context, step.stepId)) {
+            const visited = new Set([step.stepId]);
+            for (const fallbackId of step.fallbackStepIds ?? []) {
+                if (visited.has(fallbackId)) {
+                    continue;
+                }
+                visited.add(fallbackId);
+                const index = this.indexOf(fallbackId);
+                const fallback = this.steps[index].step;
+                if (fallback.stateValidator && !this.predicate(fallback.stateValidator, context, fallback.stepId)) {
+                    continue;
+                }
+                // Everything from the fallback on has to be done again.
+                for (let i = index; i <= Math.max(index, this.currentIndex); i++) {
+                    this.completed.delete(this.steps[i].step.stepId);
+                    this.skipped.delete(this.steps[i].step.stepId);
+                }
+                this.emit({ type: 'regressed', stepId: fallbackId, fromStepId: step.stepId, chapterId: this.steps[index].chapterId });
+                await this.transition(async () => this.enter(index, context, true, false));
+                return 'regressed';
+            }
+        }
+        if (step.completion && this.predicate(step.completion, context, step.stepId)) {
+            await this.transition(async () => this.leave('completed', context));
+            return 'advanced';
+        }
+        if (step.timeoutMs !== undefined && this.now() - this.enteredAtMs >= step.timeoutMs) {
+            await this.transition(async () => this.leave('timed-out', context));
+            return 'timed-out';
+        }
+        return 'waiting';
+    }
+    /** The player acknowledges a MANUAL step (no completion predicate); a gameplay step throws `DYFM-ONBOARDING-NOT-MANUAL`. */
+    async next(context) {
+        const step = this.activeStep('next');
+        if (step.completion) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: step '${step.stepId}' completes by '${step.completion.name}', not by "Next" — use skip('step') to leave it`,
+                errorCode: 'DYFM-ONBOARDING-NOT-MANUAL',
+                issuerService: ISSUER,
+            });
+        }
+        await this.transition(async () => this.leave('completed', context));
+    }
+    /** Skip the active step, the rest of its chapter, or the whole onboarding. */
+    async skip(context, scope) {
+        const step = this.activeStep('skip');
+        if (scope === 'all') {
+            this.status = 'skipped';
+            this.currentIndex = -1;
+            this.emit({ type: 'skipped', stepId: step.stepId });
+            return;
+        }
+        if (scope === 'chapter') {
+            const chapterIndex = this.steps[this.currentIndex].chapterIndex;
+            for (let i = this.currentIndex + 1; i < this.steps.length && this.steps[i].chapterIndex === chapterIndex; i++) {
+                const id = this.steps[i].step.stepId;
+                if (!this.completed.has(id) && !this.skipped.has(id)) {
+                    this.skipped.add(id);
+                    this.emit({ type: 'step-skipped', stepId: id, chapterId: this.steps[i].chapterId });
+                }
+            }
+        }
+        await this.transition(async () => this.leave('skipped', context));
+    }
+    /** Start over — all of it, or from a chapter on (earlier chapters keep their progress). */
+    async restart(context, fromChapterId) {
+        const from = fromChapterId === undefined
+            ? 0
+            : this.steps.findIndex((s) => s.chapterId === fromChapterId);
+        if (from < 0) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: restart from unknown chapter '${fromChapterId}'`,
+                errorCode: 'DYFM-ONBOARDING-UNKNOWN-CHAPTER',
+                issuerService: ISSUER,
+            });
+        }
+        for (let i = from; i < this.steps.length; i++) {
+            this.completed.delete(this.steps[i].step.stepId);
+            this.skipped.delete(this.steps[i].step.stepId);
+        }
+        this.status = 'active';
+        this.pendingResume = false;
+        this.emit({ type: 'restarted', chapterId: this.steps[from].chapterId });
+        await this.transition(async () => this.enter(from, context, true, false));
+    }
+    /** The progress as data (`dyfm-onboarding/1`); ids in catalog order, so two equal states serialise identically. */
+    exportState() {
+        const inOrder = (set) => this.steps
+            .map((s) => s.step.stepId).filter((id) => set.has(id));
+        const state = {
+            schema: 'dyfm-onboarding/1',
+            catalogVersion: this.catalog.catalogVersion,
+            status: this.status,
+            completedStepIds: inOrder(this.completed),
+            skippedStepIds: inOrder(this.skipped),
+        };
+        if (this.status === 'active' && this.currentIndex >= 0) {
+            state.stepId = this.steps[this.currentIndex].step.stepId;
+        }
+        return state;
+    }
+    /**
+     * Restores a save onto THIS catalog: ids are rewritten by the migration rules, vanished ids are dropped, and an
+     * active step that no longer exists (or is already done) continues at the first unfinished step. No command runs —
+     * an active onboarding must be `resume`d, and until then `evaluate` / `next` / `skip` throw
+     * `DYFM-ONBOARDING-NOT-RESUMED` (a forgotten resume would otherwise leave the player stuck, silently).
+     */
+    importState(state) {
+        if (!state || state.schema !== 'dyfm-onboarding/1'
+            || !['not-started', 'active', 'completed', 'skipped'].includes(state.status)
+            || !Array.isArray(state.completedStepIds) || !Array.isArray(state.skippedStepIds)) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: not a 'dyfm-onboarding/1' state (schema: ${String(state?.schema)}, status: ${String(state?.status)})`,
+                errorCode: 'DYFM-ONBOARDING-STATE',
+                issuerService: ISSUER,
+            });
+        }
+        const report = { migrated: state.catalogVersion !== this.catalog.catalogVersion, renamed: {}, dropped: [] };
+        const resolve = (id) => {
+            let current = id;
+            for (let hops = 0; this.indexOf(current, false) < 0; hops++) {
+                const next = this.catalog.migrations?.[current];
+                if (next === undefined || hops > this.steps.length) {
+                    if (!report.dropped.includes(id)) {
+                        report.dropped.push(id);
+                    }
+                    return undefined;
+                }
+                current = next;
+            }
+            if (current !== id) {
+                report.renamed[id] = current;
+            }
+            return current;
+        };
+        this.completed.clear();
+        this.skipped.clear();
+        state.completedStepIds.forEach((id) => {
+            const resolved = resolve(id);
+            if (resolved) {
+                this.completed.add(resolved);
+            }
+        });
+        state.skippedStepIds.forEach((id) => {
+            const resolved = resolve(id);
+            if (resolved && !this.completed.has(resolved)) {
+                this.skipped.add(resolved);
+            }
+        });
+        this.status = state.status;
+        this.currentIndex = -1;
+        this.pendingResume = false;
+        if (state.status === 'active') {
+            const resolved = state.stepId === undefined ? undefined : resolve(state.stepId);
+            let index = resolved === undefined ? -1 : this.indexOf(resolved);
+            if (index < 0 || this.isDone(index)) {
+                index = this.steps.findIndex((s, i) => !this.isDone(i));
+                if (index >= 0) {
+                    report.resumedAt = this.steps[index].step.stepId;
+                }
+            }
+            if (index < 0) {
+                this.status = 'completed';
+            }
+            else {
+                this.currentIndex = index;
+                this.pendingResume = true;
+            }
+        }
+        report.migrated = report.migrated || Object.keys(report.renamed).length > 0 || report.dropped.length > 0
+            || report.resumedAt !== undefined;
+        return report;
+    }
+    /**
+     * Enters the restored step after `importState`. Its command is NOT run again by default (it already ran before the
+     * save — e.g. placing a building twice would corrupt the game); pass `rerunCommand` for idempotent commands.
+     */
+    async resume(context, options = {}) {
+        if (!this.pendingResume) {
+            return;
+        }
+        this.pendingResume = false;
+        await this.transition(async () => this.enter(this.currentIndex, context, options.rerunCommand === true, true));
+    }
+    /** Leaves the active step (completed / skipped / timed out) and enters the next unfinished one — or finishes. */
+    async leave(how, context) {
+        const from = this.steps[this.currentIndex];
+        if (how === 'completed') {
+            this.completed.add(from.step.stepId);
+            this.emit({ type: 'step-completed', stepId: from.step.stepId, chapterId: from.chapterId });
+        }
+        else {
+            // A timed-out step is recorded as skipped: the player is not sent back into it on resume.
+            this.skipped.add(from.step.stepId);
+            this.emit({ type: how === 'skipped' ? 'step-skipped' : 'step-timed-out', stepId: from.step.stepId, chapterId: from.chapterId });
+        }
+        let next = -1;
+        for (let i = this.currentIndex + 1; i < this.steps.length; i++) {
+            if (!this.isDone(i)) {
+                next = i;
+                break;
+            }
+        }
+        if (next < 0 || this.steps[next].chapterIndex !== from.chapterIndex) {
+            const chapterDone = this.steps
+                .filter((s) => s.chapterIndex === from.chapterIndex)
+                .every((s) => this.completed.has(s.step.stepId));
+            if (chapterDone) {
+                this.emit({ type: 'chapter-completed', chapterId: from.chapterId });
+            }
+        }
+        if (next < 0) {
+            this.status = 'completed';
+            this.currentIndex = -1;
+            this.emit({ type: 'completed' });
+            return;
+        }
+        await this.enter(next, context, true, false);
+    }
+    /** Makes `index` the active step; runs its command (a failing command is reported and the step stays active). */
+    async enter(index, context, runCommand, resumed) {
+        const entry = this.steps[index];
+        this.currentIndex = index;
+        this.enteredAtMs = this.now();
+        this.emit(resumed
+            ? { type: 'step-entered', stepId: entry.step.stepId, chapterId: entry.chapterId, resumed: true }
+            : { type: 'step-entered', stepId: entry.step.stepId, chapterId: entry.chapterId });
+        if (runCommand && entry.step.command) {
+            try {
+                await this.capabilities.commands[entry.step.command.name](context, entry.step.command.args);
+            }
+            catch (error) {
+                this.emit({ type: 'command-failed', stepId: entry.step.stepId, chapterId: entry.chapterId, error: error });
+            }
+        }
+    }
+    /** Evaluates a predicate; a throwing one becomes a debuggable `DYFM-ONBOARDING-PREDICATE` (step + predicate named). */
+    predicate(ref, context, stepId) {
+        try {
+            return this.capabilities.predicates[ref.name](context, ref.args) === true;
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: predicate '${ref.name}' of step '${stepId}' threw`,
+                errorCode: 'DYFM-ONBOARDING-PREDICATE',
+                issuerService: ISSUER,
+                error: error,
+            });
+        }
+    }
+    async transition(run) {
+        this.transitioning = true;
+        try {
+            await run();
+        }
+        finally {
+            this.transitioning = false;
+        }
+    }
+    activeStep(operation) {
+        if (this.status !== 'active' || this.currentIndex < 0) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: '${operation}' needs an active onboarding (status: ${this.status})`,
+                errorCode: 'DYFM-ONBOARDING-INACTIVE',
+                issuerService: ISSUER,
+            });
+        }
+        this.assertResumed();
+        return this.steps[this.currentIndex].step;
+    }
+    assertResumed() {
+        if (this.pendingResume) {
+            throw new DyFM_Error({
+                message: 'DyFM_GuidedOnboarding: the imported onboarding is active but not resumed — call resume(context) first',
+                errorCode: 'DYFM-ONBOARDING-NOT-RESUMED',
+                issuerService: ISSUER,
+            });
+        }
+    }
+    isDone(index) {
+        const id = this.steps[index].step.stepId;
+        return this.completed.has(id) || this.skipped.has(id);
+    }
+    indexOf(stepId, required = true) {
+        const index = this.steps.findIndex((s) => s.step.stepId === stepId);
+        if (index < 0 && required) {
+            throw new DyFM_Error({
+                message: `DyFM_GuidedOnboarding: unknown step '${stepId}'`,
+                errorCode: 'DYFM-ONBOARDING-UNKNOWN-STEP',
+                issuerService: ISSUER,
+            });
+        }
+        return index;
+    }
+    emit(event) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                DyFM_Log.error(`${ISSUER}: an onEvent listener threw on '${event.type}'`, error);
+            }
+        }
+    }
+}

package/build-esm/_modules/game/_models/guided-onboarding.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/game/_models/input-action-registry.control-model.js

@@ -84,6 +84,19 @@ export class DyFM_InputActionRegistry_ControlModel {
         const chosen = best.slot;
         return { actionId: chosen.actionId, slotId: chosen.slotId, payload: chosen.payload };
     }
+    /** Every slot, in definition order (for a remap screen). */
+    listSlots() {
+        return this.slots.map((slot) => ({
+            slotId: slot.slotId,
+            actionId: slot.actionId,
+            label: this.action(slot.actionId).label,
+            chord: { ...slot.chord },
+            defaultChord: { ...slot.defaultChord },
+            isDefault: DyFM_InputActionRegistry_ControlModel.formatChord(slot.chord)
+                === DyFM_InputActionRegistry_ControlModel.formatChord(slot.defaultChord),
+            payload: slot.payload,
+        }));
+    }
     /** The current chord of a slot. */
     chordOf(slotId) {
         const slot = this.slot(slotId);

package/build-esm/_modules/game/index.js

@@ -22,6 +22,8 @@ export * from './_models/viewport.interface';
 export * from './_models/viewport.control-model';
 export * from './_models/input-action.interface';
 export * from './_models/input-action-registry.control-model';
+export * from './_models/guided-onboarding.interface';
+export * from './_models/guided-onboarding.control-model';
 // COLLECTIONS
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "1.20.101",
+  "version": "1.20.103",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",