@trolleroof/tui 0.2.4 → 0.2.6

package/src/games/tetris/engine.ts

@@ -0,0 +1,236 @@
+import { Rng } from "../../core/rng.js";
+
+/**
+ * Pure Tetris rules: 10x20 board, the 7 tetrominoes with SRS-style rotation
+ * (including standard wall kicks), gravity/drop mechanics, line clearing,
+ * guideline scoring, level progression, and the 7-bag randomizer. Everything
+ * here is deterministic given a seeded Rng, so (seed, action sequence)
+ * reproduces an episode exactly.
+ */
+
+export const BOARD_W = 10;
+export const BOARD_H = 20;
+
+export type PieceType = "I" | "O" | "T" | "S" | "Z" | "J" | "L";
+export const PIECE_TYPES: readonly PieceType[] = ["I", "O", "T", "S", "Z", "J", "L"];
+
+/** Board cell: null = empty, otherwise the piece type that locked there. */
+export type Cell = PieceType | null;
+export type Board = Cell[][]; // BOARD_H rows × BOARD_W cols
+
+export type Rotation = 0 | 1 | 2 | 3;
+
+export interface ActivePiece {
+  type: PieceType;
+  rotation: Rotation;
+  /** Top-left of the piece's bounding box in board coordinates (y grows down). */
+  x: number;
+  y: number;
+}
+
+// ── Shapes ────────────────────────────────────────────────────────────
+// Spawn-state grids per SRS: JLSTZ/T live in a 3x3 box, I in 4x4, O in 2x2
+// (rotation-invariant). The other rotation states are derived by rotating
+// the bounding box clockwise, which reproduces the SRS orientations.
+
+const SHAPE_GRIDS: Record<PieceType, string[]> = {
+  I: ["....", "XXXX", "....", "...."],
+  O: ["XX", "XX"],
+  T: [".X.", "XXX", "..."],
+  S: [".XX", "XX.", "..."],
+  Z: ["XX.", ".XX", "..."],
+  J: ["X..", "XXX", "..."],
+  L: ["..X", "XXX", "..."],
+};
+
+type Offsets = ReadonlyArray<readonly [number, number]>;
+
+function gridToOffsets(grid: string[]): Offsets {
+  const out: Array<[number, number]> = [];
+  grid.forEach((row, y) => {
+    for (let x = 0; x < row.length; x++) {
+      if (row[x] === "X") out.push([x, y]);
+    }
+  });
+  return out;
+}
+
+function rotateGridCw(grid: string[]): string[] {
+  const n = grid.length;
+  return Array.from({ length: n }, (_, y) =>
+    Array.from({ length: n }, (_, x) => grid[n - 1 - x]![y]!).join(""),
+  );
+}
+
+/** OFFSETS[type][rotation] → block offsets within the bounding box. */
+const OFFSETS: Record<PieceType, [Offsets, Offsets, Offsets, Offsets]> = (() => {
+  const table = {} as Record<PieceType, [Offsets, Offsets, Offsets, Offsets]>;
+  for (const type of PIECE_TYPES) {
+    let grid = SHAPE_GRIDS[type];
+    const rots: Offsets[] = [];
+    for (let r = 0; r < 4; r++) {
+      rots.push(gridToOffsets(grid));
+      grid = rotateGridCw(grid);
+    }
+    table[type] = rots as [Offsets, Offsets, Offsets, Offsets];
+  }
+  return table;
+})();
+
+// ── Wall kicks (SRS) ──────────────────────────────────────────────────
+// Tables use SRS convention (+y up); we negate y when applying because our
+// board y grows downward. Keyed by "from>to".
+
+const KICKS_JLSTZ: Record<string, Offsets> = {
+  "0>1": [[0, 0], [-1, 0], [-1, 1], [0, -2], [-1, -2]],
+  "1>0": [[0, 0], [1, 0], [1, -1], [0, 2], [1, 2]],
+  "1>2": [[0, 0], [1, 0], [1, -1], [0, 2], [1, 2]],
+  "2>1": [[0, 0], [-1, 0], [-1, 1], [0, -2], [-1, -2]],
+  "2>3": [[0, 0], [1, 0], [1, 1], [0, -2], [1, -2]],
+  "3>2": [[0, 0], [-1, 0], [-1, -1], [0, 2], [-1, 2]],
+  "3>0": [[0, 0], [-1, 0], [-1, -1], [0, 2], [-1, 2]],
+  "0>3": [[0, 0], [1, 0], [1, 1], [0, -2], [1, -2]],
+};
+
+const KICKS_I: Record<string, Offsets> = {
+  "0>1": [[0, 0], [-2, 0], [1, 0], [-2, -1], [1, 2]],
+  "1>0": [[0, 0], [2, 0], [-1, 0], [2, 1], [-1, -2]],
+  "1>2": [[0, 0], [-1, 0], [2, 0], [-1, 2], [2, -1]],
+  "2>1": [[0, 0], [1, 0], [-2, 0], [1, -2], [-2, 1]],
+  "2>3": [[0, 0], [2, 0], [-1, 0], [2, 1], [-1, -2]],
+  "3>2": [[0, 0], [-2, 0], [1, 0], [-2, -1], [1, 2]],
+  "3>0": [[0, 0], [1, 0], [-2, 0], [1, -2], [-2, 1]],
+  "0>3": [[0, 0], [-1, 0], [2, 0], [-1, 2], [2, -1]],
+};
+
+function kicksFor(type: PieceType, from: Rotation, to: Rotation): Offsets {
+  if (type === "O") return [[0, 0]];
+  const table = type === "I" ? KICKS_I : KICKS_JLSTZ;
+  return table[`${from}>${to}`]!;
+}
+
+// ── Board helpers ─────────────────────────────────────────────────────
+
+export function emptyBoard(): Board {
+  return Array.from({ length: BOARD_H }, () => Array<Cell>(BOARD_W).fill(null));
+}
+
+export function cloneBoard(board: Board): Board {
+  return board.map((row) => [...row]);
+}
+
+/** Absolute board coordinates of the piece's four blocks. */
+export function pieceCells(piece: ActivePiece): Array<[number, number]> {
+  return OFFSETS[piece.type][piece.rotation].map(([dx, dy]) => [piece.x + dx, piece.y + dy]);
+}
+
+/** True if any block is out of bounds (sides/floor) or overlaps a locked cell. */
+export function collides(board: Board, piece: ActivePiece): boolean {
+  for (const [x, y] of pieceCells(piece)) {
+    if (x < 0 || x >= BOARD_W || y >= BOARD_H) return true;
+    if (y >= 0 && board[y]![x] !== null) return true; // y < 0 is above the field
+  }
+  return false;
+}
+
+/** New piece at the standard spawn column, topmost block on row 0. */
+export function spawnPiece(type: PieceType): ActivePiece {
+  const size = SHAPE_GRIDS[type].length;
+  const minRow = Math.min(...OFFSETS[type][0].map(([, dy]) => dy));
+  return { type, rotation: 0, x: Math.floor((BOARD_W - size) / 2), y: -minRow };
+}
+
+/** Translate by (dx, dy); null if the result collides. */
+export function tryMove(board: Board, piece: ActivePiece, dx: number, dy: number): ActivePiece | null {
+  const next = { ...piece, x: piece.x + dx, y: piece.y + dy };
+  return collides(board, next) ? null : next;
+}
+
+/** SRS rotate (dir = 1 cw, -1 ccw), testing wall kicks in order. */
+export function tryRotate(board: Board, piece: ActivePiece, dir: 1 | -1): ActivePiece | null {
+  const to = (((piece.rotation + dir) % 4) + 4) % 4 as Rotation;
+  for (const [kx, ky] of kicksFor(piece.type, piece.rotation, to)) {
+    const next = { ...piece, rotation: to, x: piece.x + kx, y: piece.y - ky };
+    if (!collides(board, next)) return next;
+  }
+  return null;
+}
+
+/** Rows the piece would fall before locking (hard-drop distance). */
+export function dropDistance(board: Board, piece: ActivePiece): number {
+  let d = 0;
+  while (tryMove(board, piece, 0, d + 1)) d++;
+  return d;
+}
+
+export interface LockResult {
+  board: Board;
+  /** Number of lines cleared by this lock (0–4). */
+  cleared: number;
+  /** True when the piece locked (partly) above the visible field → game over. */
+  toppedOut: boolean;
+}
+
+/** Merge the piece into the board, then clear any full rows. Pure. */
+export function lockPiece(board: Board, piece: ActivePiece): LockResult {
+  const next = cloneBoard(board);
+  let toppedOut = false;
+  for (const [x, y] of pieceCells(piece)) {
+    if (y < 0) {
+      toppedOut = true;
+      continue;
+    }
+    next[y]![x] = piece.type;
+  }
+  const { board: cleared, count } = clearLines(next);
+  return { board: cleared, cleared: count, toppedOut };
+}
+
+/** Remove full rows and add empty rows on top. Pure. */
+export function clearLines(board: Board): { board: Board; count: number } {
+  const kept = board.filter((row) => row.some((cell) => cell === null));
+  const count = BOARD_H - kept.length;
+  const fresh = Array.from({ length: count }, () => Array<Cell>(BOARD_W).fill(null));
+  return { board: [...fresh, ...kept.map((row) => [...row])], count };
+}
+
+// ── Scoring / levels ──────────────────────────────────────────────────
+
+/** Guideline base points for 1/2/3/4 lines (single/double/triple/tetris). */
+export const LINE_SCORES = [0, 100, 300, 500, 800] as const;
+
+export function lineScore(cleared: number, level: number): number {
+  return LINE_SCORES[cleared]! * (level + 1);
+}
+
+/** Level increases every 10 lines. */
+export function levelForLines(lines: number): number {
+  return Math.floor(lines / 10);
+}
+
+/** Gravity interval in ms for a level — faster as levels climb. */
+export function gravityMs(level: number): number {
+  return Math.max(60, Math.round(800 * Math.pow(0.85, level)));
+}
+
+// ── 7-bag randomizer ──────────────────────────────────────────────────
+
+/** Deals pieces in shuffled bags of all 7 — deterministic per seeded Rng. */
+export class SevenBag {
+  private bag: PieceType[] = [];
+
+  constructor(private rng: Rng, private useBag = true) {}
+
+  next(): PieceType {
+    if (!this.useBag) return PIECE_TYPES[this.rng.int(PIECE_TYPES.length)]!;
+    if (this.bag.length === 0) {
+      this.bag = [...PIECE_TYPES];
+      // Fisher–Yates with the seeded Rng.
+      for (let i = this.bag.length - 1; i > 0; i--) {
+        const j = this.rng.int(i + 1);
+        [this.bag[i], this.bag[j]] = [this.bag[j]!, this.bag[i]!];
+      }
+    }
+    return this.bag.pop()!;
+  }
+}

