@telemetryos/cli 1.9.0 → 1.11.0

package/templates/vite-react-typescript/_claude/skills/tos-multi-mode/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: tos-multi-mode
+description: Architecture for apps with multiple Render view modes sharing data through a top-level entity. Use when building apps where different devices show different views (e.g., kiosk vs display) with shared data scoped to an entity like location or topic.
+---
+
+# Multi-Mode App Architecture
+
+Some TelemetryOS apps need multiple Render view modes — the same app configured once, but different devices show different views. A queue manager is a classic example: one device runs a ticket kiosk, another shows a "now serving" display. Both share the same queue data scoped to a location.
+
+## When to Use This Skill
+
+Listen for these indicators during requirements gathering:
+
+- "One screen shows X while another shows Y"
+- "Kiosk and display" or "control panel and viewer"
+- "Different devices need different views of the same data"
+- Data that's organized by location, department, topic, or similar grouping
+
+If ANY of these come up, this is a multi-mode app.
+
+---
+
+## Choosing the Top-Level Entity
+
+**This is the most important architectural decision for a multi-mode app.**
+
+Every multi-mode app needs a top-level organizing entity that scopes all shared data. The developer will almost never think of this on their own — they'll describe the modes ("a kiosk screen and a display screen") but won't mention what scopes the shared data. **You must actively discover or propose one.**
+
+### How to discover the entity
+
+Ask: "What organizes the data these modes share? For example, is this per-location, per-department, per-topic?"
+
+If the developer doesn't have a clear answer, **propose one** based on the app domain:
+
+| App Domain | Likely Entity | Examples |
+|------------|---------------|----------|
+| Queue / service | location, branch | "Downtown Office", "Main Lobby" |
+| Content / editorial | topic, channel | "Sports", "Company News" |
+| Event / scheduling | event, venue | "Conference 2025", "Room A" |
+| Organizational | department, team | "Engineering", "Sales" |
+| Retail / menu | store, menu | "Store #42", "Lunch Menu" |
+
+### Why the entity matters
+
+Explain to the developer: "This lets you run the same app at multiple [locations] — each with its own independent data — without creating separate app instances. An admin just selects which [location] each device belongs to."
+
+The entity name flows into everything:
+- **Namespace helper**: `locationNamespace('Downtown Office')` → `'queue-manager-Downtown Office'`
+- **Store keys**: `useSelectedLocationStoreState`
+- **Settings labels**: "Location" dropdown, "Locations" management section
+- **Mental model**: admins think in terms of the entity
+
+---
+
+## Architecture Overview
+
+Multi-mode apps use a 3-tier store pattern:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Instance Scope (per-device)                                │
+│  ┌─────────────────┐  ┌──────────────────────────────────┐  │
+│  │  mode: 'kiosk'  │  │  selectedLocation: 'Location A'  │  │
+│  └─────────────────┘  └──────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  Application Scope (shared across all instances)            │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  locations: ['Location A', 'Location B']              │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  Dynamic Namespace Scope (per-entity, shared between modes) │
+│  namespace: 'queue-manager-Location A'                      │
+│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐  │
+│  │  serviceTypes │ │   counters   │ │   calledHistory     │  │
+│  └──────────────┘ └──────────────┘ └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**How it connects:**
+
+1. Admin creates locations in Settings (application scope)
+2. Each device selects a mode AND a location (instance scope)
+3. All devices on the same location share the same data (dynamic namespace scope)
+4. A kiosk at "Location A" and a display at "Location A" see the same queues
+
+---
+
+## Store Layer Pattern
+
+### hooks/store.ts
+
+```typescript
+import {
+  createUseInstanceStoreState,
+  createUseApplicationStoreState,
+  createUseDynamicNamespaceStoreState,
+} from '@telemetryos/sdk/react'
+
+// --- Instance scope (per-device) ---
+
+// Which mode this device displays
+export const useModeStoreState = createUseInstanceStoreState<'kiosk' | 'display'>('mode', 'kiosk')
+
+// Which entity this device belongs to
+export const useSelectedLocationStoreState = createUseInstanceStoreState<string>('selected-location', 'Location A')
+
+// UI Scale (for display modes)
+export const useUiScaleStoreState = createUseInstanceStoreState<number>('ui-scale', 1)
+
+// --- Application scope (shared across all instances) ---
+
+// The list of all entities — managed by admins
+export const useLocationsStoreState = createUseApplicationStoreState<string[]>('locations', ['Location A'])
+
+// --- Dynamic namespace scope (per-entity, shared between modes) ---
+
+// All data that's scoped to an entity uses dynamic namespace hooks.
+// The namespace is passed at call time, not at definition time.
+
+export const useServiceTypesStoreState = createUseDynamicNamespaceStoreState<ServiceType[]>('service-types', [])
+export const useCountersStoreState = createUseDynamicNamespaceStoreState<Counter[]>('counters', [])
+export const useCalledHistoryStoreState = createUseDynamicNamespaceStoreState<CalledNumber[]>('called-history', [])
+
+// --- Namespace helper ---
+
+// Derives a unique namespace from the entity name.
+// All hooks for the same entity use the same namespace.
+export function locationNamespace(location: string): string {
+  return `queue-manager-${location}`
+}
+```
+
+### Key rules
+
+- **Mode** is always instance scope — each device picks its own mode
+- **Entity selection** is always instance scope — each device picks its entity
+- **Entity list** is always application scope — admins manage it globally
+- **All shared data** uses dynamic namespace — scoped to the entity
+- **Namespace helper** is a pure function: entity name in, namespace string out
+
+---
+
+## Entity Selection Validation
+
+The selected entity might not exist anymore (admin removed it). Always validate:
+
+```typescript
+// In Settings or Render
+const [isLoadingLocations, locations] = useLocationsStoreState()
+const [isLoadingLocation, selectedLocation, setSelectedLocation] = useSelectedLocationStoreState()
+
+// Safe fallback
+const safeLocations = locations || ['Location A']
+const effectiveLocation = safeLocations.includes(selectedLocation || '')
+  ? (selectedLocation || 'Location A')
+  : safeLocations[0]
+
+// Derive namespace from validated entity
+const ns = locationNamespace(effectiveLocation)
+
+// Now use ns with all dynamic namespace hooks
+const [isLoadingTypes, serviceTypes, setServiceTypes] = useServiceTypesStoreState(ns, 250)
+const [isLoadingCounters, counters, setCounters] = useCountersStoreState(ns, 250)
+```
+
+---
+
+## Render View Pattern
+
+Load all hooks, aggregate loading state, then branch on mode:
+
+```typescript
+import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
+import {
+  useModeStoreState,
+  useUiScaleStoreState,
+  useSelectedLocationStoreState,
+  useServiceTypesStoreState,
+  useCountersStoreState,
+  useCalledHistoryStoreState,
+  locationNamespace,
+} from '../hooks/store'
+
+export function Render() {
+  // Instance-scoped hooks
+  const [isLoadingScale, uiScale] = useUiScaleStoreState()
+  const [isLoadingMode, mode] = useModeStoreState()
+  const [isLoadingLocation, selectedLocation] = useSelectedLocationStoreState()
+
+  // Derive namespace
+  const ns = locationNamespace(selectedLocation || 'Location A')
+
+  // Dynamic namespace hooks (shared data)
+  const [isLoadingTypes, serviceTypes, setServiceTypes] = useServiceTypesStoreState(ns, 0)
+  const [isLoadingCounters, counters] = useCountersStoreState(ns, 0)
+  const [isLoadingHistory, calledHistory, setCalledHistory] = useCalledHistoryStoreState(ns, 0)
+
+  useUiScaleToSetRem(uiScale ?? 1)
+
+  // Aggregate loading state
+  const isLoading = isLoadingScale || isLoadingMode || isLoadingLocation ||
+    isLoadingTypes || isLoadingCounters || isLoadingHistory
+
+  if (isLoading) {
+    return <div className="render render--loading">Loading...</div>
+  }
+
+  // Branch on mode AFTER loading completes
+  if (mode === 'kiosk') {
+    return (
+      <TicketKiosk
+        serviceTypes={serviceTypes}
+        setServiceTypes={setServiceTypes}
+        calledHistory={calledHistory}
+        setCalledHistory={setCalledHistory}
+      />
+    )
+  }
+
+  return (
+    <NowServingDisplay
+      serviceTypes={serviceTypes}
+      counters={counters}
+      calledHistory={calledHistory}
+    />
+  )
+}
+```
+
+### Important patterns
+
+- **All hooks load before branching** — both modes may need the same shared data
+- **Namespace is derived from validated entity** — not directly from the raw store value
+- **Mode components receive data as props** — they don't call store hooks themselves
+- **setters are passed only to modes that write** — display mode typically only reads
+
+---
+
+## Settings Organization
+
+Order Settings sections intentionally:
+
+### 1. Mode selector (top — always visible)
+
+```typescript
+<SettingsHeading>Display Mode</SettingsHeading>
+<SettingsField>
+  <SettingsLabel>Mode</SettingsLabel>
+  <SettingsSelectFrame>
+    <select value={mode} onChange={(e) => setMode(e.target.value as AppMode)}>
+      <option value="kiosk">Ticket Kiosk</option>
+      <option value="display">Now Serving Display</option>
+    </select>
+  </SettingsSelectFrame>
+  <SettingsHint>
+    {mode === 'kiosk'
+      ? 'Customer-facing ticket dispenser'
+      : 'Announcement board showing current numbers'}
+  </SettingsHint>
+</SettingsField>
+```
+
+### 2. Entity selector (which entity this device belongs to)
+
+```typescript
+<SettingsField>
+  <SettingsLabel>Location</SettingsLabel>
+  <SettingsSelectFrame>
+    <select value={effectiveLocation} onChange={(e) => setSelectedLocation(e.target.value)}>
+      {safeLocations.map(loc => (
+        <option key={loc} value={loc}>{loc}</option>
+      ))}
+    </select>
+  </SettingsSelectFrame>
+  <SettingsHint>Data is managed separately per location</SettingsHint>
+</SettingsField>
+```
+
+### 3. Mode-specific and entity-scoped settings (middle)
+
+The bulk of the settings — queue management, display options, etc. All scoped to the selected entity via the derived namespace.
+
+### 4. Entity management (bottom)
+
+Add/rename/remove entities. Always at the bottom because it's infrequent admin work.
+
+---
+
+## Entity Management Pattern
+
+```typescript
+// Add
+const addLocation = () => {
+  const newName = `Location ${String.fromCharCode(65 + safeLocations.length)}`
+  setLocations([...safeLocations, newName])
+}
+
+// Rename (update selection if the renamed entity was selected)
+const renameLocation = (index: number, newName: string) => {
+  const oldName = safeLocations[index]
+  const updated = [...safeLocations]
+  updated[index] = newName
+  setLocations(updated)
+  if (effectiveLocation === oldName) {
+    setSelectedLocation(newName)
+  }
+}
+
+// Remove (fall back to first if the removed entity was selected)
+const removeLocation = (index: number) => {
+  if (safeLocations.length <= 1) return  // Always keep at least one
+  const removedName = safeLocations[index]
+  const updated = safeLocations.filter((_, i) => i !== index)
+  setLocations(updated)
+  if (effectiveLocation === removedName) {
+    setSelectedLocation(updated[0])
+  }
+}
+```
+
+### Rules
+
+- **Always keep at least 1 entity** — disable remove when only 1 remains
+- **Update selection on rename** — if the selected entity was renamed, update the selection to match
+- **Fall back on remove** — if the selected entity was removed, select the first remaining
+- **New entity naming** — use a sensible default like "Location A", "Location B", etc.
+
+---
+
+## Mode Type Definition
+
+Define modes as a union type in your types file:
+
+```typescript
+// types/queue.ts (or types/app.ts)
+export type AppMode = 'kiosk' | 'display'
+```
+
+Use this type for the store hook and any mode-dependent logic. Add new modes to the union as needed — the pattern scales to 3+ modes.
+
+---
+
+## Checklist
+
+Before implementing a multi-mode app, confirm:
+
+- [ ] Modes identified (what Render views exist)
+- [ ] Top-level entity chosen (what scopes the shared data)
+- [ ] Mode type defined as union type
+- [ ] Store hooks organized in 3 tiers (instance / application / dynamic namespace)
+- [ ] Namespace helper function created
+- [ ] Entity selection validation with safe fallback
+- [ ] Render view loads all hooks before branching on mode
+- [ ] Settings ordered: mode → entity selector → config → entity management
+- [ ] Entity management has add/rename/remove with at-least-one validation