@krtuworks/sdk 0.0.0-stage → 1.0.1

package/dist/presence.js

@@ -0,0 +1,97 @@
+/**
+ * The rich presence states the owner declared and whether the player shows their presence (the server
+ * `/v1/me/presence-states`, `/v1/me/presence-visibility`), kept per player in the store and revalidated
+ * with the ETag. A browser has no platform presence to write, so a call that passes every rule ends in
+ * `no_platform`.
+ */
+export class Presence {
+    clientId;
+    store;
+    api;
+    subject;
+    cached = null;
+    constructor(clientId, store, api, subject) {
+        this.clientId = clientId;
+        this.store = store;
+        this.api = api;
+        this.subject = subject;
+    }
+    key(subject) {
+        return `krtu:${this.clientId}:presence:${subject}`;
+    }
+    /** Reads the current player's kept copy. */
+    async load() {
+        const subject = this.subject();
+        this.cached = subject ? { subject, value: (await this.store.get(this.key(subject))) ?? { etag: null, states: null, visible: null } } : null;
+    }
+    /** The player changed or signed out: nothing of the old player stays in memory. */
+    forget() {
+        this.cached = null;
+    }
+    current() {
+        return this.cached && this.cached.subject === this.subject() ? this.cached.value : null;
+    }
+    states() {
+        return this.current()?.states ?? null;
+    }
+    visible() {
+        return this.current()?.visible ?? null;
+    }
+    async keep(subject, value) {
+        this.cached = { subject, value };
+        await this.store.set(this.key(subject), value);
+    }
+    /** Asks the server for the states and the choice (If-None-Match: a 304 keeps the kept copy). */
+    async refresh() {
+        const subject = this.subject();
+        if (!subject)
+            return;
+        if (this.cached?.subject !== subject)
+            await this.load();
+        const held = this.current();
+        const answer = await this.api.player('/v1/me/presence-states', {
+            headers: held?.etag ? { 'if-none-match': held.etag } : {},
+            accept: [304],
+        });
+        if (answer.status === 304 || !held)
+            return;
+        await this.keep(subject, {
+            etag: answer.headers.get('etag'),
+            states: answer.json?.states ?? [],
+            visible: answer.json?.visible === true,
+        });
+    }
+    async setVisible(visible) {
+        const subject = this.subject();
+        const answer = await this.api.player('/v1/me/presence-visibility', { method: 'PUT', json: { visible } });
+        if (!subject)
+            return;
+        if (this.cached?.subject !== subject)
+            await this.load();
+        await this.keep(subject, { ...(this.current() ?? { etag: null, states: null }), visible: answer.json?.visible === true });
+    }
+    /**
+     * The first rule a call breaks, or null when it passes them all: the state is declared and every
+     * parameter it declares has a non-empty value (the caller's, else the built-in one). Undeclared extras
+     * are dropped with a log line.
+     */
+    check(key, given, builtins, log) {
+        if (this.visible() === false)
+            return 'hidden';
+        const states = this.states();
+        if (!states)
+            return 'states_unknown';
+        const state = states.find((s) => s.key === key);
+        if (!state)
+            return 'unknown_state';
+        const extra = Object.keys(given).filter((name) => !state.params.includes(name));
+        if (extra.length)
+            log(`presence ${key}: dropped undeclared params ${extra.join(', ')}`);
+        for (const name of state.params) {
+            const value = Object.prototype.hasOwnProperty.call(given, name) ? String(given[name]) : (builtins[name]?.() ?? '');
+            if (value === '')
+                return 'param_missing';
+        }
+        return null;
+    }
+}

package/dist/progress.d.ts

