@khorsheed/dsh-game 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,36 @@
+/**
+ * Element looks in the panel: the same pixel rows the game draws through
+ * `dshDraw`, painted onto a small canvas. The canvas is the content here
+ * (the element's own colors), so no theme token applies to the pixels.
+ */
+import { type ReactNode } from 'react';
+import { type ElementLook } from '../types.ts';
+/** Rows of one state (the first state when the name is unknown). */
+export declare function rowsOf(look: ElementLook, state: string): readonly string[];
+/** Paint one state of a look into a 2D context, cell by cell. */
+export declare function paintLook(g: CanvasRenderingContext2D, look: ElementLook, state: string, cell: number, grid?: boolean): void;
+/** Props of {@link LookCanvas}. */
+export interface LookCanvasProps {
+    readonly look: ElementLook;
+    readonly state?: string;
+    /** Box edge in CSS px; the look scales to the largest whole cell that fits. */
+    readonly box: number;
+    readonly grid?: boolean;
+    readonly className?: string | undefined;
+    /** Editor mode: called with the cell under the pointer while painting. */
+    readonly onPaint?: (x: number, y: number) => void;
+}
+/** One look on a checkerboard, crisp at any size. */
+export declare function LookCanvas({ look, state, box, grid, className, onPaint }: LookCanvasProps): ReactNode;
+/** Replace one cell of one state; returns a new look. */
+export declare function setCell(look: ElementLook, state: string, x: number, y: number, char: string): ElementLook;
+/** Swap one palette color for another everywhere (整体换色). */
+export declare function recolor(look: ElementLook, index: number, color: string): ElementLook;
+/** The palette index for a color, appending it when new; returns the new look and the row char. */
+export declare function ensureColor(look: ElementLook, color: string): {
+    look: ElementLook;
+    char: string;
+};
+/** A blank 16×16 look in a palette, for elements that have none yet. */
+export declare function blankLook(palette: readonly string[]): ElementLook;
+//# sourceMappingURL=looks.d.ts.map

