@telemetryos/cli 1.11.0 → 1.13.0

package/templates/{vite-react-typescript → claude-code}/_claude/skills/tos-architecture/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: tos-architecture
-description: Understand TelemetryOS two-mount-point architecture (Render vs Settings). Use when debugging mount-point issues or understanding how Settings and Render communicate.
+description: Understand TelemetryOS mount point architecture (Render, Settings, and optional Web). Use when debugging mount-point issues or understanding how mount points communicate through the store.
 ---
 
 # TelemetryOS Architecture
 
 TelemetryOS applications run on digital signage devices (TVs, kiosks, displays). Understanding the architecture is key to building effective apps.
 
-## Two Mount Points
+## Mount Points
 
-Every standard TOS app has two entry points:
+Every TOS app has at least two entry points (Render and Settings). Apps that need a browser-accessible interface add a third: the Web mount point.
 
 ### /render - Device Display
 
@@ -19,7 +19,7 @@ Every standard TOS app has two entry points:
 │   (TV, Kiosk, Digital Sign)     │
 │                                 │
 │  ┌───────────────────────────┐  │
-│  │     Chrome Browser        │  │
+│  │  TelemetryOS Electron App  │  │
 │  │  ┌─────────────────────┐  │  │
 │  │  │    Your App         │  │  │
 │  │  │   /render route     │  │  │
@@ -33,7 +33,7 @@ Every standard TOS app has two entry points:
 
 **Characteristics:**
 - Runs on physical device (TelemetryOS player)
-- Chrome browser in iframe sandbox
+- Iframe sandbox in Electron app
 - Has access to `store().device` (device-local storage)
 - Displays content to viewers/customers
 - Full screen, optimized for viewing from distance
@@ -66,6 +66,38 @@ Every standard TOS app has two entry points:
 - Side panel in Studio editor
 - Form-based controls for settings
 
+### /web - Browser-Accessible Interface (Optional)
+
+```
+┌─────────────────────────────────┐
+│   Any Browser (Phone/Tablet/    │
+│   Desktop — Staff or Public)    │
+│                                 │
+│  ┌───────────────────────────┐  │
+│  │   TelemetryOS Web Host    │  │
+│  │  ┌─────────────────────┐  │  │
+│  │  │    Your App         │  │  │
+│  │  │   /app-name route   │  │  │
+│  │  │                     │  │  │
+│  │  │  Operator desk,     │  │  │
+│  │  │  public form, staff │  │  │
+│  │  │  dashboard          │  │  │
+│  │  └─────────────────────┘  │  │
+│  └───────────────────────────┘  │
+└─────────────────────────────────┘
+```
+
+**Characteristics:**
+- Runs in any browser, accessible via URL
+- Can be staff-facing (private) or public-facing
+- Application and dynamic namespace store scopes only
+- **NO access to `store().instance` or `store().device`**
+- Multi-level navigation with React Router
+- Standard HTML/CSS (no SDK settings components, no UI scaling)
+- Always pairs with multi-mode architecture and entity-driven routing
+
+See `tos-web-ui-design` for full design patterns.
+
 ## Communication Flow
 
 ```
@@ -78,10 +110,31 @@ Every standard TOS app has two entry points:
 └─────────────┘         └─────────────────┘         └─────────────┘
 ```
 
-1. **Settings writes** to instance store via hooks
-2. **Render subscribes** to instance store via same hooks
-3. Changes sync automatically (real-time)
-4. Same hooks work in both mount points
+With a Web mount point, communication extends through shared namespaces:
+
+```
+┌─────────────┐         ┌─────────────────┐         ┌─────────────┐
+│  Settings   │  ───▶   │  store().       │  ◀───   │    Web      │
+│  /settings  │  WRITE  │  shared()       │  READ   │  /app-name  │
+│             │         │  namespace      │  +WRITE │             │
+│  Admin      │         │                 │         │  Operator   │
+│  configures │         │  { queues,      │         │  manages    │
+│  entities   │         │    counters }   │         │  live data  │
+└─────────────┘         └─────────────────┘         └─────────────┘
+                                │
+                                ▼  READ + SUB
+                        ┌─────────────┐
+                        │   Render    │
+                        │   /render   │
+                        │  Displays   │
+                        │  live data  │
+                        └─────────────┘
+```
+
+1. **Settings writes** configuration to instance and application store
+2. **Web reads and writes** entity-scoped data via dynamic namespace store
+3. **Render subscribes** and displays changes in real-time
+4. Same store hooks work across all mount points (scoped by what each can access)
 
 ## Project Structure
 
