@telemetryos/cli 1.12.0 → 1.13.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @telemetryos/cli
 
+## 1.13.1
+
+### Patch Changes
+
+- - **SDK client refactor:** Removed `applicationName` from the client and `configure()` API (still accepted for backwards compatibility). The SDK now resolves `applicationSpecifier` from URL search params first with subdomain fallback, validates it as a 40-char hex hash, and adds `deviceId` from URL params. Store scoping updated accordingly. Fixed a listener leak when calling `configure()` multiple times.
+  - **Template assets moved to `public/`:** SDK template assets (logo, thumbnail) moved from `assets/` to `public/assets/` so Vite includes them in the build output automatically. Dev server updated to resolve from `public/` first.
+  - **Documentation updates for v1.13.0:** Added docs for web mount point, Navigation API, `tos claude-code` command, `vite-react-typescript-web` template, `playlist.getDuration()`, `SettingsMediaSelect` component, and custom logo support. Fixed scope availability, store scope guidance for web mount points, and various inconsistencies.
+
+- Updated dependencies
+  - @telemetryos/development-application-host-ui@1.13.1
+
+## 1.13.0
+
+### Minor Changes
+
+- ### New Features
+  - **Web mount point support** — Applications can now define a third UI surface (`/web`) alongside Render and Settings, enabling web-portal-style interfaces with full navigation control via a postMessage bridge.
+  - **`playlist.getDuration()`** — New async method returns the playlist-configured page duration in seconds.
+  - **Custom logo support** — Projects can specify a `logoPath` in `telemetry.config.json` for branding in the dev host.
+  - **`tos claude-code` command** — New CLI command to apply or update Claude Code skills and settings in existing projects.
+  - **Web project template** — New `vite-react-typescript-web` template scaffolds a project with all three mount points pre-configured.
+
+  ### Bug Fixes
+  - Fixed SDK client not properly validating bridge message responses.
+  - Fixed canvas not resizing when the sidebar toggles or window resizes after a manual drag-resize.
+  - Fixed `isLoading` usage and `useEffect` dependency arrays in Claude Code skill examples.
+  - Fixed stale active tab when the tabs array changes in the dev host.
+
+  ### Infrastructure
+  - Renamed `generate-application` to `create-project`; extracted shared template utilities.
+  - Added unit tests for Navigation, Currency, and Weather classes.
+
+### Patch Changes
+
+- Updated dependencies
+  - @telemetryos/development-application-host-ui@1.13.0
+
 ## 1.12.0
 
 ### Minor Changes

package/dist/commands/claude-code.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const claudeCodeCommand: Command;

package/dist/commands/claude-code.js

@@ -0,0 +1,29 @@
+import { Command } from 'commander';
+import path from 'path';
+import { loadProjectConfig } from '../services/project-config.js';
+import { copyDir, templatesDir } from '../utils/template.js';
+import { ansi } from '../utils/ansi.js';
+export const claudeCodeCommand = new Command('claude-code')
+    .description('Apply or update Claude Code skills and settings in a project')
+    .argument('[project-path]', 'Path to the telemetryOS project (defaults to current directory)', process.cwd())
+    .action(handleClaudeCodeCommand);
+async function handleClaudeCodeCommand(projectPath) {
+    var _a, _b, _c;
+    const resolvedPath = path.resolve(projectPath);
+    let config;
+    try {
+        config = await loadProjectConfig(resolvedPath);
+    }
+    catch (error) {
+        console.error(`\n${ansi.red}Error:${ansi.reset} ${error instanceof Error ? error.message : error}`);
+        process.exit(1);
+    }
+    const name = (_a = config.name) !== null && _a !== void 0 ? _a : '';
+    const description = (_b = config.description) !== null && _b !== void 0 ? _b : '';
+    const version = (_c = config.version) !== null && _c !== void 0 ? _c : '';
+    console.log(`\nApplying Claude Code skills and settings...\n`);
+    await copyDir(path.join(templatesDir, 'claude-code'), resolvedPath, { name, version, description, author: '' }, (createdFilePath) => {
+        console.log(`.${path.sep}${path.relative(process.cwd(), createdFilePath)}`);
+    });
+    console.log(`\n${ansi.green}Done!${ansi.reset} Claude Code skills and settings have been applied.`);
+}