package/lib/types/client/looks.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Element looks in the panel: the same pixel rows the game draws through
+ * `dshDraw`, painted onto a small canvas. The canvas is the content here
+ * (the element's own colors), so no theme token applies to the pixels.
+ */
+import { useEffect, useRef } from 'react';
+import { LOOK_CHARS } from "../types.js";
+import css from './GameTab.module.css';
+/** Rows of one state (the first state when the name is unknown). */
+export function rowsOf(look, state) {
+    return look.states[state] ?? Object.values(look.states)[0] ?? [];
+}
+/** Paint one state of a look into a 2D context, cell by cell. */
+export function paintLook(g, look, state, cell, grid = false) {
+    const rows = rowsOf(look, state);
+    const w = rows[0]?.length ?? 0;
+    g.clearRect(0, 0, w * cell, rows.length * cell);
+    rows.forEach((row, y) => {
+        for (let x = 0; x < row.length; x++) {
+            const color = look.palette[LOOK_CHARS.indexOf(row[x])];
+            if (color === undefined)
+                continue;
+            g.fillStyle = color;
+            g.fillRect(x * cell, y * cell, cell, cell);
+        }
+    });
+    if (grid && cell >= 6) {
+        g.strokeStyle = 'rgba(127,127,127,0.18)'; /* panel-check: allow-color — editor grid over the element's own pixels */
+        g.lineWidth = 1;
+        for (let x = 0; x <= w; x++) {
+            g.beginPath();
+            g.moveTo(x * cell + 0.5, 0);
+            g.lineTo(x * cell + 0.5, rows.length * cell);
+            g.stroke();
+        }
+        for (let y = 0; y <= rows.length; y++) {
+            g.beginPath();
+            g.moveTo(0, y * cell + 0.5);
+            g.lineTo(w * cell, y * cell + 0.5);
+            g.stroke();
+        }
+    }
+}
+/** One look on a checkerboard, crisp at any size. */
+export function LookCanvas({ look, state = 'idle', box, grid = false, className, onPaint }) {
+    const ref = useRef(null);
+    const rows = rowsOf(look, state);
+    const w = Math.max(1, rows[0]?.length ?? 1);
+    const h = Math.max(1, rows.length);
+    const cell = Math.max(1, Math.floor(box / Math.max(w, h)));
+    const painting = useRef(false);
+    useEffect(() => {
+        const g = ref.current?.getContext('2d');
+        if (g)
+            paintLook(g, look, state, cell, grid);
+    }, [look, state, cell, grid]);
+    const cellAt = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        const x = Math.floor((event.clientX - rect.left) / rect.width * w);
+        const y = Math.floor((event.clientY - rect.top) / rect.height * h);
+        return x >= 0 && y >= 0 && x < w && y < h ? [x, y] : undefined;
+    };
+    const paint = (event) => {
+        const at = cellAt(event);
+        if (at && onPaint)
+            onPaint(at[0], at[1]);
+    };
+    return _jsx("canvas", { ref: ref, className: [css.look, className].filter(Boolean).join(' '), width: w * cell, height: h * cell, "data-editable": onPaint ? 'true' : 'false', ...(onPaint ? {
+            onPointerDown: (e) => { painting.current = true; e.currentTarget.setPointerCapture(e.pointerId); paint(e); },
+            onPointerMove: (e) => { if (painting.current)
+                paint(e); },
+            onPointerUp: () => { painting.current = false; },
+            onPointerCancel: () => { painting.current = false; },
+        } : {}) });
+}
+/** Replace one cell of one state; returns a new look. */
+export function setCell(look, state, x, y, char) {
+    const name = look.states[state] ? state : Object.keys(look.states)[0];
+    const rows = [...rowsOf(look, name)];
+    const row = rows[y];
+    if (row === undefined || row[x] === char)
+        return look;
+    rows[y] = row.slice(0, x) + char + row.slice(x + 1);
+    return { ...look, states: { ...look.states, [name]: rows } };
+}
+/** Swap one palette color for another everywhere (整体换色). */
+export function recolor(look, index, color) {
+    if (index < 0 || index >= look.palette.length)
+        return look;
+    return { ...look, palette: look.palette.map((c, i) => (i === index ? color : c)) };
+}
+/** The palette index for a color, appending it when new; returns the new look and the row char. */
+export function ensureColor(look, color) {
+    const at = look.palette.findIndex(c => c.toLowerCase() === color.toLowerCase());
+    if (at >= 0)
+        return { look, char: LOOK_CHARS[at] };
+    if (look.palette.length >= LOOK_CHARS.length)
+        return { look, char: LOOK_CHARS[0] };
+    return { look: { ...look, palette: [...look.palette, color] }, char: LOOK_CHARS[look.palette.length] };
+}
+/** A blank 16×16 look in a palette, for elements that have none yet. */
+export function blankLook(palette) {
+    return { palette: palette.slice(0, 16), states: { idle: Array.from({ length: 16 }, () => '.'.repeat(16)) } };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * A deliberately small markdown view for design chapters: headings, lists,
+ * quotes, pipe tables and paragraphs. No HTML passes through — every line is
+ * rendered as text.
+ */
+import type { ReactNode } from 'react';
+/** Render chapter text. */
+export declare function Markdown({ text }: {
+    text: string;
+}): ReactNode;
+//# sourceMappingURL=markdown.d.ts.map

package/lib/types/client/markdown.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import css from './GameTab.module.css';
+/** Split a pipe-table row into its cells. */
+function cells(line) {
+    return line.trim().replace(/^\||\|$/g, '').split('|').map(c => c.trim());
+}
+/** Render chapter text. */
+export function Markdown({ text }) {
+    const lines = text.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '')
+            continue;
+        const heading = /^(#{1,3})\s+(.*)$/.exec(line);
+        if (heading !== null) {
+            out.push(heading[1].length === 1 ? _jsx("h3", { className: css.mdH1, children: heading[2] }, i) : _jsx("h4", { className: css.mdH2, children: heading[2] }, i));
+            continue;
+        }
+        if (/^\s*\|/.test(line)) {
+            const rows = [];
+            while (i < lines.length && /^\s*\|/.test(lines[i] ?? '')) {
+                const row = lines[i] ?? '';
+                if (!/^\s*\|[\s:|-]+\|\s*$/.test(row))
+                    rows.push(cells(row));
+                i++;
+            }
+            i--;
+            const [head, ...body] = rows;
+            out.push(_jsx("div", { className: css.mdTableWrap, children: _jsxs("table", { className: css.mdTable, children: [head !== undefined && _jsx("thead", { children: _jsx("tr", { children: head.map((c, j) => _jsx("th", { children: c }, j)) }) }), _jsx("tbody", { children: body.map((r, k) => _jsx("tr", { children: r.map((c, j) => _jsx("td", { children: c }, j)) }, k)) })] }) }, i));
+            continue;
+        }
+        if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+            const items = [];
+            const ordered = /^\s*\d+\./.test(line);
+            while (i < lines.length && /^\s*([-*]|\d+\.)\s+/.test(lines[i] ?? '')) {
+                items.push((lines[i] ?? '').replace(/^\s*([-*]|\d+\.)\s+/, ''));
+                i++;
+            }
+            i--;
+            const list = items.map((item, k) => _jsx("li", { children: item }, k));
+            out.push(ordered ? _jsx("ol", { className: css.mdList, children: list }, i) : _jsx("ul", { className: css.mdList, children: list }, i));
+            continue;
+        }
+        if (line.startsWith('>')) {
+            out.push(_jsx("blockquote", { className: css.mdQuote, children: line.replace(/^>\s?/, '') }, i));
+            continue;
+        }
+        out.push(_jsx("p", { className: css.mdP, children: line }, i));
+    }
+    return _jsx("div", { className: css.md, children: out });
+}

