@crowdedkingdoms/crowdyjs 8.7.0 → 8.9.0

package/dist/kit/quests.js

@@ -106,6 +106,78 @@ export class QuestsKit {
         const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
         return Promise.all(mine.map((c) => this.state(c.containerId)));
     }
+    // -- FTUE / tutorial step sequencing (Wave 2) -----------------------------
+    /**
+     * STUDIO (admin) — define an ordered tutorial chain as quest defs. Steps
+     * are plain quests whose `questId` encodes the chain + index
+     * (`"<chain>:<i>"`), so no new server surface is involved: the sequencing
+     * is a read-side convention enforced by {@link tutorial} /
+     * {@link acceptNextTutorialStep} (a step is `locked` until every earlier
+     * step completes).
+     */
+    async defineTutorial(input) {
+        const chain = input.chain ?? 'ftue';
+        const created = [];
+        for (const [index, step] of input.steps.entries()) {
+            created.push(await this.defineQuest({
+                questId: `${chain}:${index}`,
+                displayName: step.displayName,
+                targetCount: step.targetCount ?? 1,
+                rewardItemId: step.rewardItemId,
+                rewardQty: step.rewardQty,
+                rewardGold: step.rewardGold,
+            }));
+        }
+        return created;
+    }
+    /** One tutorial step joined with the player's progress. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- documented shape
+    /**
+     * A player's view of a tutorial chain: steps in order, each `locked`
+     * (an earlier step is incomplete), `active` (the first incomplete step),
+     * or `complete`. The client shows/drives only the `active` step; the
+     * trusted advance authority is unchanged (players still cannot complete
+     * their own quests).
+     */
+    async tutorial(ownerUserId, chain = 'ftue') {
+        const prefix = `${chain}:`;
+        const defs = (await this.catalog())
+            .filter((def) => def.questId.startsWith(prefix))
+            .map((def) => ({ def, stepIndex: Number(def.questId.slice(prefix.length)) }))
+            .filter(({ stepIndex }) => Number.isFinite(stepIndex))
+            .sort((a, b) => a.stepIndex - b.stepIndex);
+        const progressRows = await this.mine(ownerUserId);
+        let blocked = false;
+        return defs.map(({ def, stepIndex }) => {
+            const progress = progressRows.find((p) => p.questId === def.questId) ?? null;
+            const complete = progress?.completed === true;
+            const status = complete
+                ? 'complete'
+                : blocked
+                    ? 'locked'
+                    : 'active';
+            if (!complete)
+                blocked = true;
+            return { stepIndex, def, progress, status };
+        });
+    }
+    /**
+     * Ensure the player's ACTIVE tutorial step has a progress row (accepting
+     * it when missing) and return the step. Returns null when the chain is
+     * complete. Calling this for a locked step is impossible by construction —
+     * it always targets the first incomplete step.
+     */
+    async acceptNextTutorialStep(ownerUserId, chain = 'ftue', options = {}) {
+        const steps = await this.tutorial(ownerUserId, chain);
+        const active = steps.find((step) => step.status === 'active');
+        if (!active)
+            return null;
+        if (active.progress)
+            return active;
+        await this.accept(ownerUserId, active.def.containerId, options);
+        const refreshed = await this.tutorial(ownerUserId, chain);
+        return refreshed.find((step) => step.stepIndex === active.stepIndex) ?? null;
+    }
     /** Read one progress row. */
     async state(progressId) {
         const container = await this.gameModel.container({

package/dist/kit/racing.d.ts

@@ -0,0 +1,85 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+import { type RaceTimingEvent } from './wire.js';
+/** Options for {@link RacingKit}. */
+export interface RacingKitOptions {
+    /** The racing engine module name. Defaults to `'racing'`. */
+    moduleName?: string;
+    /** The possession (ball) engine module name. Defaults to `'possession'`. */
+    possessionModuleName?: string;
+    /** The course container type. Defaults to `'Course'`. */
+    courseTypeName?: string;
+}
+/** Your live run as the engine reports it. */
+export interface KitRaceRun {
+    courseId: string;
+    started: boolean;
+    lap: number;
+    nextGate: number;
+    splitsMs: number[];
+    bestLapMs: number;
+    finished: boolean;
+    totalMs: number;
+}
+/**
+ * Runtime helpers for the racing engine (Wave 3, G16) and its possession
+ * sub-template (G17 sports-lite): server-timed gates/laps from the pose
+ * stream (type-97 events), course records with ghost replays on the actor
+ * lane (suffix `ghost:<courseId>`, FLAG_RESERVED3), and the authoritative
+ * ball (claim/steal/pass/shoot; lane suffix `ball`).
+ *
+ * Obtained via `client.kit(appId).racing`.
+ */
+export declare class RacingKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly engines;
+    private readonly moduleName;
+    private readonly possessionModuleName;
+    private readonly courseTypeName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, engines: EngineDetector, options?: RacingKitOptions);
+    /** Is the racing engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /** Is the possession (ball) engine deployed + enabled? */
+    possessionAvailable(): Promise<boolean>;
+    /** STUDIO (admin) — create a course (`gates` = [[x, z, radius], ...]). */
+    defineCourse(input: {
+        courseId: string;
+        gates: Array<[number, number, number]>;
+        laps?: number;
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Enter a course: your next pose through gate 0 starts the clock. */
+    enter(courseId: string): Promise<Record<string, unknown>>;
+    /** Your live run (splits, lap, next gate). */
+    raceStatus(): Promise<KitRaceRun>;
+    /** The course record (holder, time, ghost length). */
+    best(courseId: string): Promise<Record<string, unknown>>;
+    /** Replay the course-record ghost onto the actor lane. */
+    ghostPlay(courseId: string): Promise<Record<string, unknown>>;
+    /** Parse a type-97 race-timing server event. */
+    parseRaceTiming(bytes: Uint8Array): RaceTimingEvent | null;
+    /** Join the ball match (teams fill by join order). */
+    joinMatch(): Promise<Record<string, unknown>>;
+    /** Claim the free ball (or steal after the protection window). */
+    claim(): Promise<Record<string, unknown>>;
+    /** Pass along a direction (holder only). */
+    pass(dirX: number, dirZ: number): Promise<Record<string, unknown>>;
+    /** Shoot at the opposing goal (holder only; the server aims). */
+    shoot(): Promise<Record<string, unknown>>;
+    /** The live ball match (teams, ball, standings, summary). */
+    matchState(): Promise<Record<string, unknown>>;
+    private invoke;
+}
+//# sourceMappingURL=racing.d.ts.map

package/dist/kit/racing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"racing.d.ts","sourceRoot":"","sources":["../../src/kit/racing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvE,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAMlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAGrB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,gBAAqB;IAOhC,oEAAoE;IACpE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC,0DAA0D;IAC1D,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAIvC,0EAA0E;IACpE,YAAY,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IAaD,sEAAsE;IAChE,KAAK,CAAC,QAAQ,EAAE,MAAM;IAI5B,8CAA8C;IACxC,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;IAcvC,sDAAsD;IAChD,IAAI,CAAC,QAAQ,EAAE,MAAM;IAI3B,0DAA0D;IACpD,SAAS,CAAC,QAAQ,EAAE,MAAM;IAIhC,gDAAgD;IAChD,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,GAAG,IAAI;IAM1D,sDAAsD;IAChD,SAAS;IAIf,kEAAkE;IAC5D,KAAK;IAIX,4CAA4C;IACtC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIrC,iEAAiE;IAC3D,KAAK;IAIX,6DAA6D;IACvD,UAAU;YAIF,MAAM;CAOrB"}

package/dist/kit/racing.js

@@ -0,0 +1,99 @@
+import { parseRaceTimingEvent } from './wire.js';
+/**
+ * Runtime helpers for the racing engine (Wave 3, G16) and its possession
+ * sub-template (G17 sports-lite): server-timed gates/laps from the pose
+ * stream (type-97 events), course records with ghost replays on the actor
+ * lane (suffix `ghost:<courseId>`, FLAG_RESERVED3), and the authoritative
+ * ball (claim/steal/pass/shoot; lane suffix `ball`).
+ *
+ * Obtained via `client.kit(appId).racing`.
+ */
+export class RacingKit {
+    constructor(appId, gameModel, engines, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.engines = engines;
+        this.moduleName = options.moduleName ?? 'racing';
+        this.possessionModuleName = options.possessionModuleName ?? 'possession';
+        this.courseTypeName = options.courseTypeName ?? 'Course';
+    }
+    /** Is the racing engine deployed + enabled (cached per session)? */
+    engineAvailable() {
+        return this.engines.has(this.moduleName);
+    }
+    /** Is the possession (ball) engine deployed + enabled? */
+    possessionAvailable() {
+        return this.engines.has(this.possessionModuleName);
+    }
+    /** STUDIO (admin) — create a course (`gates` = [[x, z, radius], ...]). */
+    async defineCourse(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.courseTypeName,
+            displayName: input.displayName ?? `course-${input.courseId}`,
+            properties: [
+                { key: 'course_id', valueType: 'string', valueJson: JSON.stringify(input.courseId) },
+                { key: 'gates', valueType: 'string', valueJson: JSON.stringify(JSON.stringify(input.gates)) },
+                { key: 'laps', valueType: 'int', valueJson: String(input.laps ?? 1) },
+            ],
+        });
+    }
+    /** Enter a course: your next pose through gate 0 starts the clock. */
+    async enter(courseId) {
+        return this.invoke(this.moduleName, 'enter', { courseId });
+    }
+    /** Your live run (splits, lap, next gate). */
+    async raceStatus() {
+        const body = await this.invoke(this.moduleName, 'race_status', {});
+        return {
+            courseId: String(body.courseId ?? ''),
+            started: body.started === true,
+            lap: Number(body.lap ?? 0),
+            nextGate: Number(body.nextGate ?? 0),
+            splitsMs: Array.isArray(body.splitsMs) ? body.splitsMs.map(Number) : [],
+            bestLapMs: Number(body.bestLapMs ?? 0),
+            finished: body.finished === true,
+            totalMs: Number(body.totalMs ?? 0),
+        };
+    }
+    /** The course record (holder, time, ghost length). */
+    async best(courseId) {
+        return this.invoke(this.moduleName, 'best', { courseId });
+    }
+    /** Replay the course-record ghost onto the actor lane. */
+    async ghostPlay(courseId) {
+        return this.invoke(this.moduleName, 'ghost_play', { courseId });
+    }
+    /** Parse a type-97 race-timing server event. */
+    parseRaceTiming(bytes) {
+        return parseRaceTimingEvent(bytes);
+    }
+    // -- possession (sports-lite ball) ----------------------------------------
+    /** Join the ball match (teams fill by join order). */
+    async joinMatch() {
+        return this.invoke(this.possessionModuleName, 'join_match', {});
+    }
+    /** Claim the free ball (or steal after the protection window). */
+    async claim() {
+        return this.invoke(this.possessionModuleName, 'claim', {});
+    }
+    /** Pass along a direction (holder only). */
+    async pass(dirX, dirZ) {
+        return this.invoke(this.possessionModuleName, 'pass', { dirX, dirZ });
+    }
+    /** Shoot at the opposing goal (holder only; the server aims). */
+    async shoot() {
+        return this.invoke(this.possessionModuleName, 'shoot', {});
+    }
+    /** The live ball match (teams, ball, standings, summary). */
+    async matchState() {
+        return this.invoke(this.possessionModuleName, 'match_state', {});
+    }
+    async invoke(moduleName, exportName, params) {
+        const result = await this.engines.invoke(moduleName, exportName, params);
+        if (!result.success) {
+            throw new Error(`racing.${exportName} failed: ${result.reason ?? 'unknown'}`);
+        }
+        return result.body;
+    }
+}

package/dist/kit/social.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"social.d.ts","sourceRoot":"","sources":["../../src/kit/social.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"social.d.ts","sourceRoot":"","sources":["../../src/kit/social.ts"],"names":[],"mappings":"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"}

package/dist/kit/telemetry.d.ts

@@ -0,0 +1,66 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+/** Options for {@link TelemetryKit}. */
+export interface TelemetryKitOptions {
+    /** The counter container type name. Defaults to `'TelemetryCounter'`. */
+    counterTypeName?: string;
+    /**
+     * Sample rate for `track()` in [0, 1] — the client-side budget knob.
+     * Defaults to 1 (every event).
+     */
+    sampleRate?: number;
+}
+/**
+ * Game analytics events (matrix P7) — MODEL-THIN by design: `track()`
+ * writes a naming-convention row into the existing model event log via a
+ * fire-and-forget container property bump, and sampled counters live in
+ * ordinary `TelemetryCounter` containers (`event_name` + `count`). Export
+ * and BI are platform concerns, deliberately out of scope; the convention
+ * is the abstraction.
+ *
+ * Naming convention: `<area>.<action>` (e.g. `ftue.step_completed`,
+ * `shop.purchase`). Keep cardinality low — counters are containers.
+ *
+ * Obtained via `client.kit(appId).telemetry`.
+ */
+export declare class TelemetryKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly counterTypeName;
+    private readonly sampleRate;
+    /** event name -> counter container id (cached per session). */
+    private readonly counterIds;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: TelemetryKitOptions);
+    /**
+     * Track one event — fire-and-forget (never throws, never blocks
+     * gameplay): bumps the event's sampled counter. `props` ride the
+     * container's last-props snapshot for spot-debugging (NOT a warehouse).
+     */
+    track(name: string, props?: Record<string, unknown>): void;
+    /** The awaitable form of {@link track} for tests/backfills. */
+    bump(name: string, props?: Record<string, unknown>): Promise<void>;
+    /** Read the sampled counters (dashboards, tests). */
+    counters(): Promise<Array<{
+        eventName: string;
+        count: number;
+        lastProps: string;
+    }>>;
+    private ensureCounter;
+}
+/** The telemetry blueprint: one counter type; the convention is the point. */
+export declare function telemetryBlueprint(counterTypeName?: string): {
+    name: string;
+    containerTypes: {
+        typeName: string;
+        displayName: string;
+        description: string;
+    }[];
+    propertyDefinitions: {
+        containerTypeName: string;
+        key: string;
+        valueType: string;
+        defaultValueJson: string;
+        description: string;
+    }[];
+};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/kit/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/kit/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGvD,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAGrC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,mBAAwB;IAMnC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAK9D,+DAA+D;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB5E,qDAAqD;IAC/C,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;YAiB3E,aAAa;CA0B5B;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,eAAe,SAAqB;;;;;;;;;;;;;;EAmCtE"}

