@telemetryos/cli 1.10.0 → 1.12.0

package/templates/vite-react-typescript/_claude/skills/tos-render-ui-design/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: tos-render-ui-design
+description: Foundation for TelemetryOS Render views. MUST use FIRST before tos-render-signage-design or tos-render-kiosk-design. Covers UI scaling, rem usage, responsive layouts, and best practices for all display types.
+---
+
+# Render View UI Design (Foundation)
+
+This skill covers the foundational UI design patterns for ALL TelemetryOS Render views, whether building digital signage (display-only) or interactive kiosks (touch-enabled).
+
+> **Note:** Always read this skill FIRST, then read either `tos-render-signage-design` (display-only) or `tos-render-kiosk-design` (interactive) depending on your use case.
+
+> **Base styles:** The init project already provides base infrastructural styles in `index.css` (viewport scaling, box-sizing) and `Render.css` (`.render` class with padding, overflow, flexbox). Build on these—don't override them. But feel free to build a new visual theme.
+
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+---
+
+## Quick Reference
+
+| Concept | Key Points | Where Used |
+|---------|-----------|------------|
+| UI Scaling | Call `useUiScaleToSetRem(uiScale)` once in Render | All render views |
+| rem Units | All sizing in rem (not px) | All styles |
+| Title Safe Zone | Keep ~3rem padding from edges | All layouts |
+| Text Size | Minimum 2rem for body, 4rem for headlines | All text |
+| Flex Layouts | Use `min-height: 0` on flex children | All containers |
+| Text Overflow | Truncate with ellipsis or line-clamp | All text that might overflow |
+| Responsive | Use `useUiAspectRatio()` for portrait/landscape | Adaptive layouts |
+| Outside-In Layout | Divide viewport space first, components fill allocations (see signage skill) | Signage layouts |
+
+**Next steps after reading:**
+- Display-only content? → Read `tos-render-signage-design`
+- Interactive kiosk? → Read `tos-render-kiosk-design`
+
+---
+
+## UI Scale System
+
+Displays range from tablets to 8K video walls. Standard CSS pixels create inconsistent sizing. The SDK provides hooks that redefine `rem` as viewport-relative:
+
+### useUiScaleToSetRem(uiScale)
+
+Sets the document's root font-size based on viewport. **Call once in your Render view:**
+
+```typescript
+import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+
+export function Render() {
+  const [_isLoading, uiScale] = useUiScaleStoreState()
+  useUiScaleToSetRem(uiScale)
+
+  return <div className="content">...</div>
+}
+```
+
+**How it works:**
+- At scale 1: `1rem` = 1% of viewport's longest dimension
+- At scale 2: `1rem` = 2% of viewport's longest dimension
+- A 2rem font occupies identical screen percentage on Full HD and 4K
+
+### useUiAspectRatio()
+
+Returns current aspect ratio, updating on resize:
+
+```typescript
+import { useUiAspectRatio } from '@telemetryos/sdk/react'
+
+export function Render() {
+  const aspectRatio = useUiAspectRatio()
+
+  // > 1 = landscape, < 1 = portrait, = 1 = square
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className={isPortrait ? 'portrait-layout' : 'landscape-layout'}>
+      ...
+    </div>
+  )
+}
+```
+
+---
+
+## Layout Fundamentals
+
+### Use rem for Everything
+
+All sizing should use `rem` to scale with the UI scale setting:
+
+```css
+/* CORRECT - Scales with viewport */
+.title {
+  font-size: 4rem;
+  margin-bottom: 1rem;
+}
+
+.card {
+  padding: 2rem;
+  border-radius: 0.5rem;
+}
+```
+
+```css
+/* WRONG - Fixed pixels don't scale */
+.title {
+  font-size: 48px;
+  margin-bottom: 12px;
+}
+```
+
+### Title Safe Zone
+
+The init project's `.render` class already applies ~3rem padding from screen edges (SMPTE ST 2046-1 standard for avoiding bezel cutoff). Keep this padding when building your layout.
+
+### Constrain Layouts
+
+The init project's `index.css` and `.render` class already set up the base layout with `overflow: hidden` and flexbox. When adding child elements, use `min-height: 0` or `min-width: 0` on flex children to allow them to shrink:
+
+```css
+.my-content {
+  flex: 1;
+  min-height: 0; /* Allows flex children to shrink below content size */
+}
+```
+
+### Text Truncation
+
+When text might overflow, truncate gracefully:
+
+```css
+/* Single line truncation */
+.title {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Multi-line truncation */
+.description {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+---
+
+## Typography
+
+### Minimum Text Size
+
+Text should be no smaller than ~2rem for comfortable viewing at typical distances (approximately 4% of screen height):
+
+```css
+.body-text {
+  font-size: 2rem; /* Minimum readable size */
+}
+
+.headline {
+  font-size: 4rem;
+}
+
+.small-label {
+  font-size: 1.5rem; /* Use sparingly */
+}
+```
+
+**Why 2rem minimum?**
+- Content is viewed from a distance (not handheld)
+- Smaller text becomes unreadable
+- 2rem ≈ 4% of screen height at scale 1
+
+---
+
+## Responsive Design
+
+### Adaptive Content for Orientation
+
+Use `useUiAspectRatio()` to adapt layouts for portrait vs landscape:
+
+```typescript
+function Dashboard() {
+  const aspectRatio = useUiAspectRatio()
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className={`dashboard ${isPortrait ? 'dashboard--portrait' : ''}`}>
+      <PrimaryContent />
+      {/* Hide sidebar in portrait mode */}
+      {!isPortrait && <Sidebar />}
+    </div>
+  )
+}
+```
+
+```css
+.dashboard {
+  display: flex;
+  gap: 2rem;
+}
+
+.dashboard--portrait {
+  flex-direction: column;
+}
+```
+
+---
+
+## Store Hook for UI Scale
+
+Create a store hook to let admins adjust the UI scale in Settings:
+
+```typescript
+// hooks/store.ts
+import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
+
+export const useUiScaleStoreState = createUseInstanceStoreState<number>('ui-scale', 1)
+```
+
+```typescript
+// Settings.tsx - Add slider control
+import { SettingsSliderFrame, SettingsField, SettingsLabel } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+
+export function Settings() {
+  // Pass 0 debounce for instant slider updates
+  const [isLoading, uiScale, setUiScale] = useUiScaleStoreState(0)
+
+  return (
+    <SettingsField>
+      <SettingsLabel>UI Scale</SettingsLabel>
+      <SettingsSliderFrame>
+        <input
+          type="range"
+          min={1}
+          max={3}
+          step={0.01}
+          disabled={isLoading}
+          value={uiScale}
+          onChange={(e) => setUiScale(parseFloat(e.target.value))}
+        />
+        <span>{uiScale}x</span>
+      </SettingsSliderFrame>
+    </SettingsField>
+  )
+}
+```
+
+---
+
+## Best Practices Summary
+
+✅ **Use rem everywhere** - All sizing should use rem units, not px
+✅ **Call useUiScaleToSetRem() once** - In Render view with uiScale from store
+✅ **Respect title safe zone** - Keep the ~3rem padding from init project
+✅ **Keep text readable** - Minimum 2rem for body, 4rem for headlines
+✅ **Constrain flex layouts** - Use `min-height: 0` on flex children
+✅ **Truncate overflow** - Use ellipsis or line-clamp for text that might overflow
+✅ **Adapt to orientation** - Use `useUiAspectRatio()` for portrait/landscape layouts
+✅ **Don't override base styles** - Build on index.css, don't replace it
+
+---
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using `px` units | Won't scale across resolutions | Use `rem` everywhere |
+| Fixed heights in `px` | Breaks on different aspect ratios | Use `vh`, `%`, or flex |
+| Forgetting `useUiScaleToSetRem()` | `rem` units won't scale properly | Call it once in Render view with uiScale |
+| Text below 2rem | Unreadable from viewing distance | Minimum 2rem for body text |
+| Removing `.render` padding | Content cut off by bezels | Keep the ~3rem padding from init project |
+| Overriding `index.css` base styles | Breaks viewport scaling | Add new styles, don't modify base setup |
+
+---
+
+## Next Steps
+
+After mastering these foundational concepts, read the appropriate specialized skill:
+
+### Building Display-Only Content (Digital Signage)?
+→ Read `tos-render-signage-design`
+- No user interaction patterns
+- No scrolling constraints
+- Auto-rotation considerations
+
+### Building Interactive Content (Kiosk)?
+→ Read `tos-render-kiosk-design`
+- Touch interaction patterns
+- Idle timeout behavior
+- Navigation state management

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

@@ -45,10 +45,11 @@ Wait for their answer. Their response will tell you:
 - ANY mention of user input/interaction
 - **Implementation:** Render view WITH onClick handlers
 
-**Multi-App Indicators**:
-- "one app shows X and another shows Y"
-- "main display and control panel"
-- "shared information between apps"
+**Multi-Mode Indicators** (same app, different views per device):
+- "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 organized by location, department, topic, or similar grouping
 
 ### Confirm Interaction Model
 
@@ -60,8 +61,8 @@ Before proceeding to Phase 2, explicitly state your understanding:
 **For Interactive Kiosk:**
 > "Got it - we're building an interactive kiosk. Users will be able to touch/click elements on the screen. We'll use @telemetryos/sdk with onClick handlers in the render view. Does that match what you have in mind?"
 
-**For Multi-App System:**
-> "Got it - you're describing TWO separate apps: [App A description] and [App B description]. They'll communicate via shared store namespaces. We'll need to gather requirements for each app. Does that match what you have in mind?"
+**For Multi-Mode App:**
+> "Got it — this is a multi-mode app. Different devices will show different views: [Mode A description] and [Mode B description]. They'll share data scoped to a [entity]. Let me gather requirements for each mode."
 
 Wait for confirmation before proceeding.
 
@@ -304,35 +305,64 @@ For each setting identified, record:
 
 ---
 
-## Phase 5: Multi-App Communication (If Applicable)
+## Phase 5: Multi-Mode Design (If Applicable)
 
-**Only if Phase 1 identified multiple apps.**
+**Only if Phase 1 identified a multi-mode app.**
 
-### Communication Pattern Questions
+### Step 1: Identify the Modes
 
-**Data Sharing:**
-- "How should [App A] and [App B] share data?"
-- Suggest: "Typically, apps share data via store namespaces. App A writes to a shared namespace, App B reads from it."
+Confirm the distinct Render views:
 
-**Namespace Design:**
-- "What data needs to be shared?"
-- Design namespace structure: `store().shared('namespace-name')`
+- "Let's name the modes. You mentioned [X] and [Y] — should we call them '[mode-a]' and '[mode-b]'?"
+- Each mode becomes a value in the mode union type (e.g., `'kiosk' | 'display'`)
+- Ask what each mode shows and whether it reads or writes shared data
 
-**Update Pattern:**
-- "When should App B see updates from App A - immediately (subscribe) or on-demand?"
+### Step 2: Discover the Top-Level Entity
 
-### Shared Store Pattern
+**The developer will almost never volunteer this on their own.** You MUST actively discover or propose the organizing entity that scopes all shared data.
+
+Ask: "What organizes the data these modes share? For example, is this per-location, per-department, per-topic, per-event?"
+
+If the developer doesn't have a clear answer, **propose one** based on the app domain:
+
+| App Domain | Likely Entity |
+|------------|---------------|
+| Queue / service | location, branch |
+| Content / editorial | topic, channel |
+| Event / scheduling | event, venue |
+| Organizational | department, team |
+| Retail / menu | store, menu |
+
+Explain WHY: "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."
+
+Confirm the entity name before proceeding.
+
+### Step 3: Map Shared Data
+
+For each content element from Phase 2, determine if it's:
+- **Per-device** (instance scope) — mode selection, entity selection, UI scale
+- **Account-wide** (application scope) — entity list, API keys
+- **Per-entity** (dynamic namespace scope) — the actual shared data between modes
+
+### Step 4: Mode-Specific Settings
+
+Ask: "Are there any settings that only apply to one mode? For example, audio chime only on the display, or touch feedback only on the kiosk?"
+
+### Reference: Multi-Mode Store Pattern
 
-**Pattern: Shared Store Namespace**
 ```typescript
