@khorsheed/dsh-game 0.0.0-stage → 0.1.0

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

package/lib/types/index.js

@@ -0,0 +1,22 @@
+import { registerTurnHooks } from "./hooks.js";
+import { GameRemoteService } from "./remote.js";
+import { GameService } from "./store.js";
+export { GameService, resolveGameStateRoot } from "./store.js";
+export { GameRemoteService } from "./remote.js";
+export * from "./types.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'game';
+/** The service core writes through the mounted filesystem. */
+export const inject = ['fs'];
+/**
+ * Plugin body.
+ * @param ctx - owning Cordis Context.
+ * @param config - plugin config.
+ */
+export function apply(ctx, config = {}) {
+    const store = new GameService(ctx, config);
+    ctx.provide('gameStore', store);
+    ctx.effect(() => () => { void store.dispose(); }, 'game: checker browser');
+    ctx.plugin(GameRemoteService, {});
+    registerTurnHooks(ctx, store);
+}

package/lib/types/kits/canvas2d.d.ts

@@ -0,0 +1,6 @@
+import { type RuntimeKit } from './types.ts';
+/** Blank when the first canvas, scaled to 32×32 through a 2D context, holds one color. */
+export declare const BLANK_PROBE = "(() => {\n  const c = document.querySelector('canvas');\n  if (!c || c.width <= 0 || c.height <= 0) return null;\n  const probe = document.createElement('canvas'); probe.width = 32; probe.height = 32;\n  const p = probe.getContext('2d'); p.drawImage(c, 0, 0, 32, 32);\n  const d = p.getImageData(0, 0, 32, 32).data; const distinct = new Set();\n  for (let i = 0; i < d.length; i += 4) { distinct.add(d[i] + ',' + d[i + 1] + ',' + d[i + 2]); if (distinct.size > 1) break; }\n  return distinct.size <= 1;\n})()";
+/** The 2D canvas kit. */
+export declare const CANVAS_2D: RuntimeKit;
+//# sourceMappingURL=canvas2d.d.ts.map

package/lib/types/kits/canvas2d.js

@@ -0,0 +1,60 @@
+/**
+ * The `2d-canvas` kit: native canvas plus an HTML/CSS layer, pixel-row looks
+ * drawn with `dshDraw`, the eight built-in 2D art styles. This is the
+ * workbench's original runtime, moved behind the kit seam unchanged.
+ * @module @khorsheed/dsh-game
+ */
+import { normalizeLook, PIXEL_LOOK_HINT } from "../project.js";
+import { ART_STYLES } from "../types.js";
+import { KIT_RUNTIME_FILE } from "./types.js";
+/** The frame runtime: pixel-look drawing helpers over `window.dshElements`. Kept as a string (never `fn.toString()`). */
+const RUNTIME = `(function(){
+  var CH = '0123456789abcdefghijklmnopqrstuvwxyz';
+  window.dshDraw = function(g, look, state, x, y, scale){
+    if (typeof look === 'string') { var el = window.dshElements[look]; look = el && el.look }
+    if (!look || !look.states || !look.palette) return false;
+    var names = Object.keys(look.states), rows = look.states[state] || look.states[names[0]];
+    if (!rows) return false;
+    scale = scale || 1;
+    for (var r = 0; r < rows.length; r++) for (var c = 0; c < rows[r].length; c++) {
+      var col = look.palette[CH.indexOf(rows[r].charAt(c))];
+      if (!col) continue;
+      g.fillStyle = col; g.fillRect(Math.round(x + c * scale), Math.round(y + r * scale), Math.ceil(scale), Math.ceil(scale));
+    }
+    return true;
+  };
+  window.dshLookSize = function(look){
+    if (typeof look === 'string') { var el = window.dshElements[look]; look = el && el.look }
+    var rows = look && look.states && look.states[Object.keys(look.states)[0]];
+    return rows ? { w: rows[0].length, h: rows.length } : { w: 0, h: 0 };
+  };
+})();`;
+/** Blank when the first canvas, scaled to 32×32 through a 2D context, holds one color. */
+export const BLANK_PROBE = `(() => {
+  const c = document.querySelector('canvas');
+  if (!c || c.width <= 0 || c.height <= 0) return null;
+  const probe = document.createElement('canvas'); probe.width = 32; probe.height = 32;
+  const p = probe.getContext('2d'); p.drawImage(c, 0, 0, 32, 32);
+  const d = p.getImageData(0, 0, 32, 32).data; const distinct = new Set();
+  for (let i = 0; i < d.length; i += 4) { distinct.add(d[i] + ',' + d[i + 1] + ',' + d[i + 2]); if (distinct.size > 1) break; }
+  return distinct.size <= 1;
+})()`;
+const STYLE_LINES = ART_STYLES.map(s => `- \`${s.id}\` ${s.label}：${s.look}`).join('\n');
+/** The 2D canvas kit. */
+export const CANVAS_2D = {
+    id: '2d-canvas',
+    version: 1,
+    label: '2D 画布',
+    runtimeFiles: () => ({ [KIT_RUNTIME_FILE]: { type: 'text/javascript', text: RUNTIME } }),
+    normalizeLook,
+    lookHint: PIXEL_LOOK_HINT,
+    blankProbe: BLANK_PROBE,
+    styles: ART_STYLES,
+    skillSection: `## 运行环境
+- 只有 2D：原生 canvas 加 HTML/CSS 做界面。不能联网、不能引外部 CDN（沙箱 CSP 全拦），所有代码和资源都放项目里。
+- 存档用 \`localStorage\`（面板替你保存在用户浏览器里）。
+- 没有文生图：画面全部用代码画（canvas 绘制、像素数组、SVG）。严格按 game.json 的 artStyle 画：
+${STYLE_LINES}
+- 外观 look 的格式：\`{ "palette": ["#1a1c2c", "#ffcd75", …], "states": { "idle": ["..00..", ".0110.", …], "move": [...] } }\`。每行一个字符串，\`.\` 透明，\`0-9a-z\` 是 palette 下标；同一状态各行等宽，常用 16×16。颜色优先取 game.json 的 \`palette\`（来自美术风格）。画的时候用 \`dshDraw(ctx2d, 元素id或look, 状态名, x, y, 放大倍数)\`，尺寸用 \`dshLookSize(元素id)\`。
+`,
+};

package/lib/types/kits/ids.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shipped kit ids, apart from the kits themselves so the manifest parser
+ * (shared with the browser half) can check one without pulling a kit in.
+ * @module @khorsheed/dsh-game
+ */
+import type { KitId } from './types.ts';
+/** Every kit id this build ships. */
+export declare const KIT_IDS: readonly KitId[];
+/** Whether a value names a shipped kit. */
+export declare function isKitId(value: unknown): value is KitId;
+//# sourceMappingURL=ids.d.ts.map

package/lib/types/kits/ids.js

@@ -0,0 +1,6 @@
+/** Every kit id this build ships. */
+export const KIT_IDS = ['2d-canvas', '3d-three'];
+/** Whether a value names a shipped kit. */
+export function isKitId(value) {
+    return typeof value === 'string' && KIT_IDS.includes(value);
+}