@uzuhq/code-sdk 0.7.6 → 0.7.7

package/dist/types.d.ts

@@ -1,345 +0,0 @@
-/**
- * @docs
- * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
- * - APIリファレンス: docs/docs/uzu_code/sdk-guide/api-reference.md
- * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
- * - 外部 automation API: docs/docs/uzu_code/sdk-guide/dev-hooks.md
- */
-/** @deprecated 旧フラット形式。新コードでは BridgeMessage を使用 */
-export type PlayScreenMessage = {
-    type: string;
-    [key: string]: unknown;
-};
-/** ブリッジメッセージのチャンネル */
-export type BridgeChannel = 'sdk' | 'game';
-/** ワイヤーフォーマット: { channel, type, payload, playerId? } */
-export interface BridgeMessage {
-    channel: BridgeChannel;
-    type: string;
-    payload: Record<string, unknown>;
-    /**
-     * 送信元プレイヤーの ID（ゲーム → ホスト方向のみ）。
-     * Web エミュレータでは複数プレイヤーの iframe が同一オリジンになり
-     * postMessage の送信元 iframe を区別できないため、ホストはこの値で
-     * 自分宛メッセージかを判定する。
-     *
-     * Flutter ホスト（QueryParamsBuilder）と dev ハーネスは URL に必ず
-     * playerId を付与するため、ゲーム → ホスト方向では常に存在する。
-     * optional なのはホスト → ゲーム方向のメッセージが持たないため
-     * （受信側は playerId 無し = 旧 SDK ビルドとして扱う）。
-     */
-    playerId?: string;
-}
-/**
- * 自分の席種別。ホストが iframe URL の `?seatKind=` で伝える。
- *
- * roster に載るのは `player` だけ。観測者 (`spectator` / `admin`) は roster 外の接続として
- * 開くので、「player か観測者か」は `state.players` の空振りで分かる。一方 **`spectator` と
- * `admin` の区別は state から導けない**ため、この値で分ける。seatId の命名規約
- * (`admin_0` 等) をシナリオに見せると、規約が変わった瞬間に静かに壊れる。
- *
- * 自己申告なので権限の根拠にはならない。表示の分岐にだけ使うこと。
- */
-export type SeatKind = 'player' | 'spectator' | 'admin';
-/**
- * roster に載る席。
- *
- * roster は配役を受け取る参加者だけで構成される。観測者 (GM 席・観戦席) は roster に
- * 載らないまま接続してくるので、シナリオは「roster に居ない = 観測者」で判別する。
- * 席種別は roster エントリではなく自分の `SeatKind` として渡る。
- */
-export interface Seat {
-    id: string;
-    nickname: string;
-    iconUrl: string;
-    /** ホスト（mobile / emulator）から渡される、選択済みキャラクターの ID。未選択時は undefined。 */
-    characterId?: string;
-}
-/** プレイヤーごとのリアルタイム状態 */
-export interface PlayerVoiceState {
-    /** 音声状態。音声通話に未接続の場合は null */
-    audioStatus: 'speaking' | 'listening' | 'muted' | 'unstable' | null;
-}
-/** @deprecated 旧形式。新コードでは onPlayersChanged() と PlayerVoiceState を使用 */
-export interface PlayersChangedMessage {
-    players: Record<string, PlayerVoiceState>;
-}
-export type Emit = (eventName: string, data?: Record<string, unknown>) => void;
-/**
- * events handler。
- *
- * `emit(name, data)` の `data` をそのまま受け取る。先読み中か確定後かは渡さない
- * (どちらで呼ばれても同じ処理をする前提。 `predict` で宣言済みなので分岐の必要がない)。
- */
-export type EventHandler = (data: Record<string, unknown>) => void;
-/**
- * events の購読宣言。
- *
- * 先読みは外れることがあり、実行してしまったものは取り消せない。取り消せない副作用
- * (analytics / 実績解除 / 長い演出) は必ず `predict: false` にすること。
- */
-export interface EventSubscription {
-    /** 先読み時点で実行してよいか。宣言必須。 */
-    predict: boolean;
-    handler: EventHandler;
-}
-/** dev harness で観測される 1 件の emit。`data` は `emit(name)` 省略時に空 object になる。 */
-export interface ServerEvent {
-    name: string;
-    data: Record<string, unknown>;
-}
-export interface SeededRandom {
-    float(): number;
-    int(max: number): number;
-    pick<T>(array: T[]): T;
-    shuffle<T>(array: T[]): T[];
-}
-/**
- * 素の action handler の実行文脈。空なのは意図的。
- *
- * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
- * 再現できない値 (tick / 乱数) をここで配ると、サーバー・ソロ・dev では本物が入るのに
- * オンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
- * そういう値が要る処理は `serverActions` 側に書く。
- */
-export interface ActionContext {
-    /**
-     * サーバーで処理される時刻 (ms)。先読みではクロックオフセットからの推定値。
-     *
-     * 推定なのでサーバーとは数十 ms ずれる。時刻での分岐に使うと境界で判定が割れるので、
-     * 分岐は `update()` (サーバー専用) で行う。
-     *
-     * 同じ action を再適用しても値は変わらない (初回予測時の値を使い回す)。
-     */
-    now: number;
-    emit: Emit;
-}
-/** `deadlines` handler の実行文脈。サーバーでしか走らないので tick 以外を渡せる。 */
-export interface DeadlineContext {
-    /** 発火時刻 (ms)。サーバー専用なので常に正確。 */
-    now: number;
-    random: SeededRandom;
-    emit: Emit;
-}
-/** `deadlines` handler の引数。 */
-export interface DeadlineArgs<S> {
-    state: S;
-    ctx: DeadlineContext;
-}
-/**
- * サーバー権威の締切。
- *
- * 「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが `at` の最も早いものに
- * 合わせて自分で起き、過ぎた締切の `handler` を呼ぶ。`tickRate` で毎秒ポーリングする
- * 必要が無くなり、その間 Durable Object は hibernate できる。
- *
- * 締切は state から導出するので、予約を張り替える処理を書かなくてよい。action が
- * throw して state が巻き戻れば、締切も一緒に巻き戻る。
- */
-export interface Deadline<S> {
-    /**
-     * 締切の絶対時刻 (ms)。締切が無いときは null / undefined。
-     *
-     * `state.timer?.endsAt` のような optional chain の結果をそのまま返せるよう
-     * undefined も受ける。数値以外は「締切なし」として同じに扱う。
-     *
-     * state が変わるたびに呼ばれるので、state だけから決まる軽い関数にすること。
-     * ここで実時刻や乱数を読むと、呼ばれるたびに答えが変わって予約が暴れる。
-     */
-    at(args: {
-        state: S;
-    }): number | null | undefined;
-    /**
-     * `at` の時刻を過ぎたときにサーバーで呼ばれる。
-     *
-     * 発火は at-least-once だが、SDK が発火直前に `at` を評価し直して過ぎているものだけを
-     * 呼ぶので、handler 側で二重発火を弾く必要は無い。
-     */
-    handler(args: DeadlineArgs<S>): void;
-}
-/** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
-export interface ServerActionContext {
-    tick: number;
-    random: SeededRandom;
-    /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
-    now: number;
-    emit: Emit;
-}
-/** @deprecated `ServerActionContext` を使う。 */
-export type ServerOnlyActionContext = ServerActionContext;
-/**
- * action handler の引数。
- *
- * オブジェクトなのは使うものだけ書けるようにするため。`ctx` を入れ子で残しているのは、
- * 実行環境が与えるものをひとまとまりで helper へ渡せるようにするため。
- */
-export interface ActionArgs<S, P = any> {
-    state: S;
-    payload: P;
-    playerId: string;
-    ctx: ActionContext;
-}
-/**
- * `P` は既定が `any` なので、 注釈のない handler はそのまま動く。 payload の形を
- * 書いた handler だけが検査され、 送信側もその型で縛られる。 全部に注釈しないと
- * 恩恵が無い、 という移行にならないようにするための既定値。
- */
-export type ActionHandler<S, P = any> = (args: ActionArgs<S, P>) => void;
-/** `serverActions` handler の引数。`ctx` にサーバー限定の tick / random が入る。 */
-export interface ServerActionArgs<S, P = any> {
-    state: S;
-    payload: P;
-    playerId: string;
-    ctx: ServerActionContext;
-}
-export type ServerActionHandler<S, P = any> = (args: ServerActionArgs<S, P>) => Promise<void> | void;
-/** @deprecated `ServerActionHandler` を使う。 */
-export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
-/**
- * @deprecated `serverActions` フィールドに直接書く。
- * `serverOnly()` で wrap された handler。`__serverOnly` brand で識別する。
- */
-export type ServerOnlyAction<S> = ServerActionHandler<S> & {
-    readonly __serverOnly: true;
-};
-/** `update()` の ctx。サーバーでしか走らないので tick / random / playerInputs を持つ。 */
-export interface UpdateContext {
-    random: SeededRandom;
-    tick: number;
-    /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
-    now: number;
-    emit: Emit;
-    playerInputs: Record<string, Record<string, any>>;
-}
-export interface UpdateArgs<S> {
-    state: S;
-    ctx: UpdateContext;
-}
-/**
- * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
- *
- * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
- */
-export interface SetupContext {
-    random: SeededRandom;
-    /** サーバーの実時刻 (ms)。setup はサーバーでしか走らないので常に正確。 */
-    now: number;
-}
-/** `setup()` の引数。 */
-export interface SetupArgs {
-    /** 配役を受け取る参加者。観測者は含まれない。 */
-    players: Seat[];
-    ctx: SetupContext;
-}
-/**
- * `actions` の形だけを見る緩い制約。
- *
- * `Record<string, ActionHandler<S>>` (payload: any) を制約に使うと、 推論時に
- * handler 型がそちらへ広げられ payload の型が取り出せなくなる。 payload を
- * `any` のままにしてキーと引数の形だけ縛る。
- */
-export type ActionMap<S> = Record<string, (args: ActionArgs<S, any>) => void>;
-/** `serverActions` 用。 ActionMap と同じ理由で payload は any のままにする。 */
-export type ServerActionMap<S> = Record<string, (args: ServerActionArgs<S, any>) => Promise<void> | void>;
-/** action 名から payload 型を引く表。 注釈のない handler は `any` になる。 */
-export type PayloadMap<A> = {
-    [K in keyof A]: A[K] extends (args: infer G) => any ? G extends {
-        payload: infer P;
-    } ? P : never : never;
-};
-/**
- * `inputs` が受け取る送信関数。 action 名と payload の両方が型で縛られる。
- *
- * payload を一律 optional にすると、 形が必須の action でも省略が通ってしまう。
- * payload 型が undefined を含むとき (= 注釈なしの any や明示的に optional) だけ
- * 省略できるようにする。
- */
-export type SendAction<A> = <K extends keyof A & string>(...args: undefined extends PayloadMap<A>[K] ? [type: K, payload?: PayloadMap<A>[K]] : [type: K, payload: PayloadMap<A>[K]]) => void;
-export interface GameLogic<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> {
-    setup(args: SetupArgs): S;
-    /**
-     * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
-     *
-     * `serverActions` に同名のキーを置くと、同じ action の「サーバーだけで走る続き」に
-     * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
-     * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
-     */
-    actions: A;
-    /**
-     * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
-     * 再現できない処理をここに書く。async 可。
-     *
-     * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
-     * (旧 `serverOnly()` 相当) になる。
-     */
-    serverActions?: SA;
-    update(args: UpdateArgs<S>): void;
-    /**
-     * state 由来の締切。サーバーが `at` の時刻に自分で起きて `handler` を呼ぶ。
-     *
-     * 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
-     * ポーリング中は Durable Object が hibernate できない。
-     */
-    deadlines?: Record<string, Deadline<S>>;
-    tickRate?: number;
-}
-export interface GameConfig<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = ServerActionMap<S>> extends ConnectionCallbacks {
-    logic: GameLogic<S, A, SA>;
-    /**
-     * `mySeatKind` は自分の席種別。roster に自分が居ない (= 観測者) ときに、GM ビューと
-     * 観戦ビューを出し分けるために使う。他プレイヤーの席種別は渡らない。
-     */
-    onState: (state: S, myPlayerId: string, mySeatKind: SeatKind) => void;
-    inputs: (sendAction: SendAction<A & SA>) => void;
-    /**
-     * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
-     *
-     * 同じ出来事が二重に実行されないよう、SDK は「先読みで実行した記録」を持ち、
-     * サーバーから同一の event (name と data が完全一致) が届いたら実行を抑止する。
-     * したがって `data` には**クライアントとサーバーで必ず同じ値になるもの**だけを
-     * 入れること。`ctx.now` や乱数 ID を混ぜると一致せず二重実行になる。
-     */
-    events?: Record<string, EventSubscription>;
-    playerCount: number;
-    /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
-    orientation?: 'portrait' | 'landscape';
-    /**
-     * Dev harness で各 iframe inner viewport 短辺の下限 (CSS px)。
-     * default 360。狭い viewport では親 frame に `body { zoom: N }` を当てて
-     * iframe 内部の `window.innerWidth/Height` を保証する。
-     */
-    devMinIframeShortEdge?: number;
-}
-export type PatchFn = (ops: Operation[]) => void;
-export type SetFn = (path: string, value: unknown) => void;
-export interface SyncConfig<S = any> extends ConnectionCallbacks {
-    initialState: (players: Seat[]) => S;
-    onState: (state: S, myPlayerId: string, serverTime: number) => void;
-    inputs: (patch: PatchFn, set: SetFn) => void;
-    events?: Record<string, (data: Record<string, unknown>) => void>;
-    playerCount: number;
-    /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
-    orientation?: 'portrait' | 'landscape';
-    /**
-     * Dev harness で各 iframe inner viewport 短辺の下限 (CSS px)。
-     * default 360。狭い viewport では親 frame に `body { zoom: N }` を当てて
-     * iframe 内部の `window.innerWidth/Height` を保証する。
-     */
-    devMinIframeShortEdge?: number;
-}
-export interface Operation {
-    op: 'replace' | 'add' | 'remove';
-    path: string;
-    value?: unknown;
-}
-/** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
-export declare const SERVER_TIME: "__SERVER_TIME__";
-/** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */
-export declare const DEFAULT_ICON_URLS: readonly ["https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/4d0da24d-bcf2-4f7b-d1a0-f1bb8c747300/original", "https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/8c75fccb-41d6-429d-e943-06c728a72a00/original", "https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/43f45d11-da38-4d6e-637d-3df78e583500/original"];
-export type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
-export interface ConnectionCallbacks {
-    /** WebSocket 接続状態が変化した時に呼ばれる */
-    onConnectionStateChange?: (state: ConnectionState) => void;
-    /** サーバーで patch 適用が失敗した時に呼ばれる (sync モード専用) */
-    onPatchFailed?: (reason: string) => void;
-}

package/dist/types.js

@@ -1,8 +0,0 @@
-/** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
-export const SERVER_TIME = '__SERVER_TIME__';
-/** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */
-export const DEFAULT_ICON_URLS = [
-    'https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/4d0da24d-bcf2-4f7b-d1a0-f1bb8c747300/original',
-    'https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/8c75fccb-41d6-429d-e943-06c728a72a00/original',
-    'https://imagedelivery.net/htp-D7B2hJT5XtdWYN9e7Q/43f45d11-da38-4d6e-637d-3df78e583500/original',
-];