@futdevpro/fsm-dynamo 1.20.102 → 1.20.103

package/build/_modules/game/_models/guided-onboarding.control-model.d.ts

@@ -0,0 +1,81 @@
+import { DyFM_OnboardingCapabilities, DyFM_OnboardingCatalog, DyFM_OnboardingEvaluation_Type, DyFM_OnboardingEvent, DyFM_OnboardingFinding, DyFM_OnboardingMigrationReport, DyFM_OnboardingPosition, DyFM_OnboardingState, DyFM_OnboardingStatus_Type } from './guided-onboarding.interface';
+/**
+ * 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 declare class DyFM_GuidedOnboarding_ControlModel<TContext> {
+    private readonly catalog;
+    private readonly capabilities;
+    private readonly now;
+    private readonly steps;
+    private readonly chapterCount;
+    private status;
+    private currentIndex;
+    private enteredAtMs;
+    private readonly completed;
+    private readonly skipped;
+    private readonly listeners;
+    /** `importState` restored an active step, but it was not entered yet (`resume`). */
+    private pendingResume;
+    /** A transition (with a possibly async command) is running — a re-entrant `evaluate` waits it out. */
+    private transitioning;
+    /** Validates the catalog against the capabilities; any finding throws `DYFM-ONBOARDING-CATALOG` listing them all. */
+    constructor(catalog: DyFM_OnboardingCatalog, capabilities: DyFM_OnboardingCapabilities<TContext>, now?: () => number);
+    /**
+     * 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<TContext>(catalog: DyFM_OnboardingCatalog, capabilities?: DyFM_OnboardingCapabilities<TContext>): DyFM_OnboardingFinding[];
+    /** Subscribe; returns the unsubscribe. A throwing listener is logged and isolated — it never breaks the runtime. */
+    onEvent(listener: (event: DyFM_OnboardingEvent) => void): () => void;
+    getStatus(): DyFM_OnboardingStatus_Type;
+    /** Where the player is; `null` unless active. */
+    position(): DyFM_OnboardingPosition | null;
+    /** Starts a not-yet-started onboarding at its first step (no-op otherwise — a finished one is `restart`ed). */
+    start(context: TContext): Promise<void>;
+    /**
+     * 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.
+     */
+    evaluate(context: TContext): Promise<DyFM_OnboardingEvaluation_Type>;
+    /** The player acknowledges a MANUAL step (no completion predicate); a gameplay step throws `DYFM-ONBOARDING-NOT-MANUAL`. */
+    next(context: TContext): Promise<void>;
+    /** Skip the active step, the rest of its chapter, or the whole onboarding. */
+    skip(context: TContext, scope: 'step' | 'chapter' | 'all'): Promise<void>;
+    /** Start over — all of it, or from a chapter on (earlier chapters keep their progress). */
+    restart(context: TContext, fromChapterId?: string): Promise<void>;
+    /** The progress as data (`dyfm-onboarding/1`); ids in catalog order, so two equal states serialise identically. */
+    exportState(): DyFM_OnboardingState;
+    /**
+     * 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: DyFM_OnboardingState): DyFM_OnboardingMigrationReport;
+    /**
+     * 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.
+     */
+    resume(context: TContext, options?: {
+        rerunCommand?: boolean;
+    }): Promise<void>;
+    /** Leaves the active step (completed / skipped / timed out) and enters the next unfinished one — or finishes. */
+    private leave;
+    /** Makes `index` the active step; runs its command (a failing command is reported and the step stays active). */
+    private enter;
+    /** Evaluates a predicate; a throwing one becomes a debuggable `DYFM-ONBOARDING-PREDICATE` (step + predicate named). */
+    private predicate;
+    private transition;
+    private activeStep;
+    private assertResumed;
+    private isDone;
+    private indexOf;
+    private emit;
+}
+//# sourceMappingURL=guided-onboarding.control-model.d.ts.map

