feat(players): app Players library and circular NPC tokens on scenes

Add userData players/teams, scene npcTokens with hex-inscribed sizing, session scale synced to presentation, and Playwright e2e coverage.

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

app/shared/types/appPlayers.test.ts

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  clampPlayerImageOffset,
+  clampPlayerImageScale,
+  DEFAULT_PLAYER_IMAGE_SCALE,
+  DEFAULT_PLAYER_RING_COLOR,
+  normalizeAppPlayer,
+  normalizeSceneNpcToken,
+  PLAYER_IMAGE_OFFSET_MAX,
+  PLAYER_IMAGE_SCALE_MAX,
+  PLAYER_IMAGE_SCALE_MIN,
+} from './appPlayers';
+import { asNpcId, asSceneNpcTokenId } from './ids';
+
+void test('clampPlayerImageOffset clamps and defaults', () => {
+  assert.deepEqual(clampPlayerImageOffset(null), { x: 0, y: 0 });
+  assert.deepEqual(clampPlayerImageOffset({ x: 99, y: -99 }), {
+    x: PLAYER_IMAGE_OFFSET_MAX,
+    y: -PLAYER_IMAGE_OFFSET_MAX,
+  });
+});
+
+void test('clampPlayerImageScale clamps and defaults', () => {
+  assert.equal(clampPlayerImageScale(null), DEFAULT_PLAYER_IMAGE_SCALE);
+  assert.equal(clampPlayerImageScale(0.1), PLAYER_IMAGE_SCALE_MIN);
+  assert.equal(clampPlayerImageScale(9), PLAYER_IMAGE_SCALE_MAX);
+});
+
+void test('normalizeAppPlayer fills ringColor and offset', () => {
+  const p = normalizeAppPlayer({
+    id: 'player_1',
+    name: 'Ada',
+    imageRelPath: 'files/a.png',
+    sha256: 'abc',
+  });
+  assert.ok(p);
+  assert.equal(p!.ringColor, DEFAULT_PLAYER_RING_COLOR);
+  assert.deepEqual(p!.imageOffset, { x: 0, y: 0 });
+  assert.equal(p!.imageScale, DEFAULT_PLAYER_IMAGE_SCALE);
+  assert.equal(p!.teamId, null);
+});
+
+void test('normalizeAppPlayer drops unknown teamId when set provided', () => {
+  const p = normalizeAppPlayer(
+    {
+      id: 'player_1',
+      name: 'Ada',
+      imageRelPath: 'files/a.png',
+      sha256: 'abc',
+      teamId: 'missing',
+    },
+    new Set(['other']),
+  );
+  assert.equal(p!.teamId, null);
+});
+
+void test('normalizeSceneNpcToken validates and clamps', () => {
+  const t = normalizeSceneNpcToken({
+    id: 'snt_1',
+    npcId: 'npc_1',
+    nx: 1.5,
+    ny: -0.2,
+    sizeN: 0.2,
+  });
+  assert.ok(t);
+  assert.equal(t!.id, asSceneNpcTokenId('snt_1'));
+  assert.equal(t!.npcId, asNpcId('npc_1'));
+  assert.equal(t!.nx, 1);
+  assert.equal(t!.ny, 0);
+  assert.equal(normalizeSceneNpcToken({ id: 'x' }), null);
+});

app/shared/types/appPlayers.ts

