Skip to content
Closed
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
## 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 app's file panel rules (`client.addFilePanel`, Paseo 0.13.0, getpaseo/paseo#7411): id, title, icon, `files` selector and a function `Component`. Before, every plugin that called it failed `client-eval`.
- `client-eval` warns when `requirements.paseo` admits a Paseo release that lacks a client method the plugin calls without a guard (`addFilePanel` before 0.13.0): the call throws there and the app drops the whole client. `ppd install` and `ppd dev` print the same warning as a note.

## 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 app's registration rules: ids, contexts, callbacks, duplicates, icons, file panel selectors, cleanup. Any violation fails, because the app then drops the whole client. When `requirements.paseo` admits a release without a method the client calls (`addFilePanel` needs 0.13.0), the factory runs again without it, and a throw 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
9 changes: 6 additions & 3 deletions THIRD_PARTY_NOTICES
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ License, Version 2.0. Those portions remain under the Apache License, Version
Paseo
https://github.com/getpaseo/paseo
Copyright (c) 2025-present Mohamed Boudra
Source revision: 9bd58f66b2dfc195898bf1178e84f02933c0d41e
Paseo does not ship a NOTICE file at this revision.
Source revision: 9bd58f66b2dfc195898bf1178e84f02933c0d41e, and
e464fd3bd308e792cd2cf484bd543057b50cb867 (getpaseo/paseo#7411) where marked
below. Paseo does not ship a NOTICE file at either revision.

Files with adapted portions, and the Paseo files they come from. Every file
listed here starts with a notice naming its sources and describing how it was
Expand All @@ -20,6 +21,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/evaluate.ts at e464fd3 (addFilePanel)
packages/app/src/plugins/icons.ts at e464fd3 (parsePluginIcon)
src/check/manifest.ts
packages/server/src/server/plugins/manifest.ts
packages/protocol/src/plugin-config.ts
Expand All @@ -41,7 +44,7 @@ under dist/ (for example dist/check/client-rules.js), and the notices are kept.
plugin-examples/provider-direct/server/provider.ts

The Paseo license, reproduced verbatim from the LICENSE file at the source
revision above:
revisions above (it is the same at both):

--------------------------------------------------------------------------------

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 app's registration rules: ids, contexts, titles, callbacks, components, duplicates, icons, file panel selectors, the cleanup function, and methods the app's client context does not have. Any violation fails, because the app then drops the whole client. When `requirements.paseo` admits a release that lacks a method the contribution calls (`addFilePanel` before 0.13.0), it runs again without that method; if it throws, that is a warning: declare the newer range or guard the call. |
| `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, 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
15 changes: 15 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,6 +32,8 @@ 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)`.
- `Plugin contribution must return a cleanup function`.

Expand Down Expand Up @@ -89,6 +91,19 @@ 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">on Paseo before 0.13.0, client.addFilePanel is undefined</h3>

```text
WARN client-eval on Paseo before 0.13.0, which requirements.paseo ">=0.11.2" admits, client.addFilePanel is undefined and the contribution throws, so those apps show none of this client. Declare ">=0.13.0" or guard with typeof client.addFilePanel === "function"
error on those apps: client.addFilePanel is not a function
contributions: addFilePanel
```

File panels arrived in Paseo 0.13.0. On an older app the call throws and the app drops the whole client, while apps
below `requirements.paseo` skip the plugin. Declare `"paseo": ">=0.13.0"`, or register the panel only when
`typeof client.addFilePanel === "function"` to keep older apps. `ppd install` and `ppd dev` print the same text 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 an app the range admits lacks a client method you call (file 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
5 changes: 3 additions & 2 deletions skills/paseo-plugin-dev/references/host-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests th
| 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. |
| 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 app's rules. |
| Newer client methods (checked) | `client.addFilePanel` exists from Paseo 0.13.0, like the `Loading` and `DocumentFrame` components of `/client/ui`. On an older app the method is undefined, so an unguarded call drops the whole client. Apps below `requirements.paseo` skip the plugin. | Declare `"paseo": ">=0.13.0"`, or guard with `typeof client.addFilePanel === "function"`. `ppd check` warns about an unguarded call the range lets an older app reach; it cannot see `Loading` or `DocumentFrame` used on one. |
| 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. |
4 changes: 3 additions & 1 deletion src/check/bundle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,8 @@ export interface ClientEvaluationOptions {
settleMs?: number;
/** The app's Lucide names. When given, unknown contribution icons are contract errors, like in the app. */
icons?: ReadonlySet<string> | null;
/** Client methods left undefined, like on an app that predates them (CLIENT_METHOD_SINCE). */
absentMethods?: readonly string[];
}

/** Icon names in a contribution: `icon` fields up to two levels deep (header buttons nest them). */
Expand Down Expand Up @@ -205,7 +207,7 @@ export async function evaluateClientBundle(bundle: string, pluginDir: string, op
{},
{
get: (_, key) => {
if (typeof key !== "string") return undefined;
if (typeof key !== "string" || options.absentMethods?.includes(key)) return undefined;
if (/^add[A-Z]/.test(key)) {
return (...args: unknown[]) => {
rules.register(key, args);
Expand Down
Loading
Loading