@puredesktop/create-app 2.1.7 → 2.1.8

package/bin/create-puredesktop-app.mjs

@@ -394,7 +394,8 @@ Before shipping:
 
 Register in PureDesktop (File -> Register App...) with:
   entrypoint: http://localhost:${options.port}
-  permissions: network, settings, agents
+  permissions: network, settings, filesystem, agents
 
-Build your UI in src/components/AppShell.tsx.
-`)
+Build product surfaces in src/components, workflow hooks in src/hooks, and domain logic in src/lib.
+Keep src/App.tsx and src/components/AppShell.tsx thin.
+`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "Scaffold a PureDesktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {

package/template/README.md

@@ -36,7 +36,9 @@ and declared app agent tools.
 - `src/App.tsx`: bridge and boot gates wrapped in `AppFrame`.
 - `src/bridge/platformBridge.ts`: local app bridge exports.
 - `src/hooks/useAppBoot.ts`: boot data loading after bridge readiness.
-- `src/components/AppShell.tsx`: first app-owned UI surface.
+- `src/components/AppShell.tsx`: thin app-owned composition root.
+- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
+  when the first product surface exists.
 - `docs/`: builder-facing app, bridge, agent, and tool-handler docs.
 
 ## Builder Docs

package/template/docs/README.md

@@ -14,8 +14,9 @@ Read these in order when building or repairing an app:
 3. [Bridge helpers](./bridge/README.md)
 4. [App agent](./agent.md)
 5. [Tool handlers](./tool-handlers.md)
-6. [UI and components](./ui-and-components.md)
-7. [Theme CSS variables](./theme-vars.md)
+6. [Adding an app agent tool](./howtos/adding-agent-tool.md)
+7. [UI and components](./ui-and-components.md)
+8. [Theme CSS variables](./theme-vars.md)
 
 Key files in this scaffold:
 
@@ -25,7 +26,11 @@ Key files in this scaffold:
 - `src/App.tsx`: bridge readiness, boot loading, and `AppFrame` wrapper.
 - `src/bridge/platformBridge.ts`: local app bridge surface.
 - `src/hooks/useAppBoot.ts`: app boot data loading after the bridge is ready.
-- `src/components/AppShell.tsx`: first app-owned UI surface.
+- `src/components/AppShell.tsx`: thin app-owned composition root.
+- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
+  when the first product surface exists.
+- `src/lib/starterWorkspace.ts`: starter data/helper example showing where
+  reusable non-rendering logic belongs.
 - `scripts/validate-puredesktop-app.mjs`: registration and tool scaffold check.
 
 Use `npm run puredesktop:check` after `npm run build` before registration.

package/template/docs/howtos/adding-agent-tool.md

@@ -0,0 +1,106 @@
+# Adding An App Agent Tool
+
+App agent tools are a three-file contract. A tool is not available until the
+manifest, registration catalog, and runtime handler all contain the same name.
+
+## Edit Sequence
+
+1. Add the tool declaration to `plugin.json` under `app.agents.tools`.
+   Include a clear `description`, an `inputSchema`, and `requiresApproval`.
+   Set `requiresApproval: true` for writes that mutate app data, files,
+   external services, or broad app state.
+
+2. Add the same tool name to `src/agents/catalog.ts`.
+   `APP_AGENT_TOOL_NAMES` is the list registered with the shell at runtime. Keep
+   it in the same order as `plugin.json` `app.agents.tools`.
+
+3. Add the same tool name to `src/agents/handlers/index.ts`.
+   Implement the handler with app-owned state or domain helpers. Return compact
+   JSON for reads and a short result for writes. Return
+   `agentToolErrorContent(message)` for invalid input the assistant can correct.
+
+4. Update `agents.md` when the app assistant needs to know when or how to use
+   the tool.
+
+5. Run checks:
+
+   ```bash
+   npm run typecheck
+   npm run build
+   npm run puredesktop:check
+   ```
+
+During dev mode, `npm run typecheck` is enough to catch TypeScript errors, but
+`npm run puredesktop:check` only proves the final package after `npm run build`
+refreshes `dist`.
+
+## Existing Tool Scaffold
+
+For apps that already have tools, these files already exist:
+
+```text
+src/
+  agents/
+    catalog.ts
+    handlers/
+      index.ts
+  hooks/
+    useAppAgentTools.ts
+```
+
+Only edit `plugin.json`, `src/agents/catalog.ts`,
+`src/agents/handlers/index.ts`, and optionally `agents.md`.
+
+## First Tool In An App
+
+If `src/agents/` does not exist, create the scaffold:
+
+```ts
+// src/agents/catalog.ts
+export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
+
+export const APP_AGENT_LOG_LABEL = '{{APP_SLUG}}'
+```
+
+```ts
+// src/agents/handlers/index.ts
+import { agentToolErrorContent } from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
+import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+
+const listItems: AgentToolHandler = async () => {
+  return agentToolErrorContent('listItems is not implemented yet.')
+}
+
+export const appAgentHandlers = {
+  listItems,
+} satisfies Record<string, AgentToolHandler>
+```
+
+```ts
+// src/hooks/useAppAgentTools.ts
+import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+import { APP_AGENT_LOG_LABEL, APP_AGENT_TOOL_NAMES } from '../agents/catalog'
+import { appAgentHandlers } from '../agents/handlers'
+
+export function useAppAgentTools(ready: boolean): void {
+  usePlatformAgentTools({
+    ready,
+    tools: APP_AGENT_TOOL_NAMES,
+    logLabel: APP_AGENT_LOG_LABEL,
+    handlers: appAgentHandlers,
+  })
+}
+```
+
+Then wire the hook in `src/App.tsx` immediately after `usePlatformBridge()`:
+
+```ts
+const { error: bridgeError, ready } = usePlatformBridge()
+useAppAgentTools(ready)
+```
+
+## Common Failure
+
+Do not update only `plugin.json` and the handler. If `APP_AGENT_TOOL_NAMES`
+does not include the new tool, the iframe never registers it with the shell. The
+assistant will see a declared tool that the running app cannot handle.

