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
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
- Without a Paseo host and without `requirements.paseo`, `ppd check` now applies the Paseo 0.15.3 client contract instead of 0.12.0, including the 0.13.0 rules.
- Verify the daemon, compiler and web UI on Paseo 0.15.3. Add an isolated nested-file regression covering panel selection, changes, deletion, restoration, reload and reopening.
- Close the browser when initial app navigation fails.
- A panel title that several plugins offer fails with the matching labels in `openFile`, `chooseFilePanel` and `openWith`; pass the full label (`"Title \u2014 owner"`) to choose one. Panels with identical full labels fail as indistinguishable. Before, Playwright's strict-mode error surfaced.
- Add `FileOpenOptions.pickerTimeoutMs` and `ppd web --picker-timeout MS` to change the 10 s panel picker wait.
- `openFile` waits for the Files controls after `reload` instead of failing when the restored sidebar mounts late.

## 0.2.0 (2026-10-30)

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,9 @@ try {
}
```

Paths are workspace-relative, use `/`, and must not contain `.` or `..` segments. Tab helpers use the full relative path, even when the visible tab shows only its basename. `openFile` focuses an existing tab, otherwise opens through Files, scrolling long trees to find the row. Pass `panel` when a picker is expected; the helper waits up to 10 s for it even when the tab appears first, then fails with a clear error. Panel names accept a unique title or the full host label; an ambiguous title fails instead of choosing a plugin. Omit `panel` when reopening with a saved association; use `openWith` to change it. These helpers target desktop file tabs; compact file sheets can be exercised through `ui.page`.
Paths are workspace-relative, use `/`, and must not contain `.` or `..` segments. Tab helpers use the full relative path, even when the visible tab shows only its basename. `openFile` focuses an existing tab, otherwise opens through Files, scrolling long trees to find the row. Pass `panel` when a picker is expected; the helper waits up to 10 s for it (`pickerTimeoutMs` changes this) even when the tab appears first, then fails with a clear error. Panel names accept a unique title or the full host label (`"Viewer \u2014 paseo-doc-viewer"`); a title several plugins offer fails with the matching labels instead of choosing a plugin. Omit `panel` when reopening with a saved association; use `openWith` to change it. These helpers target desktop file tabs; compact file sheets can be exercised through `ui.page`.

The CLI accepts the same opening step: `ppd web --workspace <id> --open-file report.pdf --shot report.png`. Add `--with Viewer` for files with a panel picker. `PPD_E2E=1 npx vitest run test/file-panels-e2e.test.ts` exercises duplicate folder and file names, a file below 400 others, a nested CSV, a panel requested without a picker, remembered panel choice, rewrite, deletion, restoration, app reload and tab closure on a fresh isolated daemon; it removes the daemon and temporary workspace on failure too.
The CLI accepts the same opening step: `ppd web --workspace <id> --open-file report.pdf --shot report.png`. Add `--with Viewer` for files with a panel picker, and `--picker-timeout MS` to wait longer than 10 s for it. `PPD_E2E=1 npx vitest run test/file-panels-e2e.test.ts` exercises duplicate folder and file names, a file below 400 others, a nested CSV, a panel requested without a picker, a panel title two plugins share, remembered panel choice, rewrite, deletion, restoration, app reload and tab closure on a fresh isolated daemon; it removes the daemon and temporary workspace on failure too.

## Fake agent

Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/lib/commands.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
"topic": "web",
"usage": "ppd web",
"summary": "open the web UI in Chrome, screenshot, click through",
"help": "ppd web [--shot FILE] [--viewport WxH] [--command TEXT] [--click LABEL]... [options]\n\nOpens the dev daemon's web UI in Chrome (Playwright), opens the only workspace (or --workspace), runs the\nsteps in order and prints console errors.\n\n --shot FILE save a screenshot\n --viewport WxH e.g. 390x844; widths under 768 get the compact (phone) layout with touch\n --command TEXT select a Command Center item by its exact title\n --open-file PATH open a workspace-relative file through Paseo's Files tree\n --with PANEL answer the panel picker with a unique panel title or full label (requires --open-file);\n fails when the file opens without a picker (saved association or single panel)\n --click LABEL click an element by its accessible name (repeatable)\n --workspace ID workspace id, name or path\n --path /route open an app route instead of a workspace\n --wait MS settle time before the screenshot (default 1500)\n --full-page full-page screenshot\n --headed show the browser\n --name N target dev daemon"
"help": "ppd web [--shot FILE] [--viewport WxH] [--command TEXT] [--click LABEL]... [options]\n\nOpens the dev daemon's web UI in Chrome (Playwright), opens the only workspace (or --workspace), runs the\nsteps in order and prints console errors.\n\n --shot FILE save a screenshot\n --viewport WxH e.g. 390x844; widths under 768 get the compact (phone) layout with touch\n --command TEXT select a Command Center item by its exact title\n --open-file PATH open a workspace-relative file through Paseo's Files tree\n --with PANEL answer the panel picker with a unique panel title or full label (requires --open-file);\n fails when the file opens without a picker (saved association or single panel)\n --picker-timeout MS how long --with waits for the panel picker (default 10000)\n --click LABEL click an element by its accessible name (repeatable)\n --workspace ID workspace id, name or path\n --path /route open an app route instead of a workspace\n --wait MS settle time before the screenshot (default 1500)\n --full-page full-page screenshot\n --headed show the browser\n --name N target dev daemon"
},
{
"topic": "android",
Expand Down
1 change: 1 addition & 0 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ steps in order and prints console errors.
--open-file PATH open a workspace-relative file through Paseo's Files tree
--with PANEL answer the panel picker with a unique panel title or full label (requires --open-file);
fails when the file opens without a picker (saved association or single panel)
--picker-timeout MS how long --with waits for the panel picker (default 10000)
--click LABEL click an element by its accessible name (repeatable)
--workspace ID workspace id, name or path
--path /route open an app route instead of a workspace
Expand Down
44 changes: 32 additions & 12 deletions src/web.ts
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ export interface FileOpenOptions {
panel?: string;
/** Remember the panel choice when the host shows its picker. */
remember?: boolean;
/** How long to wait for the panel picker when `panel` is set (default 10 000 ms). */
pickerTimeoutMs?: number;
}

const CHROME_PATHS: Record<string, string[]> = {
Expand Down Expand Up @@ -88,6 +90,19 @@ function panelName(panel: string): RegExp {
return new RegExp(`^${escaped}(?: \\u2014 .+)?$`);
}

/** The one offered label that `panel` names, by unique title or full "Title \u2014 owner" label. */
export function pickPanel(panel: string, offered: readonly string[], where = "the panel picker"): string {
const matches = offered.filter((label) => panelName(panel).test(label));
if (matches.length === 0) throw new Error(`${where} offers no panel named "${panel}"; it offers: ${offered.join(", ")}`);
if (new Set(matches).size === 1 && matches.length > 1) {
throw new Error(`${where} offers ${matches.length} panels labelled "${matches[0]}", which ppd cannot tell apart; give the panels distinct titles`);
}
if (matches.length > 1) {
throw new Error(`${where} offers ${matches.length} panels titled "${panel}": ${matches.join(", ")}. Pass the full label, such as "${matches[0]}"`);
}
return matches[0]!;
}

export class PaseoWeb {
/** Console errors, page errors and plugin evaluation failures. */
readonly errors: string[] = [];
Expand Down Expand Up @@ -152,9 +167,10 @@ export class PaseoWeb {
/** Open the host's Files tree in the current workspace. */
async openFiles(): Promise<void> {
const browse = this.page.getByRole("button", { name: "Browse workspace files", exact: true });
if (!(await browse.isVisible())) {
await this.page.getByRole("button", { name: "Open Explorer sidebar", exact: true }).click();
}
const sidebar = this.page.getByRole("button", { name: "Open Explorer sidebar", exact: true });
// After a reload the restored sidebar mounts after the app shell: wait for either control before choosing.
await waitForUi(browse.or(sidebar).first(), 'the Files button or an "Open Explorer sidebar" button', 30_000);
if (!(await browse.isVisible())) await sidebar.click();
await browse.click();
}

Expand Down Expand Up @@ -237,7 +253,7 @@ export class PaseoWeb {
await (await this.fileRow(path)).dblclick();
// The tab can mount before the file metadata and picker arrive. Wait for the actual radio,
// rather than treating an early tab as evidence that a saved association bypassed the picker.
if (options.panel) await this.chooseFilePanel(options.panel, options.remember);
if (options.panel) await this.chooseFilePanel(options.panel, options.remember, options.pickerTimeoutMs);
const tab = this.fileTab(path);
await waitForUi(tab, `file tab ${path}`, 30_000);
return tab;
Expand All @@ -258,12 +274,8 @@ export class PaseoWeb {
{ cause: error },
);
}
const radio = dialog.getByRole("radio", { name: panelName(panel) });
if ((await radio.count()) === 0) {
const offered = await dialog.getByRole("radio").evaluateAll((radios) => radios.map((radio) => radio.getAttribute("aria-label") ?? radio.textContent?.trim() ?? ""));
throw new Error(`the panel picker offers no panel named "${panel}"; it offers: ${offered.join(", ")}`);
}
await radio.click();
const offered = await dialog.getByRole("radio").evaluateAll((radios) => radios.map((radio) => radio.getAttribute("aria-label") ?? radio.textContent?.trim() ?? ""));
await dialog.getByRole("radio", { name: pickPanel(panel, offered), exact: true }).click();
await dialog.getByRole("checkbox", { name: "Don't ask me again", exact: true }).setChecked(remember);
await dialog.getByRole("button", { name: "Use", exact: true }).click();
}
Expand All @@ -272,7 +284,11 @@ export class PaseoWeb {
async openWith(name: string, panel: string): Promise<void> {
await this.fileTab(name).click({ button: "right" });
await this.page.getByRole("menuitem", { name: "Open with…", exact: true }).hover();
await this.page.getByRole("menuitem", { name: panelName(panel) }).click();
const panels = this.page.getByRole("menuitem", { name: / \u2014 / });
await waitForUi(panels.first(), 'the "Open with" panel list', 10_000);
// The tab menu's own items carry no " \u2014 owner" suffix; only the submenu's panels do.
const offered = await panels.evaluateAll((items) => items.map((item) => item.textContent?.trim() ?? ""));
await this.page.getByRole("menuitem", { name: pickPanel(panel, offered, 'the "Open with" menu'), exact: true }).click();
}

/** Keep a preview tab open when another file is opened. */
Expand Down Expand Up @@ -384,11 +400,15 @@ export async function webCommand(args: string[]): Promise<number> {
"full-page": { type: "boolean" },
"open-file": { type: "string" },
with: { type: "string" },
"picker-timeout": { type: "string" },
},
strict: true,
});
if (values.wait !== undefined && !/^\d+$/.test(values.wait)) throw new UsageError(`--wait must be milliseconds, got ${values.wait}`);
if (values.with && !values["open-file"]) throw new UsageError("--with requires --open-file");
const pickerTimeout = values["picker-timeout"];
if (pickerTimeout !== undefined && !/^\d+$/.test(pickerTimeout)) throw new UsageError(`--picker-timeout must be milliseconds, got ${pickerTimeout}`);
if (pickerTimeout !== undefined && !values.with) throw new UsageError("--picker-timeout requires --with");
const daemon = requireDaemon(values.name);
if (!daemon.webDist) throw new Error("this dev daemon has no web UI: restart it with `ppd daemon up --web-dist <dir>`");
const viewport = values.viewport ? parseViewport(values.viewport) : undefined;
Expand All @@ -410,7 +430,7 @@ export async function webCommand(args: string[]): Promise<number> {
}
}
if (values.command) await web.runCommand(values.command);
if (values["open-file"]) await web.openFile(values["open-file"], { panel: values.with });
if (values["open-file"]) await web.openFile(values["open-file"], { panel: values.with, pickerTimeoutMs: pickerTimeout === undefined ? undefined : Number(pickerTimeout) });
for (const label of values.click ?? []) await web.click(label);
await web.page.waitForTimeout(values.wait ? Number(values.wait) : 1500);
if (values.shot) console.log(`screenshot: ${await web.shot(values.shot, values["full-page"])}`);
Expand Down
2 changes: 2 additions & 0 deletions test/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,5 +52,7 @@ describe("ppd CLI guards", () => {
expect(unknown.status).toBe(1);
expect(unknown.stderr).toMatch(/Unknown option '--frob'[\s\S]*run `ppd check --help`/);
expect(ppd("check", "--max-client-kb", "lots").stderr).toMatch(/--max-client-kb must be a whole number of KiB/);
expect(ppd("web", "--open-file", "a.csv", "--with", "Viewer", "--picker-timeout", "soon").stderr).toMatch(/--picker-timeout must be milliseconds, got soon/);
expect(ppd("web", "--open-file", "a.csv", "--picker-timeout", "5000").stderr).toMatch(/--picker-timeout requires --with/);
});
});
19 changes: 19 additions & 0 deletions test/file-panels-e2e.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ describe.skipIf(!enabled)("native file-tab helpers (PPD_E2E=1)", () => {
// More files than the virtualized Files tree renders at once.
for (let index = 0; index < 400; index++) writeFileSync(join(workspace, `filler-${String(index).padStart(3, "0")}.txt`), "");
writeFileSync(join(workspace, "zz-last.csv"), "Last row,4\n");
// Its own extension, so the csv association remembered below does not skip its picker.
writeFileSync(join(workspace, "twin.tsv"), "Twin\t5\n");
const daemon = await daemonUp({ name, workspace, log: () => {} });
const cli = (args: string[]) => {
const result = runPaseo(daemon.paseoBin, daemon.home, [...args, "--json"]);
Expand Down Expand Up @@ -109,4 +111,21 @@ describe.skipIf(!enabled)("native file-tab helpers (PPD_E2E=1)", () => {
expect(ui.pluginErrors).toEqual([]);
expect(ui.errors).toEqual([]);
}, 120_000);

it("refuses a panel title two plugins share and accepts the full label", async () => {
const ui = web!;
expect((await installPlugin(join(FIXTURES, "file-panel-twin"), { name, log: () => {} })).status).toBe("running");
await ui.reload();
await expect(ui.openFile("twin.tsv", { panel: "Fixture", pickerTimeoutMs: 20_000 }))
.rejects.toThrow('the panel picker offers 2 panels titled "Fixture": ');
await ui.chooseFilePanel("Fixture \u2014 file-panel-twin");
await expect.poll(() => ui.page.getByText("Twin panel", { exact: true }).isVisible()).toBe(true);
await expect(ui.openWith("twin.tsv", "Fixture")).rejects.toThrow('the "Open with" menu offers 2 panels titled "Fixture": ');
await ui.page.keyboard.press("Escape");
await ui.page.keyboard.press("Escape");
await ui.openWith("twin.tsv", "Fixture \u2014 file-panel-fixture");
await expect.poll(() => ui.page.getByText("Twin\t5", { exact: true }).isVisible()).toBe(true);
await ui.closeFile("twin.tsv");
expect(ui.pluginErrors).toEqual([]);
}, 180_000);
});
12 changes: 12 additions & 0 deletions test/fixtures/file-panel-twin/index.client.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import type { PluginClientContext, PluginFilePanelProps } from "@getpaseo/plugin/client";
import { Text } from "react-native";

// Same title as file-panel-fixture, so the picker offers two "Fixture" panels.
function Twin({ theme }: PluginFilePanelProps) {
return <Text style={{ color: theme.colors.foreground }}>Twin panel</Text>;
}

export default function contribute(client: PluginClientContext) {
const remove = client.addFilePanel({ id: "twin", title: "Fixture", icon: "FileText", files: { extensions: ["csv", "tsv"] }, Component: Twin });
return () => remove();
}
4 changes: 4 additions & 0 deletions test/fixtures/file-panel-twin/paseo-plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"id": "file-panel-twin",
"requirements": { "paseo": ">=0.13.0" }
}
2 changes: 1 addition & 1 deletion test/fixtures/file-panel/index.client.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,6 @@ function Reader({ file, theme }: PluginFilePanelProps) {
}

export default function contribute(client: PluginClientContext) {
const remove = client.addFilePanel({ id: "reader", title: "Fixture", icon: "FileText", files: { extensions: ["csv"] }, Component: Reader });
const remove = client.addFilePanel({ id: "reader", title: "Fixture", icon: "FileText", files: { extensions: ["csv", "tsv"] }, Component: Reader });
return () => remove();
}
19 changes: 18 additions & 1 deletion test/web.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { noWorkspaceNote, pluginEvaluationFailure, isCompactViewport, parseViewport, pickWorkspace } from "../src/web.ts";
import { noWorkspaceNote, pluginEvaluationFailure, isCompactViewport, parseViewport, pickPanel, pickWorkspace } from "../src/web.ts";

describe("web helpers", () => {
it("reads the app's plugin evaluation warning (packages/app/src/plugins/registry.ts)", () => {
Expand Down Expand Up @@ -29,4 +29,21 @@ describe("web helpers", () => {
expect(noWorkspaceNote(entries)).toBe("2 workspaces on the dev daemon, none opened: pass --workspace <id, name or dir> (ids: wks_1, wks_2)");
expect(noWorkspaceNote([])).toMatch(/^no workspace on the dev daemon/);
});

it("picks a panel by unique title or full label, and lists the options when a title is ambiguous", () => {
const offered = ["Source", "Viewer \u2014 doc-viewer", "Viewer \u2014 csv-viewer", "Chart \u2014 csv-viewer"];
expect(pickPanel("Source", offered)).toBe("Source");
expect(pickPanel("Chart", offered)).toBe("Chart \u2014 csv-viewer");
expect(pickPanel("Viewer \u2014 csv-viewer", offered)).toBe("Viewer \u2014 csv-viewer");
expect(() => pickPanel("Viewer", offered)).toThrow(
'the panel picker offers 2 panels titled "Viewer": Viewer \u2014 doc-viewer, Viewer \u2014 csv-viewer. Pass the full label, such as "Viewer \u2014 doc-viewer"',
);
expect(() => pickPanel("View", offered)).toThrow(/offers no panel named "View"; it offers: Source, Viewer/);
expect(() => pickPanel("Viewer \u2014 csv", offered)).toThrow(/no panel named/);
expect(() => pickPanel("Viewer", offered, 'the "Open with" menu')).toThrow(/^the "Open with" menu offers 2 panels titled "Viewer"/);
const twins = ["Viewer \u2014 doc-viewer", "Viewer \u2014 doc-viewer", "Source \u2014 Paseo"];
for (const name of ["Viewer", "Viewer \u2014 doc-viewer"]) {
expect(() => pickPanel(name, twins)).toThrow('the panel picker offers 2 panels labelled "Viewer \u2014 doc-viewer", which ppd cannot tell apart; give the panels distinct titles');
}
});
});
Loading