package/build/_modules/game/_models/guided-onboarding.control-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guided-onboarding.control-model.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/guided-onboarding.control-model.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,uBAAuB,EAEvB,oBAAoB,EACpB,0BAA0B,EAE3B,MAAM,+BAA+B,CAAC;AAWvC;;;;;;;;GAQG;AACH,qBAAa,kCAAkC,CAAC,QAAQ;IAgBpD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAjBtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,oFAAoF;IACpF,OAAO,CAAC,aAAa,CAAkB;IACvC,sGAAsG;IACtG,OAAO,CAAC,aAAa,CAAkB;IAEvC,qHAAqH;gBAElG,OAAO,EAAE,sBAAsB,EAC/B,YAAY,EAAE,2BAA2B,CAAC,QAAQ,CAAC,EACnD,GAAG,GAAE,MAAM,MAAiC;IAoB/D;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAC7B,OAAO,EAAE,sBAAsB,EAC/B,YAAY,CAAC,EAAE,2BAA2B,CAAC,QAAQ,CAAC,GACnD,sBAAsB,EAAE;IA8F3B,oHAAoH;IACpH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAYpE,SAAS,IAAI,0BAA0B;IAIvC,iDAAiD;IACjD,QAAQ,IAAI,uBAAuB,GAAG,IAAI;IAsB1C,+GAA+G;IACzG,KAAK,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAmD1E,4HAA4H;IACtH,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5C,8EAA8E;IACxE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B/E,2FAA2F;IACrF,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvE,mHAAmH;IACnH,WAAW,IAAI,oBAAoB;IAkBnC;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,8BAA8B;IAgFxE;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxF,iHAAiH;YACnG,KAAK;IAyCnB,iHAAiH;YACnG,KAAK;IAmBnB,uHAAuH;IACvH,OAAO,CAAC,SAAS;YAaH,UAAU;IASxB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,IAAI;CASb"}

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