@@ -0,0 +1,158 @@
+/** App-local библиотека живых игроков (userData, не в project zip). */
+
+import type { NpcId, PlayerId, PlayerTeamId, SceneNpcTokenId } from './ids';
+import { asNpcId, asPlayerId, asPlayerTeamId, asSceneNpcTokenId } from './ids';
+import { normalizeHexColor } from '../npcs/npcGroups';
+
+export type { PlayerId, PlayerTeamId, SceneNpcTokenId };
+export { asPlayerId, asPlayerTeamId, asSceneNpcTokenId };
+
+export type PlayerImageOffset = { x: number; y: number };
+
+/** Плоская команда игроков (без вложенности). */
+export type AppPlayerTeam = {
+  id: PlayerTeamId;
+  name: string;
+  /** Hex `#rrggbb`. */
+  color: string;
+};
+
+export type AppPlayer = {
+  id: PlayerId;
+  name: string;
+  /** Относительный путь файла в каталоге `userData/players/`. */
+  imageRelPath: string;
+  sha256: string;
+  teamId: PlayerTeamId | null;
+  ringColor: string;
+  imageOffset: PlayerImageOffset;
+  /** Масштаб аватара внутри круга (1 = по умолчанию). */
+  imageScale: number;
+};
+
+/** Расстановка кампанийного НПС на карте как игрового токена (в проекте). */
+export type SceneNpcToken = {
+  id: SceneNpcTokenId;
+  npcId: NpcId;
+  nx: number;
+  ny: number;
+  sizeN: number;
+};
+
+export const DEFAULT_PLAYER_RING_COLOR = '#c9a227';
+export const DEFAULT_PLAYER_IMAGE_OFFSET: PlayerImageOffset = { x: 0, y: 0 };
+export const PLAYER_IMAGE_OFFSET_MIN = -0.45;
+export const PLAYER_IMAGE_OFFSET_MAX = 0.45;
+export const DEFAULT_PLAYER_IMAGE_SCALE = 1;
+export const PLAYER_IMAGE_SCALE_MIN = 0.5;
+export const PLAYER_IMAGE_SCALE_MAX = 3;
+export const PLAYER_IMAGE_SCALE_STEP = 0.08;
+
+export const DEFAULT_SCENE_NPC_TOKEN_SIZE_N = 0.1;
+export const SCENE_NPC_TOKEN_SIZE_MIN = 0.04;
+export const SCENE_NPC_TOKEN_SIZE_MAX = 0.45;
+
+/** Множитель размера всех НПС-токенов на пульте/презентации (session-only). */
+export const DEFAULT_NPC_TOKEN_SESSION_SCALE = 1;
+export const NPC_TOKEN_SESSION_SCALE_MIN = 0.4;
+export const NPC_TOKEN_SESSION_SCALE_MAX = 2.5;
+
+export type SceneNpcTokensSessionState = {
+  revision: number;
+  byPlacementId: Record<string, { nx: number; ny: number }>;
+  /** Общий масштаб отображения всех НПС-токенов (не пишется в проект). */
+  scale: number;
+};
+
+export type SceneNpcTokensSessionEvent =
+  | { kind: 'move'; placementId: string; nx: number; ny: number }
+  | { kind: 'setScale'; scale: number }
+  | { kind: 'clear' };
+
+export function clampNpcTokenSessionScale(raw: unknown): number {
+  const n = typeof raw === 'number' && Number.isFinite(raw) ? raw : DEFAULT_NPC_TOKEN_SESSION_SCALE;
+  return Math.max(NPC_TOKEN_SESSION_SCALE_MIN, Math.min(NPC_TOKEN_SESSION_SCALE_MAX, n));
+}
+
+export type PlayersUpsertProgressEvent = {
+  percent: number;
+  stage: string;
+  detail?: string;
+};
+
+export function clampPlayerImageOffset(raw: unknown): PlayerImageOffset {
+  if (!raw || typeof raw !== 'object') return { ...DEFAULT_PLAYER_IMAGE_OFFSET };
+  const obj = raw as { x?: unknown; y?: unknown };
+  const x = typeof obj.x === 'number' && Number.isFinite(obj.x) ? obj.x : 0;
+  const y = typeof obj.y === 'number' && Number.isFinite(obj.y) ? obj.y : 0;
+  return {
+    x: Math.max(PLAYER_IMAGE_OFFSET_MIN, Math.min(PLAYER_IMAGE_OFFSET_MAX, x)),
+    y: Math.max(PLAYER_IMAGE_OFFSET_MIN, Math.min(PLAYER_IMAGE_OFFSET_MAX, y)),
+  };
+}
+
+export function clampPlayerImageScale(raw: unknown): number {
+  const n = typeof raw === 'number' && Number.isFinite(raw) ? raw : DEFAULT_PLAYER_IMAGE_SCALE;
+  return Math.max(PLAYER_IMAGE_SCALE_MIN, Math.min(PLAYER_IMAGE_SCALE_MAX, n));
+}
+
+export function clampSceneNpcTokenSizeN(sizeN: number): number {
+  if (!Number.isFinite(sizeN)) return DEFAULT_SCENE_NPC_TOKEN_SIZE_N;
+  return Math.max(SCENE_NPC_TOKEN_SIZE_MIN, Math.min(SCENE_NPC_TOKEN_SIZE_MAX, sizeN));
+}
+
+export function normalizeAppPlayerTeam(raw: unknown): AppPlayerTeam | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const obj = raw as Partial<AppPlayerTeam>;
+  if (typeof obj.id !== 'string' || !obj.id) return null;
+  if (typeof obj.name !== 'string') return null;
+  const name = obj.name.trim();
+  if (!name) return null;
+  return {
+    id: asPlayerTeamId(obj.id),
+    name,
+    color: normalizeHexColor(obj.color, DEFAULT_PLAYER_RING_COLOR),
+  };
+}
+
+export function normalizeAppPlayer(raw: unknown, teamIds?: Set<string>): AppPlayer | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const obj = raw as Partial<AppPlayer> & { teamId?: string | null };
+  if (typeof obj.id !== 'string' || !obj.id) return null;
+  if (typeof obj.name !== 'string') return null;
+  const name = obj.name.trim();
+  if (!name) return null;
+  if (typeof obj.imageRelPath !== 'string' || !obj.imageRelPath) return null;
+  if (typeof obj.sha256 !== 'string' || !obj.sha256) return null;
+  let teamId: PlayerTeamId | null = null;
+  if (typeof obj.teamId === 'string' && obj.teamId) {
+    if (!teamIds || teamIds.has(obj.teamId)) teamId = asPlayerTeamId(obj.teamId);
+  }
+  return {
+    id: asPlayerId(obj.id),
+    name,
+    imageRelPath: obj.imageRelPath,
+    sha256: obj.sha256,
+    teamId,
+    ringColor: normalizeHexColor(obj.ringColor, DEFAULT_PLAYER_RING_COLOR),
+    imageOffset: clampPlayerImageOffset(obj.imageOffset),
+    imageScale: clampPlayerImageScale((obj as { imageScale?: unknown }).imageScale),
+  };
+}
+
+export function normalizeSceneNpcToken(raw: unknown): SceneNpcToken | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const obj = raw as Partial<SceneNpcToken>;
+  if (typeof obj.id !== 'string' || !obj.id) return null;
+  if (typeof obj.npcId !== 'string' || !obj.npcId) return null;
+  const nx = typeof obj.nx === 'number' && Number.isFinite(obj.nx) ? obj.nx : null;
+  const ny = typeof obj.ny === 'number' && Number.isFinite(obj.ny) ? obj.ny : null;
+  if (nx === null || ny === null) return null;
+  return {
+    id: asSceneNpcTokenId(obj.id),
+    npcId: asNpcId(obj.npcId),
+    nx: Math.max(0, Math.min(1, nx)),
+    ny: Math.max(0, Math.min(1, ny)),
+    sizeN: clampSceneNpcTokenSizeN(typeof obj.sizeN === 'number' ? obj.sizeN : DEFAULT_SCENE_NPC_TOKEN_SIZE_N),
+  };
+}

