@puredesktop/create-app 2.1.0 → 2.1.1

package/template/docs/theme-vars.md

@@ -0,0 +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 |
+| --- | --- |
+| `--platform-colors-accent` | colors |
+| `--platform-colors-accent-hover` | colors |
+| `--platform-colors-accent-muted` | colors |
+| `--platform-colors-app-viewport` | colors |
+| `--platform-colors-bg` | colors |
+| `--platform-colors-border` | colors |
+| `--platform-colors-border-strong` | colors |
+| `--platform-colors-chrome-tab-strip` | colors |
+| `--platform-colors-chrome-titlebar` | colors |
+| `--platform-colors-danger` | colors |
+| `--platform-colors-divider` | colors |
+| `--platform-colors-elevated` | colors |
+| `--platform-colors-focus` | colors |
+| `--platform-colors-info` | colors |
+| `--platform-colors-selection` | colors |
+| `--platform-colors-semantic-blue` | colors |
+| `--platform-colors-semantic-blue-border` | colors |
+| `--platform-colors-semantic-blue-muted` | colors |
+| `--platform-colors-semantic-blue-text` | colors |
+| `--platform-colors-semantic-green` | colors |
+| `--platform-colors-semantic-green-border` | colors |
+| `--platform-colors-semantic-green-muted` | colors |
+| `--platform-colors-semantic-green-text` | colors |
+| `--platform-colors-semantic-orange` | colors |
+| `--platform-colors-semantic-orange-border` | colors |
+| `--platform-colors-semantic-orange-muted` | colors |
+| `--platform-colors-semantic-orange-text` | colors |
+| `--platform-colors-semantic-red` | colors |
+| `--platform-colors-semantic-red-border` | colors |
+| `--platform-colors-semantic-red-muted` | colors |
+| `--platform-colors-semantic-red-text` | colors |
+| `--platform-colors-success` | colors |
+| `--platform-colors-surface` | colors |
+| `--platform-colors-surface-active` | colors |
+| `--platform-colors-surface-hover` | colors |
+| `--platform-colors-text` | colors |
+| `--platform-colors-text-danger` | colors |
+| `--platform-colors-text-disabled` | colors |
+| `--platform-colors-text-inverse` | colors |
+| `--platform-colors-text-secondary` | colors |
+| `--platform-colors-warning` | colors |
+| `--platform-radius-full` | radius |
+| `--platform-radius-lg` | radius |
+| `--platform-radius-md` | radius |
+| `--platform-radius-sm` | radius |
+| `--platform-shadow-lg` | shadow |
+| `--platform-shadow-md` | shadow |
+| `--platform-shadow-sm` | shadow |
+| `--platform-spacing-lg` | spacing |
+| `--platform-spacing-md` | spacing |
+| `--platform-spacing-sm` | spacing |
+| `--platform-spacing-xl` | spacing |
+| `--platform-spacing-xs` | spacing |
+| `--platform-spacing-xxl` | spacing |
+| `--platform-transition-base` | transition |
+| `--platform-transition-fast` | transition |
+| `--platform-transition-slow` | transition |
+| `--platform-typography-font-family` | typography |
+| `--platform-typography-font-family-content` | typography |
+| `--platform-typography-font-family-mono` | typography |
+| `--platform-typography-font-size-base` | typography |
+| `--platform-typography-font-size-lg` | typography |
+| `--platform-typography-font-size-sm` | typography |
+| `--platform-typography-font-size-xl` | typography |
+| `--platform-typography-font-size-xs` | typography |
+| `--platform-typography-font-weight-bold` | typography |
+| `--platform-typography-font-weight-medium` | typography |
+| `--platform-typography-font-weight-normal` | typography |
+| `--platform-typography-line-height-base` | typography |
+| `--platform-typography-line-height-tight` | typography |
+| `--platform-z-index-zi-app-base` | zIndex |
+| `--platform-z-index-zi-app-chrome` | zIndex |
+| `--platform-z-index-zi-app-menus` | zIndex |
+| `--platform-z-index-zi-app-modal` | zIndex |
+| `--platform-z-index-zi-app-sidebar` | zIndex |
+| `--platform-z-index-zi-app-toast` | zIndex |
+| `--platform-z-index-zi-app-viewport-toolbar` | zIndex |
+
+## 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

