@dreamboard-games/sdk 0.2.1-alpha.1 → 0.3.0-alpha.1

package/src/reducer/parse-utils.ts

@@ -1,28 +0,0 @@
-import { z } from "zod";
-
-export function formatIssue(
-  label: string,
-  issue: { path: PropertyKey[]; message: string },
-): string {
-  const path = issue.path
-    .map((segment) =>
-      typeof segment === "symbol" ? segment.toString() : String(segment),
-    )
-    .join(".");
-  return `${path || label}: ${issue.message}`;
-}
-
-export function safeParseOrThrow<Schema extends z.ZodTypeAny>(
-  schema: Schema,
-  value: unknown,
-  label: string,
-): z.output<Schema> {
-  const parsed = schema.safeParse(value);
-  if (!parsed.success) {
-    const message = parsed.error.issues
-      .map((issue) => formatIssue(label, issue))
-      .join("; ");
-    throw new Error(message || `Invalid ${label}`);
-  }
-  return parsed.data;
-}

package/src/reducer/per-player.ts

@@ -1,422 +0,0 @@
-import { z } from "zod";
-import type { Brand } from "./model/table";
-
-/**
- * Opaque brand applied to a runtime player identifier.
- *
- * Generators produce a workspace-specific `PlayerId` alias (e.g.
- * `Brand<string, "PlayerId">` in `shared/manifest-contract.ts`). Authors
- * obtain `PlayerId` values only through:
- *   - `q.player.order()` / `q.player.current()` (reducer queries),
- *   - engine-injected callback arguments (actions, phases, prompts),
- *   - `perPlayerKeys(...)` / entries iteration,
- *   - `asPlayerId(raw)` as an explicit escape hatch (e.g. ingress parsing).
- *
- * The brand is a phantom type: at runtime a `PlayerId` is just a string.
- * Do not JSON-serialize the brand marker; it exists purely at the type
- * level to block accidental literal comparisons such as
- * `playerId === "player-1"`.
- */
-export type PlayerId = Brand<string, "PlayerId">;
-
-/**
- * Explicit conversion from a raw string to a branded `PlayerId`.
- *
- * Use at trust boundaries only (wire ingress, tests, fixtures). Inside
- * reducer logic, obtain `PlayerId` values from the engine instead of
- * constructing them yourself.
- */
-export function asPlayerId(raw: string): PlayerId {
-  return raw as PlayerId;
-}
-
-/**
- * Type guard that narrows `unknown` to `PlayerId` when the value is a
- * non-empty string. Does not validate against a specific player roster;
- * use `perPlayerSchema`/ingress parsing for that.
- */
-export function isPlayerId(value: unknown): value is PlayerId {
-  return typeof value === "string" && value.length > 0;
-}
-
-/**
- * A runtime-accurate per-player map.
- *
- * `PerPlayer<Value>` is an opaque, ordered container whose entries are
- * exactly the players that exist at runtime (the seats passed to
- * `initialize`).
- *
- * The `__perPlayer` discriminator keeps the structural type nominal-ish
- * without depending on a symbol (symbols do not round-trip through JSON,
- * which this shape must).
- *
- * Construct with `perPlayer(ids, init)` and read with the accessors in
- * this module; do not reach into `entries` directly unless you need
- * ordered iteration.
- */
-export interface PerPlayer<Value, Id extends PlayerId = PlayerId> {
-  readonly __perPlayer: true;
-  readonly entries: ReadonlyArray<readonly [Id, Value]>;
-}
-
-/**
- * Construct a `PerPlayer<Value>` with one entry per `id` in `ids`.
- *
- * `ids` is treated as the authoritative runtime seat list: the returned
- * `PerPlayer` contains exactly `ids.length` entries, in the same order.
- * Duplicate ids throw.
- */
-export function perPlayer<Value, Id extends PlayerId = PlayerId>(
-  ids: readonly Id[],
-  init: (id: Id, index: number) => Value,
-): PerPlayer<Value, Id> {
-  const seen = new Set<string>();
-  const entries: Array<readonly [Id, Value]> = [];
-  for (const [index, id] of ids.entries()) {
-    if (seen.has(id)) {
-      throw new Error(`perPlayer: duplicate player id '${id}'`);
-    }
-    seen.add(id);
-    entries.push([id, init(id, index)] as const);
-  }
-  return { __perPlayer: true, entries };
-}
-
-/** Ordered list of seat ids present in the `PerPlayer`. */
-export function perPlayerKeys<Id extends PlayerId>(
-  value: PerPlayer<unknown, Id>,
-): Id[] {
-  return value.entries.map((entry) => entry[0]);
-}
-
-/** Ordered list of values present in the `PerPlayer`. */
-export function perPlayerValues<Value>(
-  value: PerPlayer<Value, PlayerId>,
-): Value[] {
-  return value.entries.map((entry) => entry[1]);
-}
-
-/**
- * Ordered `[id, value]` pairs. Returns the backing array as-is; callers
- * must not mutate it.
- */
-export function perPlayerEntries<Value, Id extends PlayerId>(
-  value: PerPlayer<Value, Id>,
-): ReadonlyArray<readonly [Id, Value]> {
-  return value.entries;
-}
-
-/** Number of seats in the `PerPlayer`. */
-export function perPlayerSize(value: PerPlayer<unknown, PlayerId>): number {
-  return value.entries.length;
-}
-
-/** Whether `id` has a value. */
-export function perPlayerHas<Id extends PlayerId>(
-  value: PerPlayer<unknown, Id>,
-  id: Id,
-): boolean {
-  for (const [candidate] of value.entries) {
-    if (candidate === id) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/** Lookup with no fallback; returns `undefined` for missing seats. */
-export function perPlayerGet<Value, Id extends PlayerId>(
-  value: PerPlayer<Value, Id>,
-  id: Id,
-): Value | undefined {
-  for (const [candidate, v] of value.entries) {
-    if (candidate === id) {
-      return v;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Lookup that throws if `id` is not present.
- *
- * Use when the caller has already established (via `q.player.order()`,
- * an action context, etc.) that `id` is an active runtime seat.
- */
-export function perPlayerRequire<Value, Id extends PlayerId>(
-  value: PerPlayer<Value, Id>,
-  id: Id,
-): Value {
-  const found = perPlayerGet(value, id);
-  if (found === undefined && !perPlayerHas(value, id)) {
-    throw new Error(`perPlayerRequire: missing entry for player id '${id}'`);
-  }
-  return found as Value;
-}
-
-/**
- * Return a new `PerPlayer` with `id`'s value replaced (or added if the
- * id is not present). Preserves entry order; new entries are appended.
- */
-export function perPlayerSet<Value, Id extends PlayerId>(
-  value: PerPlayer<Value, Id>,
-  id: Id,
-  next: Value,
-): PerPlayer<Value, Id> {
-  const entries = value.entries.slice();
-  const index = entries.findIndex((entry) => entry[0] === id);
-  if (index >= 0) {
-    entries[index] = [id, next] as const;
-  } else {
-    entries.push([id, next] as const);
-  }
-  return { __perPlayer: true, entries };
-}
-
-/**
- * Return a new `PerPlayer` where each value is replaced by `f(value, id)`.
- * Seat order is preserved.
- */
-export function perPlayerMap<Value, Next, Id extends PlayerId>(
-  value: PerPlayer<Value, Id>,
-  f: (v: Value, id: Id, index: number) => Next,
-): PerPlayer<Next, Id> {
-  return {
-    __perPlayer: true,
-    entries: value.entries.map(
-      ([id, v], index) => [id, f(v, id, index)] as const,
-    ),
-  };
-}
-
-/**
- * Structural check for a `PerPlayer` without a Zod schema. Useful in
- * debug paths and as a fast pre-filter before schema validation.
- */
-export function isPerPlayer(value: unknown): value is PerPlayer<unknown> {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const candidate = value as { __perPlayer?: unknown; entries?: unknown };
-  if (candidate.__perPlayer !== true) {
-    return false;
-  }
-  if (!Array.isArray(candidate.entries)) {
-    return false;
-  }
-  return candidate.entries.every(
-    (entry) =>
-      Array.isArray(entry) &&
-      entry.length === 2 &&
-      typeof entry[0] === "string",
-  );
-}
-
-/**
- * Options accepted by `perPlayerSchema`.
- *
- * Setting `players` locks the schema to an exact seat list: parse fails
- * if the input is missing any seat or has an unknown id. Leaving
- * `players` unset yields a schema that accepts any non-empty string as
- * a key, which is the right default for generic SDK types.
- *
- * `playerIdSchema` lets callers feed a manifest-scoped Zod id schema in
- * so parse errors carry the same message as other branded ids.
- */
-export type PerPlayerSchemaOptions<Id extends PlayerId> = {
-  readonly playerIdSchema?: z.ZodType<Id>;
-  readonly players?: readonly Id[];
-};
-
-/**
- * Build a Zod schema that validates a wire-shaped `PerPlayer<Value>`.
- *
- * When `options.players` is supplied the schema enforces that entries
- * match that exact set (same cardinality, same ids, any order). This is
- * the mechanism that catches the class of bug where a 3-player session
- * produced a view shape the old `Record<PlayerId, T>` type claimed had
- * a `player-4` key.
- */
-export function perPlayerSchema<Value, Id extends PlayerId = PlayerId>(
-  valueSchema: z.ZodType<Value>,
-  options: PerPlayerSchemaOptions<Id> = {},
-): z.ZodType<PerPlayer<Value, Id>> {
-  const keySchema =
-    options.playerIdSchema ?? (z.string().min(1) as unknown as z.ZodType<Id>);
-
-  const base = z
-    .object({
-      __perPlayer: z.literal(true),
-      entries: z.array(z.tuple([keySchema, valueSchema])),
-    })
-    .transform(
-      (value): PerPlayer<Value, Id> => ({
-        __perPlayer: true as const,
-        entries: value.entries as ReadonlyArray<readonly [Id, Value]>,
-      }),
-    );
-
-  if (!options.players) {
-    return base as unknown as z.ZodType<PerPlayer<Value, Id>>;
-  }
-
-  const expected = options.players;
-  return base.superRefine((value, ctx) => {
-    const seen = new Set<string>();
-    for (const [id] of value.entries) {
-      if (seen.has(id)) {
-        ctx.addIssue({
-          code: "custom",
-          message: `Duplicate player id '${id}'`,
-        });
-      }
-      seen.add(id);
-    }
-    for (const expectedId of expected) {
-      if (!seen.has(expectedId)) {
-        ctx.addIssue({
-          code: "custom",
-          message: `Missing entry for player id '${expectedId}'`,
-        });
-      }
-    }
-    for (const id of seen) {
-      if (!expected.some((expectedId) => expectedId === id)) {
-        ctx.addIssue({
-          code: "custom",
-          message: `Unexpected player id '${id}' (allowed: ${expected.join(", ")})`,
-        });
-      }
-    }
-  }) as unknown as z.ZodType<PerPlayer<Value, Id>>;
-}
-
-// ---------------------------------------------------------------------------
-// BoardRef: replacement for flat `"board:player-N"` literal unions.
-// ---------------------------------------------------------------------------
-
-/**
- * Reference to a board by its authored `baseId`, plus an optional seat
- * for per-player boards.
- *
- * Replaces the old generated `"ring:player-1" | "ring:player-2" | ...`
- * flat unions whose keys pretended to be static but were actually
- * derived from `maxPlayers` and therefore misaligned with the runtime
- * seat list.
- *
- * The discriminant is the *presence* of `seat`, not a `scope` field, so
- * authors can destructure and pass the ref directly without needing a
- * discriminator check for shared boards.
- */
-export type BoardRef<
-  BaseId extends string = string,
-  Id extends PlayerId = PlayerId,
-> = SharedBoardRef<BaseId> | PerPlayerBoardRef<BaseId, Id>;
-
-export interface SharedBoardRef<BaseId extends string = string> {
-  readonly baseId: BaseId;
-  readonly seat?: undefined;
-}
-
-export interface PerPlayerBoardRef<
-  BaseId extends string = string,
-  Id extends PlayerId = PlayerId,
-> {
-  readonly baseId: BaseId;
-  readonly seat: Id;
-}
-
-/** Construct a shared board ref. */
-export function sharedBoardRef<BaseId extends string>(
-  baseId: BaseId,
-): SharedBoardRef<BaseId> {
-  return { baseId };
-}
-
-/** Construct a per-player board ref. */
-export function perPlayerBoardRef<BaseId extends string, Id extends PlayerId>(
-  baseId: BaseId,
-  seat: Id,
-): PerPlayerBoardRef<BaseId, Id> {
-  return { baseId, seat };
-}
-
-/**
- * Construct a `BoardRef` without knowing the scope ahead of time. Pass
- * `seat` for per-player boards; omit for shared boards.
- */
-export function boardRef<BaseId extends string, Id extends PlayerId>(
-  baseId: BaseId,
-  seat?: Id,
-): BoardRef<BaseId, Id> {
-  if (seat === undefined) {
-    return { baseId };
-  }
-  return { baseId, seat };
-}
-
-/** Stable string key for Maps/Records keyed by a `BoardRef`. */
-export function boardRefKey(ref: BoardRef): string {
-  return ref.seat === undefined ? ref.baseId : `${ref.baseId}:${ref.seat}`;
-}
-
-/**
- * Inverse of `boardRefKey`. Parses `"base"` as a shared ref and
- * `"base:player-N"` as a per-player ref. Returns `null` for malformed
- * input.
- */
-export function parseBoardRefKey(key: string): BoardRef | null {
-  if (!key.length) {
-    return null;
-  }
-  const colon = key.indexOf(":");
-  if (colon < 0) {
-    return { baseId: key };
-  }
-  const baseId = key.slice(0, colon);
-  const seat = key.slice(colon + 1);
-  if (!baseId.length || !seat.length) {
-    return null;
-  }
-  return { baseId, seat: seat as PlayerId };
-}
-
-/**
- * Zod schema for a `BoardRef` with free-form base and seat ids.
- *
- * Feed a manifest-scoped `baseIdSchema` and `playerIdSchema` to bind
- * the ref to a specific workspace.
- */
-export function boardRefSchema<
-  BaseId extends string = string,
-  Id extends PlayerId = PlayerId,
->(
-  options: {
-    readonly baseIdSchema?: z.ZodType<BaseId>;
-    readonly playerIdSchema?: z.ZodType<Id>;
-  } = {},
-): z.ZodType<BoardRef<BaseId, Id>> {
-  const baseSchema =
-    options.baseIdSchema ?? (z.string().min(1) as unknown as z.ZodType<BaseId>);
-  const playerSchema =
-    options.playerIdSchema ?? (z.string().min(1) as unknown as z.ZodType<Id>);
-  const shared = z.strictObject({ baseId: baseSchema });
-  const perPlayer = z.strictObject({ baseId: baseSchema, seat: playerSchema });
-  return z.union([perPlayer, shared]) as unknown as z.ZodType<
-    BoardRef<BaseId, Id>
-  >;
-}
-
-/** True when `ref` targets a shared board (no seat). */
-export function isSharedBoardRef<BaseId extends string>(
-  ref: BoardRef<BaseId, PlayerId>,
-): ref is SharedBoardRef<BaseId> {
-  return ref.seat === undefined;
-}
-
-/** True when `ref` targets a per-player board (has a seat). */
-export function isPerPlayerBoardRef<BaseId extends string, Id extends PlayerId>(
-  ref: BoardRef<BaseId, Id>,
-): ref is PerPlayerBoardRef<BaseId, Id> {
-  return ref.seat !== undefined;
-}

package/src/reducer/rng.ts

@@ -1,69 +0,0 @@
-import type { RuntimeRngState } from "./model";
-
-/**
- * Deterministic pseudo-random integer generator for reducer-native games.
- *
- * The public contract is `(rng.seed, rng.cursor) -> value`, with the cursor
- * advanced by one per call. Same `(seed, cursor)` tuple always produces the
- * same output, which is what makes session replay deterministic without
- * having to persist anything beyond the seed and cursor.
- *
- * Internally we hash `(seed, cursor)` through a Murmur3-style 32-bit
- * finalizer rather than computing a linear combination of the cursor. The
- * older `(seed * A + C + cursor) & 0x7fffffff` form was linear in `cursor`,
- * so consecutive samples differed by a fixed step — for a d6 that meant
- * every roll produced a simple `+1` counter through the faces. Mixing
- * `(seed, cursor)` with an avalanche finalizer is still pure and still
- * cheap, but now nearby cursors yield well-distributed outputs.
- *
- * Distribution note: the `% bound` step is biased when `bound` is not a
- * power of two. For gameplay-level bounds (≤ 64) the bias is negligible
- * and we leave it in to keep replay fixtures stable against future bound
- * changes. If a caller ever needs strict uniformity we can add an
- * explicit `nextUniformInt` without touching the existing consumers.
- */
-export function nextRandomInt(
-  bound: number,
-  rng: RuntimeRngState,
-): [number, RuntimeRngState] {
-  if (bound <= 0) {
-    throw new Error("Random bound must be positive.");
-  }
-  const seed = rng.seed ?? 1;
-  const raw = hashSeedCursor(seed, rng.cursor);
-  const value = raw % bound;
-  return [
-    value,
-    {
-      ...rng,
-      cursor: rng.cursor + 1,
-      trace: [
-        ...rng.trace,
-        `cursor=${rng.cursor};bound=${bound};value=${value}`,
-      ],
-    },
-  ];
-}
-
-/**
- * Mix `(seed, cursor)` into a uniformly-distributed uint32 using a
- * Murmur3-style finalizer. The seed is split into its low and high 32-bit
- * halves so large 53-bit JS-integer seeds (including the negative seeds
- * the backend derives from its own 64-bit generator) don't collapse onto
- * the same bucket after a `| 0` truncation.
- */
-function hashSeedCursor(seed: number, cursor: number): number {
-  const seedLo = seed | 0;
-  // `Math.floor(seed / 2^32) | 0` keeps the upper bits of large seeds.
-  // For small seeds this is 0 (or -1 for negatives), so the stir below is
-  // still dominated by `seedLo` + `cursor` as you'd expect.
-  const seedHi = Math.floor(seed / 0x1_0000_0000) | 0;
-  let x = Math.imul(seedLo, 0x9e3779b1);
-  x = (x + Math.imul(seedHi, 0x85ebca77)) | 0;
-  x = (x + Math.imul(cursor | 0, 0xc2b2ae3d)) | 0;
-  // Murmur3 32-bit finalizer.
-  x = Math.imul(x ^ (x >>> 16), 0x85ebca6b);
-  x = Math.imul(x ^ (x >>> 13), 0xc2b2ae35);
-  x = x ^ (x >>> 16);
-  return x >>> 0;
-}

package/src/reducer/schema-helpers.ts

@@ -1,185 +0,0 @@
-import { z } from "zod";
-import type { SchemaLike } from "./model";
-
-export type SparseMap<Key extends string, Value> = Partial<Record<Key, Value>>;
-export type SparseCounts<Key extends string> = SparseMap<Key, number>;
-
-type SparseSchemaMetadata = {
-  keySchema: z.ZodType<string>;
-  valueSchema: z.ZodTypeAny;
-};
-
-const sparseSchemas = new WeakMap<object, SparseSchemaMetadata>();
-
-export function sparseMap<
-  KeySchema extends z.ZodType<string>,
-  ValueSchema extends z.ZodTypeAny,
->(
-  keySchema: KeySchema,
-  valueSchema: ValueSchema,
-): z.ZodType<SparseMap<z.infer<KeySchema>, z.infer<ValueSchema>>> {
-  const schema = z.partialRecord(keySchema, valueSchema) as z.ZodType<
-    SparseMap<z.infer<KeySchema>, z.infer<ValueSchema>>
-  >;
-  sparseSchemas.set(schema as unknown as object, {
-    keySchema,
-    valueSchema,
-  });
-  return schema;
-}
-
-export function sparseCounts<KeySchema extends z.ZodType<string>>(
-  keySchema: KeySchema,
-): z.ZodType<SparseCounts<z.infer<KeySchema>>> {
-  return sparseMap(keySchema, z.number().int().min(0)) as z.ZodType<
-    SparseCounts<z.infer<KeySchema>>
-  >;
-}
-
-export function getZodDef(schema: unknown): {
-  type?: string;
-} & Record<string, unknown> {
-  const anySchema = schema as {
-    _zod?: { def?: Record<string, unknown> };
-    def?: Record<string, unknown>;
-  };
-  const fromInternal = anySchema?._zod?.def;
-  if (fromInternal && typeof fromInternal === "object") {
-    return fromInternal;
-  }
-  const fromLegacy = anySchema?.def;
-  if (fromLegacy && typeof fromLegacy === "object") {
-    return fromLegacy;
-  }
-  return {};
-}
-
-export function unwrapWrappers(schema: unknown): unknown {
-  let current = schema;
-  while (true) {
-    const def = getZodDef(current);
-    const innerType = def.innerType;
-    if (
-      (def.type === "nullable" ||
-        def.type === "optional" ||
-        def.type === "default" ||
-        def.type === "readonly" ||
-        def.type === "catch") &&
-      innerType
-    ) {
-      current = innerType;
-      continue;
-    }
-    return current;
-  }
-}
-
-export function isPlainZodString(schema: unknown): boolean {
-  return getZodDef(schema).type === "string";
-}
-
-export function isZodArray(schema: unknown): boolean {
-  return getZodDef(schema).type === "array";
-}
-
-export function isEnumKeyedRecordSchema(schema: unknown): boolean {
-  const def = getZodDef(schema);
-  const keyType = def.keyType;
-  return (
-    def.type === "record" &&
-    typeof keyType === "object" &&
-    keyType !== null &&
-    getZodDef(keyType).type === "enum"
-  );
-}
-
-export function isSparseMapSchema(schema: unknown): boolean {
-  const inner = unwrapWrappers(schema);
-  return (
-    typeof inner === "object" &&
-    inner !== null &&
-    sparseSchemas.has(inner as object)
-  );
-}
-
-function getSparseSchemaMetadata(
-  schema: unknown,
-): SparseSchemaMetadata | undefined {
-  const inner = unwrapWrappers(schema);
-  if (typeof inner !== "object" || inner === null) {
-    return undefined;
-  }
-  return sparseSchemas.get(inner as object);
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-export function getObjectShape(
-  schema: unknown,
-): Record<string, unknown> | null {
-  const def = getZodDef(schema);
-  if (def.type !== "object") {
-    return null;
-  }
-  const shape = def.shape;
-  if (typeof shape === "function") {
-    const resolved = shape();
-    return resolved && typeof resolved === "object"
-      ? (resolved as Record<string, unknown>)
-      : null;
-  }
-  return shape && typeof shape === "object"
-    ? (shape as Record<string, unknown>)
-    : null;
-}
-
-function normalizeSchemaInput(schema: unknown, input: unknown): unknown {
-  const inner = unwrapWrappers(schema);
-  const sparse = getSparseSchemaMetadata(inner);
-  if (sparse && isPlainObject(input)) {
-    const filtered = Object.fromEntries(
-      Object.entries(input)
-        .filter(
-          ([key, value]) =>
-            typeof value !== "undefined" &&
-            sparse.keySchema.safeParse(key).success,
-        )
-        .map(([key, value]) => [
-          key,
-          normalizeSchemaInput(sparse.valueSchema, value),
-        ]),
-    );
-    return filtered;
-  }
-
-  const shape = getObjectShape(inner);
-  if (shape && isPlainObject(input)) {
-    return Object.fromEntries(
-      Object.entries(input).map(([key, value]) => {
-        const fieldSchema = shape[key];
-        return [
-          key,
-          typeof fieldSchema === "undefined"
-            ? value
-            : normalizeSchemaInput(fieldSchema, value),
-        ];
-      }),
-    );
-  }
-
-  const def = getZodDef(inner);
-  if (def.type === "array" && Array.isArray(input) && def.element) {
-    return input.map((value) => normalizeSchemaInput(def.element, value));
-  }
-
-  return input;
-}
-
-export function normalizeCommandParams<Output>(
-  schema: SchemaLike<Output>,
-  input: unknown,
-): Output {
-  return schema.parse(normalizeSchemaInput(schema, input));
-}