@@ -0,0 +1,108 @@
+import type { Api } from './api.js';
+import type { ResolvedOptions } from './config.js';
+import type { KrtuStore } from './store.js';
+export type StatKind = 'SUM' | 'MAX' | 'MIN' | 'LATEST';
+export type SortOrder = 'ASC' | 'DESC';
+export type UploadMethod = 'KEEP_BEST' | 'FORCE_UPDATE';
+/** What folding a leaderboard's waiting scores needs: which score is better and what a new one does to the stored one. */
+export interface BoardRule {
+    sortOrder: SortOrder;
+    uploadMethod: UploadMethod;
+}
+/** A value the game reported and not yet frozen into an op: an increase, or a value to keep. */
+interface Contribution {
+    op: 'add' | 'set';
+    value: number;
+}
+/** A score the game submitted and not yet frozen into an op. */
+interface ScoreContribution {
+    value: number;
+    details?: string;
+}
+export interface ProgressRefusal {
+    type: 'stat' | 'unlock' | 'score';
+    key: string;
+    code: string;
+}
+/**
+ * Folds what waits for one stat into as few values as its kind allows: SUM adds, MAX
+ * keeps the largest, MIN the smallest, LATEST the last. A stat whose kind is not known yet only folds
+ * its runs of increases; values to keep wait one by one, in order.
+ */
+export declare function foldContributions(pending: Contribution[], kind: StatKind | undefined): Contribution[];
+/**
+ * Folds what waits for one leaderboard into as few scores as its upload method allows: KEEP_BEST keeps
+ * the better one (an equal score keeps the earlier, as the server keeps the stored one), FORCE_UPDATE
+ * the last. A board whose rule is not known yet folds nothing: every score waits, in order.
+ */
+export declare function foldScores(pending: ScoreContribution[], rule: BoardRule | undefined): ScoreContribution[];
+export interface ProgressContext {
+    opts: ResolvedOptions;
+    store: KrtuStore;
+    api: Api;
+    subject: () => string | null;
+}
+/**
+ * Stats and achievements: progress is never lost and never
+ * counted twice. Every report is written to the store at once; per stat at most one op is in flight,
+ * frozen with its opId until it has an answer (sent again unchanged after a failure), and the rest
+ * waits folded behind it. Ops have no age limit and do not depend on the statistics choice.
+ */
+export declare class ProgressQueue {
+    private readonly ctx;
+    private kinds;
+    private kindsLoaded;
+    private boards;
+    private notBefore;
+    private backoffMs;
+    readonly refusals: ProgressRefusal[];
+    constructor(ctx: ProgressContext);
+    private key;
+    private get kindsKey();
+    private get boardsKey();
+    private load;
+    private save;
+    /** Loads what the server taught: the stats' kinds and the leaderboards' rules. */
+    private loadKinds;
+    /** Learns the stats' kinds (from `GET /v1/me/progress`): what waits folds tighter from now on. */
+    learnKinds(stats: Array<{
+        key: string;
+        kind: StatKind;
+    }>): Promise<void>;
+    /**
+     * Learns the leaderboards' rules (from `GET /v1/me/leaderboards`): what waits folds tighter from now
+     * on. A board the server answers without its upload method stays unknown, so nothing folds for it.
+     */
+    learnBoards(boards: Array<{
+        key: string;
+        sortOrder: SortOrder;
+        uploadMethod?: UploadMethod;
+    }>): Promise<void>;
+    report(type: 'add' | 'set', key: string, value: number): Promise<void>;
+    submitScore(key: string, value: number, details?: Uint8Array): Promise<void>;
+    unlock(key: string): Promise<void>;
+    /** How many ops wait for `owner` (in flight or not yet frozen). */
+    waiting(owner: string): Promise<number>;
+    /**
+     * Moves `from`'s waiting progress to `to` (the first player after anon play, or a merge target).
+     * Frozen ops keep their ids: one the server already applied under the old account answers
+     * `duplicate` under the new one (the merge moved its receipt), so nothing counts twice.
+     */
+    move(from: string, to: string): Promise<void>;
+    /** Freezes the next op of every stat and achievement with none in flight; returns every op to send. */
+    private freeze;
+    /**
+     * Sends the signed-in player's ops until nothing waits or a send fails. Answers per op: applied and
+     * duplicate end the op; a refusal for good ends it too (and everything waiting for a stat,
+     * achievement or leaderboard that no longer exists); anything else keeps it frozen for the next flush.
+     * A score refused `module_disabled` stays frozen too: the owner may switch the module on again.
+     */
+    flush(): Promise<{
+        applied: number;
+        stoppedBy: string | null;
+        values: Record<string, number>;
+    }>;
+    private backoff;
+    resetBackoff(): void;
+}
+export {};