@@ -0,0 +1,491 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_GuidedOnboarding_ControlModel = void 0;
+const log_util_1 = require("../../../_collections/utils/log.util");
+const error_control_model_1 = require("../../../_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.
+ */
+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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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) {
+                log_util_1.DyFM_Log.error(`${ISSUER}: an onEvent listener threw on '${event.type}'`, error);
+            }
+        }
+    }
+}
+exports.DyFM_GuidedOnboarding_ControlModel = DyFM_GuidedOnboarding_ControlModel;
+//# sourceMappingURL=guided-onboarding.control-model.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guided-onboarding.control-model.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/guided-onboarding.control-model.ts"],"names":[],"mappings":";;;AAAA,mEAAgE;AAChE,6FAAiF;AAsBjF,MAAM,MAAM,GAAW,oCAAoC,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAa,kCAAkC;IAgB1B;IACA;IACA;IAjBF,KAAK,GAA8B,EAAE,CAAC;IACtC,YAAY,CAAS;IAC9B,MAAM,GAA+B,aAAa,CAAC;IACnD,YAAY,GAAW,CAAC,CAAC,CAAC;IAC1B,WAAW,GAAW,CAAC,CAAC;IACf,SAAS,GAAgB,IAAI,GAAG,EAAU,CAAC;IAC3C,OAAO,GAAgB,IAAI,GAAG,EAAU,CAAC;IACzC,SAAS,GAA8C,EAAE,CAAC;IAC3E,oFAAoF;IAC5E,aAAa,GAAY,KAAK,CAAC;IACvC,sGAAsG;IAC9F,aAAa,GAAY,KAAK,CAAC;IAEvC,qHAAqH;IACrH,YACmB,OAA+B,EAC/B,YAAmD,EACnD,MAAoB,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAF5C,YAAO,GAAP,OAAO,CAAwB;QAC/B,iBAAY,GAAZ,YAAY,CAAuC;QACnD,QAAG,GAAH,GAAG,CAAyC;QAE7D,MAAM,QAAQ,GAA6B,kCAAkC,CAAC,eAAe,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAErH,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,4CAA4C,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAyB,EAAU,EAAE,CACtG,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;gBACtD,SAAS,EAAE,yBAAyB;gBACpC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAuE,EAAE,YAAoB,EAAQ,EAAE;YAC/H,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAoC,EAAQ,EAAE;gBACnE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5F,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,OAA+B,EAC/B,YAAoD;QAEpD,MAAM,QAAQ,GAA6B,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,OAAe,EAAU,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAEjI,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC7E,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,sCAAsC,CAAC,CAAC;YAErE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,IAAI,OAAO,CAAC,cAAc,KAAK,EAAE,EAAE,CAAC;YAC7G,GAAG,CAAC,aAAa,EAAE,gBAAgB,EAAE,qCAAqC,CAAC,CAAC;QAC9E,CAAC;QAED,MAAM,UAAU,GAAgB,IAAI,GAAG,EAAU,CAAC;QAClD,MAAM,OAAO,GAAgB,IAAI,GAAG,EAAU,CAAC;QAE/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAuE,EAAE,CAAS,EAAQ,EAAE;YACpH,IAAI,CAAC,OAAO,EAAE,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7D,GAAG,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAAG,EAAE,4CAA4C,OAAO,EAAE,SAAS,GAAG,CAAC,CAAC;YAC7G,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAEnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC5D,GAAG,CAAC,mBAAmB,EAAE,YAAY,CAAC,GAAG,EAAE,YAAY,OAAO,EAAE,SAAS,gBAAgB,CAAC,CAAC;gBAE3F,OAAO;YACT,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAoC,EAAE,CAAS,EAAQ,EAAE;gBAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC9C,GAAG,CAAC,aAAa,EAAE,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,4DAA4D,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;gBAChI,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,CAAC,GAAmC,EAAE,IAA+B,EAAE,IAAY,EAAQ,EAAE;YAC5G,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,OAAO;YACT,CAAC;YAED,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBACtD,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,8BAA8B,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,YAAY,IAAI,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;gBAChF,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,yBAAyB,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACrH,CAAC;QACH,CAAC,CAAC;QAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAoD,EAAE,CAAS,EAAQ,EAAE;YACjG,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAoC,EAAE,CAAS,EAAQ,EAAE;gBACvF,MAAM,IAAI,GAAW,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC;gBAElD,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;gBACvD,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,IAAI,aAAa,CAAC,CAAC;gBAC/D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,GAAG,IAAI,iBAAiB,CAAC,CAAC;gBACvE,CAAC,IAAI,EAAE,eAAe,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,QAAgB,EAAQ,EAAE;oBAC/D,IAAI,QAAQ,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;wBACvD,GAAG,CAAC,cAAc,EAAE,GAAG,IAAI,kBAAkB,EAAE,IAAI,QAAQ,sCAAsC,CAAC,CAAC;oBACrG,CAAC;gBACH,CAAC,CAAC,CAAC;gBAEH,IAAI,IAAI,EAAE,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC9F,GAAG,CAAC,aAAa,EAAE,GAAG,IAAI,YAAY,EAAE,8BAA8B,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;gBAC3F,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3D,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxB,GAAG,CAAC,2BAA2B,EAAE,cAAc,MAAM,EAAE,EAAE,qEAAqE,CAAC,CAAC;gBAChI,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAgB,IAAI,GAAG,CAAS,CAAE,MAAM,CAAE,CAAC,CAAC;YACtD,IAAI,MAAM,GAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;YAElD,OAAO,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;gBAClG,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACrB,GAAG,CAAC,qBAAqB,EAAE,cAAc,MAAM,EAAE,EAAE,kBAAkB,MAAM,GAAG,CAAC,CAAC;oBAChF,MAAM,GAAG,SAAS,CAAC;oBACnB,MAAM;gBACR,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,MAAM,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;YACxC,CAAC;YAED,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjD,GAAG,CAAC,sBAAsB,EAAE,cAAc,MAAM,EAAE,EAAE,gBAAgB,MAAM,uCAAuC,CAAC,CAAC;YACrH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,oHAAoH;IACpH,OAAO,CAAC,QAA+C;QACrD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE9B,OAAO,GAAS,EAAE;YAChB,MAAM,KAAK,GAAW,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAEvD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,iDAAiD;IACjD,QAAQ;QACN,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,OAAO,GAA4B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,MAAM,YAAY,GAA8B,IAAI,CAAC,KAAK;aACvD,MAAM,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QAE5F,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,kBAAkB,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC;YACjD,gBAAgB,EAAE,YAAY,CAAC,MAAM;YACrC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI;YAClD,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YAC7B,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU;SACjC,CAAC;IACJ,CAAC;IAED,+GAA+G;IAC/G,KAAK,CAAC,KAAK,CAAC,OAAiB;QAC3B,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;YAClC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACxF,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAiB;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,MAAM,IAAI,GAAmC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC;QAEhF,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtF,MAAM,OAAO,GAAgB,IAAI,GAAG,CAAS,CAAE,IAAI,CAAC,MAAM,CAAE,CAAC,CAAC;YAE9D,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,eAAe,IAAI,EAAE,EAAE,CAAC;gBACpD,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC5B,SAAS;gBACX,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBAExB,MAAM,KAAK,GAAW,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC/C,MAAM,QAAQ,GAAmC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;gBAExE,IAAI,QAAQ,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBAClG,SAAS;gBACX,CAAC;gBAED,wDAAwD;gBACxD,KAAK,IAAI,CAAC,GAAW,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBACzE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACjD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACjD,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;gBACtH,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;gBAE1F,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;YAEnF,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpF,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;YAEnF,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,4HAA4H;IAC5H,KAAK,CAAC,IAAI,CAAC,OAAiB;QAC1B,MAAM,IAAI,GAAmC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAErE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,gCAAgC,IAAI,CAAC,MAAM,mBAAmB,IAAI,CAAC,UAAU,CAAC,IAAI,iDAAiD;gBAC5I,SAAS,EAAE,4BAA4B;gBACvC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,OAAiB,EAAE,KAAiC;QAC7D,MAAM,IAAI,GAAmC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAErE,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACxB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAEpD,OAAO;QACT,CAAC;QAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC;YAExE,KAAK,IAAI,CAAC,GAAW,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,KAAK,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtH,MAAM,EAAE,GAAW,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;gBAE7C,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;oBACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBACrB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;gBACtF,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,2FAA2F;IAC3F,KAAK,CAAC,OAAO,CAAC,OAAiB,EAAE,aAAsB;QACrD,MAAM,IAAI,GAAW,aAAa,KAAK,SAAS;YAC9C,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,aAAa,CAAC,CAAC;QAEjG,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,wDAAwD,aAAa,GAAG;gBACjF,SAAS,EAAE,iCAAiC;gBAC5C,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,KAAK,IAAI,CAAC,GAAW,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACjD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QACxE,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,mHAAmH;IACnH,WAAW;QACT,MAAM,OAAO,GAAG,CAAC,GAAgB,EAAY,EAAE,CAAC,IAAI,CAAC,KAAK;aACvD,GAAG,CAAC,CAAC,CAA0B,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,EAAU,EAAW,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3G,MAAM,KAAK,GAAyB;YAClC,MAAM,EAAE,mBAAmB;YAC3B,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;YAC3C,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,gBAAgB,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;YACzC,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;SACtC,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,IAAI,CAAC,EAAE,CAAC;YACvD,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3D,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,KAA2B;QACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,mBAAmB;eAC7C,CAAC,CAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;eAC3E,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,mEAAmE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,aAAa,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;gBACtI,SAAS,EAAE,uBAAuB;gBAClC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAmC,EAAE,QAAQ,EAAE,KAAK,CAAC,cAAc,KAAK,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC5I,MAAM,OAAO,GAAG,CAAC,EAAU,EAAsB,EAAE;YACjD,IAAI,OAAO,GAAW,EAAE,CAAC;YAEzB,KAAK,IAAI,IAAI,GAAW,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;gBACpE,MAAM,IAAI,GAAuB,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC;gBAEpE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBACnD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;wBACjC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC1B,CAAC;oBAED,OAAO,SAAS,CAAC;gBACnB,CAAC;gBACD,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YAED,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;gBACnB,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;YAC/B,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;QAEF,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,EAAU,EAAQ,EAAE;YAClD,MAAM,QAAQ,GAAuB,OAAO,CAAC,EAAE,CAAC,CAAC;YAEjD,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,EAAU,EAAQ,EAAE;YAChD,MAAM,QAAQ,GAAuB,OAAO,CAAC,EAAE,CAAC,CAAC;YAEjD,IAAI,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAE3B,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAuB,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpG,IAAI,KAAK,GAAW,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAEzE,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAA0B,EAAE,CAAS,EAAW,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;gBAElG,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;oBACf,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;gBACnD,CAAC;YACH,CAAC;YAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;gBAC1B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;eACnG,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC;QAEpC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,OAAiB,EAAE,UAAsC,EAAE;QACtE,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,IAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,YAAY,KAAK,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAChI,CAAC;IAED,iHAAiH;IACzG,KAAK,CAAC,KAAK,CAAC,GAA0C,EAAE,OAAiB;QAC/E,MAAM,IAAI,GAA4B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEpE,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YACxB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC7F,CAAC;aAAM,CAAC;YACN,0FAA0F;YAC1F,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAClI,CAAC;QAED,IAAI,IAAI,GAAW,CAAC,CAAC,CAAC;QAEtB,KAAK,IAAI,CAAC,GAAW,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpB,IAAI,GAAG,CAAC,CAAC;gBACT,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;YACpE,MAAM,WAAW,GAAY,IAAI,CAAC,KAAK;iBACpC,MAAM,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,YAAY,CAAC;iBACrF,KAAK,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAErF,IAAI,WAAW,EAAE,CAAC;gBAChB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QAED,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;YAC1B,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;YAEjC,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,iHAAiH;IACzG,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,OAAiB,EAAE,UAAmB,EAAE,OAAgB;QACzF,MAAM,KAAK,GAA4B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAEzD,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO;YACf,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YAChG,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAErF,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC;gBACH,MAAO,IAAI,CAAC,YAAY,CAAC,QAA8E,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAC9H,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YAC7G,CAAC;QACH,CAAC;IACH,CAAC;IAED,uHAAuH;IAC/G,SAAS,CAAC,GAAuB,EAAE,OAAiB,EAAE,MAAc;QAC1E,IAAI,CAAC;YACH,OAAQ,IAAI,CAAC,YAAY,CAAC,UAAmE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;QACtI,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,qCAAqC,GAAG,CAAC,IAAI,cAAc,MAAM,SAAS;gBACnF,SAAS,EAAE,2BAA2B;gBACtC,aAAa,EAAE,MAAM;gBACrB,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,GAAwB;QAC/C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC7B,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,SAAiB;QAClC,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,2BAA2B,SAAS,yCAAyC,IAAI,CAAC,MAAM,GAAG;gBACpG,SAAS,EAAE,0BAA0B;gBACrC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IAEO,aAAa;QACnB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,uGAAuG;gBAChH,SAAS,EAAE,6BAA6B;gBACxC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,MAAM,EAAE,GAAW,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QAEjD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IAEO,OAAO,CAAC,MAAc,EAAE,WAAoB,IAAI;QACtD,MAAM,KAAK,GAAW,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QAE9G,IAAI,KAAK,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,wCAAwC,MAAM,GAAG;gBAC1D,SAAS,EAAE,8BAA8B;gBACzC,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,IAAI,CAAC,KAA2B;QACtC,KAAK,MAAM,QAAQ,IAAI,CAAE,GAAG,IAAI,CAAC,SAAS,CAAE,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,mBAAQ,CAAC,KAAK,CAAC,GAAG,MAAM,mCAAmC,KAAK,CAAC,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAljBD,gFAkjBC"}