app/shared/types/domain.ts

@@ -10,10 +10,11 @@ import type {
 } from './ids';
 import type { MaterialLegend } from './materialLegend';
 import type { SceneToken } from './appTokens';
+import type { SceneNpcToken, PlayerImageOffset } from './appPlayers';
 import type { SceneGrid } from './sceneGrid';
 import type { SceneTrap } from './sceneTraps';
 
-export const PROJECT_SCHEMA_VERSION = 10 as const;
+export const PROJECT_SCHEMA_VERSION = 11 as const;
 
 /** Материал кампании: изображение, показываемое поверх сцены во время игры. */
 export type ProjectMaterial = {
@@ -46,6 +47,12 @@ export type ProjectNpc = {
   y: number;
   /** `null` — системная секция «Без группы». */
   groupId: NpcGroupId | null;
+  /** Цвет кольца игрового токена на сцене. */
+  ringColor: string;
+  /** Сдвиг аватара внутри круга токена. */
+  imageOffset: PlayerImageOffset;
+  /** Масштаб аватара внутри круга токена. */
+  imageScale: number;
 };
 
 /** Однонаправленная связь: от `sourceNpcId` к `targetNpcId`; подпись на линии. */
@@ -154,6 +161,8 @@ export type Scene = {
   traps: SceneTrap[];
   /** Неигровые токены на карте (ссылки на app-local пул). */
   tokens: SceneToken[];
+  /** Кампанийные НПС на карте как игровые токены (отдельно от неигровых). */
+  npcTokens: SceneNpcToken[];
   /** Боевая сетка поверх превью (под ловушками/эффектами). */
   grid: SceneGrid;
   media: SceneMediaRefs;

app/shared/types/ids.ts

@@ -10,6 +10,9 @@ export type NpcRelationId = Brand<string, 'NpcRelationId'>;
 export type NpcGroupId = Brand<string, 'NpcGroupId'>;
 export type TokenId = Brand<string, 'TokenId'>;
 export type SceneTokenId = Brand<string, 'SceneTokenId'>;
+export type PlayerId = Brand<string, 'PlayerId'>;
+export type PlayerTeamId = Brand<string, 'PlayerTeamId'>;
+export type SceneNpcTokenId = Brand<string, 'SceneNpcTokenId'>;
 
 export function asProjectId(value: string): ProjectId {
   return value as ProjectId;
@@ -50,3 +53,15 @@ export function asTokenId(value: string): TokenId {
 export function asSceneTokenId(value: string): SceneTokenId {
   return value as SceneTokenId;
 }
+
+export function asPlayerId(value: string): PlayerId {
+  return value as PlayerId;
+}
+
+export function asPlayerTeamId(value: string): PlayerTeamId {
+  return value as PlayerTeamId;
+}
+
+export function asSceneNpcTokenId(value: string): SceneNpcTokenId {
+  return value as SceneNpcTokenId;
+}

app/shared/types/index.ts

@@ -1,3 +1,4 @@
+export * from './appPlayers';
 export * from './appTokens';
 export * from './domain';
 export * from './effects';

app/shared/types/sceneGrid.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { sceneGridTokenFitFactor } from './sceneGrid';
+
+void test('sceneGridTokenFitFactor: square and disabled = 1', () => {
+  assert.equal(sceneGridTokenFitFactor(undefined), 1);
+  assert.equal(sceneGridTokenFitFactor({ enabled: false, type: 'hex' }), 1);
+  assert.equal(sceneGridTokenFitFactor({ enabled: true, type: 'square' }), 1);
+});
+
+void test('sceneGridTokenFitFactor: hex uses inscribed diameter', () => {
+  assert.ok(Math.abs(sceneGridTokenFitFactor({ enabled: true, type: 'hex' }) - Math.sqrt(3) / 2) < 1e-9);
+});

app/shared/types/sceneGrid.ts

@@ -59,3 +59,14 @@ export function normalizeSceneGrid(raw: unknown): SceneGrid {
 export function sceneGridTypeLabelRu(type: SceneGridType): string {
   return type === 'hex' ? 'Гексогональная' : 'Квадратная';
 }
+
+/**
+ * Множитель диаметра токена «в одну ячейку» относительно `grid.sizeN`.
+ * Square: сторона клетки = sizeN.
+ * Flat-top hex: sizeN — ширина (vertex-to-vertex, описанная окружность);
+ * вписанная окружность = flat-to-flat = sizeN · √3/2.
+ */
+export function sceneGridTokenFitFactor(grid: Pick<SceneGrid, 'enabled' | 'type'> | null | undefined): number {
+  if (!grid?.enabled || grid.type !== 'hex') return 1;
+  return Math.sqrt(3) / 2;
+}