@@ -91,9 +144,12 @@ src/
 ├── App.tsx             # Router - directs to correct view
 ├── views/
 │   ├── Settings.tsx    # /settings mount point
-│   └── Render.tsx      # /render mount point
+│   ├── Render.tsx      # /render mount point
+│   ├── Render.css      # /render styles
+│   ├── Web.tsx         # /app-name mount point (if using web)
+│   └── Web.css         # Web view styles (if using web)
 ├── hooks/
-│   └── store.ts        # Shared store hooks (used in both views)
+│   └── store.ts        # Shared store hooks (used across all mount points)
 ├── components/         # Reusable UI components
 ├── types/              # TypeScript interfaces
 └── utils/              # Helper functions
@@ -103,29 +159,34 @@ src/
 
 ```typescript
 // App.tsx
+import { createBrowserRouter, RouterProvider } from 'react-router'
 import Settings from './views/Settings'
 import Render from './views/Render'
 
-export function App() {
-  const path = window.location.pathname
-
-  if (path === '/settings') return <Settings />
-  if (path === '/render') return <Render />
+const router = createBrowserRouter([
+  { path: '/render', element: <Render /> },
+  { path: '/settings', element: <Settings /> },
+])
 
-  return <div>Invalid mount point: {path}</div>
+export function App() {
+  return <RouterProvider router={router} />
 }
 ```
 
-Or with React Router:
+With a web mount point, add routes under the app name:
 
 ```typescript
 import { createBrowserRouter, RouterProvider } from 'react-router'
-import Settings from './views/Settings'
-import Render from './views/Render'
+import { Render } from './views/Render'
+import { Settings } from './views/Settings'
+import { WebEntities, WebDetail, WebOperator } from './views/Web'
 
 const router = createBrowserRouter([
-  { path: '/render', element: <Render /> },
-  { path: '/settings', element: <Settings /> },
+  { path: '/render', Component: Render },
+  { path: '/settings', Component: Settings },
+  { path: '/my-app', Component: WebEntities },
+  { path: '/my-app/locations/:locationName', Component: WebDetail },
+  { path: '/my-app/locations/:locationName/counters/:counterId', Component: WebOperator },
 ])
 
 export function App() {
@@ -157,6 +218,15 @@ export function App() {
 - Form-based interaction
 - Preview pane integration
 
+### Web Only
+
+- Standard HTML/CSS (no SDK settings components)
+- Runs in any browser (phone, tablet, desktop)
+- `store().application` and `store().shared(namespace)` only
+- NO access to `store().instance` or `store().device`
+- Multi-level React Router navigation
+- No UI scaling (`useUiScaleToSetRem` not used)
+
 ## telemetry.config.json
 
 ```json
@@ -174,12 +244,32 @@ export function App() {
 }
 ```
 
+With a web mount point:
+
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "useSpaRouting": true,
+  "mountPoints": {
+    "render": "/render",
+    "settings": "/settings",
+    "web": "/my-app"
+  },
+  "devServer": {
+    "runCommand": "vite --port 3000",
+    "url": "http://localhost:3000"
+  }
+}
+```
+
 ### Mount Point Configuration
 
-| Mount Point | Purpose | Route |
-|-------------|---------|-------|
-| render | Device display | /render |
-| settings | Admin config UI | /settings |
+| Mount Point | Purpose | Route | Store Access |
+|-------------|---------|-------|--------------|
+| render | Device display | /render | instance, application, device, shared |
+| settings | Admin config UI | /settings | instance, application, shared |
+| web (optional) | Browser interface | /app-name | application, shared |
 
 ### Optional: Workers
 
