feat(players): NPC disposition types and launch-with-players session tokens

Add Hostile/Neutral/Friendly ring types with session-only inactive overrides on control, plus launch-with-players flow and live player tokens on the map.

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

app/main/players/sceneNpcTokensSessionStore.test.ts

@@ -30,3 +30,31 @@ void test('SceneNpcTokensSessionStore setScale', () => {
   assert.equal(s3.scale, DEFAULT_NPC_TOKEN_SESSION_SCALE);
   assert.deepEqual(s3.byPlacementId, {});
 });
+
+void test('SceneNpcTokensSessionStore setDisposition without inventing position', () => {
+  const store = new SceneNpcTokensSessionStore();
+  const s1 = store.dispatch({
+    kind: 'setDisposition',
+    placementId: 'a',
+    disposition: 'hostile',
+  });
+  assert.equal(s1.byPlacementId.a?.disposition, 'hostile');
+  assert.equal(s1.byPlacementId.a?.nx, undefined);
+  assert.equal(s1.byPlacementId.a?.ny, undefined);
+  const s2 = store.dispatch({ kind: 'move', placementId: 'a', nx: 0.4, ny: 0.6 });
+  assert.equal(s2.byPlacementId.a?.nx, 0.4);
+  assert.equal(s2.byPlacementId.a?.disposition, 'hostile');
+});
+
+void test('SceneNpcTokensSessionStore setInactive is session flag', () => {
+  const store = new SceneNpcTokensSessionStore();
+  const s1 = store.dispatch({ kind: 'setInactive', placementId: 'a', inactive: true });
+  assert.equal(s1.byPlacementId.a?.inactive, true);
+  const s2 = store.dispatch({ kind: 'setInactive', placementId: 'a', inactive: false });
+  assert.deepEqual(s2.byPlacementId, {});
+  store.dispatch({ kind: 'move', placementId: 'a', nx: 0.2, ny: 0.3 });
+  store.dispatch({ kind: 'setInactive', placementId: 'a', inactive: true });
+  const s3 = store.dispatch({ kind: 'setInactive', placementId: 'a', inactive: false });
+  assert.equal(s3.byPlacementId.a?.nx, 0.2);
+  assert.equal(s3.byPlacementId.a?.inactive, undefined);
+});

app/main/players/sceneNpcTokensSessionStore.ts

@@ -2,8 +2,10 @@ import {
   clampNpcTokenSessionScale,
   DEFAULT_NPC_TOKEN_SESSION_SCALE,
   type SceneNpcTokensSessionEvent,
+  type SceneNpcTokensSessionPlacement,
   type SceneNpcTokensSessionState,
 } from '../../shared/types/appPlayers';
