@khorsheed/dsh-game 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,131 @@
+/**
+ * The game tab's injected face and props.
+ * @module @khorsheed/dsh-game/client
+ */
+import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { Reveal } from './reveal.ts';
+import type { BundleFile, LiveVersion, CommitResult, DeleteProjectResult, WorkingChanges, GameResult, PlayBundle, ProjectCard, SessionGameState, TurnReport, VersionDiff } from '../types.ts';
+type R<T> = Promise<RemoteResult<T>>;
+type Ok<T extends object = object> = GameResult<{
+    readonly ok: true;
+} & T>;
+/** Every call the panel makes, already bound to the Remote. */
+export interface GameApi {
+    state: (sid: SessionId) => R<SessionGameState>;
+    liveVersion: (sid: SessionId) => R<LiveVersion | null>;
+    projectCards: () => R<ProjectCard[]>;
+    turnReport: (sid: SessionId, turn: number) => R<TurnReport | null>;
+    bind: (sid: SessionId, projectId: string | null) => R<Ok>;
+    deleteProject: (sid: SessionId, projectId: string, mode: 'trash' | 'forget') => R<DeleteProjectResult>;
+    bundle: (projectId: string, which: 'current' | 'candidate') => R<Ok<{
+        readonly bundle: PlayBundle;
+    }>>;
+    versionBundle: (projectId: string, version: number) => R<Ok<{
+        readonly bundle: PlayBundle;
+    }>>;
+    workingFile: (projectId: string, path: string) => R<Ok<{
+        readonly file: BundleFile;
+    }>>;
+    confirm: (sid: SessionId, projectId: string) => R<Ok<{
+        readonly version: number;
+    }>>;
+    commit: (sid: SessionId, projectId: string) => R<GameResult<CommitResult>>;
+    changes: (projectId: string) => R<GameResult<WorkingChanges & {
+        readonly ok: true;
+    }>>;
+    reject: (sid: SessionId, projectId: string, reason: string) => R<Ok>;
+    rollback: (sid: SessionId, projectId: string, version: number) => R<Ok>;
+    diff: (projectId: string, from: number, to: number) => R<Ok<{
+        readonly diff: VersionDiff;
+    }>>;
+    checkShot: (projectId: string, version?: number) => R<Ok<{
+        readonly webp: string;
+    }>>;
+    setAutoConfirm: (sid: SessionId, projectId: string, on: boolean) => R<Ok>;
+    logPlay: (sid: SessionId, entry: {
+        projectId: string;
+        version: number;
+        seconds: number;
+        errors: string[];
+    }) => R<Ok>;
+    setParam: (sid: SessionId, projectId: string, key: string, value: number) => R<Ok>;
+    finalizeParams: (sid: SessionId, projectId: string) => R<Ok>;
+    resetParams: (sid: SessionId, projectId: string) => R<Ok>;
+    editElement: (sid: SessionId, projectId: string, elementId: string, patch: {
+        look?: string;
+        fields?: string;
+    }) => R<Ok<{
+        readonly elementJson: string;
+    }>>;
+    pickProposal: (sid: SessionId, projectId: string, elementId: string, at: string, index: number) => R<Ok>;
+    writeChapter: (sid: SessionId, projectId: string, chapterId: string, text: string) => R<Ok>;
+    requestRestyle: (sid: SessionId, projectId: string, styleId: string) => R<Ok>;
+    setOnePager: (sid: SessionId, projectId: string, patch: {
+        pitch?: string;
+        elementTypes?: string;
+        pillars?: string;
+    }) => R<Ok>;
+    dropPending: (sid: SessionId, projectId: string, key: string) => R<Ok>;
+}
+/** Where a jump into the game tab lands. */
+export interface NavTarget {
+    readonly view: 'play' | 'elements' | 'design' | 'versions';
+    readonly elementId?: string;
+    readonly chapterId?: string;
+}
+/** What the tab body gets from the plugin. */
+export interface GameTabInjected {
+    /** Open the game tab at a place (the turn card's 查看). */
+    openAt: (target: NavTarget) => void;
+    /** The tab body follows jumps; returns the unsubscribe. */
+    subscribeNav: (listener: (target: NavTarget) => void) => () => void;
+    /** A jump made before the tab body mounted, taken once. */
+    takeNav: () => NavTarget | null;
+    api: GameApi;
+    /** Put text into the session's composer draft (appended; never sent). False when there is no composer. */
+    insertDraft: (sessionId: SessionId, text: string) => boolean;
+    /**
+     * Put a reference into the session's composer as one chip (`label` shown,
+     * `text` what the model receives); falls back to appending `text` as plain
+     * draft text where the host has no chip seam. Never sends.
+     */
+    insertRef: (sessionId: SessionId, ref: {
+        readonly label: string;
+        readonly text: string;
+    }) => boolean;
+    /** Turn-boundary pushes, plus the panel's own mutations, per session id. */
+    subscribeSessionEvents: (listener: (sessionId: string) => void) => () => void;
+    /** Tell every game surface of this page that a session's state moved. */
+    touch: (sessionId: SessionId) => void;
+    /** Carries out the agent's 「请用户看这里」 (page-wide). */
+    reveal: Reveal;
+}
+/** Full props of the game tab body. */
+export type GameTabProps = PropsRuntime<'sidebar.right.pane.tab'> & InjectFace<GameTabInjected> & PropsLocale<'game'>;
+/** What every view inside the tab receives. */
+export interface ViewProps {
+    readonly t: GameTabProps['t'];
+    readonly sessionId: GameTabProps['sessionId'];
+    readonly api: GameApi;
+    readonly insertDraft: (text: string) => boolean;
+    /** Insert a reference chip into the composer (see `GameTabInjected.insertRef`). */
+    readonly insertRef: (ref: {
+        readonly label: string;
+        readonly text: string;
+    }) => boolean;
+    /** Re-read the state after a mutation (and tell the other game surfaces). */
+    readonly refresh: () => void;
+    /** Show a short confirmation line at the panel's foot. */
+    readonly toast: (text: string) => void;
+    /** Carries out the agent's 「请用户看这里」 (page-wide). */
+    readonly reveal: Reveal;
+}
+/** A Remote call's game-level failure code, or undefined on success. */
+export declare function failureOf(result: RemoteResult<{
+    ok: boolean;
+    error?: string;
+}>): string | undefined;
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/contract.js

