Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,12 @@
## Unreleased

- Verified on Paseo 0.12.0: `ppd daemon up` and `ppd doctor` no longer print the version note on it.
- `ppd check` applies the client registration rules of the Paseo version it checks against: the app's or source checkout's version, or without a host the oldest release `requirements.paseo` admits. From 0.13.0 that includes file panels (`client.addFilePanel`, getpaseo/paseo#7411), agent panels (`client.addAgentPanel`), workspace panels without `context`, translated labels, `{ svg }` and component icons, and the `notification` timeline item. Before, every plugin that used them failed `client-eval`.
- On an app version without a method, `client.<method>` is undefined like in the app: a guarded call passes, an unguarded one fails `client-eval`.
- `client-eval` warns when the host accepts the client but the oldest release `requirements.paseo` admits would reject it. `ppd install` and `ppd dev` print the same warning as a note.
- A source checkout's version is raised to the release of the newer client methods its evaluator defines, since its package version lags main until a release is cut.
- When `requirements.paseo` excludes the installed app (a prerelease counts by its stable core, like in Paseo), `client-eval` checks against the range's lower bound and warns that the app would not load the plugin.
- From 0.13.0 a label is a non-empty string or a message from the SDK's `message()`; anything else gets the SDK's error text. `"addFilePanel" in client` works as a guard.

## 0.1.0 (2026-10-18)

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ Every command has `ppd <command> --help`.
| Compile | Paseo's own `compilePlugin`, from the installed app or `PASEO_SOURCE`; an esbuild replica (labeled `APPROXIMATION`) only when neither is found. Compile errors carry file:line:col. |
| Client modules | Bundle requires only host-provided modules; no gesture handler, reanimated, safe-area or Lucide imports. |
| Server bundle | Requires only host modules and Node built-ins; evaluated in a child process (Paseo's evaluator inside the 120 s compile step with the app or a checkout, a replica with a 30 s limit on the approximation); registered RPCs listed; the returned cleanup is called and handles it leaves open (servers, timers) are warnings. A `process.exit` or a hang fails. |
| Client eval | Factory runs in a child process against stub host modules, with the app's registration rules: ids, contexts, callbacks, duplicates, icons, cleanup. Any violation fails, because the app then drops the whole client. |
| Client eval | Factory runs in a child process against stub host modules, with the registration rules of the checked Paseo version (the app's or checkout's; without either, the oldest release `requirements.paseo` admits): ids, contexts, labels, callbacks, duplicates, icons, file panel selectors, cleanup. A method that version lacks is undefined, as in the app. Any violation fails, because the app then drops the whole client. When the range admits an older release whose rules reject the client, that is a warning. |
| Hermes | No class syntax; `hermesc` parse and a smoke run in the Hermes VM when the binaries are found. |
| Icons | Every contribution icon exists in the app's Lucide set (read from the app bundle). |
| Size, deps, boundaries | Bundle sizes, runtime deps in `dependencies`, client/server import boundaries, `@types/node` range. |
Expand Down
2 changes: 2 additions & 0 deletions THIRD_PARTY_NOTICES
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ under dist/ (for example dist/check/client-rules.js), and the notices are kept.

src/check/client-rules.ts
packages/app/src/plugins/evaluate.ts
packages/app/src/plugins/icons.ts
packages/plugin/src/icons.ts
src/check/manifest.ts
packages/server/src/server/plugins/manifest.ts
packages/protocol/src/plugin-config.ts
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/routes/(docs)/docs/check/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ It exits 1 on any `FAIL`; warnings and skips do not fail. All flags are on [Comm
| `client-requires` | The client bundle requires only modules the app provides: the SDK, `react`, `react-native`, `react/jsx-runtime`, `zod`, `@tanstack/react-query`. Gesture handler, reanimated, safe-area, SVG, Lucide and DOM packages are not available to plugins. |
| `server-requires` | The server bundle requires only host modules and Node built-ins; any other bare require would resolve from Paseo's install, not your plugin. |
| `server-eval` | The server contribution runs in a child process and the RPCs it registered are listed: with the app or a checkout, Paseo's own evaluator runs it inside the compile step (120 s limit); on the approximation, a replica runs it with a 30 s limit. The returned cleanup is called; handles it leaves open (servers, timers) are warnings. A `process.exit`, a hang or a missing cleanup function fails. |
| `client-eval` | The client contribution runs in a child process against stub host modules and the app's registration rules: ids, contexts, titles, callbacks, components, duplicates, icons, the cleanup function, and methods the app's client context does not have. Any violation fails, because the app then drops the whole client. |
| `client-eval` | The client contribution runs in a child process against stub host modules and the registration rules of the checked Paseo version: the installed app's or `PASEO_SOURCE`'s, and on the approximation the oldest release `requirements.paseo` admits. The rules cover ids, contexts, titles, callbacks, components, duplicates, icons, file panel selectors, the cleanup function, and methods the app's client context does not have. A method added after that version (`addFilePanel` and `addAgentPanel` in 0.13.0) is undefined, as in the app. Any violation fails, because the app then drops the whole client. When the host accepts the client but the oldest release the range admits would reject it, that is a warning. |
| `hermes-class` | No `class` syntax in the client bundle: it crashes plugin loading on Hermes, the phone JavaScript engine. |
| `hermes-parse` | `hermesc` compiles the client bundle. Skipped without `hermesc`. |
| `hermes-vm` | The Hermes VM evaluates the bundle and runs the contribution. Skipped without the VM. |
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/routes/(docs)/docs/compatibility/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Windows is not supported.
| `@getpaseo/client` and `ws` inside `app.asar` | `agentTimeline` | the call fails naming the modules it looked for. |
| `paseo daemon run --home`, `PASEO_HOME`, `PASEO_LISTEN` and the `config.json` keys | `ppd daemon up` | a start failure prints the daemon output and how it was started. |
| Accessible names in the web UI ("New workspace", "Open menu", "Workspace actions", "Search commands") | `ppd web`, `PaseoWeb` | a timeout names the label it waited for. |
| Rules vendored from Paseo (client registration, manifest schema, build options) | every `ppd check` (`manifest`, `client-eval`), the client check in `ppd install` and `ppd dev`, and the approximation's compile | drift shows up in the weekly CI job against Paseo main. |
| Rules vendored from Paseo (client registration for 0.12 and 0.13 or later, the release that added each newer client method, manifest schema, build options) | every `ppd check` (`manifest`, `client-eval`), the client check in `ppd install` and `ppd dev`, and the approximation's compile | drift shows up in the weekly CI job against Paseo main. |

`ppd daemon up` prints a note when the installed Paseo is not {meta.verifiedPaseo}, and `ppd doctor` shows the same text
as a warning on its `paseo CLI` line:
Expand Down
18 changes: 18 additions & 0 deletions docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,11 @@ prints the same lines and keeps watching. Each line under `client:` is a registr

- `Unknown Lucide icon: X`: the app's Lucide build has no icon named X.
- `Command Center item X has no icon`, `Workspace panel X has invalid context`, `Screen X is not a component`.
- `File panel X has invalid selector`: `files` takes only `extensions` (without the dot) and `filenames`, plain
names with no `/`, `\`, `*` or `?`, at least one in all.
- `client.X is not part of the app's plugin client context (calling it throws)`.
- `Paseo 0.12.0 has no client.addFilePanel (added in 0.13.0), and the contribution threw: ...`: see
[below](#older-paseo).
- `Plugin contribution must return a cleanup function`.

Fix the line, save, and `ppd dev` re-checks on reload. `ppd check` reports the same rules as `client-eval`.
Expand Down Expand Up @@ -89,6 +93,20 @@ approximation; with the app or a checkout the server is evaluated inside the com
blocking loop at module load or in `contribute` ends here. `plugin code called process.exit(N)` means what it says: the host would
lose the whole plugin process. A timer or server left running after the cleanup is a warning, not a failure.

<h3 id="older-paseo">Paseo 0.12.0 would reject this client</h3>

```text
WARN client-eval Paseo 0.12.0, which requirements.paseo ">=0.12.0" admits, would reject this client and show none of its UI. Raise requirements.paseo or use only what that release accepts
Paseo 0.12.0 has no client.addFilePanel (added in 0.13.0), and the contribution threw: client.addFilePanel is not a function. Guard the call with typeof, or require a newer Paseo
contributions: addFilePanel (Paseo 0.14.0 rules)
```

Paseo 0.13.0 added file panels and agent panels (betas: file panels in beta.1, agent and context-free panels in beta.2), made `context` optional on workspace panels, and accepts translated
labels and `{ svg }` or component icons. An older app the range admits throws on these and drops the whole client;
apps below `requirements.paseo` skip the plugin. Declare `"paseo": ">=0.13.0"`, or guard each newer call with
`typeof client.addFilePanel === "function"`. Without a host, `ppd check` applies the oldest admitted release's rules
directly, so the same problem is a `FAIL`. `ppd install` and `ppd dev` print the warning as a `note:` line.

<h2 id="daemon">Dev daemon</h2>

<h3 id="no-daemon">no running dev daemon</h3>
Expand Down
2 changes: 1 addition & 1 deletion skills/paseo-plugin-dev/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ These protect the user's real Paseo. Each has a `ppd` guard; keep them when work

Run in order. Each step ends on its stated observable.

1. **Contract check**: `ppd check <plugin>`. Done when there are 0 FAIL. It compiles and evaluates with the installed Paseo app's own compiler and checks icons against the app's Lucide set. Without the app (Linux, CI) it falls back to an esbuild replica and prints `APPROXIMATION`: say so in your report rather than claiming the real host accepted the plugin. `PASEO_SOURCE=<paseo checkout>` tests against unreleased Paseo instead.
1. **Contract check**: `ppd check <plugin>`. Done when there are 0 FAIL. It compiles and evaluates with the installed Paseo app's own compiler and checks icons against the app's Lucide set. Without the app (Linux, CI) it falls back to an esbuild replica and prints `APPROXIMATION`: say so in your report rather than claiming the real host accepted the plugin. `PASEO_SOURCE=<paseo checkout>` tests against unreleased Paseo instead. A `client-eval` WARN naming `requirements.paseo` means the oldest app the range admits would reject the client (file and agent panels need 0.13.0): raise the range or guard the call.
2. **Dev daemon**: `ppd daemon up --workspace <dir with sample files> --caffeinate`. Done when it prints a URL. It runs detached with a pidfile, so harness time limits do not kill it. Its home is under `$TMPDIR` (on macOS a `/var/folders/...` path, not `/tmp`).
3. **Install**: `ppd install <plugin>` (directory) and `ppd install <plugin> --git` (committed HEAD through the manifest `build`, like a registry install; installed as `<id>-git` next to the directory install). Done when each prints `running` and `client: passes the app's registration rules`, exit 0. `client-rejected` means the app would drop the whole client (an unknown icon, a bad id): fix it before looking at the UI.
4. **Real UI**: `ppd web --shot out/desktop.png --click "<your header button label>"` and `ppd web --viewport 390x844 --shot out/phone.png --command "<your Command Center item>"`. Done when you have looked at both screenshots and `ppd web` exits 0 with `console errors: none` and `plugin evaluation errors: none`. Console errors alone are not enough: the app reports a client that failed to evaluate only as a warning.
Expand Down
9 changes: 5 additions & 4 deletions skills/paseo-plugin-dev/references/host-contract.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# Paseo plugin host contract

What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests the rows marked (checked).
What Paseo 0.11 to 0.14 actually give a plugin at runtime. `ppd check` tests the rows marked (checked).

| Area | Contract | What to do |
| --- | --- | --- |
| Client modules (checked) | Only `react`, `react/jsx-runtime`, `react-native`, `@tanstack/react-query`, `zod`, `@getpaseo/plugin`, `@getpaseo/plugin/client`, `/client/ui`, `/client/react-native`. Any other runtime require throws `Module "<name>" is not available in plugin client code`. Other npm packages are fine only if esbuild bundles them fully. | Keep host modules in `devDependencies`. |
| Gestures (checked) | No `react-native-gesture-handler` or `react-native-reanimated`. | Build pinch and double tap from `onResponder*` / `PanResponder` and `Animated`. |
| Safe area (checked) | Plugin panels get no safe-area insets (getpaseo/paseo#5866, PR #5867). The Android nav bar can cover the last rows. | Pad the bottom yourself; runtime-detect a host `useSafeAreaInsets` export if one appears. |
| Horizontal scroll | A plugin horizontal `ScrollView` is not registered with the host, so a fast right swipe on a zoomed page opens the mobile sidebar. | Known limit; keep horizontal panning short or behind a mode. |
| Icons (checked) | Contribution `icon` fields are Lucide names, validated at registration: an unknown name throws, and the app then drops the whole plugin client (every contribution, not only that item) with just a console warning. `Icon` from `/client/react-native` renders nothing for an unknown name. No `lucide-react-native` import. | `ppd check` checks names against the installed app's Lucide set; `ppd install` and `ppd web` report a rejected client. |
| Client registration (checked) | Contribution ids match `/^[a-z][a-z0-9-]*$/` and are unique per kind; `context` and callbacks are validated; the factory must return a cleanup function. Any violation drops the whole client, like an unknown icon. | `ppd check` applies the app's rules. |
| Icons (checked) | Contribution `icon` fields are Lucide names before 0.13.0; from 0.13.0 also `{ svg }` (no scripts, styles, event handlers or external hrefs) or a component (not for attachment sources). They are validated at registration: an unknown name throws, and the app then drops the whole plugin client (every contribution, not only that item) with just a console warning. `Icon` from `/client/react-native` renders nothing for an unknown name. No `lucide-react-native` import. | `ppd check` checks names against the installed app's Lucide set; `ppd install` and `ppd web` report a rejected client. |
| Client registration (checked) | Contribution ids match `/^[a-z][a-z0-9-]*$/` and are unique per kind; `context` and callbacks are validated; file panel selectors list extensions without dots and plain filenames, no paths or wildcards; the factory must return a cleanup function. Any violation drops the whole client, like an unknown icon. | `ppd check` applies the rules of the checked app version. |
| Paseo 0.13 client contract (checked) | 0.13.0 added `client.addFilePanel` and `client.addAgentPanel`, made workspace panel `context` optional, and accepts translated labels and `{ svg }` or component icons. On an older app the new methods are undefined and the rest throws at registration, so the whole client is dropped. Apps below `requirements.paseo` skip the plugin. | Declare `"paseo": ">=0.13.0"`, or guard with `typeof client.addFilePanel === "function"`. `ppd check` warns when the oldest app the range admits would reject the client. |
| Cleanup (checked) | The server contribution must return a cleanup too; it runs when the plugin child shuts down (reload, disable, remove). A server, socket or interval it leaves open can keep the old child alive or its port busy for the next load. | Close everything you open; `ppd check` warns about handles left open after cleanup. |
| Hermes (checked) | iOS and Android evaluate the client bundle from source on Hermes. Class syntax fails to parse (getpaseo/paseo#5783), including classes inside bundled dependencies. Paseo lowers async/await for you. | Functions and closures instead of classes; check dependencies too. |
| Server bundle (checked) | Compiled to one CJS string and `eval`'d in a plugin subprocess. Bare requires other than host modules and Node built-ins resolve from Paseo's install, not the plugin. WASM must be inlined (a 12.6 MB bundle parsed in about 60 ms). No native addons, no file-path WASM, no assumption of system binaries. | Pure JS/WASM dependencies, bundled. |
Expand All @@ -18,6 +19,6 @@ What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests th
| RPC timeout | 30 s per RPC (`REQUEST_TIMEOUT_MS`). Handlers get no abort signal (hooks do get `context.signal`). After a timeout the handler keeps running and holding memory and concurrency. | Deadline every heavy job (`Promise.race`), cap input sizes, test worst-case fixtures with `assertWithinRpcBudget`. Synchronous WASM cannot be interrupted. |
| Crashes | A crashed plugin child is not respawned (getpaseo/paseo#6821). One out-of-memory parse takes the plugin down until `paseo plugin reload`. | Size and decompression caps before parsing; stream large formats. |
| Response size | Direct websocket messages cap at 100 MiB; clients behind the relay should budget well under 32 MiB. Large base64 images add up fast. | Page or chunk responses; budget bytes per response. |
| MIME and previews | The daemon labels many binaries `application/octet-stream`; the Files tree has no previewer hook for plugins (getpaseo/paseo#3109, #5930). | Detect formats by magic bytes; provide your own entry points (panel, Command Center item, slash command). |
| MIME and previews | Daemons before 0.13.0 label many binaries, PDFs included, `application/octet-stream`. From 0.13.0 a file panel (`client.addFilePanel`) renders the file tab for the extensions and filenames it claims; before that, plugins have no previewer hook (getpaseo/paseo#3109, #5930). | Detect formats by magic bytes; on 0.13.0 and later register a file panel, otherwise provide your own entry points (panel, Command Center item, slash command). |
| Media | No native video primitive (#4562). Host `playAudio` exists from 0.11.2. | Plan media features around what the host exposes. |
| Theme and layout | Color every `Text` from `theme.colors`; size layout from `layout.compact`. No HTML elements, no `className`. | Test both `ppd web` viewports. |
Loading
Loading