package/dist/kit/telemetry.js

@@ -0,0 +1,133 @@
+import { kitContainerProperties } from './shared.js';
+/**
+ * Game analytics events (matrix P7) — MODEL-THIN by design: `track()`
+ * writes a naming-convention row into the existing model event log via a
+ * fire-and-forget container property bump, and sampled counters live in
+ * ordinary `TelemetryCounter` containers (`event_name` + `count`). Export
+ * and BI are platform concerns, deliberately out of scope; the convention
+ * is the abstraction.
+ *
+ * Naming convention: `<area>.<action>` (e.g. `ftue.step_completed`,
+ * `shop.purchase`). Keep cardinality low — counters are containers.
+ *
+ * Obtained via `client.kit(appId).telemetry`.
+ */
+export class TelemetryKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        /** event name -> counter container id (cached per session). */
+        this.counterIds = new Map();
+        this.counterTypeName = options.counterTypeName ?? 'TelemetryCounter';
+        this.sampleRate = options.sampleRate ?? 1;
+    }
+    /**
+     * Track one event — fire-and-forget (never throws, never blocks
+     * gameplay): bumps the event's sampled counter. `props` ride the
+     * container's last-props snapshot for spot-debugging (NOT a warehouse).
+     */
+    track(name, props = {}) {
+        if (Math.random() > this.sampleRate)
+            return;
+        void this.bump(name, props).catch(() => undefined);
+    }
+    /** The awaitable form of {@link track} for tests/backfills. */
+    async bump(name, props = {}) {
+        const containerId = await this.ensureCounter(name);
+        const current = await kitContainerProperties(this.gameModel, String(this.appId), containerId);
+        await this.gameModel.setProperty({
+            appId: this.appId,
+            containerId,
+            key: 'count',
+            valueType: 'int',
+            valueJson: String(Number(current.count ?? 0) + 1),
+        });
+        if (Object.keys(props).length > 0) {
+            await this.gameModel.setProperty({
+                appId: this.appId,
+                containerId,
+                key: 'last_props',
+                valueType: 'string',
+                valueJson: JSON.stringify(JSON.stringify(props).slice(0, 500)),
+            });
+        }
+    }
+    /** Read the sampled counters (dashboards, tests). */
+    async counters() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.counterTypeName,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                eventName: String(props.event_name ?? ''),
+                count: Number(props.count ?? 0),
+                lastProps: String(props.last_props ?? ''),
+            };
+        }));
+    }
+    async ensureCounter(name) {
+        const cached = this.counterIds.get(name);
+        if (cached)
+            return cached;
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.counterTypeName,
+        });
+        for (const c of containers) {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            if (String(props.event_name ?? '') === name) {
+                this.counterIds.set(name, c.containerId);
+                return c.containerId;
+            }
+        }
+        const created = await this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.counterTypeName,
+            displayName: `telemetry ${name}`,
+            properties: [
+                { key: 'event_name', valueType: 'string', valueJson: JSON.stringify(name) },
+                { key: 'count', valueType: 'int', valueJson: '0' },
+            ],
+        });
+        this.counterIds.set(name, created.containerId);
+        return created.containerId;
+    }
+}
+/** The telemetry blueprint: one counter type; the convention is the point. */
+export function telemetryBlueprint(counterTypeName = 'TelemetryCounter') {
+    return {
+        name: 'telemetry',
+        containerTypes: [
+            {
+                typeName: counterTypeName,
+                displayName: 'Telemetry counter',
+                description: "One sampled event counter (event_name + count + last_props). Naming convention: '<area>.<action>'.",
+            },
+        ],
+        propertyDefinitions: [
+            {
+                containerTypeName: counterTypeName,
+                key: 'event_name',
+                valueType: 'string',
+                defaultValueJson: '""',
+                description: "The tracked event's convention name ('<area>.<action>').",
+            },
+            {
+                containerTypeName: counterTypeName,
+                key: 'count',
+                valueType: 'int',
+                defaultValueJson: '0',
+                description: 'Sampled occurrence count.',
+            },
+            {
+                containerTypeName: counterTypeName,
+                key: 'last_props',
+                valueType: 'string',
+                defaultValueJson: '""',
+                description: 'The last tracked props JSON (spot-debugging, not a warehouse).',
+            },
+        ],
+    };
+}

