@khorsheed/dsh-game 0.0.0-stage → 0.1.1

package/lib/types/client/reveal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The game tab follows the agent: `game_publish` says where the user should
+ * look (the play area, an element's page, the element grid…), the page picks
+ * the request up on its poll, and this controller carries it out — unless the
+ * user is busy in the panel (a game running, a touch in the last 20 s), in
+ * which case it waits as a notice. The page itself never decides where to go.
+ *
+ * Each request is carried out once; one found on a reload is history. Every
+ * decision leaves a `[game:reveal]` console line.
+ * @module @khorsheed/dsh-game/client
+ */
+import type { NavTarget } from './contract.ts';
+import type { ShowRequest } from '../types.ts';
+/** A request held back while the user was busy. */
+export interface RevealNotice {
+    readonly text: string;
+    readonly target: NavTarget;
+}
+/** The page-wide controller. */
+export declare class Reveal {
+    private readonly open;
+    private lastTouch;
+    private playing;
+    private mounted;
+    private noticeNow;
+    private readonly listeners;
+    /** The last request sequence carried out per project. */
+    private readonly done;
+    /** @param open - opens the game tab at a place (the plugin's openAt). */
+    constructor(open: (target: NavTarget) => void);
+    get notice(): RevealNotice | null;
+    dismiss(): void;
+    follow(): void;
+    /** The tab mounted; the result unmounts it. A mounted tab is navigated at any width. */
+    mount(): () => void;
+    touched(): void;
+    setPlaying(on: boolean): void;
+    subscribe(listener: () => void): () => void;
+    private changed;
+    /** The agent's request for a project, as the poll returned it. */
+    request(projectId: string, request: ShowRequest, now?: number): 'opened' | 'notice' | 'skipped' | null;
+}
+//# sourceMappingURL=reveal.d.ts.map

package/lib/types/client/reveal.js

@@ -0,0 +1,73 @@
+/** A touch this recent means the user is busy in the panel. */
+const BUSY_MS = 20_000;
+/** Below this window width a closed panel is not opened: it would cover the conversation. */
+const WIDE_PX = 820;
+/** A request older than this, seen first on this page, is history (a reload). */
+const FRESH_MS = 90_000;
+/** The page-wide controller. */
+export class Reveal {
+    open;
+    lastTouch = 0;
+    playing = false;
+    mounted = 0;
+    noticeNow = null;
+    listeners = new Set();
+    /** The last request sequence carried out per project. */
+    done = new Map();
+    /** @param open - opens the game tab at a place (the plugin's openAt). */
+    constructor(open) {
+        this.open = open;
+    }
+    get notice() { return this.noticeNow; }
+    dismiss() { this.noticeNow = null; this.changed(); }
+    follow() {
+        const n = this.noticeNow;
+        this.dismiss();
+        if (n !== null)
+            this.open(n.target);
+    }
+    /** The tab mounted; the result unmounts it. A mounted tab is navigated at any width. */
+    mount() {
+        this.mounted++;
+        return () => { this.mounted--; };
+    }
+    touched() { this.lastTouch = Date.now(); }
+    setPlaying(on) { this.playing = on; }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    changed() { for (const l of this.listeners)
+        l(); }
+    /** The agent's request for a project, as the poll returned it. */
+    request(projectId, request, now = Date.now()) {
+        const seen = this.done.get(projectId);
+        this.done.set(projectId, Math.max(request.seq, seen ?? 0));
+        if (seen !== undefined ? request.seq <= seen : now - Date.parse(request.at) > FRESH_MS)
+            return null;
+        const target = {
+            view: request.target.view,
+            ...(request.target.elementId === undefined ? {} : { elementId: request.target.elementId }),
+            ...(request.target.chapterId === undefined ? {} : { chapterId: request.target.chapterId }),
+        };
+        const busy = this.playing ? 'a game is running' : now - this.lastTouch < BUSY_MS ? 'the panel was just used' : null;
+        const narrow = this.mounted === 0 && (typeof window === 'undefined' || window.innerWidth < WIDE_PX);
+        const outcome = busy !== null ? 'notice' : narrow ? 'skipped' : 'opened';
+        try {
+            console.info(`[game:reveal] #${request.seq} ${request.note} → ${outcome}${busy === null ? '' : ` (${busy})`}${narrow && busy === null ? ' (closed panel, narrow window)' : ''}`, target);
+        }
+        catch {
+            // No console.
+        }
+        if (outcome === 'notice') {
+            this.noticeNow = { text: request.note, target };
+            this.changed();
+        }
+        if (outcome === 'opened') {
+            this.noticeNow = null;
+            this.open(target);
+            this.changed();
+        }
+        return outcome;
+    }
+}

package/lib/types/client/style-samples.d.ts

@@ -0,0 +1,5 @@
+type G = CanvasRenderingContext2D;
+/** Draw the sample scene for one style into a W×H canvas. */
+export declare function drawStyleSample(g: G, styleId: string, w: number, h: number): void;
+export {};
+//# sourceMappingURL=style-samples.d.ts.map

package/lib/types/client/style-samples.js

@@ -0,0 +1,196 @@
+/**
+ * The art-style gallery's samples: one small scene (a keeper, a lamp post, a
+ * blob creature, the ground) drawn in each built-in style from that style's
+ * own palette, so the user compares looks on the same subject. Pure canvas
+ * drawing; colors are the style's content, not theme tokens.
+ */
+import { ART_STYLES } from "../types.js";
+/** Deterministic jitter for the hand-drawn style. */
+function jitter(seed) {
+    const x = Math.sin(seed * 12.9898) * 43758.5453;
+    return (x - Math.floor(x)) - 0.5;
+}
+/** A pixel sprite from rows, drawn with `cell`-px blocks. */
+function sprite(g, rows, colors, x, y, cell) {
+    rows.forEach((row, ry) => [...row].forEach((ch, rx) => {
+        const c = colors[ch];
+        if (c === undefined)
+            return;
+        g.fillStyle = c;
+        g.fillRect(x + rx * cell, y + ry * cell, cell, cell);
+    }));
+}
+const KEEPER = ['..hh..', '.hhhh.', '..ff..', '.cccc.', 'cccccc', '.cccc.', '.c..c.', '.b..b.'];
+const BLOB = ['..eeee..', '.eeeeee.', 'eeyeeyee', 'eeeeeeee', 'eeemmeee', '.eeeeee.', 'e.e..e.e'];
+/** Draw the sample scene for one style into a W×H canvas. */
+export function drawStyleSample(g, styleId, w, h) {
+    const p = (ART_STYLES.find(s => s.id === styleId) ?? ART_STYLES[0]).palette;
+    const ground = h * 0.74;
+    g.save();
+    g.clearRect(0, 0, w, h);
+    switch (styleId) {
+        case 'pixel': {
+            g.fillStyle = p[15];
+            g.fillRect(0, 0, w, h);
+            for (let i = 0; i < 14; i++) {
+                g.fillStyle = p[13];
+                g.fillRect((i * 37) % w, (i * 23) % (ground * 0.6), 2, 2);
+            }
+            g.fillStyle = p[7];
+            g.fillRect(0, ground, w, h - ground);
+            for (let x = 0; x < w; x += 8) {
+                g.fillStyle = p[6];
+                g.fillRect(x, ground, 4, 4);
+            }
+            g.fillStyle = p[14];
+            g.fillRect(w * 0.72, ground - 52, 6, 52);
+            g.fillStyle = p[4];
+            g.fillRect(w * 0.72 - 4, ground - 60, 14, 10);
+            sprite(g, KEEPER, { h: p[2], f: p[4], c: p[9], b: p[0] }, w * 0.22, ground - 32, 4);
+            sprite(g, BLOB, { e: p[13], y: p[4], m: p[0] }, w * 0.46, ground - 28, 4);
+            break;
+        }
+        case 'flat': {
+            g.fillStyle = p[6];
+            g.fillRect(0, 0, w, h);
+            g.fillStyle = p[3];
+            g.beginPath();
+            g.arc(w * 0.82, h * 0.22, 14, 0, Math.PI * 2);
+            g.fill();
+            g.fillStyle = p[1];
+            g.beginPath();
+            g.roundRect(0, ground, w, h - ground, 0);
+            g.fill();
+            g.fillStyle = p[0];
+            g.beginPath();
+            g.roundRect(w * 0.7, ground - 54, 8, 54, 4);
+            g.fill();
+            g.fillStyle = p[3];
+            g.beginPath();
+            g.arc(w * 0.7 + 4, ground - 58, 9, 0, Math.PI * 2);
+            g.fill();
+            g.fillStyle = p[5];
+            g.beginPath();
+            g.roundRect(w * 0.2, ground - 30, 22, 30, 8);
+            g.fill();
+            g.fillStyle = p[4];
+            g.beginPath();
+            g.arc(w * 0.2 + 11, ground - 38, 9, 0, Math.PI * 2);
+            g.fill();
+            g.fillStyle = p[7];
+            g.beginPath();
+            g.ellipse(w * 0.5, ground - 14, 18, 14, 0, 0, Math.PI * 2);
+            g.fill();
+            g.fillStyle = p[6];
+            g.beginPath();
+            g.arc(w * 0.5 - 6, ground - 17, 3, 0, Math.PI * 2);
+            g.arc(w * 0.5 + 6, ground - 17, 3, 0, Math.PI * 2);
+            g.fill();
+            break;
+        }
+        case 'line': {
+            g.fillStyle = p[1];
+            g.fillRect(0, 0, w, h);
+            g.strokeStyle = p[0];
+            g.lineWidth = 1.6;
+            g.lineCap = 'round';
+            const wobble = (pts, fill) => {
+                g.beginPath();
+                pts.forEach(([x, y], i) => { const jx = x + jitter(i + x) * 1.6, jy = y + jitter(i + y) * 1.6; if (i === 0)
+                    g.moveTo(jx, jy);
+                else
+                    g.lineTo(jx, jy); });
+                if (fill) {
+                    g.fillStyle = fill;
+                    g.fill();
+                }
+                g.stroke();
+            };
+            wobble([[0, ground], [w, ground + 2]]);
+            wobble([[w * 0.7, ground], [w * 0.7, ground - 54], [w * 0.7 + 8, ground - 54], [w * 0.7 + 8, ground]], p[5]);
+            wobble([[w * 0.2, ground], [w * 0.2, ground - 28], [w * 0.2 + 20, ground - 28], [w * 0.2 + 20, ground]], p[4]);
+            g.beginPath();
+            g.arc(w * 0.2 + 10, ground - 37, 9, 0, Math.PI * 2);
+            g.fillStyle = p[2];
+            g.fill();
+            g.stroke();
+            g.beginPath();
+            g.ellipse(w * 0.5, ground - 13, 17, 13, 0, 0, Math.PI * 2);
+            g.fillStyle = p[6];
+            g.fill();
+            g.stroke();
+            g.fillStyle = p[0];
+            g.fillRect(w * 0.5 - 7, ground - 16, 3, 3);
+            g.fillRect(w * 0.5 + 4, ground - 16, 3, 3);
+            break;
+        }
+        case 'neon': {
+            g.fillStyle = p[0];
+            g.fillRect(0, 0, w, h);
+            g.strokeStyle = p[1];
+            g.lineWidth = 1;
+            for (let x = 0; x < w; x += 16) {
+                g.beginPath();
+                g.moveTo(x, ground);
+                g.lineTo(w / 2 + (x - w / 2) * 2, h);
+                g.stroke();
+            }
+            const glow = (color, draw) => { g.shadowColor = color; g.shadowBlur = 10; g.strokeStyle = color; g.lineWidth = 2; draw(); g.shadowBlur = 0; };
+            glow(p[3], () => { g.beginPath(); g.moveTo(0, ground); g.lineTo(w, ground); g.stroke(); });
+            glow(p[5], () => { g.strokeRect(w * 0.7, ground - 54, 8, 54); g.beginPath(); g.arc(w * 0.7 + 4, ground - 60, 6, 0, Math.PI * 2); g.stroke(); });
+            glow(p[2], () => { g.strokeRect(w * 0.2, ground - 28, 20, 28); g.beginPath(); g.arc(w * 0.2 + 10, ground - 36, 7, 0, Math.PI * 2); g.stroke(); });
+            glow(p[4], () => { g.beginPath(); g.ellipse(w * 0.5, ground - 13, 16, 12, 0, 0, Math.PI * 2); g.stroke(); });
+            break;
+        }
+        case 'paper': {
+            g.fillStyle = p[0];
+            g.fillRect(0, 0, w, h);
+            for (let i = 0; i < 60; i++) {
+                g.fillStyle = p[1];
+                g.globalAlpha = 0.25;
+                g.fillRect((i * 53) % w, (i * 29) % h, 3, 1);
+            }
+            g.globalAlpha = 1;
+            const cut = (color, draw, angle = 0) => {
+                g.save();
+                g.rotate(angle);
+                g.shadowColor = 'rgba(60,40,20,0.35)' /* the paper style's own cast shadow */;
+                g.shadowBlur = 4;
+                g.shadowOffsetY = 2;
+                g.fillStyle = color;
+                draw();
+                g.restore();
+            };
+            cut(p[4], () => { g.fillRect(0, ground, w, h - ground); });
+            cut(p[5], () => { g.beginPath(); g.ellipse(w * 0.3, ground + 4, 60, 14, 0, 0, Math.PI * 2); g.fill(); });
+            cut(p[7], () => { g.fillRect(w * 0.7, ground - 54, 8, 54); }, 0.01);
+            cut(p[2], () => { g.beginPath(); g.arc(w * 0.7 + 4, ground - 58, 9, 0, Math.PI * 2); g.fill(); });
+            cut(p[6], () => { g.fillRect(w * 0.2, ground - 28, 20, 28); }, -0.02);
+            cut(p[2], () => { g.beginPath(); g.arc(w * 0.2 + 10, ground - 36, 8, 0, Math.PI * 2); g.fill(); });
+            cut(p[3], () => { g.beginPath(); g.ellipse(w * 0.5, ground - 12, 16, 12, 0, 0, Math.PI * 2); g.fill(); });
+            break;
+        }
+        default: {
+            g.fillStyle = p[1];
+            g.fillRect(0, 0, w, h);
+            g.fillStyle = p[0];
+            g.fillRect(0, ground, w, 3);
+            g.fillRect(w * 0.7, ground - 54, 6, 54);
+            g.fillStyle = p[2];
+            g.beginPath();
+            g.arc(w * 0.7 + 3, ground - 58, 7, 0, Math.PI * 2);
+            g.fill();
+            g.fillStyle = p[0];
+            g.fillRect(w * 0.2, ground - 28, 16, 28);
+            g.beginPath();
+            g.arc(w * 0.2 + 8, ground - 35, 7, 0, Math.PI * 2);
+            g.fill();
+            g.strokeStyle = p[0];
+            g.lineWidth = 2;
+            g.beginPath();
+            g.ellipse(w * 0.5, ground - 12, 15, 11, 0, 0, Math.PI * 2);
+            g.stroke();
+        }
+    }
+    g.restore();
+}

package/lib/types/fsutil.d.ts

@@ -0,0 +1,26 @@
+import type { BundleFile } from './types.ts';
+/** Whether `child` is `parent` or inside it. */
+export declare function inside(parent: string, child: string): boolean;
+/** Write a file atomically (tmp + rename), creating its directory. */
+export declare function writeAtomic(path: string, data: string | Uint8Array): Promise<void>;
+/** Read a text file, undefined when absent or unreadable. */
+export declare function readText(path: string): Promise<string | undefined>;
+/** Read JSON, undefined when absent or broken. */
+export declare function readJson<T>(path: string): Promise<T | undefined>;
+/** One walked file: project-relative POSIX path plus its bytes. */
+export interface WalkedFile {
+    readonly path: string;
+    readonly data: Buffer;
+}
+/**
+ * Walk a directory (dot-entries skipped), bounded by the walk limits.
+ * @param root - directory to walk.
+ * @param keep - project-relative path filter.
+ * @returns the files, sorted by path.
+ */
+export declare function walk(root: string, keep: (path: string) => boolean): Promise<WalkedFile[]>;
+/** The sandbox bundle form of walked files. */
+export declare function bundleOf(files: readonly WalkedFile[]): Record<string, BundleFile>;
+/** A content fingerprint over (path, bytes) pairs. */
+export declare function fingerprintOf(files: readonly WalkedFile[]): string;
+//# sourceMappingURL=fsutil.d.ts.map

package/lib/types/fsutil.js

@@ -0,0 +1,104 @@
+/**
+ * File helpers the game service builds on: atomic writes, tolerant reads, the
+ * bounded project walk, and the sandbox bundle form of walked files.
+ * @module @khorsheed/dsh-game
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { isTextFile, mimeOf } from "./project.js";
+/** Walk limits for one project read: enough for a small game, bounded for a stray huge folder. */
+const MAX_FILES = 600;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 48 * 1024 * 1024;
+/** Whether `child` is `parent` or inside it. */
+export function inside(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/** Write a file atomically (tmp + rename), creating its directory. */
+export async function writeAtomic(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${randomBytes(4).toString('hex')}.tmp`;
+    await writeFile(tmp, data);
+    await rename(tmp, path);
+}
+/** Read a text file, undefined when absent or unreadable. */
+export async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read JSON, undefined when absent or broken. */
+export async function readJson(path) {
+    const text = await readText(path);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Walk a directory (dot-entries skipped), bounded by the walk limits.
+ * @param root - directory to walk.
+ * @param keep - project-relative path filter.
+ * @returns the files, sorted by path.
+ */
+export async function walk(root, keep) {
+    const out = [];
+    let total = 0;
+    const visit = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (out.length >= MAX_FILES || entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(dir, entry.name);
+            const rel = relative(root, full).split(sep).join('/');
+            if (entry.isDirectory()) {
+                await visit(full);
+                continue;
+            }
+            if (!entry.isFile() || !keep(rel))
+                continue;
+            const info = await stat(full).catch(() => undefined);
+            if (info === undefined || info.size > MAX_FILE_BYTES || total + info.size > MAX_TOTAL_BYTES)
+                continue;
+            total += info.size;
+            out.push({ path: rel, data: await readFile(full) });
+        }
+    };
+    await visit(root);
+    return out;
+}
+/** The sandbox bundle form of walked files. */
+export function bundleOf(files) {
+    const out = {};
+    for (const f of files) {
+        out[f.path] = isTextFile(f.path)
+            ? { type: mimeOf(f.path), text: f.data.toString('utf8') }
+            : { type: mimeOf(f.path), b64: f.data.toString('base64') };
+    }
+    return out;
+}
+/** A content fingerprint over (path, bytes) pairs. */
+export function fingerprintOf(files) {
+    const hash = createHash('sha1');
+    for (const f of files) {
+        hash.update(f.path);
+        hash.update('\0');
+        hash.update(createHash('sha1').update(f.data).digest());
+    }
+    return hash.digest('hex').slice(0, 16);
+}

package/lib/types/hooks.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The end-of-turn loop (proposal §6, probes P0-4/P0-5): when a turn that is
+ * bound to a game project is about to close, run the checks on what it
+ * changed. A failure is steered back into the SAME turn with the findings —
+ * at most {@link FIX_CAP} times — and a pass deploys into the play area (or
+ * leaves a candidate when auto-confirm is off).
+ *
+ * `agent/turn-stopping` fires only for a turn completing normally (never on
+ * abort or error), so a user's stop is never overridden. Sessions with no
+ * bound project are untouched, which is what keeps the hook inert outside the
+ * game preset: only `game_open` binds.
+ * @module @khorsheed/dsh-game
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { GameService } from './store.ts';
+import { type CheckRecord } from './types.ts';
+/** What a dsh-game message is, for the chat row (the text is for the model). */
+export type GameMessageOp = {
+    readonly op: 'check-failed';
+    readonly attempt: number;
+    readonly cap: number;
+    readonly failures: readonly {
+        where: string;
+        message: string;
+    }[];
+} | {
+    readonly op: 'attached';
+    readonly items: readonly string[];
+};
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A message the game plugin put into the conversation (check findings, attached changes). */
+        'dsh-game': {
+            kind: 'dsh-game';
+            plugin: '@khorsheed/dsh-game';
+        } & ContextFormed & Partial<GameMessageOp>;
+    }
+}
+/** Build a dsh-game user message. */
+export declare function gameMessage(text: string, section: string, op: GameMessageOp): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    source: {
+        op: "check-failed";
+        attempt: number;
+        cap: number;
+        failures: readonly {
+            where: string;
+            message: string;
+        }[];
+        kind: "dsh-game";
+        plugin: "@khorsheed/dsh-game";
+        form: "snapshot";
+        sections: {
+            name: string;
+            text: string;
+        }[];
+    } | {
+        op: "attached";
+        items: readonly string[];
+        kind: "dsh-game";
+        plugin: "@khorsheed/dsh-game";
+        form: "snapshot";
+        sections: {
+            name: string;
+            text: string;
+        }[];
+    };
+} & Pick<import("@deepseek-ai/dsh-llm").UserMessage, "id" | "role">;
+/** Automatic fix rounds per turn (decision: at most 2). */
+export declare const FIX_CAP = 2;
+/** The steer text for one failed check (model-facing). */
+export declare function failureText(record: CheckRecord, attempt: number): string;
+/**
+ * Register the hooks on the plugin's scope.
+ * @param ctx - the core plugin's context.
+ * @param store - the service core.
+ */
+export declare function registerTurnHooks(ctx: Context, store: GameService): void;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/types/hooks.js

@@ -0,0 +1,108 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { PANEL_CHANGES_MARK } from "./types.js";
+/** Build a dsh-game user message. */
+export function gameMessage(text, section, op) {
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: 'dsh-game', plugin: '@khorsheed/dsh-game', form: 'snapshot', sections: [{ name: section, text }], ...op },
+    });
+}
+/** Automatic fix rounds per turn (decision: at most 2). */
+export const FIX_CAP = 2;
+/** The steer text for one failed check (model-facing). */
+export function failureText(record, attempt) {
+    const lines = [
+        `[游戏检查未通过 ${attempt}/${FIX_CAP}] 这一轮改完的版本没过检查，试玩区还停在上一个版本。`,
+        ...record.failures.slice(0, 8).map(f => `- ${f.where}：${f.message}`),
+    ];
+    if (record.failures.length > 8)
+        lines.push(`- ……另有 ${record.failures.length - 8} 项`);
+    if (record.skipped !== undefined)
+        lines.push(`（${record.skipped}）`);
+    lines.push(attempt < FIX_CAP
+        ? '请修好再结束这一轮：先读报错对应的代码，改完不用告诉我，结束时会自动重新检查。若是测试本身写错了，改测试并说明理由。'
+        : '这是最后一次自动修复机会；修不好就如实告诉用户卡在哪里。');
+    return lines.join('\n');
+}
+/**
+ * Register the hooks on the plugin's scope.
+ * @param ctx - the core plugin's context.
+ * @param store - the service core.
+ */
+export function registerTurnHooks(ctx, store) {
+    /** Steers already sent, per `<session>:<turn>`. */
+    const steered = new Map();
+    ctx.on('agent/turn-stopping', async ({ agent, turn, signal }) => {
+        if (signal.aborted)
+            return;
+        const key = `${agent.session.id}:${turn}`;
+        const attempt = steered.get(key) ?? 0;
+        let outcome;
+        try {
+            outcome = await store.checkTurn(agent.session, attempt, FIX_CAP);
+        }
+        catch (error) {
+            ctx.logger.warn('game: end-of-turn check failed to run', error);
+            return;
+        }
+        if (outcome.kind !== 'fail' || signal.aborted)
+            return;
+        if (attempt >= FIX_CAP)
+            return;
+        steered.set(key, attempt + 1);
+        const text = failureText(outcome.record, attempt + 1);
+        agent.steer(gameMessage(text, 'checks', {
+            op: 'check-failed', attempt: attempt + 1, cap: FIX_CAP,
+            failures: outcome.record.failures.slice(0, 8).map(f => ({ where: f.where, message: f.message.slice(0, 300) })),
+        }));
+    });
+    // Panel changes are sent explicitly (2026-10-10, replacing the automatic
+    // attach): the dock writes them into the composer and the user sends. When
+    // such a message enters a step, the changes it lists stop being pending.
+    // The batch itself is never touched.
+    ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject' || signal.aborted || decision.messages.length === 0)
+            return decision;
+        const text = decision.messages
+            .map(m => m.content.map(block => (block.type === 'text' ? block.text : '')).join('\n'))
+            .join('\n');
+        if (text.includes(PANEL_CHANGES_MARK)) {
+            await store.clearSent(agent.session.id, text).catch((error) => {
+                ctx.logger.warn('game: could not clear sent panel changes', error);
+            });
+        }
+        return decision;
+    }, { prepend: true });
+    // Turn reports: snapshot the bound project when a turn starts, record what
+    // it changed when the turn ends (whatever its reason), for the turn-tail card.
+    const baselines = new Map();
+    ctx.on('session/event', (session, raw) => {
+        const event = raw;
+        const turn = event?.data?.turn ?? event?.turn;
+        if (event?.type === 'turn/start')
+            store.setTurnActive(session.id, true);
+        if (event?.type === 'turn/end')
+            store.setTurnActive(session.id, false);
+        if (event?.type === 'turn/start' && turn !== undefined) {
+            baselines.set(`${session.id}:${turn}`, store.turnBaseline(session.id).catch(() => undefined));
+            return;
+        }
+        if (event?.type !== 'turn/end')
+            return;
+        if (turn !== undefined) {
+            steered.delete(`${session.id}:${turn}`);
+            const key = `${session.id}:${turn}`;
+            const base = baselines.get(key);
+            baselines.delete(key);
+            if (base !== undefined) {
+                void base.then(b => (b === undefined ? undefined : store.recordTurn(session.id, turn, b)))
+                    .catch((error) => { ctx.logger.warn('game: could not record the turn report', error); });
+            }
+        }
+        else
+            for (const key of steered.keys())
+                if (key.startsWith(`${session.id}:`))
+                    steered.delete(key);
+    });
+}

package/lib/types/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Game mode, host half: provides the service core (`ctx.gameStore`), mounts
+ * its Remote face, and runs the end-of-turn check loop for sessions bound to
+ * a project. The model tools, their guidance and the skills live in the
+ * `./agent` composition entry (preset-scoped).
+ * @module @khorsheed/dsh-game
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { GameService, type GameConfig } from './store.ts';
+export { GameService, resolveGameStateRoot } from './store.ts';
+export type { GameConfig } from './store.ts';
+export { GameRemoteService } from './remote.ts';
+export * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The game mode's service core. */
+        gameStore: GameService;
+    }
+}
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "game";
+/** The service core writes through the mounted filesystem. */
+export declare const inject: string[];
+/**
+ * Plugin body.
+ * @param ctx - owning Cordis Context.
+ * @param config - plugin config.
+ */
+export declare function apply(ctx: Context, config?: GameConfig): void;
+//# sourceMappingURL=index.d.ts.map