@@ -198,34 +288,32 @@ export function App() {
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│                        Account                                  │
+│  Account                                                       │
+│                                                                │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │  store().application                                     │  │
-│  │  Shared across ALL instances of this app                 │  │
-│  │  (API keys, account-wide settings)                       │  │
+│  │  store().shared('namespace')                              │  │
+│  │  Dynamic namespace — scoped by entity                     │  │
+│  │  Accessible from: Settings, Render, Web                   │  │
 │  └──────────────────────────────────────────────────────────┘  │
-│                                                                 │
-│  ┌─────────────────────┐  ┌─────────────────────┐             │
-│  │  App Instance 1     │  │  App Instance 2     │             │
-│  │  instance store     │  │  instance store     │             │
-│  │  (Settings↔Render)  │  │  (Settings↔Render)  │             │
-│  └─────────────────────┘  └─────────────────────┘             │
-└────────────────────────────────────────────────────────────────┘
-
-┌────────────────────────────────────────────────────────────────┐
-│  Physical Device                                               │
+│                                                                │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │  store().device                                          │  │
-│  │  Local to this device only (Render only!)                │  │
-│  │  (Cache, calibration, device-specific data)              │  │
+│  │  Application                                              │  │
+│  │                                                           │  │
+│  │  ┌────────────────────────────────────────────────────┐   │  │
+│  │  │  store().application                               │   │  │
+│  │  │  Shared across ALL instances of this app            │   │  │
+│  │  │  (API keys, account-wide settings)                  │   │  │
+│  │  │  Accessible from: Settings, Render, Web             │   │  │
+│  │  └────────────────────────────────────────────────────┘   │  │
+│  │                                                           │  │
+│  │  ┌──────────────────────┐  ┌──────────────────────┐      │  │
+│  │  │  Device              │  │  Instance             │      │  │
+│  │  │  store().device      │  │  store().instance     │      │  │
+│  │  │  Render only!        │  │  Settings ↔ Render    │      │  │
+│  │  │  (Cache, calibration)│  │  NOT in Web           │      │  │
+│  │  └──────────────────────┘  └──────────────────────┘      │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └────────────────────────────────────────────────────────────────┘
-
-┌────────────────────────────────────────────────────────────────┐
-│  store().shared('namespace')                                   │
-│  Inter-app communication (any app can read/write)              │
-│  (Weather data sharing, event broadcasting)                    │
-└────────────────────────────────────────────────────────────────┘
 ```
 
 ## Development Workflow
@@ -236,6 +324,7 @@ export function App() {
 Both the render and settings mounts points are visible in the development host.
 The Render mount point is presented in a resizable pane.
 The Settings mount point shows in the right sidebar.
+The Web mount point (if configured) appears as a tab in the development host, displayed in the same area as the other mount points.
 
 
 ### Build & Deploy
@@ -243,10 +332,6 @@ The Settings mount point shows in the right sidebar.
 ```bash
 # Build production
 npm run build
-
-# Deploy via Git
-git add . && git commit -m "Update" && git push
-# GitHub integration auto-deploys
 ```
 
 ## Common Patterns
@@ -265,14 +350,6 @@ return <WeatherDisplay city={city} />
 
 ## Debugging
 
-### Check Current Path
-
-```typescript
-console.log('Current path:', window.location.pathname)
-console.log('Is Settings:', window.location.pathname === '/settings')
-console.log('Is Render:', window.location.pathname === '/render')
-```
-
 ### Verify SDK Configuration
 
 ```typescript

package/templates/{vite-react-typescript → claude-code}/_claude/skills/tos-debugging/SKILL.md

@@ -39,10 +39,10 @@ ReactDOM.createRoot(document.getElementById('root')!).render(<App />)
 **Solution:**
 ```typescript
 // WRONG - in Settings.tsx
-const [, value, setValue] = useMyState() // using createUseDeviceStoreState
+const [isLoading, value, setValue] = useMyState() // using createUseDeviceStoreState
 
 // CORRECT - use instance scope
-const [, value, setValue] = useMyState() // using createUseInstanceStoreState
+const [isLoading, value, setValue] = useMyState() // using createUseInstanceStoreState
 ```
 
 **Scope guide:**

package/templates/{vite-react-typescript → claude-code}/_claude/skills/tos-media-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tos-media-api
-description: Access TelemetryOS Media Library for images, videos, and files. Use when building apps that display user-uploaded media content.
+description: Access TelemetryOS Media Library for images, videos, and files. Use when building apps that display or select user-uploaded media content.
 ---
 
 # TelemetryOS Media API
@@ -23,6 +23,10 @@ const tagged = await media().getAllByTag('banner')
 
 // Get single item by ID
 const item = await media().getById('content-id')
+
+// Open media picker (user selects from full-screen dialog)
+const selection = await media().openPicker()
+const imagesOnly = await media().openPicker({ accept: ['image/*'] })
 ```
 
 ## Response Types
@@ -61,6 +65,29 @@ interface MediaContent {
 }
 ```
 
+### MediaSelection
+
+Returned by `openPicker()` and used by `SettingsMediaSelect`.
+
+```typescript
+interface MediaSelection {
+  id: string
+  name: string
+  thumbnailUrl: string  // Thumbnail for preview
+  url: string           // Full content URL
+  contentType: string   // MIME type
+}
+```
+
+### MediaPickerOptions
+
+```typescript
+interface MediaPickerOptions {
+  accept?: string[]            // Content type filters: ['image/*', 'video/*']
+  currentValue?: MediaSelection // Pre-select current value in picker
+}
+```
+
 ## Common Patterns
 
 ### Folder Picker in Settings
@@ -123,6 +150,64 @@ export default function Settings() {
 }
 ```
 
+### Media Picker in Settings (SettingsMediaSelect)
+
+Use the built-in `SettingsMediaSelect` component to let users pick a media item. Opens a full-screen picker dialog in the host window.
+
+```typescript
+// hooks/store.ts
+import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
+import type { MediaSelection } from '@telemetryos/sdk/react'
+
+export const useMediaState = createUseInstanceStoreState<MediaSelection | null>('selectedMedia', null)
+```
+
+```typescript
+// views/Settings.tsx
+import {
+  SettingsContainer,
+  SettingsField,
+  SettingsLabel,
+  SettingsMediaSelect,
+} from '@telemetryos/sdk/react'
+import { useMediaState } from '../hooks/store'
+
+export default function Settings() {
+  const [isLoading, selectedMedia, setSelectedMedia] = useMediaState()
+
+  return (
+    <SettingsContainer>
+      <SettingsField>
+        <SettingsLabel>Background Image</SettingsLabel>
+        <SettingsMediaSelect
+          value={selectedMedia}
+          onChange={setSelectedMedia}
+          accept={['image/*']}
+          disabled={isLoading}
+        />
+      </SettingsField>
+    </SettingsContainer>
+  )
+}
+```
+
+### Using openPicker() Directly
+
+For custom UI, call `media().openPicker()` directly instead of using the component.
+
+```typescript
+import { media } from '@telemetryos/sdk'
+
+const handleSelectMedia = async () => {
+  const selection = await media().openPicker({ accept: ['image/*'] })
+  if (selection) {
+    // selection has: id, name, thumbnailUrl, url, contentType
+    console.log('Selected:', selection.name, selection.url)
+  }
+  // selection is null if user cancelled
+}
+```
+
 ### Image Gallery in Render
 
 ```typescript
@@ -249,15 +334,15 @@ import { media } from '@telemetryos/sdk'
 import { useFolderIdState, useIntervalState } from '../hooks/store'
 
 export default function Render() {
-  const [, folderId] = useFolderIdState()
-  const [, interval] = useIntervalState() // seconds
+  const [isLoadingFolder, folderId] = useFolderIdState()
+  const [isLoadingInterval, interval] = useIntervalState() // seconds
 
   const [images, setImages] = useState<string[]>([])
   const [currentIndex, setCurrentIndex] = useState(0)
 
   // Load images
   useEffect(() => {
-    if (!folderId) return
+    if (isLoadingFolder || !folderId) return
 
     media().getAllByFolderId(folderId).then(content => {
       const urls = content
@@ -327,9 +412,11 @@ const activeContent = content.filter(item => {
 
 ## Tips
 
-1. **Use publicUrls[0]** - First URL is the primary CDN URL
-2. **Use thumbnailUrl for previews** - Smaller, faster loading
-3. **Filter by contentType** - Ensure you're displaying compatible content
-4. **Handle empty folders** - Show appropriate message when no content
-5. **Lazy load images** - Use `loading="lazy"` for galleries
-6. **Respect hidden flag** - Filter out hidden items unless intentional
+1. **Use `SettingsMediaSelect` for settings** - Preferred way to let users pick media in Settings views
+2. **Use `openPicker()` for custom UI** - When you need full control over the selection flow
+3. **Use publicUrls[0]** - First URL is the primary CDN URL
+4. **Use thumbnailUrl for previews** - Smaller, faster loading
+5. **Filter by contentType** - Ensure you're displaying compatible content
+6. **Handle empty folders** - Show appropriate message when no content
+7. **Lazy load images** - Use `loading="lazy"` for galleries
+8. **Respect hidden flag** - Filter out hidden items unless intentional

package/templates/{vite-react-typescript → claude-code}/_claude/skills/tos-multi-mode/SKILL.md

@@ -15,8 +15,10 @@ Listen for these indicators during requirements gathering:
 - "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
+- "Staff need to manage/control from their phone or browser"
+- "Public signup form" or "public status page" for the same data
 
-If ANY of these come up, this is a multi-mode app.
+If ANY of these come up, this is a multi-mode app. If staff or the public need browser access outside the device, it also needs a **web mount point**.
 
 ---
 
@@ -80,12 +82,26 @@ Multi-mode apps use a 3-tier store pattern:
 └─────────────────────────────────────────────────────────────┘
 ```
 
+With a web mount point, add a fourth access path:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Web Mount Point (browser — staff or public)                 │
+│  Entity from URL params, NOT instance store                  │
+│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐  │
+│  │  Reads/writes │ │  Same        │ │  Same namespace     │  │
+│  │  namespace    │ │  store hooks │ │  helper function    │  │
+│  └──────────────┘ └──────────────┘ └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
 **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)
+1. Admin creates entities in Settings (application scope)
+2. Each device selects a mode AND an entity (instance scope)
+3. All devices on the same entity share the same data (dynamic namespace scope)
 4. A kiosk at "Location A" and a display at "Location A" see the same queues
+5. Web views navigate to entities via URL and read/write the same namespace data
 
 ---
 
@@ -240,6 +256,75 @@ export function Render() {
 
 ---
 
+## Web Mount Point Integration
+
+When your multi-mode app needs a browser-accessible interface (operator desk, public form, staff dashboard), add a web mount point. The web view accesses the **same entity-scoped data** as Render, but gets the entity from URL params instead of instance store.
+
+### Entity from URL vs Instance Store
+
+```typescript
+// Render — entity from instance store (admin picks which entity this device shows)
+const [isLoading, selectedLocation] = useSelectedLocationStoreState()
+if (isLoading) return <div>Loading...</div>
+const ns = locationNamespace(selectedLocation || 'Location A')
+
+// Web — entity from URL params (user navigates via links)
+const { locationName } = useParams()
+const ns = locationNamespace(decodeURIComponent(locationName || ''))
+
+// Same namespace → same data → real-time sync
+```
+
+### Web Routing Maps to Entities
+
+Web routes use the app name as base path, with entity-driven sub-routes. Choose path segments that match your domain:
+
+```typescript
+// App.tsx — add web routes alongside render and settings
+const router = createBrowserRouter([
+  { path: '/render', Component: Render },
+  { path: '/settings', Component: Settings },
+  { path: '/my-app', Component: WebEntities },
+  { path: '/my-app/locations/:locationName', Component: WebDetail },
+  { path: '/my-app/locations/:locationName/counters/:counterId', Component: WebOperator },
+])
+```
+
+### Store Access in Web
+
+Web views can only use **application** and **dynamic namespace** store hooks. No instance or device store (there's no device/instance context in the browser):
+
+```typescript
+// ✅ Works in web
+const [isLoading, locations] = useLocationsStoreState()                     // application scope
+const [isLoadingCounters, counters, setCounters] = useCountersStoreState(ns, 250)   // dynamic namespace
+if (isLoading || isLoadingCounters) return <div>Loading...</div>
+
+// ❌ NOT available in web
+const [isLoading, mode] = useModeStoreState()              // instance scope — no context
+const [isLoading, uiScale] = useUiScaleStoreState()        // instance scope — no context
+```
+
+### Config
+
+Add the web mount point to `telemetry.config.json`:
+
+```json
+{
+  "name": "my-app",
+  "useSpaRouting": true,
+  "mountPoints": {
+    "render": "/render",
+    "settings": "/settings",
+    "web": "/my-app"
+  }
+}
+```
+
+See `tos-web-ui-design` for complete web view design patterns.
+
+---
+
 ## Settings Organization
 
 Order Settings sections intentionally:
@@ -357,3 +442,11 @@ Before implementing a multi-mode app, confirm:
 - [ ] 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
+
+If using a web mount point, also confirm:
+
+- [ ] `telemetry.config.json` has `"web": "/app-name"` and `useSpaRouting: true`
+- [ ] Web routes registered in App.tsx under the app name
+- [ ] Web views get entity from URL params (not instance store)
+- [ ] Web views only use application and dynamic namespace store hooks
+- [ ] Entity names are URL-encoded in links and decoded in components