package/dist/kit/territory.d.ts

@@ -0,0 +1,97 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+import { type ControlPointEvent } from './wire.js';
+/** Options for {@link TerritoryKit}. */
+export interface TerritoryKitOptions {
+    /** The territory engine module name. Defaults to `'territory'`. */
+    moduleName?: string;
+}
+/** A control point as the engine reports it. */
+export interface KitControlPoint {
+    pointId: string;
+    x: number;
+    z: number;
+    radius: number;
+    owner: string;
+    challenger: string;
+    progress: number;
+    incomePerMin: number;
+    siegeOpen: boolean;
+}
+/**
+ * Runtime helpers for the territory engine (Wave 3): control-point state,
+ * faction standings, and the admin CRUD for the map (factions, members,
+ * points). Capture itself is pure presence — stand inside a point's radius
+ * with your faction; the engine does the rest and announces flips as
+ * type-96 events.
+ *
+ * Obtained via `client.kit(appId).territory`.
+ */
+export declare class TerritoryKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly engines;
+    private readonly moduleName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, engines: EngineDetector, options?: TerritoryKitOptions);
+    /** Is the territory engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /** Every control point with live capture state. */
+    points(): Promise<KitControlPoint[]>;
+    /** Faction standings (id + treasury). */
+    factions(): Promise<Array<{
+        factionId: string;
+        gold: number;
+    }>>;
+    /** Engine totals (flips, income paid). */
+    status(): Promise<Record<string, unknown>>;
+    /** STUDIO (admin) — create a faction. */
+    defineFaction(factionId: string, displayName?: string): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** STUDIO (admin) — enroll a player in a faction. */
+    enroll(userId: string, factionId: string): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** STUDIO (admin) — create a control point. */
+    definePoint(input: {
+        pointId: string;
+        x: number;
+        z: number;
+        radius: number;
+        incomePerMin?: number;
+        siegeFromMin?: number;
+        siegeToMin?: number;
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Parse a type-96 control-point server event (flips). */
+    parseControlPoint(bytes: Uint8Array): ControlPointEvent | null;
+    private invoke;
+}
+//# sourceMappingURL=territory.d.ts.map

package/dist/kit/territory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"territory.d.ts","sourceRoot":"","sources":["../../src/kit/territory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE3E,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,mBAAwB;IAKnC,uEAAuE;IACvE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC,mDAAmD;IAC7C,MAAM,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAiB1C,yCAAyC;IACnC,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUrE,0CAA0C;IACpC,MAAM;IAIZ,yCAAyC;IACnC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;;;;;;;;;;;IAY3D,qDAAqD;IAC/C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;;;;;;IAY9C,+CAA+C;IACzC,WAAW,CAAC,KAAK,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IA0BD,0DAA0D;IAC1D,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,GAAG,IAAI;YAIhD,MAAM;CAOrB"}