@@ -0,0 +1,124 @@
+# Tool Handlers
+
+App agent tools have two halves:
+
+- `plugin.json` declares the tool schema for the shell agent.
+- app source registers a runtime handler after the iframe bridge is ready.
+
+The names must match exactly.
+
+## Generated Structure
+
+When the manifest includes `app.agents.tools`, the generator creates this
+structure and wires `useAppAgentTools(ready)` into `src/App.tsx`:
+
+```text
+src/
+  agents/
+    catalog.ts
+    handlers/
+      index.ts
+  hooks/
+    useAppAgentTools.ts
+```
+
+## Catalog
+
+Generated from manifest tool names:
+
+```ts
+export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
+
+export const APP_AGENT_LOG_LABEL = '{{APP_SLUG}}'
+```
+
+Keep this list in the same order as `plugin.json` `app.agents.tools`.
+
+## Registration Hook
+
+Generated when tools exist:
+
+```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,
+  })
+}
+```
+
+Call this hook from `src/App.tsx` after `usePlatformBridge()`:
+
+```ts
+useAppAgentTools(ready)
+```
+
+## Handler Shape
+
+Generated handlers start as explicit not-implemented tool errors. Replace each
+stub with app domain logic.
+
+```ts
+import {
+  agentToolErrorContent,
+  formatAgentToolJson,
+  readAgentToolStringArg,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
+import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+
+const listItems: AgentToolHandler = async invoke => {
+  const status = readAgentToolStringArg(invoke.arguments, 'status')
+
+  return {
+    content: formatAgentToolJson({
+      items: [],
+      status: status || null,
+    }),
+  }
+}
+
+export const appAgentHandlers = {
+  listItems,
+} satisfies Record<string, AgentToolHandler>
+```
+
+Return compact JSON for structured data. Return `agentToolErrorContent(message)`
+for validation failures that the agent can correct.
+
+## Read Tool Pattern
+
+Read tools return current app state, ids, paths, and exact values needed before a
+write. The agent needs stable ids and exact target names.
+
+## Write Tool Pattern
+
+Write tools validate precise targets. A write handler returns a short result
+with the changed id/path and enough data for the agent to explain what changed.
+
+Manifest write tools that mutate files, records, external services, or broad app
+state set `requiresApproval: true` unless the action is intentionally safe.
+
+## Validation
+
+`npm run puredesktop:check` verifies declared tool names appear in source and in
+the built output. For generated tool scaffolds, it also verifies:
+
+- `src/agents/catalog.ts` exports `APP_AGENT_TOOL_NAMES`;
+- every manifest tool name appears in the catalog;
+- `src/agents/handlers/index.ts` exports `appAgentHandlers`;
+- every manifest tool name appears in the handler map;
+- `src/hooks/useAppAgentTools.ts` registers with `usePlatformAgentTools`;
+- `src/App.tsx` calls `useAppAgentTools(ready)`.
+
+Build before running it:
+
+```bash
+npm run build
+npm run puredesktop:check
+```

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

@@ -0,0 +1,59 @@
+# 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
+
+Import shared UI from `@puredesktop/puredesktop-ui-bridge/components/...` before
+creating custom primitives.
+
+Useful starting points:
+
+- `AppFrame`
+- `EmptyState`
+- `Heading`
+- `Text`
+
+## 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.

package/template/package.json

@@ -9,10 +9,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
   },
