@puredesktop/create-app 2.1.0 → 2.1.2

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.2",
+    "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
   }
 }