feat: save games and edit scene darkness

Persist show state to local saves; author map darkness in scene editor with bake-to-scene and help updates.

Co-authored-by: Cursor <cursoragent@cursor.com>

app/shared/gameSave/buildSnapshot.ts

@@ -0,0 +1,104 @@
+import { computePathPlaybackSample } from '../types/tokenPathPlayback';
+import type { GameSaveBody } from '../types/gameSave';
+import { GAME_SAVE_SCHEMA_VERSION } from '../types/gameSave';
+import type { Project } from '../types/domain';
+import type { TokenPath } from '../types/tokenPath';
+import type { TokenPathPlaybackEntry } from '../types/tokenPathSession';
+
+export function defaultGameSaveName(now = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, '0');
+  return `${p(now.getDate())}.${p(now.getMonth() + 1)}.${now.getFullYear()} ${p(now.getHours())}:${p(now.getMinutes())}`;
+}
+
+export function canonicalGameSave(body: GameSaveBody): string {
+  return JSON.stringify(sortValue(body));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === 'object') {
+    const src = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(src).sort()) out[key] = sortValue(src[key]);
+    return out;
+  }
+  return value;
+}
+
+export function pathForPlacement(project: Project, kind: 'token' | 'npcToken', placementId: string): TokenPath | null {
+  for (const scene of Object.values(project.scenes)) {
+    const list = kind === 'token' ? scene.tokens : scene.npcTokens;
+    const found = (list ?? []).find((token) => String(token.id) === placementId);
+    if (found?.path && found.path.points.length >= 2) return found.path;
+  }
+  return null;
+}
+
+/** Движение и задержка становятся паузой в текущей точке пути. */
+export function freezeTokenPathPlayback(
+  playback: Record<string, TokenPathPlaybackEntry>,
+  pathFor: (entry: TokenPathPlaybackEntry) => TokenPath | null,
+  nowMs: number,
+): Record<string, TokenPathPlaybackEntry> {
+  const out: Record<string, TokenPathPlaybackEntry> = {};
+  for (const [key, entry] of Object.entries(playback)) {
+    out[key] = freezeEntry(entry, pathFor(entry), nowMs);
+  }
+  return out;
+}
+
+function freezeEntry(entry: TokenPathPlaybackEntry, path: TokenPath | null, nowMs: number): TokenPathPlaybackEntry {
+  if (entry.phase === 'stopped' || entry.phase === 'done' || !path) {
+    const phase = entry.phase === 'moving' || entry.phase === 'delay' ? 'stopped' : entry.phase;
+    return { ...entry, phase, rejoinDist: null, segmentStartedAtMs: 0 };
+  }
+  const sample = computePathPlaybackSample({ path, entry, nowMs });
+  if (!sample) {
+    return { ...entry, phase: 'stopped', rejoinDist: null, segmentStartedAtMs: 0 };
+  }
+  const phase = sample.markDone || sample.phase === 'done' ? 'done' : 'stopped';
+  return {
+    ...entry,
+    phase,
+    baseDist: sample.sample.dist,
+    rejoinDist: null,
+    segmentStartedAtMs: 0,
+    direction: 1,
+  };
+}
+
+export function emptyGameSaveBody(projectId: string): GameSaveBody {
+  return {
+    schemaVersion: GAME_SAVE_SCHEMA_VERSION,
+    projectId,
+    graphNodeId: null,
+    sceneId: null,
+    darknessByCard: {},
+    markersByCard: {},
+    trapsByCard: {},
+    effectsByCard: {},
+    sceneTokensByPlacementId: {},
+    npcTokens: { byPlacementId: {}, scale: 1, spawned: {} },
+    tokenPaths: { presentationVisible: {}, playback: {} },
+    timer: {
+      durationMs: 0,
+      remainingMs: 0,
+      visibleToPlayers: false,
+      layout: { cx: 0, cy: 0, scale: 1, rotationDeg: 0 },
+    },
+    playerTokens: { selectedPlayerIds: [], visible: false, byPlayerId: {} },
+    camera: { scale: 1, ox: 0.5, oy: 0.5 },
+    materials: { activeMaterialIds: [], layouts: {}, legendLayouts: {}, focusMaterialId: null },
+    npcAvatars: { activeNpcIds: [], layouts: {}, focusNpcId: null },
+    initiative: {
+      enabled: false,
+      entries: {},
+      order: [],
+      reserve: [],
+      activeId: null,
+      conditions: {},
+      playersVisible: false,
+    },
+    tokenGridSnap: false,
+  };
+}

