diff --git a/CHANGELOG.md b/CHANGELOG.md index fdb914a..f1a2bc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/README.md b/README.md index b4ae094..758d7d3 100644 --- a/README.md +++ b/README.md @@ -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 --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 --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 diff --git a/docs-site/src/lib/commands.json b/docs-site/src/lib/commands.json index afc521e..bb17794 100644 --- a/docs-site/src/lib/commands.json +++ b/docs-site/src/lib/commands.json @@ -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", diff --git a/src/cli.ts b/src/cli.ts index a5e921d..4e211a8 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -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 diff --git a/src/web.ts b/src/web.ts index 942e930..4f5d611 100644 --- a/src/web.ts +++ b/src/web.ts @@ -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 = { @@ -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[] = []; @@ -152,9 +167,10 @@ export class PaseoWeb { /** Open the host's Files tree in the current workspace. */ async openFiles(): Promise { 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(); } @@ -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; @@ -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(); } @@ -272,7 +284,11 @@ export class PaseoWeb { async openWith(name: string, panel: string): Promise { 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. */ @@ -384,11 +400,15 @@ export async function webCommand(args: string[]): Promise { "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 `"); const viewport = values.viewport ? parseViewport(values.viewport) : undefined; @@ -410,7 +430,7 @@ export async function webCommand(args: string[]): Promise { } } 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"])}`); diff --git a/test/cli.test.ts b/test/cli.test.ts index 3932a0e..d88e2f3 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -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/); }); }); diff --git a/test/file-panels-e2e.test.ts b/test/file-panels-e2e.test.ts index 6bf57c1..180e5f0 100644 --- a/test/file-panels-e2e.test.ts +++ b/test/file-panels-e2e.test.ts @@ -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"]); @@ -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); }); diff --git a/test/fixtures/file-panel-twin/index.client.tsx b/test/fixtures/file-panel-twin/index.client.tsx new file mode 100644 index 0000000..fe46c87 --- /dev/null +++ b/test/fixtures/file-panel-twin/index.client.tsx @@ -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 Twin panel; +} + +export default function contribute(client: PluginClientContext) { + const remove = client.addFilePanel({ id: "twin", title: "Fixture", icon: "FileText", files: { extensions: ["csv", "tsv"] }, Component: Twin }); + return () => remove(); +} diff --git a/test/fixtures/file-panel-twin/paseo-plugin.json b/test/fixtures/file-panel-twin/paseo-plugin.json new file mode 100644 index 0000000..68afc86 --- /dev/null +++ b/test/fixtures/file-panel-twin/paseo-plugin.json @@ -0,0 +1,4 @@ +{ + "id": "file-panel-twin", + "requirements": { "paseo": ">=0.13.0" } +} diff --git a/test/fixtures/file-panel/index.client.tsx b/test/fixtures/file-panel/index.client.tsx index a81fb58..6250beb 100644 --- a/test/fixtures/file-panel/index.client.tsx +++ b/test/fixtures/file-panel/index.client.tsx @@ -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(); } diff --git a/test/web.test.ts b/test/web.test.ts index 72fbd0b..ecd0c86 100644 --- a/test/web.test.ts +++ b/test/web.test.ts @@ -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)", () => { @@ -29,4 +29,21 @@ describe("web helpers", () => { expect(noWorkspaceNote(entries)).toBe("2 workspaces on the dev daemon, none opened: pass --workspace (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'); + } + }); });