package/dist/progress.js

@@ -0,0 +1,347 @@
+import { KrtuworksError, isKrtuworksError } from './errors.js';
+import { base64, uuidV7 } from './ids.js';
+import { withLock } from './locks.js';
+const KEY = /^[a-z][a-z0-9_.]{0,63}$/;
+const MAX_VALUE = 1e15;
+const MAX_OPS = 100;
+/** Refusals that say the stat or achievement itself is gone: what waits for it goes too. */
+const KEY_GONE = new Set(['unknown_stat', 'stat_retired', 'unknown_achievement', 'achievement_retired']);
+/** Refusals that say the leaderboard itself is gone: what waits for it goes too. */
+const BOARD_GONE = new Set(['unknown_leaderboard', 'leaderboard_retired']);
+const MAX_DETAILS = 64;
+const empty = () => ({ stats: {}, unlocks: {}, scores: {} });
+/**
+ * Folds what waits for one stat into as few values as its kind allows: SUM adds, MAX
+ * keeps the largest, MIN the smallest, LATEST the last. A stat whose kind is not known yet only folds
+ * its runs of increases; values to keep wait one by one, in order.
+ */
+export function foldContributions(pending, kind) {
+    const out = [];
+    for (const c of pending) {
+        const last = out[out.length - 1];
+        if (!last) {
+            out.push({ ...c });
+            continue;
+        }
+        if (kind === 'SUM' || (kind === undefined && c.op === 'add' && last.op === 'add')) {
+            const sum = last.value + c.value;
+            if (Math.abs(sum) < MAX_VALUE) {
+                last.value = sum;
+                last.op = 'add';
+                continue;
+            }
+        }
+        else if (kind === 'MAX') {
+            last.value = Math.max(last.value, c.value);
+            continue;
+        }
+        else if (kind === 'MIN') {
+            last.value = Math.min(last.value, c.value);
+            continue;
+        }
+        else if (kind === 'LATEST') {
+            last.value = c.value;
+            last.op = c.op;
+            continue;
+        }
+        out.push({ ...c });
+    }
+    return out;
+}
+/**
+ * Folds what waits for one leaderboard into as few scores as its upload method allows: KEEP_BEST keeps
+ * the better one (an equal score keeps the earlier, as the server keeps the stored one), FORCE_UPDATE
+ * the last. A board whose rule is not known yet folds nothing: every score waits, in order.
+ */
+export function foldScores(pending, rule) {
+    if (!rule)
+        return pending.map((c) => ({ ...c }));
+    if (rule.uploadMethod === 'FORCE_UPDATE')
+        return pending.length ? [{ ...pending[pending.length - 1] }] : [];
+    let best;
+    for (const c of pending) {
+        if (!best || (rule.sortOrder === 'DESC' ? c.value > best.value : c.value < best.value))
+            best = c;
+    }
+    return best ? [{ ...best }] : [];
+}
+function findInFlight(state, opId) {
+    const groups = [['stat', state.stats], ['unlock', state.unlocks], ['score', state.scores]];
+    for (const [type, entries] of groups) {
+        for (const [key, entry] of Object.entries(entries))
+            if (entry.inFlight.some((op) => op.opId === opId))
+                return { type, key, entry };
+    }
+    return null;
+}
+/**
+ * Stats and achievements: progress is never lost and never
+ * counted twice. Every report is written to the store at once; per stat at most one op is in flight,
+ * frozen with its opId until it has an answer (sent again unchanged after a failure), and the rest
+ * waits folded behind it. Ops have no age limit and do not depend on the statistics choice.
+ */
+export class ProgressQueue {
+    ctx;
+    kinds = {};
+    kindsLoaded = false;
+    boards = {};
+    notBefore = 0;
+    backoffMs = 0;
+    refusals = [];
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    key(owner) {
+        return `krtu:${this.ctx.opts.clientId}:progress:${owner}`;
+    }
+    get kindsKey() {
+        return `krtu:${this.ctx.opts.clientId}:statKinds`;
+    }
+    get boardsKey() {
+        return `krtu:${this.ctx.opts.clientId}:boardRules`;
+    }
+    async load(owner) {
+        const state = (await this.ctx.store.get(this.key(owner))) ?? empty();
+        state.scores ??= {};
+        return state;
+    }
+    async save(owner, state) {
+        for (const [key, s] of Object.entries(state.stats))
+            if (!s.inFlight.length && !s.pending.length)
+                delete state.stats[key];
+        for (const [key, u] of Object.entries(state.unlocks))
+            if (!u.inFlight.length && !u.pending)
+                delete state.unlocks[key];
+        for (const [key, b] of Object.entries(state.scores))
+            if (!b.inFlight.length && !b.pending.length)
+                delete state.scores[key];
+        if (Object.keys(state.stats).length || Object.keys(state.unlocks).length || Object.keys(state.scores).length)
+            await this.ctx.store.set(this.key(owner), state);
+        else
+            await this.ctx.store.delete(this.key(owner));
+    }
+    /** Loads what the server taught: the stats' kinds and the leaderboards' rules. */
+    async loadKinds() {
+        if (this.kindsLoaded)
+            return;
+        this.kinds = (await this.ctx.store.get(this.kindsKey)) ?? {};
+        this.boards = (await this.ctx.store.get(this.boardsKey)) ?? {};
+        this.kindsLoaded = true;
+    }
+    /** Learns the stats' kinds (from `GET /v1/me/progress`): what waits folds tighter from now on. */
+    async learnKinds(stats) {
+        await this.loadKinds();
+        for (const s of stats)
+            this.kinds[s.key] = s.kind;
+        await this.ctx.store.set(this.kindsKey, this.kinds);
+    }
+    /**
+     * Learns the leaderboards' rules (from `GET /v1/me/leaderboards`): what waits folds tighter from now
+     * on. A board the server answers without its upload method stays unknown, so nothing folds for it.
+     */
+    async learnBoards(boards) {
+        await this.loadKinds();
+        for (const b of boards)
+            if (b.uploadMethod)
+                this.boards[b.key] = { sortOrder: b.sortOrder, uploadMethod: b.uploadMethod };
+        await this.ctx.store.set(this.boardsKey, this.boards);
+    }
+    async report(type, key, value) {
+        if (!KEY.test(key))
+            throw new TypeError(`"${key}" is not a stat key (lowercase letters, digits, _ and ., at most 64)`);
+        if (!Number.isFinite(value) || Math.abs(value) >= MAX_VALUE)
+            throw new TypeError('a stat value is a finite number below 10^15');
+        await this.loadKinds();
+        const owner = this.ctx.subject() ?? 'anon';
+        await withLock(this.key(owner), async () => {
+            const state = await this.load(owner);
+            const entry = (state.stats[key] ??= { inFlight: [], pending: [] });
+            entry.pending = foldContributions([...entry.pending, { op: type, value }], this.kinds[key]);
+            await this.save(owner, state);
+        });
+    }
+    async submitScore(key, value, details) {
+        if (!KEY.test(key))
+            throw new TypeError(`"${key}" is not a leaderboard key (lowercase letters, digits, _ and ., at most 64)`);
+        if (!Number.isInteger(value) || Math.abs(value) >= MAX_VALUE)
+            throw new TypeError('a score is a whole number below 10^15');
+        if (details !== undefined && (!(details instanceof Uint8Array) || details.length < 1 || details.length > MAX_DETAILS)) {
+            throw new TypeError(`score details are 1-${MAX_DETAILS} bytes`);
+        }
+        await this.loadKinds();
+        const owner = this.ctx.subject() ?? 'anon';
+        await withLock(this.key(owner), async () => {
+            const state = await this.load(owner);
+            const entry = (state.scores[key] ??= { inFlight: [], pending: [] });
+            entry.pending = foldScores([...entry.pending, { value, ...(details ? { details: base64(details) } : {}) }], this.boards[key]);
+            await this.save(owner, state);
+        });
+    }
+    async unlock(key) {
+        if (!KEY.test(key))
+            throw new TypeError(`"${key}" is not an achievement key`);
+        const owner = this.ctx.subject() ?? 'anon';
+        await withLock(this.key(owner), async () => {
+            const state = await this.load(owner);
+            const entry = (state.unlocks[key] ??= { inFlight: [], pending: false });
+            if (!entry.inFlight.length)
+                entry.pending = true;
+            await this.save(owner, state);
+        });
+    }
+    /** How many ops wait for `owner` (in flight or not yet frozen). */
+    async waiting(owner) {
+        const state = await this.load(owner);
+        return (Object.values(state.stats).reduce((n, s) => n + s.inFlight.length + s.pending.length, 0) +
+            Object.values(state.unlocks).reduce((n, u) => n + u.inFlight.length + (u.pending ? 1 : 0), 0) +
+            Object.values(state.scores).reduce((n, b) => n + b.inFlight.length + b.pending.length, 0));
+    }
+    /**
+     * Moves `from`'s waiting progress to `to` (the first player after anon play, or a merge target).
+     * Frozen ops keep their ids: one the server already applied under the old account answers
+     * `duplicate` under the new one (the merge moved its receipt), so nothing counts twice.
+     */
+    async move(from, to) {
+        await this.loadKinds();
+        const [first, second] = from < to ? [from, to] : [to, from];
+        await withLock(this.key(first), () => withLock(this.key(second), async () => {
+            const source = await this.load(from);
+            const target = await this.load(to);
+            for (const [key, s] of Object.entries(source.stats)) {
+                const t = (target.stats[key] ??= { inFlight: [], pending: [] });
+                t.inFlight.push(...s.inFlight);
+                t.pending = foldContributions([...s.pending, ...t.pending], this.kinds[key]);
+            }
+            for (const [key, u] of Object.entries(source.unlocks)) {
+                const t = (target.unlocks[key] ??= { inFlight: [], pending: false });
+                t.inFlight.push(...u.inFlight);
+                t.pending = t.pending || (u.pending && !t.inFlight.length);
+            }
+            for (const [key, b] of Object.entries(source.scores)) {
+                const t = (target.scores[key] ??= { inFlight: [], pending: [] });
+                t.inFlight.push(...b.inFlight);
+                t.pending = foldScores([...b.pending, ...t.pending], this.boards[key]);
+            }
+            await this.save(to, target);
+            await this.ctx.store.delete(this.key(from));
+        }));
+    }
+    /** Freezes the next op of every stat and achievement with none in flight; returns every op to send. */
+    freeze(state) {
+        const ops = [];
+        for (const [key, s] of Object.entries(state.stats)) {
+            if (!s.inFlight.length && s.pending.length) {
+                s.pending = foldContributions(s.pending, this.kinds[key]);
+                const next = s.pending.shift();
+                s.inFlight.push({ opId: uuidV7(), type: 'stat', key, value: next.value });
+            }
+            ops.push(...s.inFlight);
+        }
+        for (const [key, u] of Object.entries(state.unlocks)) {
+            if (!u.inFlight.length && u.pending) {
+                u.inFlight.push({ opId: uuidV7(), type: 'unlock', key });
+                u.pending = false;
+            }
+            ops.push(...u.inFlight);
+        }
+        for (const [key, b] of Object.entries(state.scores)) {
+            if (!b.inFlight.length && b.pending.length) {
+                b.pending = foldScores(b.pending, this.boards[key]);
+                const next = b.pending.shift();
+                b.inFlight.push({ opId: uuidV7(), type: 'score', key, value: next.value, ...(next.details ? { details: next.details } : {}) });
+            }
+            ops.push(...b.inFlight);
+        }
+        return ops.slice(0, MAX_OPS);
+    }
+    /**
+     * Sends the signed-in player's ops until nothing waits or a send fails. Answers per op: applied and
+     * duplicate end the op; a refusal for good ends it too (and everything waiting for a stat,
+     * achievement or leaderboard that no longer exists); anything else keeps it frozen for the next flush.
+     * A score refused `module_disabled` stays frozen too: the owner may switch the module on again.
+     */
+    async flush() {
+        const owner = this.ctx.subject();
+        const out = { applied: 0, stoppedBy: null, values: {} };
+        if (!owner)
+            return { ...out, stoppedBy: 'signed_out' };
+        if (Date.now() < this.notBefore)
+            return { ...out, stoppedBy: 'waiting' };
+        await this.loadKinds();
+        for (let round = 0; round < 50; round += 1) {
+            const ops = await withLock(this.key(owner), async () => {
+                const state = await this.load(owner);
+                const frozen = this.freeze(state);
+                await this.save(owner, state);
+                return frozen;
+            });
+            if (!ops.length)
+                return out;
+            let answer;
+            try {
+                answer = await this.ctx.api.player('/v1/me/progress', {
+                    method: 'POST',
+                    json: { platform: this.ctx.opts.platform, build: this.ctx.opts.build, ops },
+                });
+            }
+            catch (err) {
+                if (!isKrtuworksError(err))
+                    throw err;
+                this.backoff(err);
+                out.stoppedBy = err.code;
+                return out;
+            }
+            this.backoffMs = 0;
+            const results = answer.json?.results ?? [];
+            const settled = await withLock(this.key(owner), async () => {
+                const state = await this.load(owner);
+                let count = 0;
+                for (const r of results) {
+                    // A refusal carries the key but not the type, and op_id_reused neither: the op is found by its id.
+                    const hit = findInFlight(state, r.opId);
+                    if (!hit)
+                        continue;
+                    const { type, key, entry } = hit;
+                    if (r.status === 'rejected' && type === 'score' && r.code === 'module_disabled') {
+                        out.stoppedBy = 'module_disabled';
+                        continue;
+                    }
+                    entry.inFlight = entry.inFlight.filter((op) => op.opId !== r.opId);
+                    count += 1;
+                    if (r.status === 'rejected') {
+                        this.refusals.push({ type, key, code: r.code ?? 'rejected' });
+                        if (type === 'score' ? BOARD_GONE.has(r.code ?? '') : KEY_GONE.has(r.code ?? '')) {
+                            if (type === 'unlock')
+                                delete state.unlocks[key];
+                            else if (type === 'score')
+                                delete state.scores[key];
+                            else
+                                delete state.stats[key];
+                        }
+                    }
+                    else {
+                        out.applied += 1;
+                        if (type === 'stat' && typeof r.value === 'number')
+                            out.values[key] = r.value;
+                    }
+                }
+                await this.save(owner, state);
+                return count;
+            });
+            if (!settled) {
+                // An answer that settles none of the ops sent: keep them frozen and try again later.
+                out.stoppedBy ??= 'unanswered';
+                return out;
+            }
+        }
+        return out;
+    }
+    backoff(err) {
+        this.backoffMs = Math.min(300_000, Math.max(5_000, this.backoffMs * 2));
+        this.notBefore = Date.now() + (err.retryAfter !== null ? err.retryAfter * 1000 : this.backoffMs);
+    }
+    resetBackoff() {
+        this.notBefore = 0;
+        this.backoffMs = 0;
+    }
+}