package/lib/types/client/preset-visibility.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The preset-composition visibility of the game right-Sidebar tab type (the
+ * canvas dual check, docs/plugin-visibility.md). The tab renders the current
+ * session's bound project, so it shows exactly where the session reaches the
+ * game tools, by either grant path of the `./agent` entry:
+ *
+ * 1. **Profile-root mount** — the inventory's `entries` carry an ENABLED
+ *   `@khorsheed/dsh-game/agent` row → visible for every session.
+ * 2. **Preset mount** (the shipped shape: the root row disabled, the game
+ *   preset names the entry) → visible exactly when the CURRENT session's
+ *   preset composition names that row.
+ *
+ * Every unreadable path fails OPEN (visible): no pluginInventory namespace, a
+ * pending/failed RPC, a missing or `broken` preset group, a session with no
+ * preset, and the no-session home state. Hidden means NOT registered (the
+ * guide enumerates the tab-type registry; an opened tab of an unregistered
+ * kind renders the host's `tab.unavailable` fallback).
+ * @module @khorsheed/dsh-game/client/preset-visibility
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+/** The criterion's row: the game tools/prompt composition entry. */
+export declare const GAME_AGENT_ROW_MODULE = "@khorsheed/dsh-game/agent";
+/**
+ * Minimal structural mirror of the official pluginInventory snapshot — the
+ * entries slice (root grants) plus the agentPresets slice (preset grants),
+ * duck-typed and host-version tolerant.
+ */
+export interface GamePluginInventorySnapshot {
+    readonly entries?: readonly {
+        readonly moduleName: string;
+        readonly enabled?: boolean;
+    }[];
+    readonly agentPresets?: readonly {
+        readonly id: string;
+        readonly broken?: string;
+        readonly rows: readonly {
+            readonly moduleName: string;
+            readonly enabled?: boolean;
+        }[];
+    }[];
+}
+/**
+ * The tab's visibility controller: one inventory fetch per page (composition
+ * data changes only with preset files, which a reload re-reads anyway),
+ * re-evaluated by the toggle on every session switch.
+ */
+export declare class GameTabVisibility {
+    private readonly ctx;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    private composition;
+    private readonly listeners;
+    /**
+     * @param ctx - client root context.
+     * @param pluginInventory - the OFFICIAL namespace, probed through ctx.get
+     *   (never injected — declaring it would pend the whole client on a host
+     *   without it, and the criterion must fail open there).
+     */
+    constructor(ctx: Context, pluginInventory: {
+        list: () => Promise<RemoteResult<GamePluginInventorySnapshot>>;
+    } | undefined);
+    show(sessionId: SessionId | undefined): boolean;
+    /**
+     * Whether the session reaches any of `modules` by either grant path — the
+     * tab's criterion over the game agent row. Every unreadable path fails open, as above.
+     */
+    grantsAny(sessionId: SessionId | undefined, modules: readonly string[]): boolean;
+    /** Subscribe to criterion-input changes (session switches, the inventory answer). */
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+/**
+ * The tab type's registration toggle (the room template): registers exactly
+ * while the criterion passes for the current session and disposes otherwise.
+ * Unlike the keyed-slot consumers, the sidebarRightTabs registry is a direct
+ * inject — no slot-declaration wait, so the toggle is ready immediately.
+ */
+export declare class RegistrationToggle {
+    private readonly register;
+    private readonly show;
+    private dispose;
+    private ready;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register: () => () => void, show: () => boolean);
+    /** The registry is reachable — decisions may register now. */
+    setReady(ready: boolean): void;
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync(): void;
+}
+//# sourceMappingURL=preset-visibility.d.ts.map

package/lib/types/client/preset-visibility.js

@@ -0,0 +1,115 @@
+/** The criterion's row: the game tools/prompt composition entry. */
+export const GAME_AGENT_ROW_MODULE = '@khorsheed/dsh-game/agent';
+/** The current session's agent preset, the dual read per host line. */
+function presetOf(row) {
+    const value = row
+        ?.projectionValues?.agentPreset
+        ?? row?.agentPreset;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The tab's visibility controller: one inventory fetch per page (composition
+ * data changes only with preset files, which a reload re-reads anyway),
+ * re-evaluated by the toggle on every session switch.
+ */
+export class GameTabVisibility {
+    ctx;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    composition = null;
+    listeners = new Set();
+    /**
+     * @param ctx - client root context.
+     * @param pluginInventory - the OFFICIAL namespace, probed through ctx.get
+     *   (never injected — declaring it would pend the whole client on a host
+     *   without it, and the criterion must fail open there).
+     */
+    constructor(ctx, pluginInventory) {
+        this.ctx = ctx;
+        if (pluginInventory !== undefined) {
+            void pluginInventory.list().then(result => {
+                if (!result.ok)
+                    return;
+                this.composition = result.value ?? null;
+                this.notify();
+            }).catch(() => { });
+        }
+        // Session switches re-decide the tab type's registration (the guide
+        // enumerates registrations, not components).
+        ctx.effect(() => ctx.sessions.list.subscribe(() => { this.notify(); }), 'game: tab visibility session follower');
+    }
+    show(sessionId) {
+        return this.grantsAny(sessionId, [GAME_AGENT_ROW_MODULE]);
+    }
+    /**
+     * Whether the session reaches any of `modules` by either grant path — the
+     * tab's criterion over the game agent row. Every unreadable path fails open, as above.
+     */
+    grantsAny(sessionId, modules) {
+        if (this.composition === null)
+            return true;
+        // Path 1: a root-mounted agent row grants the tools to every session —
+        // a deployment-level constant, checked before any per-session question.
+        if (this.composition.entries?.some(row => modules.includes(row.moduleName) && row.enabled === true) === true)
+            return true;
+        if (sessionId === undefined)
+            return true;
+        const preset = presetOf(this.ctx.sessions.list.getSnapshot().byId[sessionId]);
+        if (preset === undefined)
+            return true;
+        const group = this.composition.agentPresets?.find(candidate => candidate.id === preset);
+        if (group === undefined || group.broken !== undefined)
+            return true;
+        // Path 2: the preset-mounted row grants this session.
+        return group.rows.some(row => modules.includes(row.moduleName) && row.enabled !== false);
+    }
+    /** Subscribe to criterion-input changes (session switches, the inventory answer). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * The tab type's registration toggle (the room template): registers exactly
+ * while the criterion passes for the current session and disposes otherwise.
+ * Unlike the keyed-slot consumers, the sidebarRightTabs registry is a direct
+ * inject — no slot-declaration wait, so the toggle is ready immediately.
+ */
+export class RegistrationToggle {
+    register;
+    show;
+    dispose;
+    ready = false;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register, show) {
+        this.register = register;
+        this.show = show;
+    }
+    /** The registry is reachable — decisions may register now. */
+    setReady(ready) {
+        this.ready = ready;
+        if (!ready && this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+        this.sync();
+    }
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync() {
+        if (!this.ready)
+            return;
+        if (this.show()) {
+            this.dispose ??= this.register();
+        }
+        else if (this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+    }
+}

package/lib/types/client/preview-entry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The 3D preview's in-frame entry (the element turntable, card stills,
+ * proposal stills): plain module source, run in the same sandbox as the play
+ * area on the live bundle. Kept apart from the React component so a spec can
+ * run it through the real checker.
+ *
+ * The camera is a perspective orbit around the model. Models face +x (the
+ * kit's convention, built-in bodies included), so yaw 0 looks at the face,
+ * 90 from the side, 180 from behind; pitch looks down from above. The default
+ * view is the look's `preview` (`{ yaw, pitch }` in degrees), else a
+ * three-quarter front view from slightly above. A turntable drifts until it
+ * is dragged (sideways turns, up and down tilts) or told which side to show.
+ * @module @khorsheed/dsh-game/client
+ */
+/** The id the previewed look rides under in `window.dshElements`. */
+export declare const PREVIEW_ID = "__preview";
+/** The default view: three-quarter front, a little from above. */
+export declare const PREVIEW_YAW = 35;
+export declare const PREVIEW_PITCH = 18;
+/** The preview entry module (it runs in the frame). */
+export declare const PREVIEW_MAIN = "\nconst { createWorld, build, THREE } = await import('dsh3d')\ntry { await import('../src/looks.js') } catch (e) {}\nconst mode = (await (await fetch('_preview/mode.json')).json()).mode\nconst world = createWorld({ canvas: document.querySelector('canvas') })\nconst cam = new THREE.PerspectiveCamera(32, 1, 0.05, 500)\nworld.setCamera(cam)\nconst deg = Math.PI / 180\nlet model = null, yaw = 35, pitch = 18, radius = 4, focusY = 0.5, drag = null, spinning = mode === 'spin', viewKey = null\nconst lookNow = () => window.dshElements['__preview'].look\n/** The look's own preview angle, taken again only when it changes (an edit must not reset a dragged view). */\nfunction viewFrom(look) {\n  const p = (look && look.preview) || {}, key = JSON.stringify(p)\n  if (key === viewKey) return\n  viewKey = key\n  yaw = Number.isFinite(p.yaw) ? p.yaw : 35\n  pitch = Number.isFinite(p.pitch) ? p.pitch : 18\n}\nfunction aim() {\n  pitch = Math.max(-10, Math.min(80, pitch))\n  const p = pitch * deg, y = yaw * deg\n  cam.position.set(Math.cos(p) * Math.cos(y) * radius, focusY + Math.sin(p) * radius, Math.cos(p) * Math.sin(y) * radius)\n  cam.lookAt(0, focusY, 0)\n}\n/** Stand the model on the origin and back the camera off far enough to frame it. */\nfunction place() {\n  model.position.set(0, 0, 0)\n  model.updateMatrixWorld(true)\n  const box = new THREE.Box3().setFromObject(model)\n  if (box.isEmpty()) return\n  const center = box.getCenter(new THREE.Vector3()), size = box.getSize(new THREE.Vector3())\n  model.position.set(-center.x, -box.min.y, -center.z)\n  focusY = size.y / 2\n  const r = Math.max(0.3, box.getBoundingSphere(new THREE.Sphere()).radius)\n  radius = r / Math.sin(cam.fov * deg / 2) * 1.08\n  aim()\n}\nasync function fit() {\n  if (model) world.remove(model)\n  const look = lookNow()\n  viewFrom(look)\n  // From the look object, not the id: the world's own rebuild-by-element must not touch the preview.\n  model = build(look)\n  world.add(model, { id: '__preview' })\n  place()\n  // A glTF look fills in later: measure again once it has, then say what it can be tuned by.\n  if (model.userData.loaded) { await model.userData.loaded; place() }\n  parent.postMessage({ gamedev: 'preview-clips', names: model.userData.animations ?? [], parts: model.userData.parts?.() ?? null }, '*')\n}\n/** What a rebuild depends on; anything else (tint, bones, morphs, angle, clip) is retuned in place. */\nconst rebuildKey = look => JSON.stringify(look && look.kind === 'gltf' ? [look.src, look.material, look.outline, look.scale] : look)\nlet builtKey = null\nfunction edited() {\n  const look = lookNow(), key = rebuildKey(look)\n  if (model && key === builtKey && model.userData.retune) { model.userData.retune(look); viewFrom(look); return }\n  builtKey = key\n  fit()\n}\naddEventListener('message', e => {\n  const d = e.data\n  if (!d || !model) return\n  if (d.gamedev === 'preview-play') model.userData.play?.(d.name)\n  if (d.gamedev === 'preview-view') { yaw = d.yaw; if (Number.isFinite(d.pitch)) pitch = d.pitch; spinning = false; aim(); world.render() }\n})\nbuiltKey = rebuildKey(lookNow())\nawait fit()\naddEventListener('dshelements', () => { setTimeout(edited) })\nconst canvas = world.canvas\ncanvas.addEventListener('pointerdown', e => { drag = { x: e.clientX, y: e.clientY }; spinning = false; canvas.setPointerCapture(e.pointerId) })\ncanvas.addEventListener('pointermove', e => {\n  if (drag === null) return\n  yaw -= (e.clientX - drag.x) * 0.5\n  pitch += (e.clientY - drag.y) * 0.35\n  drag = { x: e.clientX, y: e.clientY }\n})\ncanvas.addEventListener('pointerup', () => { drag = null })\nworld.onUpdate(dt => { if (spinning && drag === null) yaw += dt * 18; aim() })\n// The checks (and specs) can drive this page like a game.\nwindow.dshGame = { ready: true, step: dt => world.step(dt), input() {}, state: () => ({ yaw, pitch, radius, focusY, perspective: world.camera === cam, spinning }) }\nif (mode === 'still') {\n  world.step(0.4)\n  parent.postMessage({ gamedev: 'preview', png: canvas.toDataURL('image/png') }, '*')\n} else world.start()\n";
+/** The preview page: a full-size canvas and the entry above. */
+export declare const PREVIEW_HTML: string;
+//# sourceMappingURL=preview-entry.d.ts.map

package/lib/types/client/preview-entry.js

@@ -0,0 +1,107 @@
+/**
+ * The 3D preview's in-frame entry (the element turntable, card stills,
+ * proposal stills): plain module source, run in the same sandbox as the play
+ * area on the live bundle. Kept apart from the React component so a spec can
+ * run it through the real checker.
+ *
+ * The camera is a perspective orbit around the model. Models face +x (the
+ * kit's convention, built-in bodies included), so yaw 0 looks at the face,
+ * 90 from the side, 180 from behind; pitch looks down from above. The default
+ * view is the look's `preview` (`{ yaw, pitch }` in degrees), else a
+ * three-quarter front view from slightly above. A turntable drifts until it
+ * is dragged (sideways turns, up and down tilts) or told which side to show.
+ * @module @khorsheed/dsh-game/client
+ */
+/** The id the previewed look rides under in `window.dshElements`. */
+export const PREVIEW_ID = '__preview';
+/** The default view: three-quarter front, a little from above. */
+export const PREVIEW_YAW = 35;
+export const PREVIEW_PITCH = 18;
+/** The preview entry module (it runs in the frame). */
+export const PREVIEW_MAIN = `
+const { createWorld, build, THREE } = await import('dsh3d')
+try { await import('../src/looks.js') } catch (e) {}
+const mode = (await (await fetch('_preview/mode.json')).json()).mode
+const world = createWorld({ canvas: document.querySelector('canvas') })
+const cam = new THREE.PerspectiveCamera(32, 1, 0.05, 500)
+world.setCamera(cam)
+const deg = Math.PI / 180
+let model = null, yaw = ${PREVIEW_YAW}, pitch = ${PREVIEW_PITCH}, radius = 4, focusY = 0.5, drag = null, spinning = mode === 'spin', viewKey = null
+const lookNow = () => window.dshElements['${PREVIEW_ID}'].look
+/** The look's own preview angle, taken again only when it changes (an edit must not reset a dragged view). */
+function viewFrom(look) {
+  const p = (look && look.preview) || {}, key = JSON.stringify(p)
+  if (key === viewKey) return
+  viewKey = key
+  yaw = Number.isFinite(p.yaw) ? p.yaw : ${PREVIEW_YAW}
+  pitch = Number.isFinite(p.pitch) ? p.pitch : ${PREVIEW_PITCH}
+}
+function aim() {
+  pitch = Math.max(-10, Math.min(80, pitch))
+  const p = pitch * deg, y = yaw * deg
+  cam.position.set(Math.cos(p) * Math.cos(y) * radius, focusY + Math.sin(p) * radius, Math.cos(p) * Math.sin(y) * radius)
+  cam.lookAt(0, focusY, 0)
+}
+/** Stand the model on the origin and back the camera off far enough to frame it. */
+function place() {
+  model.position.set(0, 0, 0)
+  model.updateMatrixWorld(true)
+  const box = new THREE.Box3().setFromObject(model)
+  if (box.isEmpty()) return
+  const center = box.getCenter(new THREE.Vector3()), size = box.getSize(new THREE.Vector3())
+  model.position.set(-center.x, -box.min.y, -center.z)
+  focusY = size.y / 2
+  const r = Math.max(0.3, box.getBoundingSphere(new THREE.Sphere()).radius)
+  radius = r / Math.sin(cam.fov * deg / 2) * 1.08
+  aim()
+}
+async function fit() {
+  if (model) world.remove(model)
+  const look = lookNow()
+  viewFrom(look)
+  // From the look object, not the id: the world's own rebuild-by-element must not touch the preview.
+  model = build(look)
+  world.add(model, { id: '${PREVIEW_ID}' })
+  place()
+  // A glTF look fills in later: measure again once it has, then say what it can be tuned by.
+  if (model.userData.loaded) { await model.userData.loaded; place() }
+  parent.postMessage({ gamedev: 'preview-clips', names: model.userData.animations ?? [], parts: model.userData.parts?.() ?? null }, '*')
+}
+/** What a rebuild depends on; anything else (tint, bones, morphs, angle, clip) is retuned in place. */
+const rebuildKey = look => JSON.stringify(look && look.kind === 'gltf' ? [look.src, look.material, look.outline, look.scale] : look)
+let builtKey = null
+function edited() {
+  const look = lookNow(), key = rebuildKey(look)
+  if (model && key === builtKey && model.userData.retune) { model.userData.retune(look); viewFrom(look); return }
+  builtKey = key
+  fit()
+}
+addEventListener('message', e => {
+  const d = e.data
+  if (!d || !model) return
+  if (d.gamedev === 'preview-play') model.userData.play?.(d.name)
+  if (d.gamedev === 'preview-view') { yaw = d.yaw; if (Number.isFinite(d.pitch)) pitch = d.pitch; spinning = false; aim(); world.render() }
+})
+builtKey = rebuildKey(lookNow())
+await fit()
+addEventListener('dshelements', () => { setTimeout(edited) })
+const canvas = world.canvas
+canvas.addEventListener('pointerdown', e => { drag = { x: e.clientX, y: e.clientY }; spinning = false; canvas.setPointerCapture(e.pointerId) })
+canvas.addEventListener('pointermove', e => {
+  if (drag === null) return
+  yaw -= (e.clientX - drag.x) * 0.5
+  pitch += (e.clientY - drag.y) * 0.35
+  drag = { x: e.clientX, y: e.clientY }
+})
+canvas.addEventListener('pointerup', () => { drag = null })
+world.onUpdate(dt => { if (spinning && drag === null) yaw += dt * 18; aim() })
+// The checks (and specs) can drive this page like a game.
+window.dshGame = { ready: true, step: dt => world.step(dt), input() {}, state: () => ({ yaw, pitch, radius, focusY, perspective: world.camera === cam, spinning }) }
+if (mode === 'still') {
+  world.step(0.4)
+  parent.postMessage({ gamedev: 'preview', png: canvas.toDataURL('image/png') }, '*')
+} else world.start()
+`;
+/** The preview page: a full-size canvas and the entry above. */
+export const PREVIEW_HTML = '<style>html,body{margin:0;height:100%;overflow:hidden}canvas{width:100%;height:100%;display:block;touch-action:none}</style>'
+    + '<canvas></canvas><script type="module" src="_preview/main.js"></script>';

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

@@ -0,0 +1,36 @@
+/**
+ * Game reference chips: what a pick in the play area (or an element card)
+ * puts into the composer. The chip shows a short label; the model receives
+ * the full reference text — element name and id, instance, position, region
+ * and state — so it knows exactly which thing the user means.
+ * @module @khorsheed/dsh-game/client
+ */
+import type { PickRef } from '../vfs.ts';
+/** The trigger-source name the chip codec registers under. */
+export declare const GAME_REF_SOURCE = "dsh-game-ref";
+/** Encode a chip payload. */
+export declare function encodeGameRef(ref: {
+    readonly label: string;
+    readonly text: string;
+}): string;
+/** Decode a chip payload; undefined on corruption. */
+export declare function decodeGameRef(raw: string): {
+    label: string;
+    text: string;
+} | undefined;
+/** The codec: the model receives the full text; a corrupt chip refuses the send (the host restores the draft). */
+export declare const gameRefCodec: {
+    clipboardText: (raw: string) => string;
+    serialize: (raw: string) => Promise<string>;
+};
+/**
+ * A pick as a chip: the label the user sees, the text the model gets.
+ * @param ref - what the game's `pick` answered (a bare id becomes `{ id }`).
+ * @param name - the element's name, when the id names one.
+ * @param groundLabel - the localized word for the ground.
+ */
+export declare function pickChip(ref: PickRef, name: string | undefined, groundLabel: string): {
+    label: string;
+    text: string;
+};
+//# sourceMappingURL=refs.d.ts.map

package/lib/types/client/refs.js

@@ -0,0 +1,44 @@
+/** The trigger-source name the chip codec registers under. */
+export const GAME_REF_SOURCE = 'dsh-game-ref';
+/** Encode a chip payload. */
+export function encodeGameRef(ref) {
+    return JSON.stringify({ v: 1, label: ref.label, text: ref.text });
+}
+/** Decode a chip payload; undefined on corruption. */
+export function decodeGameRef(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.text === 'string' && typeof parsed.label === 'string' ? { label: parsed.label, text: parsed.text } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The codec: the model receives the full text; a corrupt chip refuses the send (the host restores the draft). */
+export const gameRefCodec = {
+    clipboardText: (raw) => decodeGameRef(raw)?.text ?? raw,
+    serialize: async (raw) => {
+        const text = decodeGameRef(raw)?.text;
+        if (text === undefined)
+            throw new Error('@khorsheed/dsh-game: corrupt game reference chip');
+        return text;
+    },
+};
+const num = (n) => String(Math.round(n * 10) / 10);
+/**
+ * A pick as a chip: the label the user sees, the text the model gets.
+ * @param ref - what the game's `pick` answered (a bare id becomes `{ id }`).
+ * @param name - the element's name, when the id names one.
+ * @param groundLabel - the localized word for the ground.
+ */
+export function pickChip(ref, name, groundLabel) {
+    const where = ref.point === undefined ? '' : `(${num(ref.point.x)}, ${num(ref.point.z)})`;
+    if (ref.ground === true || ref.id === null) {
+        const label = [groundLabel, ref.region ?? where].filter(Boolean).join(' · ');
+        return { label, text: `〔${[groundLabel, ref.region, where].filter(Boolean).join(' · ')}〕` };
+    }
+    const title = name ?? ref.name ?? ref.id;
+    const label = [title, ref.state].filter(Boolean).join(' · ');
+    const idPart = ref.inst !== undefined && ref.inst !== null && ref.inst !== ref.id ? `${ref.id} #${ref.inst}` : ref.id;
+    return { label, text: `〔${[`${title}（${idPart}）`, [ref.region, where].filter(Boolean).join(' '), ref.state].filter(Boolean).join(' · ')}〕` };
+}

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