package/src/games/tetris/tetris.ts

@@ -0,0 +1,220 @@
+import type { Game, GameVariation, StepResult } from "../../core/game.js";
+import { Rng } from "../../core/rng.js";
+import {
+  ActivePiece,
+  Board,
+  PieceType,
+  SevenBag,
+  collides,
+  dropDistance,
+  emptyBoard,
+  gravityMs,
+  levelForLines,
+  lineScore,
+  lockPiece,
+  spawnPiece,
+  tryMove,
+  tryRotate,
+} from "./engine.js";
+
+export type TetrisAction =
+  | "left"
+  | "right"
+  | "rotate-cw"
+  | "rotate-ccw"
+  | "soft-drop"
+  | "hard-drop"
+  | "tick"; // gravity pulse — issued by the app timer, logged like any action
+
+export interface TetrisState {
+  board: Board;
+  active: ActivePiece | null;
+  next: PieceType[];
+  score: number;
+  lines: number;
+  level: number;
+  over: boolean;
+}
+
+const NEXT_PREVIEW = 3;
+
+export class TetrisGame implements Game<TetrisState, TetrisAction> {
+  static readonly VARIATIONS: readonly GameVariation[] = [
+    { id: "classic", title: "Standard", description: "Standard seven-bag Tetris.", goal: "Survive as long as possible" },
+    { id: "sprint", title: "Sprint", description: "Clear 10 lines to finish.", goal: "Clear 10 lines" },
+    { id: "chaos", title: "Chaos", description: "Pieces are fully random instead of bagged.", goal: "Survive the chaos" },
+  ];
+
+  readonly name = "tetris";
+  readonly actions = [
+    "left",
+    "right",
+    "rotate-cw",
+    "rotate-ccw",
+    "soft-drop",
+    "hard-drop",
+    "tick",
+  ] as const;
+  readonly variation: GameVariation;
+
+  private board: Board = emptyBoard();
+  private active: ActivePiece | null = null;
+  private queue: PieceType[] = [];
+  private bag = new SevenBag(new Rng(0));
+  private points = 0;
+  private lines = 0;
+  private over = false;
+  private readonly targetLines: number;
+  private gravityScale = 1;
+
+  constructor(variationId = "classic") {
+    this.variation = TetrisGame.VARIATIONS.find(({ id }) => id === variationId) ?? TetrisGame.VARIATIONS[0]!;
+    this.targetLines = this.variation.id === "sprint" ? 10 : 0;
+  }
+
+  reset(seed: number): void {
+    this.bag = new SevenBag(new Rng(seed), this.variation.id !== "chaos");
+    this.gravityScale = this.variation.id === "chaos" ? 0.75 + new Rng(seed).next() * 0.5 : 1;
+    this.board = emptyBoard();
+    this.points = 0;
+    this.lines = 0;
+    this.over = false;
+    this.queue = Array.from({ length: NEXT_PREVIEW + 1 }, () => this.bag.next());
+    this.active = spawnPiece(this.queue.shift()!);
+  }
+
+  step(action: TetrisAction): StepResult {
+    if (this.over || !this.active) return { reward: 0, moved: false, done: true, success: false };
+
+    switch (action) {
+      case "left":
+      case "right": {
+        const next = tryMove(this.board, this.active, action === "left" ? -1 : 1, 0);
+        if (!next) return this.noop();
+        this.active = next;
+        return { reward: 0, moved: true, done: false, success: false };
+      }
+      case "rotate-cw":
+      case "rotate-ccw": {
+        const next = tryRotate(this.board, this.active, action === "rotate-cw" ? 1 : -1);
+        if (!next) return this.noop();
+        this.active = next;
+        return { reward: 0, moved: true, done: false, success: false };
+      }
+      case "soft-drop": {
+        const next = tryMove(this.board, this.active, 0, 1);
+        if (next) {
+          this.active = next;
+          this.points += 1; // guideline: +1 per soft-dropped cell
+          return { reward: 1, moved: true, done: false, success: false };
+        }
+        const locked = this.lockActive();
+        return { reward: locked.reward, moved: true, done: this.over, success: this.hasWon(), randomEffects: locked.randomEffects };
+      }
+      case "tick": {
+        const next = tryMove(this.board, this.active, 0, 1);
+        if (next) {
+          this.active = next;
+          return { reward: 0, moved: true, done: false, success: false };
+        }
+        const locked = this.lockActive();
+        return { reward: locked.reward, moved: true, done: this.over, success: this.hasWon(), randomEffects: locked.randomEffects };
+      }
+      case "hard-drop": {
+        const dist = dropDistance(this.board, this.active);
+        this.active = { ...this.active, y: this.active.y + dist };
+        const dropPoints = 2 * dist; // guideline: +2 per hard-dropped cell
+        this.points += dropPoints;
+        const locked = this.lockActive();
+        return {
+          reward: dropPoints + locked.reward,
+          moved: true,
+          done: this.over,
+          success: this.hasWon(),
+          randomEffects: locked.randomEffects,
+        };
+      }
+    }
+  }
+
+  private noop(): StepResult {
+    return { reward: 0, moved: false, done: false, success: false };
+  }
+
+  /** Lock the active piece, score cleared lines, and spawn the next one. */
+  private lockActive(): {
+    reward: number;
+    randomEffects?: { kind: "piece_drawn"; active_piece: PieceType; queued_piece: PieceType };
+  } {
+    const piece = this.active!;
+    const res = lockPiece(this.board, piece);
+    this.board = res.board;
+    const gained = lineScore(res.cleared, this.level());
+    this.points += gained;
+    this.lines += res.cleared;
+    if (this.targetLines > 0 && this.lines >= this.targetLines) this.over = true;
+
+    if (res.toppedOut) {
+      this.over = true;
+      this.active = null;
+      return { reward: gained };
+    }
+
+    const nextType = this.queue.shift()!;
+    const queuedType = this.bag.next();
+    this.queue.push(queuedType);
+    const spawned = spawnPiece(nextType);
+    if (collides(this.board, spawned)) {
+      this.over = true;
+      this.active = null;
+    } else {
+      this.active = spawned;
+    }
+    return {
+      reward: gained,
+      randomEffects: {
+        kind: "piece_drawn",
+        active_piece: nextType,
+        queued_piece: queuedType,
+      },
+    };
+  }
+
+  state(): TetrisState {
+    return {
+      board: this.board.map((row) => [...row]),
+      active: this.active ? { ...this.active } : null,
+      next: [...this.queue],
+      score: this.points,
+      lines: this.lines,
+      level: this.level(),
+      over: this.over,
+    };
+  }
+
+  score(): number {
+    return this.points;
+  }
+
+  level(): number {
+    return levelForLines(this.lines);
+  }
+
+  linesCleared(): number {
+    return this.lines;
+  }
+
+  isOver(): boolean {
+    return this.over;
+  }
+
+  /** Classic has no win condition; goal variants use their target instead. */
+  hasWon(): boolean {
+    return this.targetLines > 0 && this.lines >= this.targetLines;
+  }
+
+  /** Current gravity interval so the app can pace its tick timer. */
+  gravityMs(): number {
+    return Math.max(60, Math.round(gravityMs(this.level()) * this.gravityScale));
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAuthAnalyticsEvent } from "./analytics/events.js";
+import { analytics } from "./analytics/posthog.js";
+import { runAuthCommand, type AuthSuccess } from "./auth.js";
+import { findGame, isPlayable, REGISTRY } from "./games/registry.js";
+import { launchOverlay as showOverlay } from "../scripts/overlay.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+function captureAuthSuccess(result: AuthSuccess): void {
+  if (result.userId) analytics.setDistinctId(result.userId);
+  analytics.capture(createAuthAnalyticsEvent(result));
+}
+
+function printUsage(): void {
+  const ids = REGISTRY.filter(isPlayable).map((entry) => entry.id).join(", ");
+  console.log("usage: gamepigeon [game]");
+  console.log("       gamepigeon auth [signup|login|oauth|status|logout]");
+  console.log("       gamepigeon auth oauth <google|github>");
+  console.log("       gamepigeon install [--codex|--claude|--opencode|--hermes|--openclaw|--antigravity|--all]");
+  console.log("");
+  console.log("With no argument, opens the arcade overlay menu.");
+  console.log(`Available games: ${ids}`);
+}
+
+async function installAdapters(target?: string): Promise<void> {
+  const proc = Bun.spawn(["bash", join(ROOT, "scripts/install-adapters.sh"), target ?? "--all"], {
+    cwd: ROOT,
+    env: { ...process.env, GAMEPIGEON_WORKSPACE_DIR: process.cwd() },
+    stdin: "ignore",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  await proc.exited;
+  if (proc.exitCode !== 0) process.exit(proc.exitCode ?? 1);
+}
+
+async function launchOverlay(gameId?: string): Promise<void> {
+  await showOverlay("show", ROOT, { gameId });
+}
+
+async function main(): Promise<void> {
+  let arg = process.argv[2];
+  if (arg === "--game") arg = process.argv[3] ?? "";
+  if (arg === "--help" || arg === "-h") {
+    printUsage();
+    return;
+  }
+  if (arg === "auth") {
+    try {
+      const result = await runAuthCommand(process.argv[3]);
+      if (result) captureAuthSuccess(result);
+    } finally {
+      await analytics.shutdown();
+    }
+    return;
+  }
+  if (arg === "install") {
+    await installAdapters(process.argv[3]);
+    return;
+  }
+
+  let gameId: string | undefined;
+  if (arg !== undefined) {
+    const entry = findGame(arg);
+    if (!entry || !isPlayable(entry)) {
+      const ids = REGISTRY.filter(isPlayable).map((entry) => entry.id).join(", ");
+      console.error(`Unknown or unavailable game "${arg}". Available games: ${ids}`);
+      process.exit(1);
+    }
+    gameId = entry.id;
+  }
+
+  await launchOverlay(gameId);
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/recording/chunks.ts

@@ -0,0 +1,93 @@
+import { RECORDING_SDK_VERSION } from "./types.js";
+import type {
+  GameEvent,
+  GameEventChunk,
+  TraceEvent,
+  TraceEventChunk,
+} from "./types.js";
+
+export interface BuildChunkInput {
+  gameId: string;
+  gameType: string;
+  gameVersion: string;
+  chunkId: string;
+  chunkSequence: number;
+  createdAtMs: number;
+  applicationVersion: string;
+  events: GameEvent[];
+}
+
+export function buildChunk(input: BuildChunkInput): GameEventChunk {
+  if (input.events.length === 0) throw new Error("cannot build an empty recording chunk");
+  for (let index = 1; index < input.events.length; index++) {
+    if (input.events[index]!.event_sequence <= input.events[index - 1]!.event_sequence) {
+      throw new Error("chunk events must have strictly increasing sequences");
+    }
+  }
+  return {
+    schema_version: 1,
+    game_id: input.gameId,
+    game_type: input.gameType,
+    game_version: input.gameVersion,
+    chunk_id: input.chunkId,
+    chunk_sequence: input.chunkSequence,
+    first_event_sequence: input.events[0]!.event_sequence,
+    last_event_sequence: input.events.at(-1)!.event_sequence,
+    event_count: input.events.length,
+    created_at_ms: input.createdAtMs,
+    client: {
+      platform: "tui",
+      application_version: input.applicationVersion,
+      recording_sdk_version: RECORDING_SDK_VERSION,
+    },
+    events: input.events,
+  };
+}
+
+export interface BuildTraceChunkInput {
+  userId: string;
+  gameId: string;
+  gameType: string;
+  gameVersion: string;
+  chunkId: string;
+  chunkSequence: number;
+  createdAtMs: number;
+  applicationVersion: string;
+  events: TraceEvent[];
+}
+
+export function buildTraceChunk(input: BuildTraceChunkInput): TraceEventChunk {
+  if (input.events.length === 0) throw new Error("cannot build an empty trace chunk");
+  for (let index = 0; index < input.events.length; index++) {
+    const event = input.events[index]!;
+    if (event.user_id !== input.userId) throw new Error("trace event user_id must match its chunk");
+    if (event.game_id !== input.gameId) throw new Error("trace event game_id must match its chunk");
+    if (event.chunk_id !== input.chunkId) throw new Error("trace event chunk_id must match its chunk");
+    if (index > 0 && event.event_sequence <= input.events[index - 1]!.event_sequence) {
+      throw new Error("trace events must have strictly increasing sequences");
+    }
+  }
+  return {
+    schema_version: 2,
+    user_id: input.userId,
+    game_id: input.gameId,
+    game_type: input.gameType,
+    game_version: input.gameVersion,
+    chunk_id: input.chunkId,
+    chunk_sequence: input.chunkSequence,
+    first_event_sequence: input.events[0]!.event_sequence,
+    last_event_sequence: input.events.at(-1)!.event_sequence,
+    event_count: input.events.length,
+    created_at_ms: input.createdAtMs,
+    client: {
+      platform: "tui",
+      application_version: input.applicationVersion,
+      recording_sdk_version: RECORDING_SDK_VERSION,
+    },
+    events: input.events,
+  };
+}
+
+export function estimatedBytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}

package/src/recording/config.test.ts

@@ -0,0 +1,31 @@
+import { chmodSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { recordingDir } from "./config.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("recordingDir", () => {
+  it("creates and tightens the application and recording roots to 0700", () => {
+    const home = mkdtempSync(join(tmpdir(), "gamepigeon-home-"));
+    roots.push(home);
+    const appRoot = join(home, ".tui-gamepigeon");
+    const recordings = join(appRoot, "recordings");
+    const previous = process.umask(0);
+    try {
+      const path = recordingDir(home);
+      chmodSync(appRoot, 0o777);
+      chmodSync(recordings, 0o777);
+      expect(recordingDir(home)).toBe(path);
+      expect(existsSync(path)).toBe(true);
+      expect(statSync(appRoot).mode & 0o777).toBe(0o700);
+      expect(statSync(recordings).mode & 0o777).toBe(0o700);
+    } finally {
+      process.umask(previous);
+    }
+  });
+});

package/src/recording/config.ts

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ensurePrivateDirectory } from "./permissions.js";
+
+export interface RecordingConfig {
+  flushIntervalMs: number;
+  maxEventsPerChunk: number;
+  maxEstimatedChunkBytes: number;
+  maxInFlightChunksPerGame: 1;
+}
+
+export const DEFAULT_RECORDING_CONFIG: RecordingConfig = {
+  flushIntervalMs: 2_000,
+  maxEventsPerChunk: 50,
+  maxEstimatedChunkBytes: 128 * 1024,
+  maxInFlightChunksPerGame: 1,
+};
+
+export function resolveRecordingConfig(
+  overrides: Partial<RecordingConfig> = {},
+): RecordingConfig {
+  const config = { ...DEFAULT_RECORDING_CONFIG, ...overrides };
+  for (const [name, value] of Object.entries(config)) {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(`recording config ${name} must be greater than zero`);
+    }
+  }
+  return config;
+}
+
+export function recordingDir(home = homedir()): string {
+  const root = join(home, ".tui-gamepigeon");
+  const recordings = join(root, "recordings");
+  ensurePrivateDirectory(root);
+  ensurePrivateDirectory(recordings);
+  return recordings;
+}