@puredesktop/create-app 2.1.4 → 2.1.6

package/template/docs/tool-handlers.md

@@ -1,124 +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
-
+# 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
-```
+
+- `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

@@ -1,59 +1,60 @@
-# 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.
+# 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 by exact exported package paths before creating custom
+primitives. Do not invent component folders.
 
 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.
+- `AppFrame` from `@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame`
+- `EmptyState` from `@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState`
+- `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.

package/template/package.json

@@ -3,16 +3,16 @@
   "private": true,
   "version": "0.1.0",
   "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
-  },
-  "dependencies": {
-    "@puredesktop/puredesktop-ui-bridge": "2.1.3",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
+  },
+  "dependencies": {
+    "@puredesktop/puredesktop-ui-bridge": "2.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "styled-components": "^6.1.18"
   },
   "devDependencies": {

package/template/plugin.json

@@ -1,20 +1,20 @@
-{
-  "schemaVersion": 1,
-  "id": "{{PLUGIN_ID}}",
-  "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings", "agents"],
-  "entrypoint": {
-    "kind": "dev-url",
-    "url": "http://localhost:{{APP_PORT}}"
-  },
-  "app": {
-    "id": "plugin.{{APP_SLUG}}",
-    "slug": "{{APP_SLUG}}",
-    "name": "{{APP_TITLE}}",
-    "navigationLabel": "{{APP_TITLE}}",
-    "productName": "pure.{{APP_SLUG}}",
-    "kind": "{{APP_SLUG}}",
-    "description": "{{APP_TITLE}} - built with PureDesktop.",
-    "usePureDesktopAiPanel": true
-  }
-}
+{
+  "schemaVersion": 1,
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{APP_TITLE}}",
+  "permissions": ["network", "settings", "agents"],
+  "entrypoint": {
+    "kind": "dev-url",
+    "url": "http://localhost:{{APP_PORT}}"
+  },
+  "app": {
+    "id": "plugin.{{APP_SLUG}}",
+    "slug": "{{APP_SLUG}}",
+    "name": "{{APP_TITLE}}",
+    "navigationLabel": "{{APP_TITLE}}",
+    "productName": "pure.{{APP_SLUG}}",
+    "kind": "{{APP_SLUG}}",
+    "description": "{{APP_TITLE}} - built with PureDesktop.",
+    "usePureDesktopAiPanel": true
+  }
+}

package/template/src/App.tsx

@@ -1,5 +1,5 @@
-import { AppFrame } from '@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame'
-import { EmptyState } from '@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState'
+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'
@@ -33,8 +33,8 @@ export function App(): React.ReactElement {
             bootError
               ? bootError.message
               : booting
-                ? 'Loading...'
-                : 'Waiting for PureDesktop shell bridge...'
+                ? 'Loading...'
+                : 'Waiting for PureDesktop shell bridge...'
           }
         />
       </AppFrame>