@puredesktop/create-app 1.0.0-beta.2 → 2.1.1

package/template/README.md

@@ -1,313 +1,56 @@
-# {{APP_TITLE}}
-
-Vite + React plugin app for **PureScience Desktop**, scaffolded with `@puredesktop/create-app`.
-
-## Dev in the shell
-
-1. `npm install`
-2. `npm run dev` — serves at `http://localhost:{{APP_PORT}}` (must match `plugin.json`)
-3. In PureScience Desktop: **File → Register App…**
-   - Entrypoint URL: `http://localhost:{{APP_PORT}}`
-   - Permissions: **Network**, **Settings**, **Agents**
-
-## Dev in the browser (optional)
-
-Open the Vite URL directly. The app runs in standalone dev mode without the shell bridge.
-
-## Build & deploy
+# {{APP_TITLE}}
 
-```bash
-npm run typecheck
-npm run build
-npm run puredesktop:check
-```
-
-Deploy the `dist/` folder to HTTPS, then register that URL in PureScience Desktop.
-
-Run `npm run puredesktop:check` after every production build. It checks the
-same package facts PureScience Desktop needs before registration:
-
-- `plugin.json` is valid and has the required app identity fields.
-- non-local URL entrypoints include the `network` permission.
-- `dist/` exists.
-- `agents.md` is matched by the `agents` permission.
-- `app.usePureDesktopAiPanel` is `true`.
-- `package.json` has the required scripts and dependencies.
-- declared `app.agents.tools` have names, descriptions, schemas, source
-  handlers, and built output.
-
-## Project layout
-
-- `src/App.tsx` — bridge + boot gates, always wraps `AppFrame`
-- `src/components/AppShell.tsx` — your UI starts here
-- `src/bridge/platformBridge.ts` — only file that calls `bridge.call`
-- `plugin.json` — catalog metadata and dev entrypoint port
-- `agents.md` — app-scoped assistant prompt used by PureDesktop agent sessions
-
-## PureDesktop app rules
-
-Every generated app must keep these files aligned:
-
-- `plugin.json` `app.slug` must match `src/constants.ts`.
-- `plugin.json` `entrypoint.url` must match the Vite dev port.
-- `plugin.json` `app.usePureDesktopAiPanel` must stay `true` for now. The
-  shell PureDesktop AI panel owns the agent UI.
-- `agents.md` must exist at the package root for app-scoped sessions.
-- `plugin.json` `permissions` must include every bridge capability the app uses:
-  `settings` for app settings, `filesystem` for files/storage/dialog/catalog
-  file opens, `network` for hosted URLs and network/OAuth/vision calls,
-  `assets` for asset library calls, `render` for print/render calls, and
-  `agents` for agent sessions, tools, credentials, context, or screen capture.
-- Keep all direct `bridge.call(...)` usage inside `src/bridge/platformBridge.ts`
-  or a local bridge helper owned by that folder.
-- Keep `AppFrame` around every return path in `src/App.tsx`, including loading
-  and error states.
-
-## Required package.json shape
-
-Keep these scripts:
-
-```json
-{
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
-  }
-}
-```
-
-Keep these runtime dependencies:
-
-- `@puredesktop/puredesktop-ui-bridge`
-- `react`
-- `react-dom`
-- `styled-components`
-
-Keep these dev dependencies:
-
-- `@vitejs/plugin-react-swc`
-- `typescript`
-- `vite`
-
-## Required plugin.json shape
+Vite + React plugin app for **PureDesktop**, scaffolded with
+`@puredesktop/create-app`.
 
-Keep this structure and update values rather than inventing new fields:
+## Start
 
