@khorsheed/dsh-game 0.0.0-stage → 0.1.0

package/lib/types/client/PlayFrame.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The play frame: one version in a `sandbox="allow-scripts"` iframe (an
+ * opaque origin — no cookies, no host storage, no network by the frame's own
+ * CSP), fed by postMessage through the shared loader. Saves live in this
+ * browser's localStorage per project; slider values are pushed in live
+ * (element edits wait for a committed version); the pick overlay asks the game what is under a click.
+ * When a play session ends (version change, restart, unmount) its length and
+ * errors go to the playtest log.
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { shellHtml } from "../vfs.js";
+import css from './GameTab.module.css';
+/** localStorage key for one project's saves. */
+const savesKey = (projectId) => `dsh-game:saves:${projectId}`;
+function readSaves(projectId) {
+    try {
+        const raw = localStorage.getItem(savesKey(projectId));
+        const parsed = raw === null ? {} : JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeSaves(projectId, saves) {
+    try {
+        localStorage.setItem(savesKey(projectId), JSON.stringify(saves));
+    }
+    catch {
+        // Storage blocked or full: the game keeps its in-frame copy for this session.
+    }
+}
+/** Forget a project's saves (重开存档). */
+export function clearSaves(projectId) {
+    try {
+        localStorage.removeItem(savesKey(projectId));
+    }
+    catch {
+        // Nothing to clear.
+    }
+}
+/** The sandboxed frame with a pick overlay. */
+export function PlayFrame({ projectId, version, files, run, params, picking, onPicked, hoverLabel, highlight, onErrors, onReport, label }) {
+    const frame = useRef(null);
+    const shell = useMemo(() => shellHtml(), []);
+    const report = useRef(onReport);
+    report.current = onReport;
+    const errorsCb = useRef(onErrors);
+    errorsCb.current = onErrors;
+    const pickedCb = useRef(onPicked);
+    pickedCb.current = onPicked;
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    const [booted, setBooted] = useState(false);
+    const [hover, setHover] = useState(null);
+    const hoverLabelRef = useRef(hoverLabel);
+    hoverLabelRef.current = hoverLabel;
+    const shiftRef = useRef(false);
+    const pointer = useRef({ x: 0, y: 0 });
+    const hoverTimer = useRef(0);
+    useEffect(() => {
+        const started = Date.now();
+        const seen = [];
+        errorsCb.current([]);
+        setBooted(false);
+        const onMessage = (event) => {
+            if (event.source !== frame.current?.contentWindow)
+                return;
+            const data = event.data;
+            if (data?.gamedev === 'error') {
+                if (seen.length < 50)
+                    seen.push(data.msg);
+                errorsCb.current([...seen]);
+            }
+            else if (data?.gamedev === 'save') {
+                writeSaves(projectId, data.saves);
+            }
+            else if (data?.gamedev === 'picked') {
+                const ref = data.ref ?? (data.id === null ? null : { id: data.id });
+                if (data.hover)
+                    setHover(ref === null ? null : { text: hoverLabelRef.current(ref), ...pointer.current });
+                else
+                    pickedCb.current({ ref, supported: data.supported, shift: shiftRef.current });
+            }
+        };
+        window.addEventListener('message', onMessage);
+        return () => {
+            window.removeEventListener('message', onMessage);
+            const seconds = (Date.now() - started) / 1000;
+            if (seconds >= 5 || seen.length > 0)
+                report.current({ version, seconds, errors: seen });
+        };
+    }, [projectId, version, run]);
+    const post = (message) => { frame.current?.contentWindow?.postMessage(message, '*'); };
+    useEffect(() => { if (booted)
+        post({ gamedev: 'params', values: params }); }, [params, booted]);
+    // 「指一下」 freezes the game (games that implement pause); leaving it resumes.
+    useEffect(() => { if (booted)
+        post({ gamedev: 'pause', on: picking }); if (!picking)
+        setHover(null); }, [picking, booted]);
+    const highlightKey = JSON.stringify(highlight);
+    useEffect(() => { if (booted)
+        post({ gamedev: 'highlight', list: highlight ?? [] }); }, [highlightKey, booted]); // eslint-disable-line react-hooks/exhaustive-deps -- the key stands for the list
+    const boot = () => {
+        if (booted)
+            return;
+        post({ gamedev: 'files', files, saves: readSaves(projectId), params: paramsRef.current });
+        setBooted(true);
+    };
+    const pick = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        shiftRef.current = event.shiftKey;
+        post({ gamedev: 'pick', x: (event.clientX - rect.left) / rect.width, y: (event.clientY - rect.top) / rect.height });
+    };
+    // Hover asks the game too (throttled), so the user sees what a click would pick.
+    const hoverAt = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        pointer.current = { x: event.clientX - rect.left, y: event.clientY - rect.top };
+        const now = Date.now();
+        if (now - hoverTimer.current < 90)
+            return;
+        hoverTimer.current = now;
+        post({ gamedev: 'pick', hover: true, x: pointer.current.x / rect.width, y: pointer.current.y / rect.height });
+    };
+    return _jsxs("div", { className: css.stageInner, "data-picking": picking ? 'true' : 'false', children: [_jsx("iframe", { ref: frame, className: css.frame, title: label, 
+                // Pointer lock: a game may grab the mouse for camera turns (a click asks, Esc releases).
+                sandbox: "allow-scripts allow-pointer-lock", srcDoc: shell, onLoad: boot }, `${version}:${run}`), picking && _jsx("div", { className: css.pickLayer, onClick: pick, onMouseMove: hoverAt, onMouseLeave: () => { setHover(null); }, role: "presentation" }), picking && hover !== null && _jsx("span", { className: css.pickHover, style: { left: hover.x, top: hover.y }, children: hover.text })] });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 试玩: the stage (the version on the play area, framed like a game screen,
+ * with its status strip), the candidate bar when a version waits for the
+ * user, the last check's verdict when it failed, the pick mode, and the
+ * parameter drawer — sliders that change the running game at once, marked
+ * amber where they differ from the finalized value (定稿 / 还原).
+ */
+import { type ReactNode } from 'react';
+import { type ProjectView } from '../types.ts';
+import { type ViewProps } from './contract.ts';
+/** Props of the play view. */
+export interface PlayViewProps extends ViewProps {
+    readonly project: ProjectView;
+    readonly onOpenElement: (id: string) => void;
+    readonly onOpenVersions: () => void;
+}
+/** The play view. */
+export declare function PlayView(props: PlayViewProps): ReactNode;
+//# sourceMappingURL=PlayView.d.ts.map

package/lib/types/client/PlayView.js

@@ -0,0 +1,161 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 试玩: the stage (the version on the play area, framed like a game screen,
+ * with its status strip), the candidate bar when a version waits for the
+ * user, the last check's verdict when it failed, the pick mode, and the
+ * parameter drawer — sliders that change the running game at once, marked
+ * amber where they differ from the finalized value (定稿 / 还原).
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { PANEL_CHANGES_MARK } from "../types.js";
+import { failureOf } from "./contract.js";
+import { LookCanvas } from "./looks.js";
+import { clearSaves, PlayFrame } from "./PlayFrame.js";
+import { pickChip } from "./refs.js";
+import css from './GameTab.module.css';
+/** A 3D look's main color, for the small swatch beside a pick. */
+function look3dColor(look) {
+    const recipe = look.kind === 'parts3d' ? look : look.recipe;
+    return recipe?.palette.body ?? Object.values(recipe?.palette ?? {})[0];
+}
+/** Round a slider value to its step for display. */
+function fmt(value, step) {
+    const decimals = Math.max(0, Math.min(4, -Math.floor(Math.log10(step))));
+    return value.toFixed(decimals);
+}
+/** The play view. */
+export function PlayView(props) {
+    const { t, sessionId, api, project, refresh, toast, insertDraft, insertRef, onOpenElement, onOpenVersions } = props;
+    const [which, setWhich] = useState('current');
+    const [bundle, setBundle] = useState(null);
+    const [error, setError] = useState(null);
+    const [run, setRun] = useState(0);
+    const [errors, setErrors] = useState([]);
+    const [picking, setPicking] = useState(false);
+    const [picked, setPicked] = useState(null);
+    const [diffOn, setDiffOn] = useState(true);
+    const [rejecting, setRejecting] = useState(false);
+    const [reason, setReason] = useState('');
+    const record = which === 'candidate' ? project.candidate : project.current;
+    const version = record?.version;
+    const loaded = useRef('');
+    // Playing is opt-in (2026-10-10): a big game should not start, and cost, on
+    // every visit. A new version stops the old run and shows its poster.
+    const [playing, setPlaying] = useState(false);
+    const [poster, setPoster] = useState(null);
+    useEffect(() => { setPlaying(false); setPicking(false); setPicked(null); }, [version, which]);
+    useEffect(() => {
+        let live = true;
+        // The poster of the version on screen (a version without its own shows none, never another build's).
+        void api.checkShot(project.id, version).then(r => { if (live)
+            setPoster(r.ok && r.value.ok ? r.value.webp : null); });
+        return () => { live = false; };
+    }, [api, project.id, version, project.lastCheck?.at]);
+    useEffect(() => { if (project.candidate === null && which === 'candidate')
+        setWhich('current'); }, [project.candidate, which]);
+    useEffect(() => {
+        if (!playing)
+            return;
+        if (version === undefined) {
+            setBundle(null);
+            loaded.current = '';
+            return;
+        }
+        const key = `${project.id}:${which}:${version}`;
+        if (loaded.current === key)
+            return;
+        let live = true;
+        void api.bundle(project.id, which).then(result => {
+            if (!live)
+                return;
+            if (result.ok && result.value.ok) {
+                loaded.current = key;
+                setBundle(result.value.bundle);
+                setError(null);
+            }
+            else
+                setError(failureOf(result) ?? 'io');
+        });
+        return () => { live = false; };
+    }, [api, project.id, which, version, playing]);
+    // Live slider values: the finalized defaults overlaid with the user's layer.
+    const params = project.manifest?.params ?? [];
+    const [local, setLocal] = useState({});
+    useEffect(() => { setLocal({}); }, [project.paramOverrides]);
+    const values = useMemo(() => Object.fromEntries(params.map(p => [p.key, local[p.key] ?? project.paramOverrides[p.key] ?? p.value])), [params, local, project.paramOverrides]);
+    const tuned = params.filter(p => values[p.key] !== p.value);
+    const commit = useRef({});
+    const slide = (param, value) => {
+        setLocal(l => ({ ...l, [param.key]: value }));
+        clearTimeout(commit.current[param.key]);
+        commit.current[param.key] = setTimeout(() => {
+            void api.setParam(sessionId, project.id, param.key, value).then(refresh);
+        }, 250);
+    };
+    const report = (r) => { void api.logPlay(sessionId, { projectId: project.id, ...r }); };
+    const pickedElement = picked?.id ? project.elements.find(e => e.id === picked.id) : undefined;
+    const nameOf = (id) => (id === null ? undefined : project.elements.find(e => e.id === id)?.name);
+    const chipOf = (ref) => pickChip(ref, nameOf(ref.id), t('play.ground'));
+    // A pick goes straight into the composer as a chip (G5); Shift keeps picking for a second reference.
+    const onPicked = (answer) => {
+        if (!answer.supported) {
+            toast(t('play.pickUnsupported'));
+            return;
+        }
+        if (answer.ref === null) {
+            toast(t('play.pickNothing'));
+            return;
+        }
+        const chip = chipOf(answer.ref);
+        if (insertRef(chip))
+            toast(t('play.inserted', { label: chip.label }));
+        setPicked({ id: answer.ref.ground === true ? null : answer.ref.id, label: chip.label });
+        if (!answer.shift)
+            setPicking(false);
+    };
+    const diff = project.candidateDiff;
+    const diffCount = diff === null ? 0 : diff.changed.length + diff.added.length;
+    const highlight = which === 'candidate' && diffOn && diff !== null
+        ? [...diff.changed.map(id => ({ id, tone: 'changed' })), ...diff.added.map(id => ({ id, tone: 'added' }))]
+        : null;
+    const check = project.lastCheck;
+    return _jsxs("div", { className: css.scroll, children: [check !== null && !check.ok && _jsxs("button", { type: "button", className: css.strip, "data-tone": check.gaveUp ? 'warn' : 'error', onClick: onOpenVersions, children: [_jsx("span", { className: css.stripDot, "aria-hidden": "true" }), _jsx("span", { children: check.gaveUp ? t('play.checkGaveUp') : t('play.checkFailed') }), _jsx("span", { className: css.stripMeta, children: check.failures[0]?.where }), _jsx("span", { className: css.stripGo, children: t('play.seeChecks') })] }), project.restyleTo !== undefined && _jsxs("div", { className: css.strip, "data-tone": "info", children: [_jsx("span", { className: css.stripDot, "aria-hidden": "true" }), _jsx("span", { children: t('play.restyling') })] }), _jsxs("section", { className: css.stage, "aria-label": t('tabs.play'), children: [_jsxs("div", { className: css.stageBar, children: [_jsx("span", { className: css.versionPill, "data-tone": which === 'candidate' ? 'warn' : 'ok', children: version === undefined ? t('meta.noVersion') : `${which === 'candidate' ? t('play.candidateShort') : t('play.live')} v${version}` }), _jsx("span", { className: css.stageHint, children: !playing ? t('play.idleHint') : picking ? t('play.pickHint') : t('play.focus') }), errors.length > 0 && _jsx("span", { className: css.errorPill, title: errors.slice(0, 5).join('\n'), children: t('play.errors', { count: errors.length }) }), _jsx("span", { className: css.spacer }), playing && bundle !== null && which === 'candidate' && diffCount > 0 && _jsx("button", { type: "button", className: css.stageBtn, "aria-pressed": diffOn, title: t('play.diffHint'), onClick: () => { setDiffOn(on => !on); }, children: t('play.diff') }), playing && bundle !== null && _jsx("button", { type: "button", className: css.stageBtn, "aria-pressed": picking, onClick: () => { setPicking(p => !p); setPicked(null); }, children: t('play.pick') }), playing && bundle !== null && _jsx("button", { type: "button", className: css.stageBtn, onClick: () => { setRun(n => n + 1); }, children: t('play.restart') }), playing && _jsx("button", { type: "button", className: css.stageBtn, onClick: () => { setPlaying(false); setPicking(false); setPicked(null); }, children: t('play.stop') })] }), _jsxs("div", { className: css.screen, children: [error !== null && _jsx("p", { className: css.screenNote, children: t('play.loadFailed', { error }) }), version === undefined
+                                ? _jsxs("div", { className: css.screenEmpty, children: [_jsx("div", { className: css.screenGlyph, "aria-hidden": "true", children: "\u25B6" }), _jsx("p", { children: project.hasEntry ? t('play.none') : t('play.noEntry') })] })
+                                : !playing
+                                    ? _jsxs("button", { type: "button", className: css.poster, onClick: () => { setPlaying(true); }, "aria-label": t('play.start', { version }), children: [poster !== null && _jsx("img", { src: `data:image/webp;base64,${poster}`, alt: "" }), _jsxs("span", { className: css.posterPlay, children: [_jsx("span", { className: css.posterIcon, "aria-hidden": "true", children: "\u25B6" }), t('play.start', { version })] })] })
+                                    : bundle !== null && _jsx(PlayFrame, { projectId: project.id, version: bundle.version, files: bundle.files, run: run, params: values, picking: picking, label: `${project.title} v${bundle.version}`, onPicked: onPicked, hoverLabel: ref => chipOf(ref).label, highlight: highlight, onErrors: setErrors, onReport: report })] }), project.candidate !== null && _jsxs("div", { className: css.candBar, "data-tone": "warn", children: [_jsxs("div", { className: css.bannerText, children: [_jsx("strong", { children: t('play.candidateTitle', { version: project.candidate.version }) }), _jsx("span", { children: project.candidate.note ?? t('play.candidate') })] }), _jsxs("div", { className: css.bannerActions, children: [_jsx("button", { type: "button", className: css.ghost, "aria-pressed": which === 'candidate', onClick: () => { setWhich(w => (w === 'candidate' ? 'current' : 'candidate')); }, children: which === 'candidate' ? t('play.backToCurrent') : t('play.tryCandidate') }), _jsx("button", { type: "button", className: css.ghost, onClick: () => { setRejecting(r => !r); }, children: t('play.reject') }), _jsx("button", { type: "button", className: css.primary, onClick: () => {
+                                            void api.confirm(sessionId, project.id).then(r => { if (!failureOf(r))
+                                                toast(t('toast.confirmed', { version: project.candidate.version })); setWhich('current'); refresh(); });
+                                        }, children: t('play.confirm') })] }), rejecting && _jsxs("div", { className: css.rejectRow, children: [_jsx("input", { className: css.input, value: reason, placeholder: t('play.rejectReason'), onChange: e => { setReason(e.target.value); } }), _jsx("button", { type: "button", className: css.ghost, onClick: () => {
+                                            const rejected = project.candidate?.version;
+                                            void api.reject(sessionId, project.id, reason).then(() => {
+                                                setRejecting(false);
+                                                setReason('');
+                                                setWhich('current');
+                                                if (rejected !== undefined)
+                                                    toast(t('nudge.rejected', { version: rejected }));
+                                                refresh();
+                                            });
+                                        }, children: t('play.rejectGo') })] })] }), picked !== null && _jsxs("div", { className: css.pickCard, children: [pickedElement !== undefined && pickedElement.look !== null ? _jsx(LookCanvas, { look: pickedElement.look, box: 32 })
+                                : _jsx("span", { className: css.swatch, style: pickedElement?.look3d != null ? { background: look3dColor(pickedElement.look3d) } : undefined }), _jsxs("span", { className: css.pickName, children: [_jsx("strong", { children: picked.label }), _jsx("span", { className: css.metaLine, children: t('play.pickedNote') })] }), pickedElement !== undefined && _jsx("button", { type: "button", className: css.ghost, onClick: () => { onOpenElement(pickedElement.id); }, children: t('play.openElement') })] })] }), params.length > 0 && _jsxs("section", { className: css.drawer, "aria-label": t('params.title'), children: [_jsxs("header", { className: css.drawerHead, children: [_jsx("strong", { children: t('params.title') }), _jsx("span", { className: css.metaLine, children: tuned.length > 0 ? t('params.changed', { count: tuned.length }) : t('params.hint') }), _jsx("span", { className: css.spacer }), _jsx("button", { type: "button", className: css.ghost, disabled: tuned.length === 0, onClick: () => {
+                                    void api.resetParams(sessionId, project.id).then(() => { setLocal({}); refresh(); });
+                                }, children: t('params.reset') }), _jsx("button", { type: "button", className: css.ghost, disabled: tuned.length === 0, onClick: () => {
+                                    const list = tuned.map(p => `${p.label} ${fmt(p.value, p.step)}→${fmt(values[p.key] ?? p.value, p.step)}`).join('、');
+                                    if (insertDraft(`${PANEL_CHANGES_MARK}${t('params.tellLead', { list })}\n\n`))
+                                        toast(t('toast.drafted'));
+                                }, children: t('params.tell') }), _jsx("button", { type: "button", className: css.ghost, disabled: tuned.length === 0, onClick: () => {
+                                    // 定稿 writes the defaults into game.json and commits at once: the play area moves to a version that has them.
+                                    void api.finalizeParams(sessionId, project.id).then(() => api.commit(sessionId, project.id)).then(r => {
+                                        setLocal({});
+                                        const result = failureOf(r) === undefined && r.ok && r.value.ok ? r.value : undefined;
+                                        toast(result?.kind === 'deployed' ? t('commit.deployed', { version: result.version })
+                                            : result?.kind === 'candidate' ? t('commit.candidate', { version: result.version })
+                                                : result?.kind === 'failed' ? t('commit.failedToast') : t('nudge.finalized'));
+                                        refresh();
+                                    });
+                                }, children: t('params.finalize') })] }), params.map(p => {
+                        const value = values[p.key] ?? p.value;
+                        const dirty = value !== p.value;
+                        return _jsxs("label", { className: css.param, "data-dirty": dirty ? 'true' : 'false', children: [_jsx("span", { className: css.paramLabel, children: p.label }), _jsx("input", { type: "range", min: p.min, max: p.max, step: p.step, value: value, className: css.range, onChange: e => { slide(p, Number(e.target.value)); } }), _jsxs("span", { className: css.paramValue, children: [fmt(value, p.step), p.unit === undefined ? '' : _jsxs("small", { children: [" ", p.unit] })] }), dirty && _jsx("span", { className: css.paramWas, title: t('params.was'), children: fmt(p.value, p.step) })] }, p.key);
+                    })] }), params.length === 0 && version !== undefined && _jsx("p", { className: css.lead, children: t('params.none') }), version !== undefined && _jsx("div", { className: css.footRow, children: _jsx("button", { type: "button", className: css.link, onClick: () => { clearSaves(project.id); setRun(n => n + 1); toast(t('toast.savesCleared')); }, children: t('play.clearSaves') }) })] });
+}

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

@@ -0,0 +1,50 @@
+/**
+ * 3D look previews in the panel: the element turntable, the proposal cards
+ * and the turn card's before/after. Every preview runs in the same sandbox as
+ * the play area, on the project's live version bundle (kit files and the
+ * project's own `src/looks.js` registrations included) with a preview entry
+ * swapped in — so the panel never carries a second copy of the builder, and
+ * what it shows is exactly what the game builds.
+ *
+ * The camera and the in-frame entry live in `preview-entry.ts`: a
+ * perspective orbit that faces the model (yaw 0 = its +x front).
+ *
+ * `spin` keeps a live, draggable turntable that follows look edits; `still`
+ * renders once, posts a PNG back and is replaced by that image (cached per
+ * look, so a scrolled-back card costs nothing). Stills render a couple at a
+ * time — a grid of element cards would otherwise open a WebGL context per
+ * card at once — and show their `placeholder` until the image arrives.
+ */
+import { type ReactNode } from 'react';
+import type { Look3D } from '../types.ts';
+import { type ModelParts } from '../vfs.ts';
+import type { GameApi } from './contract.ts';
+/** Props of {@link Preview3D}. */
+export interface Preview3DProps {
+    readonly api: GameApi;
+    readonly projectId: string;
+    /** The live version; previews need one to run (kit files and project registrations ride in it). */
+    readonly version: number | undefined;
+    readonly look: Look3D;
+    readonly mode: 'spin' | 'still';
+    readonly className?: string | undefined;
+    /** Shown while there is no live version yet. */
+    readonly emptyLabel: string;
+    /** Shown instead of `emptyLabel`, and under a still while it renders. */
+    readonly placeholder?: ReactNode;
+    /** A turntable reports a model's animation clips, and what it can be tuned by, once it has loaded. */
+    readonly onClips?: (names: readonly string[], parts: ModelParts | null) => void;
+    /** A turntable plays this clip (bump `n` to play the same one again). */
+    readonly clip?: {
+        readonly name: string;
+        readonly n: number;
+    } | null;
+    /** A turntable turns to this side (yaw in degrees: 0 front, 90 side, 180 back; bump `n` to repeat). */
+    readonly view?: {
+        readonly yaw: number;
+        readonly n: number;
+    } | null;
+}
+/** One 3D look preview. */
+export declare function Preview3D({ api, projectId, version, look, mode, className, emptyLabel, placeholder, onClips, clip, view }: Preview3DProps): ReactNode;
+//# sourceMappingURL=Preview3D.d.ts.map

package/lib/types/client/Preview3D.js

@@ -0,0 +1,176 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 3D look previews in the panel: the element turntable, the proposal cards
+ * and the turn card's before/after. Every preview runs in the same sandbox as
+ * the play area, on the project's live version bundle (kit files and the
+ * project's own `src/looks.js` registrations included) with a preview entry
+ * swapped in — so the panel never carries a second copy of the builder, and
+ * what it shows is exactly what the game builds.
+ *
+ * The camera and the in-frame entry live in `preview-entry.ts`: a
+ * perspective orbit that faces the model (yaw 0 = its +x front).
+ *
+ * `spin` keeps a live, draggable turntable that follows look edits; `still`
+ * renders once, posts a PNG back and is replaced by that image (cached per
+ * look, so a scrolled-back card costs nothing). Stills render a couple at a
+ * time — a grid of element cards would otherwise open a WebGL context per
+ * card at once — and show their `placeholder` until the image arrives.
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { shellHtml } from "../vfs.js";
+import { failureOf } from "./contract.js";
+import { PREVIEW_HTML, PREVIEW_ID, PREVIEW_MAIN } from "./preview-entry.js";
+import css from './GameTab.module.css';
+/** Live version bundles per project, fetched once per version (three.js rides in them). */
+const bundles = new Map();
+function liveBundle(api, projectId, version) {
+    const key = `${projectId}:${version}`;
+    let pending = bundles.get(key);
+    if (pending === undefined) {
+        pending = api.bundle(projectId, 'current').then(r => (failureOf(r) === undefined && r.ok && r.value.ok ? r.value.bundle.files : null));
+        bundles.set(key, pending);
+    }
+    return pending;
+}
+/** The working copy of a glTF look's file (a model exported moments ago may not be in any version yet). */
+async function withModel(api, projectId, look, files) {
+    if (files === null || look.kind !== 'gltf')
+        return files;
+    const r = await api.workingFile(projectId, look.src);
+    return failureOf(r) === undefined && r.ok && r.value.ok ? { ...files, [look.src]: r.value.file } : files;
+}
+/** Still images per look (and project version, whose style and registrations shape it). */
+const stills = new Map();
+/** Stills rendering at once; the rest wait their turn. */
+const STILL_SLOTS = 2;
+/** A still that never posts its image gives its slot back after this long. */
+const STILL_TIMEOUT_MS = 15_000;
+let stillsRunning = 0;
+const stillQueue = [];
+/** Wait for a render slot; the returned function gives it back (idempotent). */
+function stillSlot() {
+    let granted = false;
+    let released = false;
+    let grant;
+    const ready = new Promise(resolve => { grant = () => { granted = true; stillsRunning++; resolve(); }; });
+    if (stillsRunning < STILL_SLOTS)
+        grant();
+    else
+        stillQueue.push(grant);
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        if (!granted) {
+            const at = stillQueue.indexOf(grant);
+            if (at >= 0)
+                stillQueue.splice(at, 1);
+            return;
+        }
+        stillsRunning--;
+        stillQueue.shift()?.();
+    };
+    return { ready, release };
+}
+/** One 3D look preview. */
+export function Preview3D({ api, projectId, version, look, mode, className, emptyLabel, placeholder, onClips, clip, view }) {
+    const lookJson = JSON.stringify(look);
+    const stillKey = `${projectId}:${version}:${lookJson}`;
+    const [files, setFiles] = useState(null);
+    const [image, setImage] = useState(mode === 'still' ? stills.get(stillKey) ?? null : null);
+    const [visible, setVisible] = useState(mode === 'spin');
+    const box = useRef(null);
+    const frame = useRef(null);
+    const booted = useRef(false);
+    const shell = useMemo(() => shellHtml(), []);
+    // A glTF look's file: switching it reloads the frame (other look edits stream in live).
+    const modelSrc = look.kind === 'gltf' ? look.src : '';
+    useEffect(() => { booted.current = false; }, [modelSrc]);
+    // A still follows its key (a new live version or an edited look): start over from the cache or a fresh render.
+    useEffect(() => {
+        if (mode !== 'still')
+            return;
+        setImage(stills.get(stillKey) ?? null);
+        setFiles(null);
+        booted.current = false;
+    }, [mode, stillKey]);
+    // Stills wait until they scroll into view: a long chat history costs nothing until read.
+    useEffect(() => {
+        if (visible || box.current === null)
+            return;
+        const io = new IntersectionObserver(entries => { if (entries.some(e => e.isIntersecting))
+            setVisible(true); });
+        io.observe(box.current);
+        return () => { io.disconnect(); };
+    }, [visible]);
+    useEffect(() => {
+        if (version === undefined || !visible || image !== null)
+            return;
+        let live = true;
+        if (mode === 'spin') {
+            void liveBundle(api, projectId, version).then(f => withModel(api, projectId, look, f)).then(f => { if (live)
+                setFiles(f); });
+            return () => { live = false; };
+        }
+        // A still holds a render slot from loading until its image lands (or it times out).
+        const slot = stillSlot();
+        let timer;
+        void slot.ready.then(() => liveBundle(api, projectId, version)).then(f => withModel(api, projectId, look, f)).then(f => {
+            if (!live)
+                return;
+            if (f === null) {
+                slot.release();
+                return;
+            }
+            timer = setTimeout(slot.release, STILL_TIMEOUT_MS);
+            setFiles(f);
+        });
+        return () => { live = false; clearTimeout(timer); slot.release(); };
+    }, [api, projectId, version, visible, image, mode, modelSrc]); // eslint-disable-line react-hooks/exhaustive-deps -- look is read for its model file only (modelSrc)
+    useEffect(() => {
+        const onMessage = (event) => {
+            if (event.source !== frame.current?.contentWindow)
+                return;
+            const data = event.data;
+            if (data?.gamedev === 'preview' && mode === 'still') {
+                stills.set(stillKey, data.png);
+                setImage(data.png);
+            }
+            if (data?.gamedev === 'preview-clips' && mode === 'spin')
+                onClips?.(data.names, data.parts);
+        };
+        window.addEventListener('message', onMessage);
+        return () => { window.removeEventListener('message', onMessage); };
+    }, [mode, stillKey, onClips]);
+    useEffect(() => {
+        if (view == null || mode !== 'spin' || !booted.current)
+            return;
+        frame.current?.contentWindow?.postMessage({ gamedev: 'preview-view', yaw: view.yaw }, '*');
+    }, [view, mode]);
+    useEffect(() => {
+        if (clip == null || mode !== 'spin' || !booted.current)
+            return;
+        frame.current?.contentWindow?.postMessage({ gamedev: 'preview-play', name: clip.name }, '*');
+    }, [clip, mode]);
+    // A spinning preview follows look edits live (the same element message the play area gets).
+    useEffect(() => {
+        if (mode !== 'spin' || !booted.current)
+            return;
+        frame.current?.contentWindow?.postMessage({ gamedev: 'element', element: { id: PREVIEW_ID, name: PREVIEW_ID, type: 'preview', look } }, '*');
+    }, [lookJson, mode]); // eslint-disable-line react-hooks/exhaustive-deps -- lookJson stands for look
+    const boot = () => {
+        if (files === null || booted.current)
+            return;
+        const previewFiles = {
+            ...files,
+            'index.html': { type: 'text/html', text: PREVIEW_HTML },
+            '_preview/main.js': { type: 'text/javascript', text: PREVIEW_MAIN },
+            '_preview/mode.json': { type: 'application/json', text: JSON.stringify({ mode }) },
+            [`elements/${PREVIEW_ID}.json`]: { type: 'application/json', text: JSON.stringify({ id: PREVIEW_ID, name: PREVIEW_ID, type: 'preview', look }) },
+        };
+        frame.current?.contentWindow?.postMessage({ gamedev: 'files', files: previewFiles, saves: {}, params: {} }, '*');
+        booted.current = true;
+    };
+    const waiting = placeholder ?? (version === undefined ? _jsx("span", { className: css.preview3dNote, children: emptyLabel }) : null);
+    return _jsx("div", { ref: box, className: [css.preview3d, className].filter(Boolean).join(' '), children: image !== null ? _jsx("img", { src: image, alt: "" }) : _jsxs(_Fragment, { children: [(mode === 'still' || version === undefined) && waiting, version !== undefined && files !== null && _jsx("iframe", { ref: frame, className: css.preview3dFrame, "data-mode": mode, title: "preview", sandbox: "allow-scripts", srcDoc: shell, onLoad: boot }, modelSrc)] }) });
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The project switcher: every game as a card — the last check's screen, the
+ * title, live version, art style, element count, last change and the pitch —
+ * with the session's own project marked. The first card starts a new game:
+ * creation goes through the agent (the light gate needs the user's pitch,
+ * element kinds and style), so it writes an opener into the composer.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from './contract.ts';
+/** Props of the switcher. */
+export interface ProjectSwitcherProps extends ViewProps {
+    readonly currentId: string | null;
+    /** Re-fetch trigger (state revision). */
+    readonly rev: number;
+    readonly onChoose: (projectId: string | null) => void;
+    readonly onNew: () => void;
+}
+/** The card grid. */
+export declare function ProjectSwitcher({ t, api, sessionId, currentId, rev, onChoose, onNew, refresh, toast }: ProjectSwitcherProps): ReactNode;
+//# sourceMappingURL=ProjectSwitcher.d.ts.map

package/lib/types/client/ProjectSwitcher.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The project switcher: every game as a card — the last check's screen, the
+ * title, live version, art style, element count, last change and the pitch —
+ * with the session's own project marked. The first card starts a new game:
+ * creation goes through the agent (the light gate needs the user's pitch,
+ * element kinds and style), so it writes an opener into the composer.
+ */
+import { useEffect, useState } from 'react';
+import { artStyleLabel } from "../project.js";
+import { failureOf } from "./contract.js";
+import css from './GameTab.module.css';
+/** "3 分钟前" style relative time. */
+function ago(t, iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return '';
+    const min = Math.round(ms / 60000);
+    if (min < 1)
+        return t('switcher.justNow');
+    if (min < 60)
+        return t('switcher.minutes', { count: min });
+    const h = Math.round(min / 60);
+    if (h < 24)
+        return t('switcher.hours', { count: h });
+    return t('switcher.days', { count: Math.round(h / 24) });
+}
+/** The last path segment (the project folder), the full path goes in the tooltip. */
+function folderOf(root) {
+    return root.split(/[\\/]/).filter(Boolean).pop() ?? root;
+}
+/** The card grid. */
+export function ProjectSwitcher({ t, api, sessionId, currentId, rev, onChoose, onNew, refresh, toast }) {
+    const [cards, setCards] = useState(null);
+    const [reload, setReload] = useState(0);
+    // The card being deleted: its inline confirmation, and the last failure to explain there.
+    const [confirming, setConfirming] = useState(null);
+    const [busy, setBusy] = useState(false);
+    useEffect(() => {
+        let live = true;
+        void api.projectCards().then(r => { if (live)
+            setCards(r.ok ? r.value : []); }).catch(() => { if (live)
+            setCards([]); });
+        return () => { live = false; };
+    }, [api, rev, reload]);
+    const remove = (card, mode) => {
+        setBusy(true);
+        void api.deleteProject(sessionId, card.id, mode).then(r => {
+            setBusy(false);
+            const failure = failureOf(r);
+            if (failure !== undefined) {
+                const why = r.ok && !r.value.ok ? r.value.reason ?? '' : '';
+                const reason = failure === 'trash-failed' ? t('switcher.deleteTrashFailed', { reason: why })
+                    : failure === 'not-a-project' ? t('switcher.deleteNotProject')
+                        : failure === 'is-workspace' ? t('switcher.deleteIsWorkspace')
+                            : failure === 'denied' ? t('switcher.deleteDenied') : failure;
+                setConfirming({ id: card.id, error: reason });
+                return;
+            }
+            setConfirming(null);
+            toast(mode === 'trash' ? t('switcher.deletedTrash', { title: card.title }) : t('switcher.deletedForget', { title: card.title }));
+            setReload(n => n + 1);
+            refresh();
+        });
+    };
+    return _jsxs("div", { className: css.projectGrid, children: [_jsxs("button", { type: "button", className: css.newCard, onClick: onNew, children: [_jsx("span", { className: css.newPlus, "aria-hidden": "true", children: "\uFF0B" }), _jsx("strong", { children: t('switcher.new') }), _jsx("span", { className: css.metaLine, children: t('switcher.newHint') })] }), cards === null && _jsx("div", { className: css.projectCard, "data-loading": "true", children: _jsx("span", { className: css.metaLine, children: t('loading') }) }), cards?.map(card => {
+                const current = card.id === currentId;
+                if (confirming?.id === card.id) {
+                    return _jsx("div", { className: css.projectCard, "data-confirm": "true", role: "group", "aria-label": t('switcher.deleteTitle', { title: card.title }), children: _jsxs("span", { className: css.projectBody, children: [_jsx("strong", { className: css.projectTitle, children: t('switcher.deleteTitle', { title: card.title }) }), _jsx("span", { className: css.metaLine, children: t('switcher.deleteBody', { folder: card.root }) }), confirming.error !== undefined && _jsx("span", { className: css.deleteError, children: confirming.error }), _jsxs("span", { className: css.deleteActions, children: [_jsx("button", { type: "button", className: css.danger, disabled: busy, onClick: () => { remove(card, 'trash'); }, children: t('switcher.deleteTrash') }), _jsx("button", { type: "button", className: css.ghost, disabled: busy, onClick: () => { remove(card, 'forget'); }, children: t('switcher.deleteForget') }), _jsx("button", { type: "button", className: css.link, disabled: busy, onClick: () => { setConfirming(null); }, children: t('switcher.deleteCancel') })] })] }) }, card.id);
+                }
+                return _jsxs("div", { className: css.projectCardWrap, children: [_jsxs("button", { type: "button", className: css.projectCard, "aria-current": current ? 'true' : undefined, title: card.root, onClick: () => { onChoose(card.id); }, children: [_jsxs("span", { className: css.projectThumb, children: [card.thumb !== undefined
+                                            ? _jsx("img", { src: `data:image/webp;base64,${card.thumb}`, alt: "" })
+                                            : _jsx("span", { className: css.projectInitial, children: card.title.slice(0, 1) }), current && _jsx("span", { className: css.projectHere, children: t('switcher.here') })] }), _jsxs("span", { className: css.projectBody, children: [_jsx("strong", { className: css.projectTitle, children: card.title }), _jsxs("span", { className: css.projectChips, children: [_jsx("span", { className: css.headChip, "data-tone": card.version === null ? 'muted' : 'ok', children: card.version === null ? t('switcher.noVersion') : `v${card.version}` }), card.artStyle !== '' && _jsx("span", { className: css.headChip, children: artStyleLabel(card.artStyle) }), _jsx("span", { className: css.headChip, children: t('switcher.elements', { count: card.elements }) })] }), card.pitch !== '' && _jsx("span", { className: css.projectPitch, children: card.pitch }), _jsxs("span", { className: css.metaLine, children: [ago(t, card.updatedAt), " \u00B7 ", folderOf(card.root)] })] })] }), _jsx("button", { type: "button", className: css.projectDelete, "aria-label": t('switcher.delete', { title: card.title }), title: t('switcher.delete', { title: card.title }), onClick: () => { setConfirming({ id: card.id }); }, children: "\u00D7" })] }, card.id);
+            })] });
+}