@@ -0,0 +1,6 @@
+/** A Remote call's game-level failure code, or undefined on success. */
+export function failureOf(result) {
+    if (!result.ok)
+        return result.error.message;
+    return result.value.ok ? undefined : result.value.error ?? 'io';
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Stage one of the right-Sidebar registration: what the `game` tab type IS —
+ * a page (no address claims), opened from the guide or by kind.
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client';
+/** The tab kind this package owns. */
+export declare const GAME_KIND = "game";
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export declare const GAME_TAB_ID = "@khorsheed/dsh-game";
+/** The guide glyph: a gamepad on a tinted tile, in currentColor. */
+export declare function GameGlyph({ size, className }: {
+    size?: number | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * The type's registry definition (default `extension` band).
+ * @param t - namespace-bound translate.
+ * @returns the definition to register.
+ */
+export declare function gameDefinition(t: TranslateNS<'game'>): SidebarRightTabDefinition;
+//# sourceMappingURL=definition.d.ts.map

package/lib/types/client/definition.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The tab kind this package owns. */
+export const GAME_KIND = 'game';
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export const GAME_TAB_ID = '@khorsheed/dsh-game';
+/** The guide glyph: a gamepad on a tinted tile, in currentColor. */
+export function GameGlyph({ size = 16, className }) {
+    return (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: [_jsx("rect", { width: "16", height: "16", rx: "4", fill: "currentColor", fillOpacity: "0.1" }), _jsx("path", { d: "M5.2 5.5h5.6a2.6 2.6 0 0 1 2.5 1.9l.6 2.3a1.4 1.4 0 0 1-2.3 1.4L10.4 10H5.6l-1.2 1.1a1.4 1.4 0 0 1-2.3-1.4l.6-2.3a2.6 2.6 0 0 1 2.5-1.9Z", stroke: "currentColor", strokeWidth: "1.1", strokeLinejoin: "round" }), _jsx("path", { d: "M5.4 7v1.6M4.6 7.8h1.6", stroke: "currentColor", strokeWidth: "1.1", strokeLinecap: "round" }), _jsx("circle", { cx: "10.4", cy: "7.4", r: ".6", fill: "currentColor" }), _jsx("circle", { cx: "11.4", cy: "8.4", r: ".6", fill: "currentColor" })] }));
+}
+/**
+ * The type's registry definition (default `extension` band).
+ * @param t - namespace-bound translate.
+ * @returns the definition to register.
+ */
+export function gameDefinition(t) {
+    return {
+        id: GAME_TAB_ID,
+        kind: GAME_KIND,
+        title: () => t('tab.title'),
+        guide: [{
+                id: GAME_KIND,
+                order: 55,
+                title: () => t('guide.title'),
+                description: () => t('guide.description'),
+                icon: GameGlyph,
+            }],
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Game mode, browser half: mounts the `game` Remote, registers the `game`
+ * right-Sidebar tab type (self-hidden where the session cannot reach the game
+ * tools) and its body in the keyed pane seat. Turn-boundary pushes
+ * (`api-session/status` / `api-session/activity`, the two the official
+ * allowlist forwards) refresh the tab, which is how a version deployed at the
+ * end of a turn reaches the play area.
+ * @module @khorsheed/dsh-game/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { GAME_KIND, GAME_TAB_ID } from './definition.tsx';
+import { GameTab } from './GameTab.tsx';
+export { GameTab, GAME_KIND, GAME_TAB_ID };
+/** `remote.game` is mounted here and read back through ctx.get (never injected — that would deadlock the loader). */
+export declare const inject: string[];
+/**
+ * Client plugin body.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,263 @@
+import gameRemote from '@khorsheed/dsh-game/remote';
+import { GAME_CHAT_KIND, GameChatRow, gameMessageDefinition } from "./chat-node.js";
+import { gameTurnDefinition, GameTurnCard } from "./TurnCard.js";
+import { Reveal } from "./reveal.js";
+import { encodeGameRef, GAME_REF_SOURCE, gameRefCodec } from "./refs.js";
+import { GAME_KIND, GAME_TAB_ID, gameDefinition } from "./definition.js";
+import { GameTab } from "./GameTab.js";
+import { en, NS, zh } from "./locales.js";
+import { GameTabVisibility, RegistrationToggle } from "./preset-visibility.js";
+export { GameTab, GAME_KIND, GAME_TAB_ID };
+function mainSessionId(list) {
+    const view = list;
+    return Object.values(view.byId).find(s => (s.retainedBy?.mainView ?? 0) > 0)?.id ?? view.current;
+}
+/** `remote.game` is mounted here and read back through ctx.get (never injected — that would deadlock the loader). */
+export const inject = ['slots', 'remote', 'locale', 'sessions', 'sidebarRight', 'sidebarRightTabs'];
+/**
+ * Client plugin body.
+ * @param ctx - client root context.
+ */
+export async function apply(ctx) {
+    const disposers = [];
+    try {
+        disposers.push(await ctx.remote.$mount(gameRemote));
+    }
+    catch (error) {
+        /* v8 ignore next -- double-mount is a composition error, not a runtime path */
+        ctx.logger.error(error);
+    }
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'game: dictionaries');
+    const t = ctx.locale.bind(NS);
+    const remote = ctx.get('remote.game');
+    const pluginInventory = ctx.get('remote.pluginInventory');
+    const listeners = new Set();
+    const emit = (sessionId) => { for (const listener of listeners)
+        listener(sessionId); };
+    const carrier = ctx.remote;
+    if (typeof carrier.$on === 'function') {
+        for (const forwarded of ['api-session/status', 'api-session/activity']) {
+            const off = carrier.$on(forwarded, (sessionId) => { emit(sessionId); });
+            disposers.push(async () => { off(); });
+        }
+    }
+    const tabVisibility = new GameTabVisibility(ctx, pluginInventory);
+    ctx.effect(() => {
+        const toggle = new RegistrationToggle(() => ctx.sidebarRightTabs.register(gameDefinition(t)), () => tabVisibility.show(mainSessionId(ctx.sessions.list.getSnapshot())));
+        toggle.setReady(true);
+        const unsubscribe = tabVisibility.subscribe(() => { toggle.sync(); });
+        return () => { unsubscribe(); toggle.setReady(false); };
+    }, 'game: tab type visibility');
+    const api = {
+        state: sid => remote.state(sid),
+        liveVersion: sid => remote.liveVersion(sid),
+        projectCards: () => remote.projectCards(),
+        turnReport: (sid, turn) => remote.turnReport(sid, { turn }),
+        bind: (sid, projectId) => remote.bind(sid, { projectId }),
+        deleteProject: (sid, projectId, mode) => remote.deleteProject(sid, { projectId, mode }),
+        bundle: (projectId, which) => remote.bundle({ projectId, which }),
+        versionBundle: (projectId, version) => remote.versionBundle({ projectId, version }),
+        workingFile: (projectId, path) => remote.workingFile({ projectId, path }),
+        confirm: (sid, projectId) => remote.confirm(sid, { projectId }),
+        commit: (sid, projectId) => remote.commit(sid, { projectId }),
+        changes: projectId => remote.changes({ projectId }),
+        reject: (sid, projectId, reason) => remote.reject(sid, { projectId, reason }),
+        rollback: (sid, projectId, version) => remote.rollback(sid, { projectId, version }),
+        diff: (projectId, from, to) => remote.diff({ projectId, from, to }),
+        checkShot: (projectId, version) => remote.checkShot({ projectId, ...(version === undefined ? {} : { version }) }),
+        setAutoConfirm: (sid, projectId, on) => remote.setAutoConfirm(sid, { projectId, on }),
+        logPlay: (sid, entry) => remote.logPlay(sid, entry),
+        setParam: (sid, projectId, key, value) => remote.setParam(sid, { projectId, key, value }),
+        finalizeParams: (sid, projectId) => remote.finalizeParams(sid, { projectId }),
+        resetParams: (sid, projectId) => remote.resetParams(sid, { projectId }),
+        editElement: (sid, projectId, elementId, patch) => remote.editElement(sid, { projectId, elementId, ...patch }),
+        pickProposal: (sid, projectId, elementId, at, index) => remote.pickProposal(sid, { projectId, elementId, at, index }),
+        writeChapter: (sid, projectId, chapterId, text) => remote.writeChapter(sid, { projectId, chapterId, text }),
+        requestRestyle: (sid, projectId, styleId) => remote.requestRestyle(sid, { projectId, styleId }),
+        setOnePager: (sid, projectId, patch) => remote.setOnePager(sid, { projectId, ...patch }),
+        dropPending: (sid, projectId, key) => remote.dropPending(sid, { projectId, key }),
+    };
+    // Reference chips (the quote precedent): a headless trigger source carries
+    // the codec the submit-time serializer resolves by source name; the chip
+    // itself rides the scoped `slash/input-insert-reference` bail event. The
+    // source registers on a deferred inject arm (mount order is unconstrained);
+    // without the service, or when the host declines, the reference falls back
+    // to plain draft text.
+    let chipsReady = false;
+    ctx.inject(['inputTriggers'], (lctx) => {
+        lctx.effect(() => {
+            try {
+                const service = lctx.get('inputTriggers');
+                if (service === undefined)
+                    return () => { };
+                const dispose = service.registerSource({
+                    trigger: '@',
+                    name: GAME_REF_SOURCE,
+                    candidates: async () => [],
+                    onPick: () => undefined,
+                    codec: gameRefCodec,
+                    openReference: () => false,
+                });
+                chipsReady = true;
+                return () => { chipsReady = false; dispose(); };
+            }
+            catch (error) {
+                ctx.logger.error(error);
+                return () => { };
+            }
+        }, 'game: reference chips');
+    });
+    const inputFor = (sessionId) => {
+        try {
+            const scope = ctx.get('sessions')?.scope?.(sessionId);
+            const input = scope?.get('conversation')?.input?.for(scope);
+            const face = input;
+            return typeof face?.setDraft === 'function' && typeof face.state?.getSnapshot === 'function' ? face : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const navListeners = new Set();
+    let parkedNav = null;
+    const reveal = new Reveal(target => { face.openAt(target); });
+    const face = {
+        openAt: (target) => {
+            parkedNav = target;
+            try {
+                ctx.sidebarRight.openTab(GAME_KIND);
+            }
+            catch (error) {
+                ctx.logger.warn('game: openTab failed (tab type not registered?)', error);
+            }
+            for (const listener of navListeners)
+                listener(target);
+        },
+        subscribeNav: (listener) => {
+            navListeners.add(listener);
+            return () => { navListeners.delete(listener); };
+        },
+        takeNav: () => {
+            const target = parkedNav;
+            parkedNav = null;
+            return target;
+        },
+        api,
+        insertDraft: (sessionId, text) => {
+            const input = inputFor(sessionId);
+            if (input === undefined)
+                return false;
+            const kept = input.state.getSnapshot().draft.replace(/\s+$/, '');
+            input.setDraft(kept.length === 0 ? text : `${kept}\n\n${text}`);
+            if (typeof input.focus === 'function')
+                input.focus();
+            return true;
+        },
+        insertRef: (sessionId, ref) => {
+            const scope = ctx.get('sessions')?.scope?.(sessionId);
+            const input = inputFor(sessionId);
+            if (input === undefined)
+                return false;
+            if (chipsReady && scope?.bail !== undefined) {
+                for (let attempt = 0; attempt < 2; attempt += 1) {
+                    const snapshot = input.state.getSnapshot();
+                    if (typeof snapshot.draftRev !== 'number')
+                        break;
+                    // The span speaks the detect projection: each existing chip folds to one character.
+                    const folded = (snapshot.occurrences ?? []).reduce((extra, o) => extra + o.length - 1, 0);
+                    const end = snapshot.draft.length - folded;
+                    const applied = scope.bail(scope, 'slash/input-insert-reference', {
+                        reference: { source: GAME_REF_SOURCE, ref: encodeGameRef(ref), label: ref.label, clipboardText: ref.text },
+                        span: { start: end, end, draftRev: snapshot.draftRev },
+                    }) === true;
+                    if (applied) {
+                        input.focus?.();
+                        return true;
+                    }
+                }
+            }
+            const kept = input.state.getSnapshot().draft.replace(/\s+$/, '');
+            input.setDraft(kept.length === 0 ? `${ref.text} ` : `${kept} ${ref.text} `);
+            input.focus?.();
+            return true;
+        },
+        subscribeSessionEvents: (listener) => {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        touch: sessionId => { emit(sessionId); },
+        reveal,
+    };
+    // The page follows the agent: game_publish leaves a 「请用户看这里」 request the host cannot push,
+    // so the page polls the on-screen session's bound project while visible (session events nudge
+    // it early). The same read notices a binding made with no event (a room member's game_open) and
+    // refreshes the tab — refresh only; where to go is the agent's to say.
+    const lastBound = new Map();
+    let lastLook = 0;
+    const look = () => {
+        const now = Date.now();
+        if (now - lastLook < 3000)
+            return;
+        lastLook = now;
+        const sid = mainSessionId(ctx.sessions.list.getSnapshot());
+        if (sid === undefined)
+            return;
+        void api.liveVersion(sid).then(r => {
+            if (!r.ok)
+                return;
+            const bound = r.value?.projectId ?? null;
+            const before = lastBound.get(sid);
+            lastBound.set(sid, bound);
+            if (before !== undefined && before !== bound)
+                emit(sid);
+            if (r.value?.show !== undefined)
+                reveal.request(r.value.projectId, r.value.show);
+        }).catch(() => { });
+    };
+    listeners.add(() => { look(); });
+    const pollTimer = setInterval(() => { if (document.visibilityState === 'visible')
+        look(); }, 6000);
+    disposers.push(async () => { clearInterval(pollTimer); });
+    ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
+        name: 'sidebar.right.pane.tab',
+        key: GAME_TAB_ID,
+        locale: NS,
+        inject: () => face,
+    }, GameTab)), 'game: tab body');
+    // The turn card: what each agent turn changed in the game, beneath the
+    // turn's closing prose (outside the fold), with jumps into the tab. The
+    // canvas-novel turn-tail precedent.
+    // The seat's owner props are typed by ui-chat; this card reads them
+    // structurally (the canvas-novel precedent), so it registers structurally.
+    const seats = ctx.slots;
+    ctx.effect(() => seats.inject('conversation.chat.turnTail', () => {
+        const conversation = ctx.get.bind(ctx)('uiConversation');
+        const register = conversation?.events?.register;
+        if (register === undefined)
+            return () => undefined;
+        const disposeDefinition = register.call(conversation?.events, gameTurnDefinition);
+        const disposeEntry = seats.register({
+            name: 'conversation.chat.turnTail',
+            id: '@khorsheed/dsh-game/turn',
+            order: 45,
+            locale: NS,
+            inject: () => face,
+        }, GameTurnCard);
+        return () => {
+            disposeEntry();
+            disposeDefinition();
+        };
+    }), 'game: turn-tail card');
+    // The conversation rows for dsh-game messages (check findings, attached changes).
+    ctx.inject(['uiConversation'], (lctx) => {
+        lctx.effect(() => lctx.uiConversation.events.register(gameMessageDefinition), 'game: chat projection');
+    });
+    ctx.effect(() => ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+        name: 'conversation.chat.node',
+        key: GAME_CHAT_KIND,
+        locale: NS,
+    }, GameChatRow)), 'game: chat row');
+    return async () => {
+        await Promise.all(disposers.map(dispose => dispose()));
+    };
+}