package/build/_modules/game/_models/guided-onboarding.interface.d.ts

@@ -0,0 +1,102 @@
+/**
+ * BFR-WARFACTORY-014 — a DECLARATIVE reference to a game-supplied command or predicate. It is plain data (a name and
+ * one JSON argument), so a catalog can cross a package boundary — a closure over the game's services cannot.
+ */
+export interface DyFM_OnboardingRef {
+    name: string;
+    args?: unknown;
+}
+/** One onboarding step. `stepId` is stable and unique across the WHOLE catalog (saves point at it, not at an index). */
+export interface DyFM_OnboardingStep_Definition {
+    stepId: string;
+    /** Run once when the step is entered (e.g. open a panel, pre-select a building). */
+    command?: DyFM_OnboardingRef;
+    /** The step is done when this predicate holds. Without it the step is MANUAL — the player acknowledges it (`next`). */
+    completion?: DyFM_OnboardingRef;
+    /** Must keep holding while the step is active; when it breaks, the runtime regresses to a `fallbackStepIds` step. */
+    stateValidator?: DyFM_OnboardingRef;
+    /** Recovery steps in priority order; the first one whose own `stateValidator` holds is entered. */
+    fallbackStepIds?: string[];
+    /** Bounded recovery: after this long without completion the step is recorded as timed out and left. */
+    timeoutMs?: number;
+    /** Highlight target for the UI layer (the runtime never touches the DOM); alternates are tried in order. */
+    highlight?: {
+        targetId: string;
+        alternateTargetIds?: string[];
+        anchorId?: string;
+    };
+    /** Opaque, content-side data (text key, narration asset id, world position …) — carried, never interpreted. */
+    payload?: unknown;
+}
+export interface DyFM_OnboardingChapter_Definition {
+    chapterId: string;
+    steps: DyFM_OnboardingStep_Definition[];
+    payload?: unknown;
+}
+export interface DyFM_OnboardingCatalog {
+    /** Bump it when steps change — a save made with another version is migrated on import. */
+    catalogVersion: string | number;
+    chapters: DyFM_OnboardingChapter_Definition[];
+    /** Removed / renamed step id → its replacement (chains are followed; cycles are a catalog error). */
+    migrations?: Record<string, string>;
+}
+/** The game's capability surface the declarative refs resolve against. */
+export interface DyFM_OnboardingCapabilities<TContext> {
+    commands?: Record<string, (context: TContext, args: unknown) => void | Promise<void>>;
+    predicates?: Record<string, (context: TContext, args: unknown) => boolean>;
+}
+/** Lifecycle of an onboarding run. */
+export type DyFM_OnboardingStatus_Type = 'not-started' | 'active' | 'completed' | 'skipped';
+/** The serialisable progress — `dyfm-onboarding/1`. */
+export interface DyFM_OnboardingState {
+    schema: 'dyfm-onboarding/1';
+    catalogVersion: string | number;
+    status: DyFM_OnboardingStatus_Type;
+    /** The active step (only while `active`). */
+    stepId?: string;
+    completedStepIds: string[];
+    skippedStepIds: string[];
+}
+/** What `importState` did to fit an older save onto the current catalog. */
+export interface DyFM_OnboardingMigrationReport {
+    migrated: boolean;
+    /** Old id → new id, for every id a migration rule rewrote. */
+    renamed: Record<string, string>;
+    /** Ids that no longer exist and had no migration rule (dropped from the progress). */
+    dropped: string[];
+    /** The active step could not be kept: where the player continues instead. */
+    resumedAt?: string;
+}
+/** What one `evaluate()` did. */
+export type DyFM_OnboardingEvaluation_Type = 'inactive' | 'waiting' | 'advanced' | 'regressed' | 'timed-out';
+export interface DyFM_OnboardingEvent {
+    type: 'step-entered' | 'step-completed' | 'step-skipped' | 'step-timed-out' | 'regressed' | 'chapter-completed' | 'completed' | 'skipped' | 'restarted' | 'command-failed';
+    stepId?: string;
+    chapterId?: string;
+    /** `regressed`: the step that lost its state. */
+    fromStepId?: string;
+    /** `step-entered` after `importState` + `resume`. */
+    resumed?: boolean;
+    /** `command-failed`. */
+    error?: unknown;
+}
+/** Where the player is — everything a UI needs to render "Chapter 2 · step 3 of 5". */
+export interface DyFM_OnboardingPosition {
+    chapterId: string;
+    chapterIndex: number;
+    chapterCount: number;
+    step: DyFM_OnboardingStep_Definition;
+    stepIndexInChapter: number;
+    chapterStepCount: number;
+    /** Completed + skipped steps over all steps of the catalog. */
+    doneCount: number;
+    totalCount: number;
+    /** True when the step has no completion predicate — the UI shows a "Next" button. */
+    manual: boolean;
+}
+export interface DyFM_OnboardingFinding {
+    code: string;
+    path: string;
+    message: string;
+}
+//# sourceMappingURL=guided-onboarding.interface.d.ts.map

