@puredesktop/create-app 2.1.5 → 2.1.7

package/package.json

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

package/template/README.md

@@ -1,56 +1,56 @@
-# {{APP_TITLE}}
-
-Vite + React plugin app for **PureDesktop**, scaffolded with
-`@puredesktop/create-app`.
-
-## Start
-
-```bash
-npm install
-npm run dev
-```
-
-The dev server runs at `http://localhost:{{APP_PORT}}`, matching
-`plugin.json`.
-
-In PureDesktop, register the app from **File -> Register App...** with the same
-entrypoint URL.
-
-## Build
-
-```bash
+# {{APP_TITLE}}
+
+Vite + React plugin app for **PureDesktop**, scaffolded with
+`@puredesktop/create-app`.
+
+## Start
+
+```bash
+npm install
+npm run dev
+```
+
+The dev server runs at `http://localhost:{{APP_PORT}}`, matching
+`plugin.json`.
+
+In PureDesktop, register the app from **File -> Register App...** with the same
+entrypoint URL.
+
+## Build
+
+```bash
 npm run typecheck
-npm run build
-npm run puredesktop:check
-```
-
+npm run build
+npm run puredesktop:check
+```
+
 `puredesktop:check` verifies the package facts the shell needs before
 registration: manifest shape, entrypoint, permissions, `agents.md`, build output,
 and declared app agent tools.
-
-## Project Layout
-
-- `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.
-
-## Builder Docs
-
-Read [docs/README.md](./docs/README.md) before changing app structure.
-
-Bridge helper docs live in [docs/bridge/README.md](./docs/bridge/README.md).
-
-## Core Rules
-
-- `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.
+
+## Project Layout
+
+- `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.
+
+## Builder Docs
+
+Read [docs/README.md](./docs/README.md) before changing app structure.
+
+Bridge helper docs live in [docs/bridge/README.md](./docs/bridge/README.md).
+
+## Core Rules
+
+- `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/agents.md

@@ -1,11 +1,11 @@
-# {{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.
-
-When tools are available, use read-only tools before write tools. Ask for
-confirmation before destructive or external-effect changes unless the tool
-policy already requires approval.
+# {{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.
+
+When tools are available, use read-only tools before write tools. Ask for
+confirmation before destructive or external-effect changes unless the tool
+policy already requires approval.

package/template/docs/README.md

@@ -1,31 +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.
+# 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.
+
+Use `npm run puredesktop:check` after `npm run build` before registration.

package/template/docs/agent.md

@@ -1,58 +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.
+# 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

@@ -1,60 +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.
+# 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

@@ -1,84 +1,84 @@
-# 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.
-
-`platformBridge.ts` is both the exported app bridge surface and the place for
-app-owned bridge wrappers. Package bridge helpers are imported as local bindings
-first, then re-exported for app code. App-specific wrappers in this file should
-call those local bindings.
-
-## 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.
+# 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.
+
+`platformBridge.ts` is both the exported app bridge surface and the place for
+app-owned bridge wrappers. Package bridge helpers are imported as local bindings
+first, then re-exported for app code. App-specific wrappers in this file should
+call those local bindings.
+
+## 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.