package/dist/progression.d.ts

@@ -0,0 +1,39 @@
+import type { FamilyData } from './families.js';
+import type { KrtuStore } from './store.js';
+export interface LevelRef {
+    level: string;
+    world?: string;
+    part?: string;
+}
+type ProgressionEvent = FamilyData['progression'];
+/**
+ * Levels as the progression family tells them: the game says start, complete, fail,
+ * quit, checkpoint and restart; the SDK adds the attempt number (per level and player, kept across
+ * launches), the attempt's wall and active seconds and its deaths. An attempt still open when the app
+ * goes away is told as a quit.
+ */
+export declare class ProgressionTracker {
+    private readonly store;
+    private readonly clientId;
+    private readonly owner;
+    private readonly activeSeconds;
+    private readonly emit;
+    private current;
+    constructor(store: KrtuStore, clientId: string, owner: () => string, activeSeconds: () => number, emit: (data: ProgressionEvent) => void);
+    private key;
+    private ref;
+    private times;
+    private place;
+    start(level: LevelRef): Promise<void>;
+    /** Ends the attempt in play (complete, fail or quit). */
+    finish(action: 'complete' | 'fail' | 'quit', extra?: {
+        score?: number;
+    }): void;
+    checkpoint(name: string): void;
+    /** The level starts over: the attempt in play ends as a restart and a new one begins. */
+    restart(): Promise<void>;
+    /** A death counts toward the attempt in play. */
+    noteDeath(): LevelRef | null;
+    get inPlay(): LevelRef | null;
+}
+export {};