package/build/_modules/game/_models/guided-onboarding.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guided-onboarding.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/guided-onboarding.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wHAAwH;AACxH,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,uHAAuH;IACvH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,qHAAqH;IACrH,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,mGAAmG;IACnG,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4GAA4G;IAC5G,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,+GAA+G;IAC/G,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,8BAA8B,EAAE,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,QAAQ,EAAE,iCAAiC,EAAE,CAAC;IAC9C,qGAAqG;IACrG,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B,CAAC,QAAQ;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;CAC5E;AAED,sCAAsC;AACtC,MAAM,MAAM,0BAA0B,GAAG,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5F,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,MAAM,EAAE,0BAA0B,CAAC;IACnC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,4EAA4E;AAC5E,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,sFAAsF;IACtF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iCAAiC;AACjC,MAAM,MAAM,8BAA8B,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;AAE7G,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,GAAG,WAAW,GAAG,mBAAmB,GAC3G,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,uFAAuF;AACvF,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,8BAA8B,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB"}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=guided-onboarding.interface.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guided-onboarding.interface.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/guided-onboarding.interface.ts"],"names":[],"mappings":""}

package/build/_modules/game/index.d.ts

@@ -20,6 +20,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';
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
 export * from './_collections/game-save.util';

package/build/_modules/game/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAG9D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAG1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}

package/build/_modules/game/index.js

@@ -25,6 +25,8 @@ tslib_1.__exportStar(require("./_models/viewport.interface"), exports);
 tslib_1.__exportStar(require("./_models/viewport.control-model"), exports);
 tslib_1.__exportStar(require("./_models/input-action.interface"), exports);
 tslib_1.__exportStar(require("./_models/input-action-registry.control-model"), exports);
+tslib_1.__exportStar(require("./_models/guided-onboarding.interface"), exports);
+tslib_1.__exportStar(require("./_models/guided-onboarding.control-model"), exports);
 // COLLECTIONS
 tslib_1.__exportStar(require("./_collections/audio-mixer.util"), exports);
 tslib_1.__exportStar(require("./_collections/audio-scale.util"), exports);

package/build/_modules/game/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,2EAAiD;AACjD,wFAA8D;AAE9D,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,2EAAiD;AACjD,wFAA8D;AAC9D,gFAAsD;AACtD,oFAA0D;AAE1D,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}

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/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.102",
+  "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",