package/template/docs/howtos/persisting-app-state.md

@@ -0,0 +1,242 @@
+# Persisting App State
+
+PureDesktop apps persist non-document state through UI bridge helpers. This
+state is app-owned: the app defines the TypeScript type, default value, parser,
+and update commands.
+
+## State Surfaces
+
+| State | Helper | Permission |
+| --- | --- | --- |
+| Small app preferences | `usePlatformAppSettings` | `settings` |
+| Internal JSON records | `usePlatformJsonStore` | `filesystem` |
+
+Use document lifecycle APIs for user-visible documents, drafts, recents, rename,
+duplicate, and open/save workflows.
+
+## Generated App Wiring
+
+The generated app already has the bridge readiness boundary:
+
+- `src/App.tsx` calls `usePlatformBridge()` and receives `ready`.
+- `src/App.tsx` calls `useAppBoot(ready || standaloneDev)`.
+- `src/hooks/useAppBoot.ts` loads startup settings through the app bridge.
+- `src/components/AppShell.tsx` receives boot data as props.
+
+Use that structure instead of adding bridge calls inside components.
+
+When state is read once at startup, `useAppBoot` can load it and pass it down.
+When state can change while the app is open, create a dedicated hook in
+`src/hooks/` that calls the platform helper and exposes typed commands.
+
+## Add Editable App Settings
+
+1. Create or reuse the domain folder under `src/lib/<domain>/`.
+2. Define the settings type, default value, and parser in that domain folder.
+3. Create `src/hooks/use<Domain>Settings.ts`.
+4. Inside that hook, call `usePlatformAppSettings`.
+5. Pass `APP_SLUG` and the bridge `ready` value to the hook.
+6. Return typed settings plus app-specific command functions.
+7. Components call those command functions; they do not build settings patches.
+
+Hook shape:
+
+```text
+use real domain settings type
+call usePlatformAppSettings with APP_SLUG, ready, default settings, parser
+return settings, loading, error
+return field-specific commands that call patchSettings
+```
+
+Field-specific commands own the settings patch. Components call the command; they
+do not assemble the patch object.
+
+## Add An Internal JSON Store
+
+1. Add `filesystem` to `plugin.json`.
+2. Create or reuse the domain folder under `src/lib/<domain>/`.
+3. Define the store type, empty value, parser, and pure update helpers in that
+   domain folder.
+4. Create `src/hooks/use<Domain>Store.ts`.
+5. Inside that hook, call `usePlatformJsonStore`.
+6. Use a file name that includes `APP_SLUG` and the real persisted record name.
+7. Return typed store state plus app-specific command functions.
+8. Components call those command functions; they do not edit raw JSON objects.
+
+Hook shape:
+
+```text
+use real domain store type
+call usePlatformJsonStore with APP_SLUG, ready, file name, empty store, parser
+return store, loading, saving, error
+return domain commands that call updateValue with pure update functions
+```
+
+Domain commands own the store update. Components call the command; they do not
+edit raw JSON objects. Store update functions must return new store objects.
+
+## App Settings
+
+Import:
+
+```ts
+import { usePlatformAppSettings } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAppSettings'
+```
+
+Use for small app preferences such as current mode, sorting, filtering, and
+lightweight options.
+
+Options:
+
+```ts
+{
+  appSlug: string | null
+  enabled?: boolean
+  initialSettings?: TSettings
+  parse?: (value: Record<string, unknown>) => TSettings
+}
+```
+
+Returns:
+
+```ts
+{
+  settings: TSettings
+  loading: boolean
+  error: Error | null
+  patchSettings: (patch: Record<string, unknown>) => Promise<TSettings>
+  reload: () => void
+}
+```
+
+Behavior:
+
+- loads through `settings.app.get`;
+- saves through `settings.app.update`;
+- `patchSettings` shallow-merges the patch in shell preferences;
+- the shell stores app settings under the current app slug;
+- the app parser converts persisted `Record<string, unknown>` into the app's
+  typed settings object.
+
+App ownership:
+
+- keep the settings type in app code;
+- keep defaults and parsing in app code;
+- expose typed settings and typed commands to components;
+- use app settings for preferences, not large record collections.
+
+## JSON Store
+
+Import:
+
+```ts
+import { usePlatformJsonStore } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformJsonStore'
+```
+
+Use for internal app records that are larger than settings and are not
+user-visible documents.
+
+Options:
+
+```ts
+{
+  appSlug: string | null
+  fileName: `${string}.json` | null
+  initialValue: TValue
+  enabled?: boolean
+  parse?: (value: unknown) => TValue
+}
+```
+
+Returns:
+
+```ts
+{
+  value: TValue
+  path: string | null
+  loading: boolean
+  saving: boolean
+  error: Error | null
+  saveValue: (next: TValue) => Promise<TValue>
+  updateValue: (updater: (current: TValue) => TValue) => Promise<TValue>
+  reload: () => void
+}
+```
+
+Behavior:
+
+- loads through `storage.readJson`;
+- saves through `storage.writeJson`;
+- missing files load as `initialValue`;
+- saved values replace the full JSON value;
+- `updateValue` queues writes and applies each updater to the latest in-memory
+  value;
+- `fileName` must be a single `.json` file name;
+- the JSON file is stored in the shell-managed appdata folder.
+
+App ownership:
+
+- include `filesystem` in `plugin.json`;
+- keep the store type in app code;
+- keep defaults, parsing, and pure update functions in app code;
+- use an app-prefixed file name with the real persisted record name;
+- expose typed state and typed commands to components;
+- never mutate the current store object in place.
+
+## File Shape
+
+Use one `src/lib/<domain>/` folder per persisted domain. Do not put types,
+defaults, parsing, pure updates, platform hooks, and UI in one file.
+
+```text
+src/
+  hooks/
+    use<Domain>Settings.ts
+    use<Domain>Store.ts
+  lib/
+    <domain>/
+      types.ts
+      defaults.ts
+      parse.ts
+      updates.ts
+      index.ts
+  components/
+```
+
+Responsibilities:
+
+- `types.ts` exports the persisted domain types.
+- `defaults.ts` exports default settings or empty store values.
+- `parse.ts` converts unknown persisted values into valid domain state.
+- `updates.ts` contains pure functions that return new state objects.
+- `index.ts` re-exports the domain pieces used outside the folder.
+- `src/hooks/use<Domain>Settings.ts` calls `usePlatformAppSettings`.
+- `src/hooks/use<Domain>Store.ts` calls `usePlatformJsonStore`.
+- components import the app-owned hooks and render state.
+
+Split a file when it starts owning more than one responsibility. The hook should
+not define the domain model. Components should not parse persisted data. Pure
+update functions should not call platform helpers.
+
+## Verification
+
+Run:
+
+```bash
+npm run typecheck
+npm run build
+npm run puredesktop:check
+```
+
+Source checks:
+
+- app settings state has a domain settings type, default value, parser, and
+  hook;
+- JSON store state has a domain store type, empty value, parser, pure update
+  helpers, and hook;
+- components import the app-owned hooks instead of platform persistence helpers;
+- `usePlatformJsonStore` is only imported from app-owned hooks;
+- apps using `usePlatformJsonStore` include `filesystem` in `plugin.json`;
+- JSON store file names include `APP_SLUG` and the real persisted record name;
+- JSON store update functions return new objects instead of mutating existing
+  state.