-```json
-{
-  "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 PureScience Desktop.",
-    "usePureDesktopAiPanel": true
-  }
-}
-```
-
-When the app exposes tools to its app agent, add tool schemas under
-`app.agents.tools` and keep the top-level `agents` permission:
-
-```json
-{
-  "app": {
-    "agents": {
-      "tools": [
-        {
-          "name": "listItems",
-          "description": "List the current items with ids, titles, status, and next action.",
-          "inputSchema": {
-            "type": "object",
-            "properties": {
-              "status": {
-                "type": "string",
-                "description": "Optional status filter."
-              }
-            },
-            "additionalProperties": false
-          },
-          "requiresApproval": false
-        }
-      ]
-    }
-  }
-}
-```
-
-## Required app agent
-
-Every app has an app agent:
-
-1. Keep `agents` in top-level `plugin.json` permissions.
-2. Keep root-level `agents.md` next to `plugin.json`.
-3. Keep `app.usePureDesktopAiPanel` set to `true`.
-4. Run `npm run typecheck`, `npm run build`, and `npm run puredesktop:check`.
-
-Add tool handlers when the manifest declares `app.agents.tools`.
-
-Create a stable tool-name catalog:
-
-```ts
-// src/agents/catalog.ts
-export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
+```bash
+npm install
+npm run dev
 ```
 
-Register matching runtime handlers after the bridge is ready:
+The dev server runs at `http://localhost:{{APP_PORT}}`, matching
+`plugin.json`.
 
-```tsx
-import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
-import {
-  agentToolErrorContent,
-  formatAgentToolJson,
-  readAgentToolStringArg,
-} from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
-import { APP_AGENT_TOOL_NAMES } from './agents/catalog'
+In PureDesktop, register the app from **File -> Register App...** with the same
+entrypoint URL.
 
-function AppAgentTools({ ready }: { ready: boolean }) {
-  usePlatformAgentTools({
-    ready,
-    tools: APP_AGENT_TOOL_NAMES,
-    handlers: {
-      async listItems(ctx) {
-        const status = readAgentToolStringArg(ctx.arguments, 'status')
-        try {
-          return {
-            content: formatAgentToolJson({
-              items: [],
-              status: status || null,
-            }),
-          }
-        } catch (error) {
-          return agentToolErrorContent(
-            error instanceof Error ? error.message : String(error),
-          )
-        }
-      },
-    },
-  })
+## Build
 
-  return null
-}
+```bash
+npm run typecheck
+npm run build
+npm run puredesktop:check
 ```
 
-Manifest tool names and handler names must match exactly. Read tools should
-return compact JSON with stable ids. Write tools should validate exact targets,
-reject ambiguous edits, and return a concise JSON result. Destructive or
-external-effect tools should use `requiresApproval: true`.
-
-## Design baseline
-
-Build quiet, dense, legible work software. Make the main work object visible
-quickly and directly actionable. Use platform components and `--platform-*`
-CSS variables before adding local styling. Keep one source of truth for each
-object and avoid persistent chrome that competes with the work.
+`puredesktop:check` verifies the package facts the shell needs before
+registration: manifest shape, entrypoint, permissions, `agents.md`, build output,
+and declared app agent tools.
 
-## Platform CSS variables
+## Project Layout
 
-Theme variables are injected by PureDesktop and follow
-`--platform-<domain>-<token>`. Use these before adding app-local variables:
+- `plugin.json`: app identity, permissions, entrypoint, routing, and agent tool
+  declarations.
+- `agents.md`: app-scoped assistant prompt.
+- `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.
+- `docs/`: builder-facing app, bridge, agent, and tool-handler docs.
 