package/dist/progression.js

@@ -0,0 +1,81 @@
+/**
+ * Levels as the progression family tells them: the game says start, complete, fail,
+ * quit, checkpoint and restart; the SDK adds the attempt number (per level and player, kept across
+ * launches), the attempt's wall and active seconds and its deaths. An attempt still open when the app
+ * goes away is told as a quit.
+ */
+export class ProgressionTracker {
+    store;
+    clientId;
+    owner;
+    activeSeconds;
+    emit;
+    current = null;
+    constructor(store, clientId, owner, activeSeconds, emit) {
+        this.store = store;
+        this.clientId = clientId;
+        this.owner = owner;
+        this.activeSeconds = activeSeconds;
+        this.emit = emit;
+    }
+    key() {
+        return `krtu:${this.clientId}:levels:${this.owner()}`;
+    }
+    ref(level) {
+        return [level.world ?? '', level.level, level.part ?? ''].join('\u0000');
+    }
+    times(a) {
+        return {
+            attempt: a.attempt,
+            seconds: Math.round((Date.now() - a.startedAt) / 100) / 10,
+            activeSeconds: Math.max(0, this.activeSeconds() - a.activeAtStart),
+            deaths: a.deaths,
+        };
+    }
+    place(a) {
+        return { level: a.level, ...(a.world ? { world: a.world } : {}), ...(a.part ? { part: a.part } : {}) };
+    }
+    async start(level) {
+        if (this.current)
+            this.finish('quit');
+        const counts = (await this.store.get(this.key())) ?? {};
+        const ref = this.ref(level);
+        counts[ref] = (counts[ref] ?? 0) + 1;
+        await this.store.set(this.key(), counts);
+        this.current = { ...level, attempt: counts[ref], startedAt: Date.now(), activeAtStart: this.activeSeconds(), deaths: 0 };
+        this.emit({ action: 'start', ...this.place(level), attempt: this.current.attempt });
+    }
+    /** Ends the attempt in play (complete, fail or quit). */
+    finish(action, extra = {}) {
+        const a = this.current;
+        if (!a)
+            return;
+        this.current = null;
+        this.emit({ action, ...this.place(a), ...this.times(a), ...(extra.score !== undefined ? { score: extra.score } : {}) });
+    }
+    checkpoint(name) {
+        const a = this.current;
+        if (!a)
+            return;
+        this.emit({ action: 'checkpoint', ...this.place(a), checkpoint: name, ...this.times(a) });
+    }
+    /** The level starts over: the attempt in play ends as a restart and a new one begins. */
+    async restart() {
+        const a = this.current;
+        if (!a)
+            return;
+        this.current = null;
+        this.emit({ action: 'restart', ...this.place(a), ...this.times(a) });
+        await this.start(a);
+    }
+    /** A death counts toward the attempt in play. */
+    noteDeath() {
+        if (!this.current)
+            return null;
+        this.current.deaths += 1;
+        return { level: this.current.level, world: this.current.world, part: this.current.part };
+    }
+    get inPlay() {
+        return this.current ? { level: this.current.level, world: this.current.world, part: this.current.part } : null;
+    }
+}