package/template/docs/plugin-manifest.md

@@ -10,7 +10,7 @@ agent tools.
   "schemaVersion": 1,
   "id": "{{PLUGIN_ID}}",
   "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings", "agents"],
+  "permissions": ["network", "settings", "filesystem", "agents"],
   "entrypoint": {
     "kind": "dev-url",
     "url": "http://localhost:{{APP_PORT}}"

package/template/docs/theme-vars.md

@@ -1,138 +1,138 @@
-# Theme CSS Variables
-
-This file is generated from `packages/ui/src/theme/tokens.ts`.
-
-PureDesktop injects these variables through `AppFrame` and the shell bridge
-theme payload. Use them in app styling instead of hardcoded platform colors,
-spacing, typography, radii, shadows, transitions, or app stacking values.
-
-This static reference is generated by PureDesktop maintainers before the
-create-app package is released.
-
-| Variable | Domain | Light value | Dark value |
-| --- | --- | --- | --- |
-| `--platform-colors-accent` | colors | `#1b1b1e` | `#e5e5e9` |
-| `--platform-colors-accent-hover` | colors | `#1b1b1e` | `#eaeaee` |
-| `--platform-colors-accent-muted` | colors | `#eaeaee` | `#313135` |
-| `--platform-colors-app-viewport` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-bg` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-border` | colors | `#e5e5e9` | `#313135` |
-| `--platform-colors-border-strong` | colors | `#dadade` | `#43434a` |
-| `--platform-colors-chrome-tab-strip` | colors | `#ececef` | `#1b1b1e` |
-| `--platform-colors-chrome-titlebar` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-danger` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-divider` | colors | `#e5e5e9` | `#313135` |
-| `--platform-colors-elevated` | colors | `#ffffff` | `#26262a` |
-| `--platform-colors-focus` | colors | `#1b1b1e` | `#e5e5e9` |
-| `--platform-colors-info` | colors | `#3b6fb0` | `#6fa0e0` |
-| `--platform-colors-selection` | colors | `#eaeaee` | `#313135` |
-| `--platform-colors-semantic-blue` | colors | `#3b6fb0` | `#6fa0e0` |
-| `--platform-colors-semantic-blue-border` | colors | `#b9cbe4` | `#365373` |
-| `--platform-colors-semantic-blue-muted` | colors | `#e8f0fb` | `#1c2a3c` |
-| `--platform-colors-semantic-blue-text` | colors | `#244f87` | `#a8c8f0` |
-| `--platform-colors-semantic-green` | colors | `#1f8a55` | `#57b988` |
-| `--platform-colors-semantic-green-border` | colors | `#1f8a55` | `#32684d` |
-| `--platform-colors-semantic-green-muted` | colors | `#eef7f1` | `#18342a` |
-| `--platform-colors-semantic-green-text` | colors | `#16683f` | `#8fe0b6` |
-| `--platform-colors-semantic-orange` | colors | `#c98a2b` | `#e0b257` |
-| `--platform-colors-semantic-orange-border` | colors | `#e3c98f` | `#6d5b2f` |
-| `--platform-colors-semantic-orange-muted` | colors | `#f3e5c8` | `#3a3322` |
-| `--platform-colors-semantic-orange-text` | colors | `#7a5114` | `#f0ce8a` |
-| `--platform-colors-semantic-red` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-semantic-red-border` | colors | `#dfb7b1` | `#753f38` |
-| `--platform-colors-semantic-red-muted` | colors | `#f4dfdc` | `#3a211d` |
-| `--platform-colors-semantic-red-text` | colors | `#8a2d24` | `#f0a89e` |
-| `--platform-colors-success` | colors | `#1f8a55` | `#57b988` |
-| `--platform-colors-surface` | colors | `#f8f8fa` | `#26262a` |
-| `--platform-colors-surface-active` | colors | `#eaeaee` | `#161619` |
-| `--platform-colors-surface-hover` | colors | `#eaeaee` | `#2c2c30` |
-| `--platform-colors-text` | colors | `#1b1b1e` | `#ececef` |
-| `--platform-colors-text-danger` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-text-disabled` | colors | `#9a9aa0` | `#6e6e74` |
-| `--platform-colors-text-inverse` | colors | `#ffffff` | `#1b1b1e` |
-| `--platform-colors-text-secondary` | colors | `#3a3a3e` | `#c9c9cf` |
-| `--platform-colors-warning` | colors | `#c98a2b` | `#e0b257` |
-| `--platform-radius-full` | radius | `999px` | `999px` |
-| `--platform-radius-lg` | radius | `0px` | `0px` |
-| `--platform-radius-md` | radius | `0px` | `0px` |
-| `--platform-radius-sm` | radius | `0px` | `0px` |
-| `--platform-shadow-lg` | shadow | `0 18px 48px rgb(18 18 22 / 0.13)` | `0 18px 44px rgba(0, 0, 0, 0.38)` |
-| `--platform-shadow-md` | shadow | `0 8px 24px rgb(18 18 22 / 0.08)` | `0 8px 24px rgba(0, 0, 0, 0.3)` |
-| `--platform-shadow-sm` | shadow | `none` | `none` |
-| `--platform-spacing-lg` | spacing | `16px` | `16px` |
-| `--platform-spacing-md` | spacing | `12px` | `12px` |
-| `--platform-spacing-sm` | spacing | `8px` | `8px` |
-| `--platform-spacing-xl` | spacing | `24px` | `24px` |
-| `--platform-spacing-xs` | spacing | `4px` | `4px` |
-| `--platform-spacing-xxl` | spacing | `32px` | `32px` |
-| `--platform-transition-base` | transition | `200ms ease` | `200ms ease` |
-| `--platform-transition-fast` | transition | `120ms ease` | `120ms ease` |
-| `--platform-transition-slow` | transition | `320ms ease` | `320ms ease` |
-| `--platform-typography-font-family` | typography | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` |
-| `--platform-typography-font-family-content` | typography | `'Source Serif 4', Georgia, serif` | `'Source Serif 4', Georgia, serif` |
-| `--platform-typography-font-family-mono` | typography | `'JetBrains Mono', ui-monospace, monospace` | `'JetBrains Mono', ui-monospace, monospace` |
-| `--platform-typography-font-size-base` | typography | `14.5px` | `14.5px` |
-| `--platform-typography-font-size-lg` | typography | `17px` | `17px` |
-| `--platform-typography-font-size-sm` | typography | `13px` | `13px` |
-| `--platform-typography-font-size-xl` | typography | `24px` | `24px` |
-| `--platform-typography-font-size-xs` | typography | `11px` | `11px` |
-| `--platform-typography-font-weight-bold` | typography | `600` | `600` |
-| `--platform-typography-font-weight-medium` | typography | `500` | `500` |
-| `--platform-typography-font-weight-normal` | typography | `400` | `400` |
-| `--platform-typography-line-height-base` | typography | `1.6` | `1.6` |
-| `--platform-typography-line-height-tight` | typography | `1.25` | `1.25` |
-| `--platform-z-index-zi-app-base` | zIndex | `0` | `0` |
-| `--platform-z-index-zi-app-chrome` | zIndex | `20` | `20` |
-| `--platform-z-index-zi-app-menus` | zIndex | `100` | `100` |
-| `--platform-z-index-zi-app-modal` | zIndex | `300` | `300` |
-| `--platform-z-index-zi-app-sidebar` | zIndex | `10` | `10` |
-| `--platform-z-index-zi-app-toast` | zIndex | `200` | `200` |
-| `--platform-z-index-zi-app-viewport-toolbar` | zIndex | `25` | `25` |
-
-## App-Owned Colors
-
-Use platform variables for the base app shell, text, surfaces, borders,
-spacing, typography, radius, shadows, transitions, and z-index.
-
-When the app domain needs colors beyond the platform set, define app-prefixed
-variables and keep them synchronized with the shell theme through
-`data-platform-theme`.
-
-Good use cases for app-owned colors:
-
-- chart series;
-- calendar categories;
-- tags and labels;
-- syntax or document annotations;
-- domain-specific status colors not covered by platform semantic colors.
-
-Pattern:
-
-```ts
-const Root = styled.div`
-  --myapp-chart-blue: #3b73d9;
-  --myapp-chart-blue-muted: color-mix(
-    in srgb,
-    var(--myapp-chart-blue) 12%,
-    var(--platform-colors-surface)
-  );
-
-  [data-platform-theme='dark'] & {
-    --myapp-chart-blue: #8ab4ff;
-    --myapp-chart-blue-muted: color-mix(
-      in srgb,
-      var(--myapp-chart-blue) 18%,
-      var(--platform-colors-surface)
-    );
-  }
-`
-```
-
-Rules for app-owned colors:
-
-- prefix app variables with the app slug or a short app namespace;
-- provide dark-mode values inside `[data-platform-theme='dark'] &`;
-- derive muted fills, hovers, selections, and outlines with `color-mix()` and
-  platform surface, text, border, or background variables;
-- use `--platform-colors-accent` for primary app identity and actions;
-- reserve app-owned colors for domain meaning.
+# Theme CSS Variables
+
+This file is generated from `packages/ui/src/theme/tokens.ts`.
+
+PureDesktop injects these variables through `AppFrame` and the shell bridge
+theme payload. Use them in app styling instead of hardcoded platform colors,
+spacing, typography, radii, shadows, transitions, or app stacking values.
+
+This static reference is generated by PureDesktop maintainers before the
+create-app package is released.
+
+| Variable | Domain | Light value | Dark value |
+| --- | --- | --- | --- |
+| `--platform-colors-accent` | colors | `#1b1b1e` | `#e5e5e9` |
+| `--platform-colors-accent-hover` | colors | `#1b1b1e` | `#eaeaee` |
+| `--platform-colors-accent-muted` | colors | `#eaeaee` | `#313135` |
+| `--platform-colors-app-viewport` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-bg` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-border` | colors | `#e5e5e9` | `#313135` |
+| `--platform-colors-border-strong` | colors | `#dadade` | `#43434a` |
+| `--platform-colors-chrome-tab-strip` | colors | `#ececef` | `#1b1b1e` |
+| `--platform-colors-chrome-titlebar` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-danger` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-divider` | colors | `#e5e5e9` | `#313135` |
+| `--platform-colors-elevated` | colors | `#ffffff` | `#26262a` |
+| `--platform-colors-focus` | colors | `#1b1b1e` | `#e5e5e9` |
+| `--platform-colors-info` | colors | `#3b6fb0` | `#6fa0e0` |
+| `--platform-colors-selection` | colors | `#eaeaee` | `#313135` |
+| `--platform-colors-semantic-blue` | colors | `#3b6fb0` | `#6fa0e0` |
+| `--platform-colors-semantic-blue-border` | colors | `#b9cbe4` | `#365373` |
+| `--platform-colors-semantic-blue-muted` | colors | `#e8f0fb` | `#1c2a3c` |
+| `--platform-colors-semantic-blue-text` | colors | `#244f87` | `#a8c8f0` |
+| `--platform-colors-semantic-green` | colors | `#1f8a55` | `#57b988` |
+| `--platform-colors-semantic-green-border` | colors | `#1f8a55` | `#32684d` |
+| `--platform-colors-semantic-green-muted` | colors | `#eef7f1` | `#18342a` |
+| `--platform-colors-semantic-green-text` | colors | `#16683f` | `#8fe0b6` |
+| `--platform-colors-semantic-orange` | colors | `#c98a2b` | `#e0b257` |
+| `--platform-colors-semantic-orange-border` | colors | `#e3c98f` | `#6d5b2f` |
+| `--platform-colors-semantic-orange-muted` | colors | `#f3e5c8` | `#3a3322` |
+| `--platform-colors-semantic-orange-text` | colors | `#7a5114` | `#f0ce8a` |
+| `--platform-colors-semantic-red` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-semantic-red-border` | colors | `#dfb7b1` | `#753f38` |
+| `--platform-colors-semantic-red-muted` | colors | `#f4dfdc` | `#3a211d` |
+| `--platform-colors-semantic-red-text` | colors | `#8a2d24` | `#f0a89e` |
+| `--platform-colors-success` | colors | `#1f8a55` | `#57b988` |
+| `--platform-colors-surface` | colors | `#f8f8fa` | `#26262a` |
+| `--platform-colors-surface-active` | colors | `#eaeaee` | `#161619` |
+| `--platform-colors-surface-hover` | colors | `#eaeaee` | `#2c2c30` |
+| `--platform-colors-text` | colors | `#1b1b1e` | `#ececef` |
+| `--platform-colors-text-danger` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-text-disabled` | colors | `#9a9aa0` | `#6e6e74` |
+| `--platform-colors-text-inverse` | colors | `#ffffff` | `#1b1b1e` |
+| `--platform-colors-text-secondary` | colors | `#3a3a3e` | `#c9c9cf` |
+| `--platform-colors-warning` | colors | `#c98a2b` | `#e0b257` |
+| `--platform-radius-full` | radius | `999px` | `999px` |
+| `--platform-radius-lg` | radius | `0px` | `0px` |
+| `--platform-radius-md` | radius | `0px` | `0px` |
+| `--platform-radius-sm` | radius | `0px` | `0px` |
+| `--platform-shadow-lg` | shadow | `0 18px 48px rgb(18 18 22 / 0.13)` | `0 18px 44px rgba(0, 0, 0, 0.38)` |
+| `--platform-shadow-md` | shadow | `0 8px 24px rgb(18 18 22 / 0.08)` | `0 8px 24px rgba(0, 0, 0, 0.3)` |
+| `--platform-shadow-sm` | shadow | `none` | `none` |
+| `--platform-spacing-lg` | spacing | `16px` | `16px` |
+| `--platform-spacing-md` | spacing | `12px` | `12px` |
+| `--platform-spacing-sm` | spacing | `8px` | `8px` |
+| `--platform-spacing-xl` | spacing | `24px` | `24px` |
+| `--platform-spacing-xs` | spacing | `4px` | `4px` |
+| `--platform-spacing-xxl` | spacing | `32px` | `32px` |
+| `--platform-transition-base` | transition | `200ms ease` | `200ms ease` |
+| `--platform-transition-fast` | transition | `120ms ease` | `120ms ease` |
+| `--platform-transition-slow` | transition | `320ms ease` | `320ms ease` |
+| `--platform-typography-font-family` | typography | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` |
+| `--platform-typography-font-family-content` | typography | `'Source Serif 4', Georgia, serif` | `'Source Serif 4', Georgia, serif` |
+| `--platform-typography-font-family-mono` | typography | `'JetBrains Mono', ui-monospace, monospace` | `'JetBrains Mono', ui-monospace, monospace` |
+| `--platform-typography-font-size-base` | typography | `14.5px` | `14.5px` |
+| `--platform-typography-font-size-lg` | typography | `17px` | `17px` |
+| `--platform-typography-font-size-sm` | typography | `13px` | `13px` |
+| `--platform-typography-font-size-xl` | typography | `24px` | `24px` |
+| `--platform-typography-font-size-xs` | typography | `11px` | `11px` |
+| `--platform-typography-font-weight-bold` | typography | `600` | `600` |
+| `--platform-typography-font-weight-medium` | typography | `500` | `500` |
+| `--platform-typography-font-weight-normal` | typography | `400` | `400` |
+| `--platform-typography-line-height-base` | typography | `1.6` | `1.6` |
+| `--platform-typography-line-height-tight` | typography | `1.25` | `1.25` |
+| `--platform-z-index-zi-app-base` | zIndex | `0` | `0` |
+| `--platform-z-index-zi-app-chrome` | zIndex | `20` | `20` |
+| `--platform-z-index-zi-app-menus` | zIndex | `100` | `100` |
+| `--platform-z-index-zi-app-modal` | zIndex | `300` | `300` |
+| `--platform-z-index-zi-app-sidebar` | zIndex | `10` | `10` |
+| `--platform-z-index-zi-app-toast` | zIndex | `200` | `200` |
+| `--platform-z-index-zi-app-viewport-toolbar` | zIndex | `25` | `25` |
+
+## App-Owned Colors
+
+Use platform variables for the base app shell, text, surfaces, borders,
+spacing, typography, radius, shadows, transitions, and z-index.
+
+When the app domain needs colors beyond the platform set, define app-prefixed
+variables and keep them synchronized with the shell theme through
+`data-platform-theme`.
+
+Good use cases for app-owned colors:
+
+- chart series;
+- calendar categories;
+- tags and labels;
+- syntax or document annotations;
+- domain-specific status colors not covered by platform semantic colors.
+
+Pattern:
+
+```ts
+const Root = styled.div`
+  --myapp-chart-blue: #3b73d9;
+  --myapp-chart-blue-muted: color-mix(
+    in srgb,
+    var(--myapp-chart-blue) 12%,
+    var(--platform-colors-surface)
+  );
+
+  [data-platform-theme='dark'] & {
+    --myapp-chart-blue: #8ab4ff;
+    --myapp-chart-blue-muted: color-mix(
+      in srgb,
+      var(--myapp-chart-blue) 18%,
+      var(--platform-colors-surface)
+    );
+  }
+`
+```
+
+Rules for app-owned colors:
+
+- prefix app variables with the app slug or a short app namespace;
+- provide dark-mode values inside `[data-platform-theme='dark'] &`;
+- derive muted fills, hovers, selections, and outlines with `color-mix()` and
+  platform surface, text, border, or background variables;
+- use `--platform-colors-accent` for primary app identity and actions;
+- reserve app-owned colors for domain meaning.

package/template/docs/tool-handlers.md

@@ -7,6 +7,9 @@ App agent tools have two halves:
 
 The names must match exactly.
 
+For the exact edit checklist when adding a new tool, read
+[Adding an app agent tool](./adding-agent-tool.md).
+
 ## Generated Structure
 
 When the manifest includes `app.agents.tools`, the generator creates this

package/template/docs/ui-and-components.md

@@ -1,35 +1,56 @@
-# UI And Components
-
-The generated app starts intentionally small. Build the real workflow in
-`src/components/AppShell.tsx` and move domain logic into `src/lib/` as it grows.
-
-## AppFrame
-
-Every render path in `src/App.tsx` uses `AppFrame`. This gives the iframe the
-PureDesktop reset, theme CSS variables, and shell-compatible surface styling.
-
-## Component Shape
-
-Start with controlled, simple components:
-
-```text
-src/
-  components/
-    AppShell.tsx
-    ItemList.tsx
-    ItemDetail.tsx
-  lib/
-    items.ts
-    items.test.ts
-```
-
-Keep app state close to the workflow until a shared hook or reducer removes real
-duplication.
-
-## Platform Components
-
+# UI And Components
+
+The generated app starts with a small starter workspace so the iframe has a
+useful screen while the first builder task runs. Treat the starter as temporary
+scaffold, not product UI.
+
+`src/App.tsx` owns bridge readiness and `AppFrame`. `src/components/AppShell.tsx`
+is the thin composition root after boot succeeds. Do not turn either file into
+the product implementation.
+
+## AppFrame
+
+Every render path in `src/App.tsx` uses `AppFrame`. This gives the iframe the
+PureDesktop reset, theme CSS variables, and shell-compatible surface styling.
+
+## App Structure
+
+Use the first real product task to replace the starter workspace with app-owned
+surfaces. Keep responsibilities split:
+
+- `src/App.tsx`: bridge readiness, boot loading, error states, and `AppFrame`.
+- `src/components/AppShell.tsx`: thin composition root that wires boot data into
+  product surfaces.
+- `src/components/*`: product screens, panels, lists, editors, dialogs, and
+  controls.
+- `src/hooks/*`: reusable workflow state, effects, synchronization, and bridge
+  orchestration.
+- `src/lib/*`: domain types, reducers, rules, transforms, fixtures, and tests.
+
+Start with controlled, simple modules:
+
+```text
+src/
+  components/
+    AppShell.tsx
+    StarterWorkspace.tsx       # replace when the first product surface exists
+    ProjectBoard.tsx
+    ProjectDetail.tsx
+  hooks/
+    useProjects.ts
+  lib/
+    projects.ts
+    projects.test.ts
+```
+
+Keep state local only while it is display-only. When state drives multiple
+components, persistence, agent tools, bridge calls, or domain rules, move it into
+an app hook or `src/lib` module before adding more screens.
+
+## Platform Components
+
 Import shared UI by exact exported package paths before creating custom
-primitives. Do not invent component folders.
+primitives. Use existing app folders before creating new ones.
 
 Useful starting points:
 
@@ -38,23 +59,26 @@ Useful starting points:
 - `Heading` from `@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading`
 - `Text` from `@puredesktop/puredesktop-ui-bridge/components/common/typography/Text`
 - `Button` from `@puredesktop/puredesktop-ui-bridge/components/common/buttons/Button`
-
-## Styling
-
-Use styled-components and platform CSS variables:
-
-```ts
-const Root = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: var(--platform-spacing-md);
-  color: var(--platform-colors-text);
-  background: var(--platform-colors-bg);
-`
-```
-
-Use app-local CSS variables only for app-specific meaning, for example
-`--{{APP_SLUG}}-accent`.
-
-See [Theme CSS variables](./theme-vars.md) for the generated list of available
-platform variables by domain.
+
+## Styling
+
+Use styled-components and platform CSS variables:
+
+```ts
+const Root = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-md);
+  color: var(--platform-colors-text);
+  background: var(--platform-colors-bg);
+`
+```
+
+Use app-local CSS variables only for app-specific meaning, for example
+`--{{APP_SLUG}}-accent`.
+
+See [Theme CSS variables](./theme-vars.md) for the generated list of available
+platform variables by domain.
+
+Avoid inline styles except for tiny dynamic values that cannot be represented as
+props on a styled component.

package/template/package.json

@@ -10,7 +10,7 @@
     "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
   },
   "dependencies": {
-    "@puredesktop/puredesktop-ui-bridge": "2.1.7",
+    "@puredesktop/puredesktop-ui-bridge": "2.1.8",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "styled-components": "^6.1.18"

package/template/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "id": "{{PLUGIN_ID}}",
   "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings", "agents"],
+  "permissions": ["network", "settings", "filesystem", "agents"],
   "entrypoint": {
     "kind": "dev-url",
     "url": "http://localhost:{{APP_PORT}}"

package/template/scripts/validate-puredesktop-app.mjs

@@ -20,9 +20,10 @@ if (packageJson) {
   validatePackageJson(packageJson)
 }
 
-if (manifest) {
-  validateManifest(manifest)
-}
+if (manifest) {
+  validateManifest(manifest)
+  await validateBridgePermissionUsage(manifest)
+}
 
 if (await isDirectory(distPath)) {
   info.push('dist folder is present for static registration.')
@@ -135,7 +136,7 @@ function validateManifest(manifest) {
   if (errors.length === 0) info.push('plugin.json is valid.')
 }
 
-function validateEntrypoint(entrypoint, permissions) {
+function validateEntrypoint(entrypoint, permissions) {
   if (!isPlainObject(entrypoint)) {
     errors.push('entrypoint is required.')
     return
@@ -169,10 +170,47 @@ function validateEntrypoint(entrypoint, permissions) {
     }
     return
   }
-  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
-}
-
-async function validateAgentTools(manifest, distPath) {
+  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
+}
+
+async function validateBridgePermissionUsage(manifest) {
+  const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : []
+  const sourceText = await readProjectText(join(ROOT, 'src'))
+  const requirements = [
+    {
+      permission: 'filesystem',
+      hints: [
+        '/bridge/storage',
+        '/bridge/fs',
+        '/bridge/dialog',
+        '/bridge/react/usePlatformJsonStore',
+      ],
+    },
+    {
+      permission: 'settings',
+      hints: [
+        '/bridge/appSettings',
+        '/bridge/preferences',
+        '/bridge/react/usePlatformAppSettings',
+        '/bridge/react/usePlatformPreferences',
+      ],
+    },
+    {
+      permission: 'network',
+      hints: ['/bridge/network', '/bridge/vision'],
+    },
+  ]
+
+  for (const requirement of requirements) {
+    if (permissions.includes(requirement.permission)) continue
+    if (!requirement.hints.some(hint => sourceText.includes(hint))) continue
+    errors.push(
+      `Source imports ${requirement.permission}-gated bridge helpers, so plugin.json must include the ${requirement.permission} permission.`,
+    )
+  }
+}
+
+async function validateAgentTools(manifest, distPath) {
   const tools = manifest.app?.agents?.tools ?? []
   if (!Array.isArray(tools) || tools.length === 0) {
     info.push('No app agent tools declared.')

package/template/src/App.tsx

@@ -1,9 +1,10 @@
 import { AppFrame } from '@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame'
 import { EmptyState } from '@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState'
 import { usePlatformBridge } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformBridge'
-import { AppShell } from './components/AppShell'
-import { isStandaloneDevMode } from './bridge/platformBridge'
-import { useAppBoot } from './hooks/useAppBoot'
+import { AppShell } from './components/AppShell'
+import { isStandaloneDevMode } from './bridge/platformBridge'
+import { APP_TITLE } from './constants'
+import { useAppBoot } from './hooks/useAppBoot'
 
 export function App(): React.ReactElement {
   const { error: bridgeError, ready } = usePlatformBridge()
@@ -28,7 +29,7 @@ export function App(): React.ReactElement {
       <AppFrame>
         <EmptyState
           tone={bootError ? 'error' : 'neutral'}
-          title={bootError ? 'Boot failed' : '{{APP_TITLE}}'}
+          title={bootError ? 'Boot failed' : APP_TITLE}
           message={
             bootError
               ? bootError.message

package/template/src/components/AppShell.tsx

@@ -1,33 +1,11 @@
-import styled from 'styled-components'
-import { Heading } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading'
-import { Text } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Text'
-import type { AppSettings } from '../types'
-
-const Root = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  padding: 32px;
-  max-width: 720px;
-`
-
-export interface AppShellProps {
-  settings: AppSettings
-}
-
-export function AppShell({ settings }: AppShellProps): React.ReactElement {
-  return (
-    <Root>
-      <Heading level={1}>{{APP_TITLE}}</Heading>
-      <Text>
-        Start building in <code>src/components/AppShell.tsx</code>. Bridge boot
-        is wired — AppFrame, settings load, and standalone browser dev all work.
-      </Text>
-      {Object.keys(settings).length > 0 ? (
-        <Text size="sm" tone="secondary">
-          Loaded {Object.keys(settings).length} setting key(s).
-        </Text>
-      ) : null}
-    </Root>
-  )
-}
+import type { AppSettings } from '../types'
+import { APP_TITLE } from '../constants'
+import { StarterWorkspace } from './StarterWorkspace'
+
+export interface AppShellProps {
+  settings: AppSettings
+}
+
+export function AppShell({ settings }: AppShellProps): React.ReactElement {
+  return <StarterWorkspace appName={APP_TITLE} settings={settings} />
+}

package/template/src/components/StarterWorkspace.tsx

@@ -0,0 +1,154 @@
+import styled from 'styled-components'
+import { Heading } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading'
+import { Text } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Text'
+import {
+  readConfiguredSettingCount,
+  starterMilestones,
+} from '../lib/starterWorkspace'
+import type { AppSettings } from '../types'
+
+const Root = styled.div`
+  display: flex;
+  min-height: 100%;
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  padding: var(--platform-spacing-xxl);
+  color: var(--platform-colors-text);
+  background:
+    linear-gradient(
+      135deg,
+      color-mix(in srgb, var(--platform-colors-accent) 6%, transparent),
+      transparent 42%
+    ),
+    var(--platform-colors-bg);
+`
+
+const Panel = styled.section`
+  display: grid;
+  width: min(760px, 100%);
+  gap: var(--platform-spacing-xl);
+`
+
+const Header = styled.header`
+  display: grid;
+  gap: var(--platform-spacing-sm);
+`
+
+const MilestoneGrid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: var(--platform-spacing-md);
+
+  @media (max-width: 720px) {
+    grid-template-columns: 1fr;
+  }
+`
+
+const Milestone = styled.article`
+  display: grid;
+  gap: var(--platform-spacing-sm);
+  min-width: 0;
+  padding: var(--platform-spacing-lg);
+  border: 1px solid var(--platform-colors-border);
+  background: var(--platform-colors-surface);
+  box-shadow: var(--platform-shadow-sm);
+`
+
+const PulseTrack = styled.div`
+  position: relative;
+  overflow: hidden;
+  height: 3px;
+  background: var(--platform-colors-border);
+`
+
+const Pulse = styled.div`
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: 44%;
+  background: var(--platform-colors-accent);
+  animation: starter-pulse 1600ms ease-in-out infinite;
+
+  @keyframes starter-pulse {
+    0% {
+      transform: translateX(-100%);
+      opacity: 0.35;
+    }
+
+    45%,
+    60% {
+      opacity: 1;
+    }
+
+    100% {
+      transform: translateX(230%);
+      opacity: 0.35;
+    }
+  }
+`
+
+const MetaRow = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--platform-spacing-sm);
+`
+
+const MetaPill = styled.span`
+  padding: 4px 8px;
+  border: 1px solid var(--platform-colors-border);
+  background: var(--platform-colors-surface);
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-xs);
+  font-weight: var(--platform-typography-font-weight-medium);
+`
+
+interface StarterWorkspaceProps {
+  appName: string
+  settings: AppSettings
+}
+
+export function StarterWorkspace({
+  appName,
+  settings,
+}: StarterWorkspaceProps): React.ReactElement {
+  const settingCount = readConfiguredSettingCount(settings)
+
+  return (
+    <Root>
+      <Panel aria-label={`${appName} starter workspace`}>
+        <Header>
+          <Text size="sm" tone="secondary">
+            PureDesktop app workspace
+          </Text>
+          <Heading level={1}>{appName}</Heading>
+          <Text tone="secondary">
+            This workspace is ready. The first build step will replace this
+            starter screen with the product experience.
+          </Text>
+        </Header>
+
+        <MilestoneGrid>
+          {starterMilestones.map(milestone => (
+            <Milestone key={milestone.id}>
+              <Text size="sm" weight="medium">
+                {milestone.title}
+              </Text>
+              <Text size="sm" tone="secondary">
+                {milestone.detail}
+              </Text>
+              <PulseTrack aria-hidden="true">
+                <Pulse />
+              </PulseTrack>
+            </Milestone>
+          ))}
+        </MilestoneGrid>
+
+        <MetaRow>
+          <MetaPill>{settingCount} setting key(s)</MetaPill>
+          <MetaPill>Theme active</MetaPill>
+          <MetaPill>Shell connected</MetaPill>
+        </MetaRow>
+      </Panel>
+    </Root>
+  )
+}

package/template/src/constants.ts

@@ -1 +1,2 @@
-export const APP_SLUG = '{{APP_SLUG}}'
+export const APP_SLUG = '{{APP_SLUG}}'
+export const APP_TITLE = '{{APP_TITLE}}'

package/template/src/lib/starterWorkspace.ts

@@ -0,0 +1,29 @@
+import type { AppSettings } from '../types'
+
+export interface StarterMilestone {
+  detail: string
+  id: string
+  title: string
+}
+
+export const starterMilestones: StarterMilestone[] = [
+  {
+    detail: 'The starter screen is temporary and ready to be replaced by product UI.',
+    id: 'boot',
+    title: 'Workspace ready',
+  },
+  {
+    detail: 'PureDesktop styling is loaded so early screens match the shell.',
+    id: 'composition',
+    title: 'Theme active',
+  },
+  {
+    detail: 'Settings and shell capabilities are available through the app bridge.',
+    id: 'domain',
+    title: 'Shell connected',
+  },
+]
+
+export function readConfiguredSettingCount(settings: AppSettings): number {
+  return Object.keys(settings).length
+}

package/template/vite.config.js

@@ -16,13 +16,16 @@ function devServerFromManifest(metaUrl) {
   }
 }
 
-export default defineConfig({
-  plugins: [
-    react({
-      plugins: [
-        ['@swc/plugin-styled-components', { displayName: true, fileName: true }],
-      ],
-    }),
-  ],
-  server: devServerFromManifest(import.meta.url),
-})
+export default defineConfig({
+  plugins: [
+    react({
+      plugins: [
+        ['@swc/plugin-styled-components', { displayName: true, fileName: true }],
+      ],
+    }),
+  ],
+  optimizeDeps: {
+    include: ['react-dom'],
+  },
+  server: devServerFromManifest(import.meta.url),
+})