package/dist/commands/init.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { generateApplication, checkDirectoryConflicts, removeConflictingFiles, } from '../services/generate-application.js';
+import { createProject, checkDirectoryConflicts, removeConflictingFiles, } from '../services/create-project.js';
 import inquirer from 'inquirer';
 import path from 'path';
 import { resolveProjectPathAndName, validateProjectName } from '../utils/path-utils.js';
@@ -26,10 +26,11 @@ export const initCommand = new Command('init')
     .option('-d, --description <string>', 'The description of the application', '')
     .option('-a, --author <string>', 'The author of the application', '')
     .option('-v, --version <string>', 'The version of the application', '0.1.0')
-    .option('-t, --template <string>', 'The template to use (vite-react-typescript)', '')
+    .option('-t, --template <string>', 'The template to use (vite-react-typescript, vite-react-typescript-web)', '')
     .option('-y, --yes', 'Skip all prompts and use defaults', false)
     .action(handleInitCommand);
 async function handleInitCommand(projectPathArg, options) {
+    var _a, _b, _c, _d, _e, _f;
     // Step 1: Resolve path and derive name
     const cwd = process.cwd();
     const inputPath = projectPathArg || '.';
@@ -80,6 +81,7 @@ async function handleInitCommand(projectPathArg, options) {
     let author = options.author;
     let version = options.version;
     let template = options.template;
+    let claudeCode = true;
     // Step 5: Build prompt questions (skipped with --yes)
     if (options.yes) {
         if (!name) {
@@ -138,23 +140,34 @@ async function handleInitCommand(projectPathArg, options) {
                 type: 'list',
                 name: 'template',
                 message: 'Which template would you like to use?',
-                choices: [{ name: 'Vite + React + TypeScript', value: 'vite-react-typescript' }],
+                choices: [
+                    { name: 'Vite + React + TypeScript', value: 'vite-react-typescript' },
+                    { name: 'Vite + React + TypeScript + Web', value: 'vite-react-typescript-web' },
+                ],
             });
+        questions.push({
+            type: 'confirm',
+            name: 'claudeCode',
+            message: 'Include Claude Code skills and settings?',
+            default: true,
+        });
         // Step 6: Prompt user
         const answers = await inquirer.prompt(questions);
-        name = answers.name || name;
-        version = answers.version || version;
-        description = answers.description || description;
-        author = answers.author || author;
-        template = answers.template || template;
+        name = (_a = answers.name) !== null && _a !== void 0 ? _a : name;
+        version = (_b = answers.version) !== null && _b !== void 0 ? _b : version;
+        description = (_c = answers.description) !== null && _c !== void 0 ? _c : description;
+        author = (_d = answers.author) !== null && _d !== void 0 ? _d : author;
+        template = (_e = answers.template) !== null && _e !== void 0 ? _e : template;
+        claudeCode = (_f = answers.claudeCode) !== null && _f !== void 0 ? _f : claudeCode;
     }
     // Step 7: Generate application
-    await generateApplication({
+    await createProject({
         name,
         description,
         author,
         version,
         template,
+        claudeCode,
         projectPath: resolvedPath,
         progressFn: (createdFilePath) => {
             console.log(`.${path.sep}${path.relative(cwd, createdFilePath)}`);

package/dist/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { authCommand } from './commands/auth.js';
+import { claudeCodeCommand } from './commands/claude-code.js';
 import { initCommand } from './commands/init.js';
 import { publishCommand } from './commands/publish.js';
 import { rootCommand } from './commands/root.js';
 import { serveCommand } from './commands/serve.js';
 rootCommand.addCommand(authCommand);
+rootCommand.addCommand(claudeCodeCommand);
 rootCommand.addCommand(serveCommand);
 rootCommand.addCommand(initCommand);
 rootCommand.addCommand(publishCommand);

package/dist/services/create-project.d.ts

@@ -0,0 +1,13 @@
+export type CreateProjectOptions = {
+    name: string;
+    description: string;
+    author: string;
+    version: string;
+    template: string;
+    claudeCode: boolean;
+    projectPath: string;
+    progressFn: (createdFilePath: string) => void;
+};
+export declare function createProject(options: CreateProjectOptions): Promise<void>;
+export declare function checkDirectoryConflicts(projectPath: string): Promise<string[]>;
+export declare function removeConflictingFiles(projectPath: string, conflicts: string[]): Promise<void>;

package/dist/services/create-project.js

@@ -0,0 +1,188 @@
+import { spawn, execSync } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import { ansi } from '../utils/ansi.js';
+import { copyDir, templatesDir } from '../utils/template.js';
+// Files that can exist in a directory without being considered conflicts
+const safeExistingFiles = [
+    '.DS_Store',
+    '.git',
+    '.gitignore',
+    '.gitattributes',
+    '.idea',
+    '.vscode',
+    'Thumbs.db',
+    'LICENSE',
+    'README.md',
+];
+export async function createProject(options) {
+    const { name, description, author, version, template, claudeCode, projectPath, progressFn } = options;
+    await fs.mkdir(projectPath, { recursive: true });
+    // Initialize git repo early (before template dependencies that may have git hooks)
+    const gitInitialized = tryGitInit(projectPath);
+    if (gitInitialized) {
+        console.log('\nInitialized a git repository');
+    }
+    await copyDir(path.join(templatesDir, template), projectPath, {
+        name,
+        version,
+        description,
+        author,
+    }, progressFn);
+    // Optionally apply Claude Code overlay (skills and settings)
+    if (claudeCode) {
+        await copyDir(path.join(templatesDir, 'claude-code'), projectPath, {
+            name,
+            version,
+            description,
+            author,
+        }, progressFn);
+    }
+    // Install latest versions of @telemetryos/sdk and @telemetryos/cli
+    console.log('\nInstalling dependencies...');
+    await installPackages(projectPath);
+    // Create initial commit after all files are in place
+    if (gitInitialized) {
+        await tryGitCommit(projectPath);
+    }
+    printSuccessMessage(name, projectPath);
+}
+async function installPackages(projectPath) {
+    // Install SDK as a regular dependency
+    await new Promise((resolve, reject) => {
+        const sdkInstall = spawn('npm', ['install', '@telemetryos/sdk'], {
+            cwd: projectPath,
+            stdio: 'inherit',
+            shell: true,
+        });
+        sdkInstall.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`npm install @telemetryos/sdk failed with code ${code}`));
+            }
+        });
+        sdkInstall.on('error', (error) => {
+            reject(error);
+        });
+    });
+    // Install CLI as a dev dependency
+    await new Promise((resolve, reject) => {
+        const cliInstall = spawn('npm', ['install', '-D', '@telemetryos/cli'], {
+            cwd: projectPath,
+            stdio: 'inherit',
+            shell: true,
+        });
+        cliInstall.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`npm install -D @telemetryos/cli failed with code ${code}`));
+            }
+        });
+        cliInstall.on('error', (error) => {
+            reject(error);
+        });
+    });
+}
+function isInGitRepository(cwd) {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tryGitInit(projectPath) {
+    try {
+        execSync('git --version', { stdio: 'ignore' });
+        if (isInGitRepository(projectPath)) {
+            return false;
+        }
+        execSync('git init', { cwd: projectPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryGitCommit(projectPath) {
+    try {
+        execSync('git add -A', { cwd: projectPath, stdio: 'ignore' });
+        execSync('git commit -m "Initialize project using TelemetryOS CLI"', {
+            cwd: projectPath,
+            stdio: 'ignore',
+        });
+        console.log('Created initial commit');
+        return true;
+    }
+    catch {
+        // Commit failed (e.g., git user not configured)
+        // Remove .git directory to avoid half-initialized state
+        console.log('Git commit not created');
+        console.log('Removing .git directory...');
+        try {
+            await fs.rm(path.join(projectPath, '.git'), { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        return false;
+    }
+}
+export async function checkDirectoryConflicts(projectPath) {
+    try {
+        const entries = await fs.readdir(projectPath);
+        return entries.filter((file) => !safeExistingFiles.includes(file));
+    }
+    catch (error) {
+        // Directory doesn't exist, no conflicts
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+export async function removeConflictingFiles(projectPath, conflicts) {
+    for (const file of conflicts) {
+        const filePath = path.join(projectPath, file);
+        try {
+            const stat = await fs.stat(filePath);
+            if (stat.isDirectory()) {
+                await fs.rm(filePath, { recursive: true, force: true });
+            }
+            else {
+                await fs.unlink(filePath);
+            }
+        }
+        catch (error) {
+            // Ignore errors for files that may have already been removed
+            console.error(`Warning: Could not remove ${file}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+}
+function printSuccessMessage(name, projectPath) {
+    // Calculate relative path from cwd for cleaner display
+    const relativePath = path.relative(process.cwd(), projectPath);
+    const displayPath = relativePath || '.';
+    console.log(`
+${ansi.green}Success!${ansi.reset} Created ${ansi.bold}${name}${ansi.reset} at ${ansi.cyan}${displayPath}${ansi.reset}
+
+Inside that directory, you can run:
+
+  ${ansi.cyan}npm run dev${ansi.reset}
+    Starts the development server
+
+  ${ansi.cyan}npm run build${ansi.reset}
+    Builds the app for production
+
+You may begin with:
+
+  ${ansi.cyan}cd ${displayPath}${ansi.reset}
+  ${ansi.cyan}npm run dev${ansi.reset}
+
+`);
+}

package/dist/services/project-config.d.ts

@@ -2,6 +2,8 @@ import z from 'zod';
 export declare const projectConfigSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    logoPath: z.ZodOptional<z.ZodString>;
     thumbnailPath: z.ZodOptional<z.ZodString>;
     mountPoints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         path: z.ZodString;
@@ -15,6 +17,7 @@ export declare const projectConfigSchema: z.ZodObject<{
     containers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         image: z.ZodString;
     }, z.z.core.$strip>, z.ZodString]>>>;
+    useSpaRouting: z.ZodOptional<z.ZodBoolean>;
     devServer: z.ZodOptional<z.ZodObject<{
         runCommand: z.ZodOptional<z.ZodString>;
         url: z.ZodString;

package/dist/services/project-config.js

@@ -16,11 +16,14 @@ const containerSchema = z.object({
 export const projectConfigSchema = z.object({
     name: z.string().optional(),
     version: z.string().optional(),
+    description: z.string().optional(),
+    logoPath: z.string().optional(),
     thumbnailPath: z.string().optional(),
     mountPoints: z.record(z.string(), z.union([mountPointSchema, z.string()])).optional(),
     backgroundWorkers: z.record(z.string(), z.union([backgroundWorkerSchema, z.string()])).optional(),
     serverWorkers: z.record(z.string(), z.union([serverWorkerSchema, z.string()])).optional(),
     containers: z.record(z.string(), z.union([containerSchema, z.string()])).optional(),
+    useSpaRouting: z.boolean().optional(),
     devServer: z
         .object({
         runCommand: z.string().optional(),

package/dist/services/run-server.js

@@ -1,5 +1,5 @@
 import { spawn } from 'child_process';
-import { readFile } from 'fs/promises';
+import { access, readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import http from 'http';
 import path from 'path';
@@ -8,6 +8,15 @@ import serveHandler from 'serve-handler';
 import pkg from '../../package.json' with { type: 'json' };
 import { loadProjectConfig } from './project-config.js';
 import { ansi, ansiRegex } from '../utils/ansi.js';
+// import { handlePublishCommand } from '../commands/publish.js'
+const IMAGE_MIME_TYPES = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+};
 export async function runServer(projectPath, flags) {
     printSplashScreen();
     projectPath = path.resolve(process.cwd(), projectPath);
@@ -36,32 +45,12 @@ async function serveDevelopmentApplicationHostUI(projectPath, port, projectConfi
             res.end(JSON.stringify(projectConfig));
             return;
         }
+        if (url.pathname === '/__tos-logo__') {
+            await serveImageFile(res, projectPath, projectConfig.logoPath, 'logo');
+            return;
+        }
         if (url.pathname === '/__tos-thumbnail__') {
-            if (!projectConfig.thumbnailPath) {
-                res.statusCode = 404;
-                res.end('No thumbnail configured');
-                return;
-            }
-            const thumbnailFullPath = path.join(projectPath, projectConfig.thumbnailPath);
-            try {
-                const imageData = await readFile(thumbnailFullPath);
-                const ext = path.extname(projectConfig.thumbnailPath).toLowerCase();
-                const mimeTypes = {
-                    '.jpg': 'image/jpeg',
-                    '.jpeg': 'image/jpeg',
-                    '.png': 'image/png',
-                    '.gif': 'image/gif',
-                    '.svg': 'image/svg+xml',
-                    '.webp': 'image/webp',
-                };
-                const contentType = mimeTypes[ext] || 'application/octet-stream';
-                res.setHeader('Content-Type', contentType);
-                res.end(imageData);
-            }
-            catch {
-                res.statusCode = 404;
-                res.end('Thumbnail file not found');
-            }
+            await serveImageFile(res, projectPath, projectConfig.thumbnailPath, 'thumbnail');
             return;
         }
         if (url.pathname === '/__dev_proxy__' && req.method === 'POST' && res) {
@@ -192,6 +181,54 @@ async function serveDevelopmentApplicationHostUI(projectPath, port, projectConfi
     });
     server.listen(port);
 }
+async function serveImageFile(res, projectPath, filePath, label) {
+    if (!filePath) {
+        res.statusCode = 404;
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.end(`No ${label} configured`);
+        return;
+    }
+    const projectRoot = path.resolve(projectPath);
+    const validatePath = (fullPath) => fullPath.startsWith(projectRoot + path.sep) || fullPath === projectRoot;
+    // Try public/ first (Vite convention), then project root (backward compat)
+    const publicPath = path.resolve(projectPath, 'public', filePath);
+    const rootPath = path.resolve(projectPath, filePath);
+    let resolvedPath;
+    if (validatePath(publicPath)) {
+        try {
+            await access(publicPath);
+            resolvedPath = publicPath;
+        }
+        catch { }
+    }
+    if (!resolvedPath && validatePath(rootPath)) {
+        resolvedPath = rootPath;
+    }
+    if (!resolvedPath) {
+        res.statusCode = 403;
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.end('Forbidden: path escapes project root');
+        return;
+    }
+    try {
+        const imageData = await readFile(resolvedPath);
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = IMAGE_MIME_TYPES[ext] || 'application/octet-stream';
+        res.setHeader('Content-Type', contentType);
+        res.end(imageData);
+    }
+    catch (error) {
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        if ((error === null || error === void 0 ? void 0 : error.code) === 'ENOENT') {
+            res.statusCode = 404;
+            res.end(`${label.charAt(0).toUpperCase() + label.slice(1)} file not found`);
+        }
+        else {
+            res.statusCode = 500;
+            res.end(`Error reading ${label}: ${(error === null || error === void 0 ? void 0 : error.message) || 'unknown error'}`);
+        }
+    }
+}
 async function serveTelemetryApplication(rootPath, projectConfig) {
     return new Promise((resolve, reject) => {
         var _a;

package/dist/utils/template.d.ts

@@ -0,0 +1,2 @@
+export declare const templatesDir: string;
+export declare function copyDir(source: string, destination: string, replacements: Record<string, string>, progressFn: (createdFilePath: string) => void): Promise<void>;

package/dist/utils/template.js

@@ -0,0 +1,30 @@
+import fs from 'fs/promises';
+import path from 'path';
+export const templatesDir = path.join(import.meta.dirname, '../../templates');
+const ignoredTemplateFiles = ['.DS_Store', 'thumbs.db', 'node_modules', '.git', 'dist'];
+const dotfileNames = ['_gitignore', '_claude'];
+export async function copyDir(source, destination, replacements, progressFn) {
+    const dirListing = await fs.readdir(source);
+    for (const dirEntry of dirListing) {
+        if (ignoredTemplateFiles.includes(dirEntry))
+            continue;
+        const sourcePath = path.join(source, dirEntry);
+        const destinationPath = path.join(destination, dotfileNames.includes(dirEntry) ? `.${dirEntry.slice(1)}` : dirEntry);
+        const stats = await fs.stat(sourcePath);
+        if (stats.isDirectory()) {
+            await fs.mkdir(destinationPath, { recursive: true });
+            await copyDir(sourcePath, destinationPath, replacements, progressFn);
+        }
+        else if (stats.isFile()) {
+            await copyFile(sourcePath, destinationPath, replacements, progressFn);
+        }
+    }
+}
+async function copyFile(source, destination, replacements, progressFn) {
+    let contents = await fs.readFile(source, 'utf-8');
+    for (const [key, value] of Object.entries(replacements)) {
+        contents = contents.replace(new RegExp(`{{${key}}}`, 'g'), value);
+    }
+    await fs.writeFile(destination, contents, 'utf-8');
+    progressFn(destination);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetryos/cli",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "The official TelemetryOS application CLI package. Use it to build applications that run on the TelemetryOS platform",
   "type": "module",
   "bin": {
@@ -25,13 +25,13 @@
   "license": "",
   "repository": "github:TelemetryTV/Application-API",
   "dependencies": {
-    "@telemetryos/development-application-host-ui": "^1.12.0",
+    "@telemetryos/development-application-host-ui": "^1.13.1",
     "@types/serve-handler": "^6.1.4",
     "commander": "^14.0.0",
     "ignore": "^6.0.2",
     "inquirer": "^12.9.6",
     "serve-handler": "^6.1.6",
-    "tar": "^7.4.3",
+    "tar": "^7.5.9",
     "zod": "^4.1.12"
   },
   "devDependencies": {

package/templates/{vite-react-typescript → claude-code}/CLAUDE.md

@@ -16,33 +16,43 @@ tos serve          # Start dev server (or: npm run dev)
 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.
 
 **The development host is already running!** The user has already started it and the agent doesn't need to run it
 
 ## Architecture
 
-TelemetryOS apps have two mount points:
+TelemetryOS apps have at least two mount points. Apps that need a browser-accessible interface add a third: the Web mount point.
 
 | Mount | Purpose | Runs On |
 |-------|---------|---------|
 | `/render` | Content displayed on devices | Physical device (TV, kiosk) |
 | `/settings` | Configuration UI | Studio admin portal |
+| `/web` (optional) | Browser-accessible interface | Any browser (phone, tablet, desktop) |
 
-Settings and Render communicate via instance store hooks.
+Instance store hooks sync Settings ↔ Render. Application store hooks are accessible from Settings, Render, and Web. Web views typically use application and dynamic namespace store hooks for their data.
 
 ## Project Structure
 
 ```
+public/
+└── assets/          # Static assets copied to dist/ during build
+    └── tos-app.svg  # App logo (referenced by telemetry.config.json logoPath)
 src/
 ├── index.tsx        # Entry point (configure SDK here)
 ├── App.tsx          # Mount point routing
 ├── views/
 │   ├── Settings.tsx # Configuration UI
-│   └── Render.tsx   # Display content
+│   ├── Render.tsx   # Display content
+│   ├── Render.css   # Render styles
+│   ├── Web.tsx      # Browser interface (if using web)
+│   └── Web.css      # Web view styles (if using web)
 └── hooks/
     └── store.ts     # Store state hooks
 ```
 
+> **Note:** Files in `public/` are copied as-is to `dist/` by Vite (without the `public/` prefix). The `logoPath` and `thumbnailPath` in `telemetry.config.json` must reference the output path (e.g., `"assets/tos-app.svg"`, not `"public/assets/tos-app.svg"`).
+
 ## Core Pattern
 
 ### Store Hooks (Settings ↔ Render sync)
@@ -60,6 +70,7 @@ export const useUnitsState = createUseInstanceStoreState<'imperial' | 'metric'>(
 import { useCityState } from '../hooks/store'
 
 const [isLoading, city, setCity] = useCityState()
+if (isLoading) return <div>Loading...</div>
 ```
 
 ### Settings Components
@@ -113,6 +124,7 @@ const response = await proxy().fetch('https://api.example.com/data')
 | Adding ANY Settings UI | `tos-settings-ui` | SDK components are required - raw HTML won't work |
 | Adding store keys | `tos-store-sync` | Hook patterns ensure Settings↔Render sync |
 | Building multi-mode apps | `tos-multi-mode` | Entity-scoped data, mode switching, namespace patterns |
+| Building web views | `tos-web-ui-design` | Web mount point routing, styling, store access |
 | Calling external APIs | `tos-proxy-fetch` | Proxy patterns prevent CORS errors |
 | Media library access | `tos-media-api` | SDK media methods and types |
 | Weather integration | `tos-weather-api` | API-specific patterns and credentials |