-// App A writes:
-await store().shared('weather-data').set('current', data)
+// Instance scope — per device
+const useModeStoreState = createUseInstanceStoreState<'kiosk' | 'display'>('mode', 'kiosk')
+const useSelectedLocationStoreState = createUseInstanceStoreState<string>('selected-location', 'Location A')
 
-// App B subscribes:
-store().shared('weather-data').subscribe('current', callback)
+// Application scope — entity management
+const useLocationsStoreState = createUseApplicationStoreState<string[]>('locations', ['Location A'])
+
+// Dynamic namespace scope — shared between modes, scoped to entity
+const useQueuesStoreState = createUseDynamicNamespaceStoreState<Queue[]>('queues', [])
 ```
 
-Best for: Simple data sharing, pub/sub patterns between apps
+See `tos-multi-mode` skill for the complete implementation pattern.
 
 ---
 
@@ -344,10 +374,10 @@ After gathering all requirements, provide a structured summary:
 # [App Name] Requirements
 
 ## Interaction Model
-**[Display-Only | Interactive | Multi-App System]**
+**[Display-Only | Interactive | Multi-Mode]**
 - SDK: `@telemetryos/sdk`
 - Mount Points: `render` (display), `settings` (config UI)
-- Interaction: [Display-only with subscriptions | Interactive with onClick handlers]
+- Interaction: [Display-only with subscriptions | Interactive with onClick handlers | Multi-mode with entity-scoped data]
 
 ## Vision
 [One sentence description]
@@ -381,6 +411,13 @@ After gathering all requirements, provide a structured summary:
 | Company logo | Media Library | media().getById() | Static |
 | Stock prices | External API | proxy().fetch('...') | 30s |
 
+## Multi-Mode Design (if applicable)
+
+**Modes:** [mode-a] (description), [mode-b] (description)
+**Top-Level Entity:** [entity name] (e.g., location, topic)
+**Entity-Scoped Data:** [list shared data keys that use dynamic namespace]
+**Mode-Specific Settings:** [list any settings that only apply to one mode]
+
 ## Store Keys (Settings Configuration)
 
 | Key | Category | Scope | Type | Default | UI Component | Required? |
@@ -398,7 +435,8 @@ After gathering all requirements, provide a structured summary:
 1. **Store Hooks** (hooks/store.ts)
    - Create instance-scoped hooks for [list keys]
    - Create application-scoped hooks for [list keys]
-   - [If multi-app] Create shared namespace hooks
+   - [If multi-mode] Create dynamic namespace hooks for entity-scoped data
+   - [If multi-mode] Create namespace helper function
 
 2. **Settings UI** (views/Settings.tsx)
    - [For Digital Signage] UI Scale slider (instance scope, 1-3 range, 0.01 step)
@@ -452,7 +490,8 @@ If you need to clarify layout:
 3. **Validate assumptions** - Confirm important decisions before moving on
 4. **Be conversational** - This is a dialogue, not a form to fill out
 5. **Skip irrelevant questions** - If they already told you something, don't ask again
-6. **Recognize multi-app patterns** - Watch for indicators of multiple communicating apps
+6. **Recognize multi-mode patterns** — Watch for indicators of different views per device
+7. **Discover the top-level entity** — For multi-mode apps, the developer won't volunteer this. You must ask or propose one
 
 ### Common Patterns to Recognize
 
@@ -460,6 +499,7 @@ If you need to clarify layout:
 - **Menu Board** → Display-only, media library, scheduled updates
 - **Wayfinding Kiosk** → Interactive, touch navigation, search functionality
 - **Data Dashboard** → Display-only, external API, refresh interval
+- **Queue Manager** → Multi-mode (kiosk + display), entity: location, shared queue data
 
 ### What to Infer vs What to Ask
 
@@ -481,9 +521,12 @@ If you need to clarify layout:
 
 After gathering requirements, use these skills to implement:
 
+- **`tos-multi-mode`** - Multi-mode architecture patterns (if building multi-mode app — read first)
 - **`tos-store-sync`** - Create store hooks from the Store Keys table
 - **`tos-settings-ui`** - Build the Settings UI components
-- **`tos-render-design`** - Design the Render view layout
+- **`tos-render-ui-design`** - Design the Render view layout (foundation - always read first)
+- **`tos-render-signage-design`** - Display-only render patterns (if building digital signage)
+- **`tos-render-kiosk-design`** - Interactive render patterns (if building kiosk)
 - **`tos-proxy-fetch`** - Implement external API calls (if needed)
 - **`tos-weather-api`** - Integrate weather data (if needed)
 - **`tos-media-api`** - Access media library (if needed)

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

package/templates/vite-react-typescript/index.html

@@ -7,7 +7,7 @@
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Exo:ital,wght@0,100..900;1,100..900&family=Rubik:ital,wght@0,300..900;1,300..900&display=swap" rel="stylesheet">
-  <script type="module" src="src/index.tsx"></script>
+  <script type="module" src="/src/index.tsx"></script>
 </head>
 <body>
   <div id="app"></div>