-```text
---platform-mode
+## Builder Docs
 
---platform-colors-bg
---platform-colors-surface
---platform-colors-surface-hover
---platform-colors-surface-active
---platform-colors-elevated
---platform-colors-text
---platform-colors-text-secondary
---platform-colors-text-disabled
---platform-colors-text-inverse
---platform-colors-accent
---platform-colors-accent-hover
---platform-colors-accent-muted
---platform-colors-border
---platform-colors-border-strong
---platform-colors-divider
---platform-colors-danger
---platform-colors-text-danger
---platform-colors-warning
---platform-colors-success
---platform-colors-info
---platform-colors-semantic-blue
---platform-colors-semantic-blue-text
---platform-colors-semantic-blue-muted
---platform-colors-semantic-blue-border
---platform-colors-semantic-orange
---platform-colors-semantic-orange-text
---platform-colors-semantic-orange-muted
---platform-colors-semantic-orange-border
---platform-colors-semantic-green
---platform-colors-semantic-green-text
---platform-colors-semantic-green-muted
---platform-colors-semantic-green-border
---platform-colors-semantic-red
---platform-colors-semantic-red-text
---platform-colors-semantic-red-muted
---platform-colors-semantic-red-border
---platform-colors-focus
---platform-colors-selection
---platform-colors-app-viewport
---platform-colors-chrome-titlebar
---platform-colors-chrome-tab-strip
+Read [docs/README.md](./docs/README.md) before changing app structure.
 
---platform-typography-font-family
---platform-typography-font-family-content
---platform-typography-font-family-mono
---platform-typography-font-size-base
---platform-typography-font-size-xs
---platform-typography-font-size-sm
---platform-typography-font-size-lg
---platform-typography-font-size-xl
---platform-typography-line-height-base
---platform-typography-line-height-tight
---platform-typography-font-weight-normal
---platform-typography-font-weight-medium
---platform-typography-font-weight-bold
+Bridge helper docs live in [docs/bridge/README.md](./docs/bridge/README.md).
 
---platform-spacing-xs
---platform-spacing-sm
---platform-spacing-md
---platform-spacing-lg
---platform-spacing-xl
---platform-spacing-xxl
-
---platform-radius-sm
---platform-radius-md
---platform-radius-lg
---platform-radius-full
-
---platform-shadow-sm
---platform-shadow-md
---platform-shadow-lg
-
---platform-transition-fast
---platform-transition-base
---platform-transition-slow
-
---platform-z-index-zi-app-base
---platform-z-index-zi-app-sidebar
---platform-z-index-zi-app-chrome
---platform-z-index-zi-app-viewport-toolbar
---platform-z-index-zi-app-menus
---platform-z-index-zi-app-toast
---platform-z-index-zi-app-modal
-```
+## Core Rules
 
-Use the plural `--platform-colors-*` prefix for colors. Do not create
-`--platform-color-*` variables. App-specific variables should use an app prefix,
-for example `--my-app-accent`.
+- `plugin.json` `app.slug` matches `src/constants.ts` `APP_SLUG`.
+- `plugin.json` `entrypoint.url` matches the Vite dev port.
+- `app.usePureDesktopAiPanel` stays `true` for shell-owned agent UI.
+- `agents.md` stays at the package root for app-scoped sessions.
+- Bridge calls stay inside `src/bridge/platformBridge.ts` or files owned by
+  `src/bridge/`.
+- `AppFrame` wraps every `src/App.tsx` return path.

package/template/docs/README.md

