refactor: introduce dedicated identifier types for improved clarity and type safety

frontend/src/desktop/workspaceEngine.ts

@@ -1,7 +1,7 @@
 import { clamp, formatTransform } from '../utils/math';
 import { fetchLayoutRecords, upsertLayoutRecords } from './db';
-
-type DocumentId = string;
+import type { DocumentId } from '../types/identifiers';
+type TenantId = import('../types/identifiers').TenantId;
 
 interface Point {
   x: number;
@@ -63,7 +63,7 @@ interface BaseMetrics {
 }
 
 interface DragGroupItem {
-  docId?: string | number | null;
+  docId?: string | null;
   width: number;
   height: number;
   currentCenterX?: number;
@@ -80,7 +80,7 @@ interface DragState {
 }
 
 interface InertiaSimulationState {
-  docId: string;
+  docId: DocumentId;
   restRotation: number;
   rotation: number;
   dynamicRotation: number;
@@ -106,7 +106,7 @@ interface WorkspaceSnapshot {
 
 type WorkspaceSubscriber = () => void;
 
-type DeskDocument = { id?: string | number | null } & Record<string, unknown>;
+type DeskDocument = { id?: string | null } & Record<string, unknown>;
 
 type EnsureDocumentSize = (doc: DeskDocument) => DocumentSize | null;
 
@@ -226,7 +226,7 @@ export const clampCardDimensions = (width: number, height: number): CardDimensio
   };
 };
 
-export const computeFallbackCardSize = (docId: string | number): CardDimensions | null => {
+export const computeFallbackCardSize = (docId: DocumentId): CardDimensions | null => {
   const baseSeed = seededRandom(`${docId}:fallback-size`);
   const aspectSeed = seededRandom(`${docId}:fallback-aspect`);
 
@@ -259,7 +259,7 @@ function randomRangeFromSeed(seedKey: string, min: number, max: number): number
   return min + seed * span;
 }
 
-function buildKey(docId: string | number, suffix: string): string {
+function buildKey(docId: DocumentId, suffix: string): string {
   return `${docId}::${suffix}`;
 }
 
@@ -525,63 +525,34 @@ const generateInitialLayout = (
 
 export class WorkspaceEngine {
   allowLayoutPersistence: boolean;
-
-  tenantId: string | null;
-
+  tenantId: TenantId | null;
   viewId: string | null;
-
   layout: Map<DocumentId, LayoutEntry>;
-
   layoutSnapshot: Map<DocumentId, LayoutEntry>;
-
   persistedLayout: Map<DocumentId, LayoutEntry>;
-
   layoutDirty: boolean;
-
   zCounter: number;
-
   canvasSize: { width: number; height: number };
-
   visibleDocIds: Set<DocumentId>;
-
   draggingId: string | null;
-
   tagDropTargetId: string | null;
-
   pendingTagDocId: string | null;
-
   pendingRemovalTag: unknown;
-
   dragInProgress: boolean;
-
   activeDragDocIds: Set<DocumentId>;
-
   pendingSnapshotSync: boolean;
-
   pendingPersistSync: boolean;
-
   persistDebounceId: number | null;
-
   items: DeskDocument[];
-
   documentLookup: Map<string, DeskDocument>;
-
   ensureDocumentSize: EnsureDocumentSize;
-
   resolveBaseMetrics: ResolveBaseMetrics;
-
   snapshotCache: WorkspaceSnapshot;
-
   subscribers: Set<WorkspaceSubscriber>;
-
   loadingPersisted: boolean;
-
   pendingPersistence: unknown;
-
   itemRefs: ItemRefs;
-
   inertiaAnimations: Map<string, InertiaSimulationState>;
-
   initialLoadDone: boolean;
 
   constructor({
@@ -716,7 +687,7 @@ export class WorkspaceEngine {
     this.emit();
   }
 
-  setDraggingId(docId: string | number | null): void {
+  setDraggingId(docId: DocumentId | null): void {
     const normalized = docId != null ? String(docId) : null;
     if (this.draggingId === normalized) {
       return;
@@ -725,7 +696,7 @@ export class WorkspaceEngine {
     this.emit();
   }
 
-  beginDrag(docIds: Array<string | number | null> = []): void {
+  beginDrag(docIds: Array<string | null> = []): void {
     this.dragInProgress = true;
     if (Array.isArray(docIds)) {
       this.activeDragDocIds = new Set(docIds.map((id) => (id != null ? String(id) : null)).filter(Boolean));
@@ -749,7 +720,7 @@ export class WorkspaceEngine {
     }
   }
 
-  setTagDropTargetId(docId: string | number | null): void {
+  setTagDropTargetId(docId: DocumentId | null): void {
     const normalized = docId != null ? String(docId) : null;
     if (this.tagDropTargetId === normalized) {
       return;
@@ -758,7 +729,7 @@ export class WorkspaceEngine {
     this.emit();
   }
 
-  setPendingTagDocId(docId: string | number | null): void {
+  setPendingTagDocId(docId: DocumentId | null): void {
     const normalized = docId != null ? String(docId) : null;
     if (this.pendingTagDocId === normalized) {
       return;
@@ -779,7 +750,7 @@ export class WorkspaceEngine {
     this.layoutDirty = true;
   }
 
-  getLayout(docId: string | number | null): LayoutEntry | null {
+  getLayout(docId: DocumentId | null): LayoutEntry | null {
     if (docId == null) {
       return null;
     }
@@ -788,7 +759,7 @@ export class WorkspaceEngine {
   }
 
   updateLayoutEntry(
-    docId: string | number | null,
+    docId: DocumentId | null,
     updater: (previous: LayoutEntry | null) => LayoutEntry | null,
   ): void {
     if (docId == null) {
@@ -807,7 +778,7 @@ export class WorkspaceEngine {
     this.persistLayoutSnapshot();
   }
 
-  bringToFront(docId: string | number | null): void {
+  bringToFront(docId: DocumentId | null): void {
     if (docId == null) {
       return;
     }
@@ -825,7 +796,7 @@ export class WorkspaceEngine {
   }
 
   applyTransform(
-    docId: string | number | null,
+    docId: DocumentId | null,
     centerX: number,
     centerY: number,
     width: number,
@@ -896,7 +867,7 @@ export class WorkspaceEngine {
     this.persistLayoutSnapshot();
   }
 
-  cancelInertiaAnimation(docId: string | number | null): void {
+  cancelInertiaAnimation(docId: DocumentId | null): void {
     const key = docId != null ? String(docId) : null;
     if (!key) {
       return;
@@ -995,7 +966,7 @@ export class WorkspaceEngine {
     return isSettled;
   }
 
-  startInertiaAnimation(docId: string | number | null, baseState: InertiaSimulationState): void {
+  startInertiaAnimation(docId: DocumentId | null, baseState: InertiaSimulationState): void {
     const raf = window.requestAnimationFrame;
     if (!raf) {
       return;