-  "dependencies": {
-    "{{UI_PACKAGE_NAME}}": "{{UI_PACKAGE_VERSION}}",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+  "dependencies": {
+    "@puredesktop/puredesktop-ui-bridge": "2.1.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "styled-components": "^6.1.18"
   },
   "devDependencies": {

package/template/plugin.json

@@ -14,7 +14,7 @@
     "navigationLabel": "{{APP_TITLE}}",
     "productName": "pure.{{APP_SLUG}}",
     "kind": "{{APP_SLUG}}",
-    "description": "{{APP_TITLE}} - built with PureScience Desktop.",
+    "description": "{{APP_TITLE}} - built with PureDesktop.",
     "usePureDesktopAiPanel": true
   }
 }

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

@@ -199,6 +199,9 @@ async function validateAgentTools(manifest, distPath) {
 
   if (toolNames.size === 0) return
 
+  const manifestToolNames = [...toolNames]
+  await validateAgentToolScaffold(manifestToolNames)
+
   const sourceText = await readProjectText(join(ROOT, 'src'))
   const distText = await readProjectText(distPath)
   const registrationHints = ['usePlatformAgentTools', 'registerAgentTools', 'agents.tools.register']
@@ -206,7 +209,7 @@ async function validateAgentTools(manifest, distPath) {
     errors.push('Declared app agent tools must be registered in source with usePlatformAgentTools or agents.tools.register.')
   }
 
-  for (const toolName of toolNames) {
+  for (const toolName of manifestToolNames) {
     if (!sourceText.includes(toolName)) {
       errors.push(`Declared app agent tool "${toolName}" was not found in source files.`)
     }
@@ -220,6 +223,68 @@ async function validateAgentTools(manifest, distPath) {
   }
 }
 
+async function validateAgentToolScaffold(toolNames) {
+  const catalogPath = join(ROOT, 'src', 'agents', 'catalog.ts')
+  const handlersPath = join(ROOT, 'src', 'agents', 'handlers', 'index.ts')
+  const hookPath = join(ROOT, 'src', 'hooks', 'useAppAgentTools.ts')
+  const appPath = join(ROOT, 'src', 'App.tsx')
+
+  const catalogText = await readRequiredText(
+    catalogPath,
+    'Declared app agent tools require src/agents/catalog.ts.',
+  )
+  const handlersText = await readRequiredText(
+    handlersPath,
+    'Declared app agent tools require src/agents/handlers/index.ts.',
+  )
+  const hookText = await readRequiredText(
+    hookPath,
+    'Declared app agent tools require src/hooks/useAppAgentTools.ts.',
+  )
+  const appText = await readRequiredText(
+    appPath,
+    'Declared app agent tools require src/App.tsx.',
+  )
+
+  if (!catalogText || !handlersText || !hookText || !appText) return
+
+  if (!catalogText.includes('APP_AGENT_TOOL_NAMES')) {
+    errors.push('src/agents/catalog.ts must export APP_AGENT_TOOL_NAMES.')
+  }
+  if (!handlersText.includes('appAgentHandlers')) {
+    errors.push('src/agents/handlers/index.ts must export appAgentHandlers.')
+  }
+  if (!hookText.includes('usePlatformAgentTools')) {
+    errors.push('src/hooks/useAppAgentTools.ts must call usePlatformAgentTools.')
+  }
+  if (!hookText.includes('APP_AGENT_TOOL_NAMES')) {
+    errors.push('src/hooks/useAppAgentTools.ts must register APP_AGENT_TOOL_NAMES.')
+  }
+  if (!appText.includes('useAppAgentTools(ready)')) {
+    errors.push('src/App.tsx must call useAppAgentTools(ready).')
+  }
+
+  for (const toolName of toolNames) {
+    if (!catalogText.includes(toolName)) {
+      errors.push(`src/agents/catalog.ts is missing app agent tool "${toolName}".`)
+    }
+    if (!handlersText.includes(toolName)) {
+      errors.push(`src/agents/handlers/index.ts is missing app agent tool "${toolName}".`)
+    }
+  }
+}
+
+async function readRequiredText(path, message) {
+  if (!(await isFile(path))) {
+    errors.push(message)
+    return ''
+  }
+  return readFile(path, 'utf8').catch(error => {
+    errors.push(`${message} ${errorMessage(error)}`)
+    return ''
+  })
+}
+
 async function readProjectText(root) {
   const chunks = []
   await collectText(root, chunks)

package/template/src/App.tsx

@@ -33,8 +33,8 @@ export function App(): React.ReactElement {
             bootError
               ? bootError.message
               : booting
-                ? 'Loading…'
-                : 'Waiting for PureScience shell bridge…'
+                ? 'Loading...'
+                : 'Waiting for PureDesktop shell bridge...'
           }
         />
       </AppFrame>

package/template/src/bridge/platformBridge.ts

@@ -1,9 +1,58 @@
-import { bridge } from '@puredesktop/puredesktop-ui-bridge/bridge/client'
-import { PLATFORM_BRIDGE_METHODS } from '@puredesktop/puredesktop-ui-bridge/bridge/methods'
-import { APP_SLUG } from '../constants'
-import type { AppSettings } from '../types'
-
-export { bridge }
+import { bridge } from '@puredesktop/puredesktop-ui-bridge/bridge/client'
+import { getPlatformAppSettings } from '@puredesktop/puredesktop-ui-bridge/bridge/appSettings'
+import { APP_SLUG } from '../constants'
+import type { AppSettings } from '../types'
+
+export {
+  getPlatformAppSettings,
+  updatePlatformAppSettings,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/appSettings'
+export {
+  getPlatformPreferences,
+  patchPlatformPreferences,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/preferences'
+export {
+  networkFetch,
+  type PlatformNetworkFetchRequest,
+  type PlatformNetworkFetchResponse,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/network'
+export {
+  createPlatformFolder,
+  deletePlatformFile,
+  listPlatformFiles,
+  readPlatformFileBinary,
+  readPlatformFileBinaryDataUrl,
+  readPlatformFilePreview,
+  readPlatformFilePreviewUrl,
+  readPlatformTextFile,
+  renamePlatformFile,
+  writePlatformFileBinary,
+  writePlatformTextFile,
+  type PlatformFileCreateFolderResult,
+  type PlatformFileDeleteResult,
+  type PlatformFileEntry,
+  type PlatformFileListResult,
+  type PlatformFilePreviewUrlResult,
+  type PlatformFileReadBinaryResult,
+  type PlatformFileReadPreviewResult,
+  type PlatformFileRenameResult,
+  type PlatformFileWriteResult,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/fs'
+export {
+  openPlatformFileDialog,
+  openPlatformFolderDialog,
+  openPlatformImageDialog,
+  savePlatformFolderDialog,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/dialog'
+export {
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+  type PlatformStorageJsonReadResult,
+  type PlatformStorageJsonRequest,
+  type PlatformStorageJsonWriteRequest,
+  type PlatformStorageJsonWriteResult,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/storage'
+export { bridge }
 
 const STANDALONE_SETTINGS_KEY = 'puredesktop:{{APP_SLUG}}:settings'
 
@@ -20,12 +69,10 @@ function readStandaloneSettings(): AppSettings {
   }
 }
 
-export async function fetchAppSettings(): Promise<AppSettings> {
-  if (isStandaloneDevMode()) {
-    return readStandaloneSettings()
-  }
-
-  return bridge.call<AppSettings>(PLATFORM_BRIDGE_METHODS.SETTINGS_APP_GET, [
-    APP_SLUG,
-  ])
-}
+export async function fetchAppSettings(): Promise<AppSettings> {
+  if (isStandaloneDevMode()) {
+    return readStandaloneSettings()
+  }
+
+  return getPlatformAppSettings(APP_SLUG) as Promise<AppSettings>
+}