@@ -0,0 +1,31 @@
+# PureDesktop App Builder Docs
+
+This folder is the builder-facing contract for generated PureDesktop apps.
+
+A generated app is a Vite + React application rendered by PureDesktop inside a
+workspace iframe. The app owns its UI, state, domain logic, and optional tool
+handlers. The shell owns discovery, tabs, bridge permissions, filesystem and OS
+services, agent sessions, and app registration.
+
+Read these in order when building or repairing an app:
+
+1. [App lifecycle](./app-lifecycle.md)
+2. [Plugin manifest](./plugin-manifest.md)
+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)
+
+Key files in this scaffold:
+
+- `plugin.json`: app identity, entrypoint, permissions, file routing, and agent
+  tool declarations.
+- `agents.md`: app-scoped assistant instructions used by shell agent sessions.
+- `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.
+- `scripts/validate-puredesktop-app.mjs`: registration and tool scaffold check.
+
+Use `npm run puredesktop:check` after `npm run build` before registration.

package/template/docs/agent.md

@@ -0,0 +1,58 @@
+# App Agent
+
+Every generated app has an app-scoped assistant that runs in the shell agent
+drawer. The app does not render its own agent chat UI by default.
+
+## Source Files
+
+- `agents.md`: app-scoped assistant prompt.
+- `plugin.json` `app.agents.tools`: tool schemas exposed to the agent.
+- `src/agents/*`: generated app-owned tool catalog and handlers when tools
+  exist.
+- `src/hooks/useAppAgentTools.ts`: generated runtime registration hook when
+  tools exist.
+
+## How The Agent Uses App Tools
+
+1. The shell reads `plugin.json` and includes declared app tools in the app
+   agent's available tools.
+2. The app iframe loads and registers runtime handlers with
+   `usePlatformAgentTools`.
+3. The agent calls a declared tool during a shell-managed session.
+4. The shell routes the invocation to the app iframe.
+5. The app handler returns compact text or JSON.
+6. The bridge helper completes the tool call back to the shell.
+7. The shell resumes the agent session.
+
+The app owns the handler implementation. The shell owns session state,
+approvals, routing, and completion.
+
+When `plugin.json` contains `app.agents.tools`, the create-app generator writes
+the initial catalog, handler map, and registration hook. The generated handlers
+return explicit not-implemented tool errors until the app replaces them with real
+domain behavior.
+
+## agents.md
+
+Keep `agents.md` grounded in the app's real UI and data. Mention the app's work
+objects, read-first workflow, write safety rules, and expected concise output.
+
+Example:
+
+```md
+# {{APP_TITLE}} Agent
+
+You are the app-scoped assistant for {{APP_TITLE}}.
+
+Help the user understand, review, and act on the work inside this app. Stay
+grounded in the app UI and data. Prefer concise answers, concrete next actions,
+and safe tool use.
+```
+
+## Approval Policy
+
+Set `requiresApproval` on each manifest tool. Read-only inspection tools usually
+set `false`. Destructive, external-effect, or broad write tools set `true`.
+
+The shell drawer displays approvals and resumes the same session after the user
+approves or rejects.

package/template/docs/app-lifecycle.md

@@ -0,0 +1,60 @@
+# App Lifecycle
+
+A PureDesktop app is loaded into an iframe by the shell. The shell discovers the
+app from `plugin.json`, opens a workspace tab, loads the entrypoint URL or built
+static bundle, then establishes the bridge handshake with the iframe.
+
+## Registration To Render
+
+1. The shell scans installed app folders for `plugin.json`.
+2. The catalog creates one app entry from `plugin.json` `app.slug`.
+3. Opening the app creates a workspace tab.
+4. The tab renders the app entrypoint in an iframe.
+5. The iframe starts React from `src/main.tsx`.
+6. `src/App.tsx` calls `usePlatformBridge()`.
+7. The bridge client sends a handshake to the shell parent window.
+8. The shell replies with `ready` metadata, including `pluginId`, `appSlug`,
+   allowed method names, theme CSS, and optional viewport resource.
+9. The app boot hook loads app settings and other startup data.
+10. The app renders inside `AppFrame`.
+
+## App.tsx Contract
+
+`src/App.tsx` is the orchestration boundary. Keep it thin:
+
+- call `usePlatformBridge()`;
+- allow standalone browser dev mode when needed;
+- call the app boot hook after the bridge is ready;
+- render loading and error states inside `AppFrame`;
+- render the app shell inside `AppFrame` after boot succeeds.
+
+The template already follows this shape.
+
+## Viewport Resources
+
+When the shell opens a file or app resource into a tab, the bridge ready metadata
+can include:
+
+```ts
+{
+  viewport: {
+    tabId: string
+    resource: { path: string; name: string; kind: string } | null
+  }
+}
+```
+
+File-centric apps use `usePlatformViewportResource(ready, meta)` from the bridge
+React helpers. This handles cold opens and warm `resource.open` events without
+duplicating event wiring in screens.
+
+## Standalone Dev
+
+The template supports browser-only development with:
+
+```ts
+window.parent === window
+```
+
+Standalone mode is for UI iteration. Production app behavior runs inside the
+shell iframe and uses shell bridge permissions.

package/template/docs/bridge/README.md

@@ -0,0 +1,79 @@
+# Platform Bridge Helpers
+
+The bridge is the app iframe's RPC channel to the PureDesktop shell.
+
+The generated app runs in an iframe. It cannot call shell internals directly.
+Instead, app code imports helpers from `src/bridge/platformBridge.ts`. That
+local bridge module wraps the package bridge client from
+`@puredesktop/puredesktop-ui-bridge`.
+
+## Runtime Boundary
+
+```text
+App iframe -> bridge helper -> postMessage -> shell renderer -> shell handler
+```
+
+The shell validates the app origin, method name, and `plugin.json` permissions
+before running a handler.
+
+## Ready Handshake
+
+`src/App.tsx` uses `usePlatformBridge()` to wait for the shell:
+
+```ts
+const { ready, error, meta } = usePlatformBridge()
+```
+
+The shell ready payload includes:
+
+- `pluginId`: plugin package identity.
+- `appSlug`: app API scope.
+- `methods`: bridge methods available in this shell.
+- `theme`: injected theme CSS.
+- `viewport`: optional tab resource opened into the app.
+
+Call bridge helpers after `ready` is true. The template boot hook follows that
+pattern.
+
+## Local Bridge Module
+
+`src/bridge/platformBridge.ts` is the app's bridge boundary. Components and
+feature code import from that local file:
+
+```ts
+import { fetchAppSettings, networkFetch } from '../bridge/platformBridge'
+```
+
+Keep request-shape knowledge in this bridge folder. Component code calls
+domain-named helpers.
+
+## Helper Domains
+
+- [Dialog](./dialog.md)
+- [Filesystem](./fs.md)
+- [Network](./network.md)
+- [Settings](./settings.md)
+- [Storage](./storage.md)
+
+## Permissions
+
+Bridge calls are gated by top-level `plugin.json` `permissions`.
+
+| Permission | Helper domains |
+| --- | --- |
+| `settings` | settings and preferences |
+| `filesystem` | filesystem, dialogs, storage, file routing |
+| `network` | network requests and OAuth-style flows |
+| `render` | print and render helpers |
+| `assets` | asset library helpers |
+| `agents` | agent sessions, agent tools, credentials |
+
+## Events
+
+The bridge also delivers shell events into the iframe. Common app events include
+theme changes, viewport resource opens, render progress, filesystem watch
+changes, agent run events, and app tool invocations.
+
+Use the package React hooks when they exist. For example,
+`usePlatformViewportResource(ready, meta)` handles file opens without manual
+event wiring.

package/template/docs/bridge/dialog.md

@@ -0,0 +1,56 @@
+# Dialog
+
+Permission: `filesystem`
+
+Dialog helpers open shell-native file and folder pickers.
+
+Import from the generated app bridge:
+
+```ts
+import {
+  openPlatformFileDialog,
+  openPlatformFolderDialog,
+  openPlatformImageDialog,
+  savePlatformFolderDialog,
+} from '../../src/bridge/platformBridge'
+```
+
+## openPlatformFolderDialog
+
+Opens a folder picker.
+
+```ts
+const folderPath = await openPlatformFolderDialog()
+```
+
+Returns the selected absolute folder path, or `null` when cancelled.
+
+## savePlatformFolderDialog
+
+Opens a folder picker configured for choosing a parent directory.
+
+```ts
+const parentPath = await savePlatformFolderDialog()
+```
+
+Returns the selected absolute folder path, or `null` when cancelled.
+
+## openPlatformImageDialog
+
+Opens an image file picker.
+
+```ts
+const imagePath = await openPlatformImageDialog()
+```
+
+Returns the selected absolute image path, or `null` when cancelled.
+
+## openPlatformFileDialog
+
+Opens a text/document file picker.
+
+```ts
+const filePath = await openPlatformFileDialog()
+```
+
+Returns the selected absolute file path, or `null` when cancelled.