@telemetryos/cli 1.9.0 → 1.11.0

package/templates/vite-react-typescript/_claude/skills/tos-store-sync/SKILL.md

@@ -26,6 +26,7 @@ import {
   createUseInstanceStoreState,
   createUseApplicationStoreState,
   createUseDeviceStoreState,
+  createUseDynamicNamespaceStoreState,
 } from '@telemetryos/sdk/react'
 
 // Localization (instance scope)
@@ -39,16 +40,33 @@ export const useApiKeyStoreState = createUseApplicationStoreState<string>('apiKe
 export const useBrightnessStoreState = createUseDeviceStoreState<number>('brightness', 100)
 ```
 
-**Usage:**
+**Usage (Always Handle isLoading):**
+
+⚠️ **Important:** The `isLoading` boolean is `true` until the store returns the first value. During this time, the `value` is either the `initialValue` or potentially `undefined`. Always check `isLoading` before relying on the value.
+
 ```typescript
 // Instance-scoped (Settings + Render) - 250ms debounce for text input
-const [, city, setCity] = useCityStoreState(250)
+const [isLoading, city, setCity] = useCityStoreState(250)
 
-// Application-scoped (shared across all instances) - 250ms debounce for text input
-const [, apiKey, setApiKey] = useApiKeyStoreState(250)
+// ❌ BAD: Ignoring isLoading can cause bugs - value may not be from store yet!
+// const [, city, setCity] = useCityStoreState(250)
+// return <div>{city}</div>  // May show default value instead of real data
+
+// ✅ GOOD Pattern 1: Check isLoading before rendering
+if (isLoading) return <Spinner />
+return <div>Weather for {city}</div>
+
+// ✅ GOOD Pattern 2: Use fallback value with nullish coalescing
+return <div>Weather for {city ?? "Unknown City"}</div>
+
+// Application-scoped (shared across all instances) - 250ms debounce
+const [isLoading, apiKey, setApiKey] = useApiKeyStoreState(250)
+if (isLoading) return <LoadingState />
+return <APIClient apiKey={apiKey} />
 
 // Device-scoped (Render only - NOT available in Settings) - 5ms for slider
-const [, brightness, setBrightness] = useBrightnessStoreState(5)
+const [isLoading, brightness, setBrightness] = useBrightnessStoreState(5)
+const safeValue = brightness ?? 100  // Fallback to default if still loading
 ```
 
 ## Quick Pattern
@@ -179,6 +197,73 @@ const [isLoading, temp] = useTempStoreState()
 - Event broadcasting
 - Coordinated updates
 
+### createUseDynamicNamespaceStoreState
+
+Like shared store, but the namespace is passed at **call time** instead of definition time. Use when the namespace is dynamic — derived from other data at runtime (e.g., a user-selected location, a route parameter, or any runtime key).
+
+> **Building a multi-mode app?** For the complete architecture pattern using dynamic namespaces with mode switching and entity management, see the `tos-multi-mode` skill.
+
+```typescript
+import { createUseDynamicNamespaceStoreState } from '@telemetryos/sdk/react'
+
+// Define with key + default only (no namespace yet)
+export const useItemsStoreState = createUseDynamicNamespaceStoreState<Item[]>('items', [])
+
+// Usage - pass namespace AND debounceDelay at call time
+const [isLoading, items, setItems] = useItemsStoreState(namespace, 250)
+```
+
+**Key difference from `createUseSharedStoreState`:**
+
+| | `createUseSharedStoreState` | `createUseDynamicNamespaceStoreState` |
+|---|---|---|
+| **Namespace** | Fixed at hook definition | Passed at call time |
+| **Definition** | `(key, default, namespace)` | `(key, default)` |
+| **Call signature** | `(debounceDelay?)` | `(namespace, debounceDelay)` |
+| **Use when** | Namespace is always the same | Namespace depends on runtime data |
+
+**Use cases:**
+- Multi-location apps (same data structure per location)
+- User-selected scopes or categories
+- Data partitioned by a runtime key (route param, selected item, etc.)
+
+**Pattern: Namespace helper + instance-scoped selector**
+
+A common pattern is combining an instance-scoped hook (to select which namespace) with dynamic namespace hooks (to access that namespace's data):
+
+```typescript
+// hooks/store.ts
+import {
+  createUseInstanceStoreState,
+  createUseDynamicNamespaceStoreState,
+} from '@telemetryos/sdk/react'
+
+// Instance-scoped: which location this device is assigned to
+export const useSelectedLocationStoreState = createUseInstanceStoreState<string>('selected-location', 'Location A')
+
+// Dynamic namespace: per-location data
+export const useQueuesStoreState = createUseDynamicNamespaceStoreState<Queue[]>('queues', [])
+export const useCountersStoreState = createUseDynamicNamespaceStoreState<Counter[]>('counters', [])
+
+// Helper to build namespace from location
+export function locationNamespace(location: string): string {
+  return `my-app-${location}`
+}
+```
+
+```typescript
+// In a component
+const [isLoadingLocation, selectedLocation] = useSelectedLocationStoreState()
+const ns = locationNamespace(selectedLocation)
+
+const [isLoadingQueues, queues, setQueues] = useQueuesStoreState(ns, 250)
+const [isLoadingCounters, counters, setCounters] = useCountersStoreState(ns, 250)
+
+if (isLoadingLocation || isLoadingQueues || isLoadingCounters) return <Spinner />
+```
+
+When `selectedLocation` changes, the namespace changes, and the hooks automatically re-subscribe to the new namespace's data.
+
 ## Return Value
 
 All hooks return a tuple:
@@ -199,6 +284,12 @@ The default debounce delay is 0ms (immediate updates). Pass a value for debounce
 const [isLoading, city, setCity] = useCityStoreState(250) // 250ms debounce for text inputs
 ```
 
+**Note:** `createUseDynamicNamespaceStoreState` hooks take `(namespace, debounceDelay)` — namespace is required at call time:
+
+```typescript
+const [isLoading, items, setItems] = useItemsStoreState(namespace, 250)
+```
+
 ## TypeScript Types
 
 ### Primitive Types