app/shared/graph/sceneListOrder.test.ts

@@ -22,6 +22,7 @@ function scene(id: string): Scene {
     previewVideoAutostart: false,
     previewRotationDeg: 0,
     darkenScene: false,
+    darknessStrokes: [],
     traps: [],
     tokens: [],
     npcTokens: [],

app/shared/graph/storylineExportImport.test.ts

@@ -43,6 +43,7 @@ function scene(id: string, title: string): Scene {
     previewVideoAutostart: false,
     previewRotationDeg: 0,
     darkenScene: false,
+    darknessStrokes: [],
     traps: [],
     tokens: [],
     npcTokens: [],

app/shared/ipc/contracts.ts

@@ -34,6 +34,7 @@ import type {
   DisplayInfo,
   Scene,
   SceneDarknessEvent,
+  SceneDarknessRevealStroke,
   SceneDarknessState,
   SceneMarkerEvent,
   SceneMarkerState,
@@ -166,6 +167,11 @@ export const ipcChannels = {
     materialUpsertProgress: 'project.materialUpsertProgress',
     npcUpsertProgress: 'project.npcUpsertProgress',
   },
+  gameSave: {
+    list: 'gameSave.list',
+    write: 'gameSave.write',
+    isDirty: 'gameSave.isDirty',
+  },
   windows: {
     openMultiWindow: 'windows.openMultiWindow',
     closeMultiWindow: 'windows.closeMultiWindow',
@@ -787,8 +793,20 @@ export type IpcInvokeMap = {
     res: { ok: true };
   };
   [ipcChannels.windows.openMultiWindow]: {
-    req: { playerIds?: string[] };
-    res: { ok: true };
+    req: { playerIds?: string[]; saveId?: string };
+    res: { ok: true; project: Project | null };
+  };
+  [ipcChannels.gameSave.list]: {
+    req: Record<string, never>;
+    res: { saves: { id: string; name: string; savedAt: string }[] };
+  };
+  [ipcChannels.gameSave.write]: {
+    req: { id: string | null; name: string };
+    res: { save: { id: string; name: string; savedAt: string } };
+  };
+  [ipcChannels.gameSave.isDirty]: {
+    req: Record<string, never>;
+    res: { dirty: boolean };
   };
   [ipcChannels.windows.closeMultiWindow]: {
     req: Record<string, never>;
@@ -1268,6 +1286,7 @@ export type ScenePatch = {
   previewVideoAutostart?: boolean;
   previewRotationDeg?: 0 | 90 | 180 | 270;
   darkenScene?: boolean;
+  darknessStrokes?: SceneDarknessRevealStroke[];
   traps?: SceneTrap[];
   tokens?: SceneToken[];
   npcTokens?: SceneNpcToken[];

app/shared/types/domain.ts

@@ -13,6 +13,7 @@ import type { SceneToken } from './appTokens';
 import type { SceneNpcToken, PlayerImageOffset } from './appPlayers';
 import type { NpcDisposition } from './npcDisposition';
 import type { SceneGrid, SceneGridTemplate } from './sceneGrid';
+import type { SceneDarknessRevealStroke } from './sceneDarkness';
 import type { SceneTrap } from './sceneTraps';
 
 export const PROJECT_SCHEMA_VERSION = 12 as const;
@@ -185,6 +186,11 @@ export type Scene = {
   previewRotationDeg: 0 | 90 | 180 | 270;
   /** В режиме показа: сцена начинается полностью затемнённой; мастер «раскрывает» кистью. */
   darkenScene: boolean;
+  /**
+   * Стартовые штрихи затемнения (база в файле партии).
+   * При входе на карточку без сессионного кэша поднимаются в показ.
+   */
+  darknessStrokes: SceneDarknessRevealStroke[];
   /** Ловушки на карте (только для image-превью); расстановка в проекте. */
   traps: SceneTrap[];
   /** Неигровые токены на карте (ссылки на app-local пул). */

app/shared/types/effects.ts

@@ -199,3 +199,15 @@ export type EffectsEvent =
        */
       hitMode?: 'inclusive' | 'brush';
     };
+
+/** Туман, огонь, дождь, вода и следы льда/тьмы живут на карточке, пока идёт показ. */
+export function isPersistentFieldEffect(type: EffectInstanceType): boolean {
+  return (
+    type === 'fog' ||
+    type === 'fire' ||
+    type === 'rain' ||
+    type === 'water' ||
+    type === 'ice' ||
+    type === 'shadow'
+  );
+}

app/shared/types/gameSave.ts

@@ -0,0 +1,74 @@
+import type { SceneNpcSessionSpawn, SceneNpcTokensSessionPlacement, ScenePlayerTokenPlacement } from './appPlayers';
+import type { SceneTokensSessionPlacement } from './appTokens';
+import type { EffectInstance } from './effects';
+import type { InitiativeState } from './initiative';
+import type { MaterialsOverlayLayout } from './materials';
+import type { NpcsOverlayLayout } from './npcs';
+import type { SceneDarknessRevealStroke } from './sceneDarkness';
+import type { SceneMarkerStroke } from './sceneMarker';
+import type { SceneTrapRuntime } from './sceneTraps';
+import type { SceneViewCamera } from './sceneView';
+import type { SessionTimerLayout } from './sessionTimer';
+import type { TokenPathPlaybackEntry } from './tokenPathSession';
+
+export const GAME_SAVE_SCHEMA_VERSION = 1;
+
+export type GameSaveListItem = {
+  id: string;
+  name: string;
+  savedAt: string;
+};
+
+/** Тело слепка без id/имени/времени записи: по нему сравнивают «стол изменился». */
+export type GameSaveBody = {
+  schemaVersion: typeof GAME_SAVE_SCHEMA_VERSION;
+  projectId: string;
+  graphNodeId: string | null;
+  sceneId: string | null;
+  darknessByCard: Record<string, SceneDarknessRevealStroke[]>;
+  markersByCard: Record<string, SceneMarkerStroke[]>;
+  trapsByCard: Record<string, Record<string, SceneTrapRuntime>>;
+  effectsByCard: Record<string, EffectInstance[]>;
+  sceneTokensByPlacementId: Record<string, SceneTokensSessionPlacement>;
+  npcTokens: {
+    byPlacementId: Record<string, SceneNpcTokensSessionPlacement>;
+    scale: number;
+    spawned: Record<string, SceneNpcSessionSpawn>;
+  };
+  tokenPaths: {
+    presentationVisible: Record<string, true>;
+    playback: Record<string, TokenPathPlaybackEntry>;
+  };
+  timer: {
+    durationMs: number;
+    remainingMs: number;
+    visibleToPlayers: boolean;
+    layout: SessionTimerLayout;
+  };
+  /** null — токены игроков в момент сохранения не были показаны. */
+  playerTokens: {
+    selectedPlayerIds: string[];
+    visible: boolean;
+    byPlayerId: Record<string, ScenePlayerTokenPlacement>;
+  };
+  camera: SceneViewCamera;
+  materials: {
+    activeMaterialIds: string[];
+    layouts: Record<string, MaterialsOverlayLayout>;
+    legendLayouts: Record<string, MaterialsOverlayLayout>;
+    focusMaterialId: string | null;
+  };
+  npcAvatars: {
+    activeNpcIds: string[];
+    layouts: Record<string, NpcsOverlayLayout>;
+    focusNpcId: string | null;
+  };
+  initiative: Omit<InitiativeState, 'revision'>;
+  tokenGridSnap: boolean;
+};
+
+export type GameSaveFile = GameSaveBody & {
+  id: string;
+  name: string;
+  savedAt: string;
+};

app/shared/types/index.ts

@@ -3,6 +3,7 @@ export * from './appPlaylists';
 export * from './appTokens';
 export * from './domain';
 export * from './effects';
+export * from './gameSave';
 export * from './ids';
 export * from './materialLegend';
 export * from './materials';

app/shared/types/sceneDarkness.test.ts

@@ -3,7 +3,9 @@ import test from 'node:test';
 
 import {
   normalizeSceneDarknessBrushShape,
+  normalizeSceneDarknessRevealStroke,
   normalizeSceneDarknessStrokeMode,
+  normalizeSceneDarknessStrokes,
 } from './sceneDarkness';
 
 void test('normalizeSceneDarknessStrokeMode: reveal по умолчанию', () => {
@@ -18,3 +20,44 @@ void test('normalizeSceneDarknessBrushShape: circle по умолчанию', ()
   assert.equal(normalizeSceneDarknessBrushShape('square'), 'square');
   assert.equal(normalizeSceneDarknessBrushShape('triangle'), 'circle');
 });
+
+void test('normalizeSceneDarknessStrokes: отбрасывает мусор, нормализует точки', () => {
+  assert.deepEqual(normalizeSceneDarknessStrokes(null), []);
+  assert.deepEqual(normalizeSceneDarknessStrokes('x'), []);
+  const out = normalizeSceneDarknessStrokes([
+    { id: 'bad' },
+    {
+      id: 'ok',
+      seed: 1,
+      createdAtMs: 10,
+      radiusN: 2,
+      mode: 'cover',
+      shape: 'square',
+      points: [
+        { x: -1, y: 2, tMs: 10 },
+        { x: 0.5, y: 0.5 },
+      ],
+    },
+  ]);
+  assert.equal(out.length, 1);
+  assert.equal(out[0]?.id, 'ok');
+  assert.equal(out[0]?.mode, 'cover');
+  assert.equal(out[0]?.shape, 'square');
+  assert.equal(out[0]?.radiusN, 1);
+  assert.equal(out[0]?.points[0]?.x, 0);
+  assert.equal(out[0]?.points[0]?.y, 1);
+  assert.equal(out[0]?.points[1]?.tMs, 0);
+});
+
+void test('normalizeSceneDarknessRevealStroke: null без точек', () => {
+  assert.equal(
+    normalizeSceneDarknessRevealStroke({
+      id: 'x',
+      seed: 1,
+      createdAtMs: 1,
+      radiusN: 0.1,
+      points: [],
+    }),
+    null,
+  );
+});

app/shared/types/sceneDarkness.ts

@@ -44,3 +44,43 @@ export function normalizeSceneDarknessStrokeMode(raw: unknown): SceneDarknessStr
 export function normalizeSceneDarknessBrushShape(raw: unknown): SceneDarknessBrushShape {
   return raw === 'square' ? 'square' : 'circle';
 }
+
+export function normalizeSceneDarknessRevealStroke(raw: unknown): SceneDarknessRevealStroke | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const o = raw as Record<string, unknown>;
+  if (typeof o.id !== 'string' || !o.id) return null;
+  if (typeof o.seed !== 'number' || !Number.isFinite(o.seed)) return null;
+  if (typeof o.createdAtMs !== 'number' || !Number.isFinite(o.createdAtMs)) return null;
+  if (typeof o.radiusN !== 'number' || !Number.isFinite(o.radiusN)) return null;
+  if (!Array.isArray(o.points) || o.points.length === 0) return null;
+  const points: NPoint[] = [];
+  for (const p of o.points) {
+    if (!p || typeof p !== 'object') continue;
+    const pt = p as Record<string, unknown>;
+    if (typeof pt.x !== 'number' || typeof pt.y !== 'number') continue;
+    const tMs = typeof pt.tMs === 'number' && Number.isFinite(pt.tMs) ? pt.tMs : 0;
+    points.push({
+      x: Math.max(0, Math.min(1, pt.x)),
+      y: Math.max(0, Math.min(1, pt.y)),
+      tMs,
+      ...(typeof pt.pressure === 'number' ? { pressure: pt.pressure } : {}),
+    });
+  }
+  if (points.length === 0) return null;
+  return {
+    id: o.id,
+    seed: o.seed,
+    createdAtMs: o.createdAtMs,
+    points,
+    radiusN: Math.max(0.001, Math.min(1, o.radiusN)),
+    mode: normalizeSceneDarknessStrokeMode(o.mode),
+    shape: normalizeSceneDarknessBrushShape(o.shape),
+  };
+}
+
+export function normalizeSceneDarknessStrokes(raw: unknown): SceneDarknessRevealStroke[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((s) => normalizeSceneDarknessRevealStroke(s))
+    .filter((s): s is SceneDarknessRevealStroke => Boolean(s));
+}