+import { normalizeNpcDisposition } from '../../shared/types/npcDisposition';
 
 function emptyState(revision = 1): SceneNpcTokensSessionState {
   return {
@@ -13,6 +15,36 @@ function emptyState(revision = 1): SceneNpcTokensSessionState {
   };
 }
 
+function isEmptyPlacement(p: SceneNpcTokensSessionPlacement): boolean {
+  return p.nx === undefined && p.ny === undefined && !p.disposition && !p.inactive;
+}
+
+function withMove(
+  prev: SceneNpcTokensSessionPlacement | undefined,
+  nx: number,
+  ny: number,
+): SceneNpcTokensSessionPlacement {
+  return {
+    nx,
+    ny,
+    ...(prev?.disposition ? { disposition: prev.disposition } : {}),
+    ...(prev?.inactive ? { inactive: true } : {}),
+  };
+}
+
+function withoutPlacement(
+  state: SceneNpcTokensSessionState,
+  placementId: string,
+): SceneNpcTokensSessionState {
+  if (!(placementId in state.byPlacementId)) return state;
+  const { [placementId]: _removed, ...rest } = state.byPlacementId;
+  return {
+    revision: state.revision + 1,
+    byPlacementId: rest,
+    scale: state.scale,
+  };
+}
+
 export class SceneNpcTokensSessionStore {
   private state: SceneNpcTokensSessionState = emptyState();
 
@@ -57,7 +89,55 @@ export class SceneNpcTokensSessionStore {
           revision: this.state.revision + 1,
           byPlacementId: {
             ...this.state.byPlacementId,
-            [placementId]: { nx, ny },
+            [placementId]: withMove(prev, nx, ny),
+          },
+          scale: this.state.scale,
+        };
+        return this.state;
+      }
+      case 'setDisposition': {
+        const placementId = String(event.placementId ?? '');
+        if (!placementId) return this.state;
+        const disposition = normalizeNpcDisposition(event.disposition);
+        const prev = this.state.byPlacementId[placementId];
+        if (prev?.disposition === disposition) return this.state;
+        const next: SceneNpcTokensSessionPlacement = {
+          ...(prev?.nx !== undefined ? { nx: prev.nx } : {}),
+          ...(prev?.ny !== undefined ? { ny: prev.ny } : {}),
+          disposition,
+          ...(prev?.inactive ? { inactive: true } : {}),
+        };
+        this.state = {
+          revision: this.state.revision + 1,
+          byPlacementId: {
+            ...this.state.byPlacementId,
+            [placementId]: next,
+          },
+          scale: this.state.scale,
+        };
+        return this.state;
+      }
+      case 'setInactive': {
+        const placementId = String(event.placementId ?? '');
+        if (!placementId) return this.state;
+        const inactive = Boolean(event.inactive);
+        const prev = this.state.byPlacementId[placementId];
+        if (Boolean(prev?.inactive) === inactive) return this.state;
+        const next: SceneNpcTokensSessionPlacement = {
+          ...(prev?.nx !== undefined ? { nx: prev.nx } : {}),
+          ...(prev?.ny !== undefined ? { ny: prev.ny } : {}),
+          ...(prev?.disposition ? { disposition: prev.disposition } : {}),
+          ...(inactive ? { inactive: true } : {}),
+        };
+        if (isEmptyPlacement(next)) {
+          this.state = withoutPlacement(this.state, placementId);
+          return this.state;
+        }
+        this.state = {
+          revision: this.state.revision + 1,
+          byPlacementId: {
+            ...this.state.byPlacementId,
+            [placementId]: next,
           },
           scale: this.state.scale,
         };

app/main/players/scenePlayerTokensSessionStore.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ScenePlayerTokensSessionStore } from './scenePlayerTokensSessionStore';
+
+void test('ScenePlayerTokensSessionStore selection and show/hide', () => {
+  const store = new ScenePlayerTokensSessionStore();
+  store.dispatch({ kind: 'setSelection', playerIds: ['a', 'b', 'a'] });
+  assert.deepEqual(store.getState().selectedPlayerIds, ['a', 'b']);
+  assert.equal(store.getState().visible, false);
+
+  store.dispatch({ kind: 'show', sizeN: 0.08 });
+  assert.equal(store.getState().visible, true);
+  assert.equal(Object.keys(store.getState().byPlayerId).length, 2);
+  assert.ok(store.getState().byPlayerId.a);
+  assert.equal(store.getState().byPlayerId.a?.ny, 0.88);
+
+  store.dispatch({ kind: 'setVisible', visible: false });
+  assert.equal(store.getState().visible, false);
+  assert.ok(store.getState().byPlayerId.a);
+
+  store.dispatch({ kind: 'clearPlacements' });
+  assert.equal(store.getState().visible, false);
+  assert.deepEqual(store.getState().byPlayerId, {});
+  assert.deepEqual(store.getState().selectedPlayerIds, ['a', 'b']);
+});
+
+void test('ScenePlayerTokensSessionStore move and reset', () => {
+  const store = new ScenePlayerTokensSessionStore();
+  store.dispatch({ kind: 'setSelection', playerIds: ['p1'] });
+  store.dispatch({ kind: 'show', sizeN: 0.1 });
+  const s1 = store.dispatch({ kind: 'move', playerId: 'p1', nx: 0.3, ny: 0.4 });
+  assert.equal(s1.byPlayerId.p1?.nx, 0.3);
+  assert.equal(s1.byPlayerId.p1?.ny, 0.4);
+  const s2 = store.reset();
+  assert.deepEqual(s2.selectedPlayerIds, []);
+  assert.equal(s2.visible, false);
+  assert.deepEqual(s2.byPlayerId, {});
+});

app/main/players/scenePlayerTokensSessionStore.ts

@@ -0,0 +1,143 @@
+import {
+  clampSceneNpcTokenSizeN,
+  DEFAULT_SCENE_NPC_TOKEN_SIZE_N,
+  layoutPlayerTokensBottom,
+  type ScenePlayerTokensSessionEvent,
+  type ScenePlayerTokensSessionState,
+} from '../../shared/types/appPlayers';
+
+function emptyState(revision = 1): ScenePlayerTokensSessionState {
+  return {
+    revision,
+    selectedPlayerIds: [],
+    visible: false,
+    byPlayerId: {},
+  };
+}
+
+function normalizePlayerIds(raw: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const id of raw) {
+    const s = String(id ?? '').trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+export class ScenePlayerTokensSessionStore {
+  private state: ScenePlayerTokensSessionState = emptyState();
+
+  getState(): ScenePlayerTokensSessionState {
+    return this.state;
+  }
+
+  reset(): ScenePlayerTokensSessionState {
+    if (
+      this.state.selectedPlayerIds.length === 0 &&
+      !this.state.visible &&
+      Object.keys(this.state.byPlayerId).length === 0
+    ) {
+      return this.state;
+    }
+    this.state = emptyState(this.state.revision + 1);
+    return this.state;
+  }
+
+  /** Смена сцены: спрятать токены, сбросить позиции; выбор игроков сохранить. */
+  clearPlacements(): ScenePlayerTokensSessionState {
+    if (!this.state.visible && Object.keys(this.state.byPlayerId).length === 0) {
+      return this.state;
+    }
+    this.state = {
+      ...this.state,
+      revision: this.state.revision + 1,
+      visible: false,
+      byPlayerId: {},
+    };
+    return this.state;
+  }
+
+  dispatch(event: ScenePlayerTokensSessionEvent): ScenePlayerTokensSessionState {
+    switch (event.kind) {
+      case 'clear':
+        return this.reset();
+      case 'clearPlacements':
+        return this.clearPlacements();
+      case 'setSelection': {
+        const selectedPlayerIds = normalizePlayerIds(event.playerIds);
+        const same =
+          selectedPlayerIds.length === this.state.selectedPlayerIds.length &&
+          selectedPlayerIds.every((id, i) => id === this.state.selectedPlayerIds[i]);
+        if (same) return this.state;
+        this.state = {
+          revision: this.state.revision + 1,
+          selectedPlayerIds,
+          visible: false,
+          byPlayerId: {},
+        };
+        return this.state;
+      }
+      case 'setVisible': {
+        const visible = Boolean(event.visible);
+        if (this.state.visible === visible) return this.state;
+        if (visible && this.state.selectedPlayerIds.length === 0) return this.state;
+        this.state = { ...this.state, revision: this.state.revision + 1, visible };
+        return this.state;
+      }
+      case 'show': {
+        if (this.state.selectedPlayerIds.length === 0) return this.state;
+        const sizeN = clampSceneNpcTokenSizeN(event.sizeN);
+        const byPlayerId =
+          Object.keys(this.state.byPlayerId).length > 0
+            ? this.state.byPlayerId
+            : layoutPlayerTokensBottom(this.state.selectedPlayerIds, sizeN);
+        if (this.state.visible && byPlayerId === this.state.byPlayerId) return this.state;
+        this.state = {
+          ...this.state,
+          revision: this.state.revision + 1,
+          visible: true,
+          byPlayerId,
+        };
+        return this.state;
+      }
+      case 'seedBottom': {
+        if (this.state.selectedPlayerIds.length === 0) return this.state;
+        if (Object.keys(this.state.byPlayerId).length > 0) return this.state;
+        const sizeN = clampSceneNpcTokenSizeN(event.sizeN);
+        this.state = {
+          ...this.state,
+          revision: this.state.revision + 1,
+          byPlayerId: layoutPlayerTokensBottom(this.state.selectedPlayerIds, sizeN),
+        };
+        return this.state;
+      }
+      case 'move': {
+        const playerId = String(event.playerId ?? '');
+        if (!playerId || !this.state.selectedPlayerIds.includes(playerId)) return this.state;
+        const nx = Math.max(0, Math.min(1, event.nx));
+        const ny = Math.max(0, Math.min(1, event.ny));
+        if (!Number.isFinite(nx) || !Number.isFinite(ny)) return this.state;
+        const prev = this.state.byPlayerId[playerId];
+        if (prev && prev.nx === nx && prev.ny === ny) return this.state;
+        const sizeN = clampSceneNpcTokenSizeN(prev?.sizeN ?? DEFAULT_SCENE_NPC_TOKEN_SIZE_N);
+        this.state = {
+          ...this.state,
+          revision: this.state.revision + 1,
+          byPlayerId: {
+            ...this.state.byPlayerId,
+            [playerId]: { nx, ny, sizeN },
+          },
+        };
+        return this.state;
+      }
+      default: {
+        const _exhaustive: never = event;
+        void _exhaustive;
+        return this.state;
+      }
+    }
+  }
+}