[website] Add URL query support for the site file browser

[fellyph]

This pull request is related to issue #3612, to create a new query API to support plugin and theme debugging. This PR introduces a new query API filebrowser to open the playground with the filebrowser active, pointing to a specific file and line.

Summary

• Add a file-browser query state layer to keep the selected file in sync with the URL
• Wire the site manager, info panel, and file editor to consume the new query-based routing
• Update docs and Playwright coverage for the query API flow

Testing

• Pull the branch file-browser-query-api
• Install the dependencies
• Run the website locally
• Test the following URLS:

File Browser tab only
http://127.0.0.1:5400/website-server/?filebrowser

Open wp-config.php
http://127.0.0.1:5400/website-server/?filebrowser=wp-config.php

Open wp-config.php at line 1
http://127.0.0.1:5400/website-server/?filebrowser=wp-config.php:1

Open wp-content/index.php
http://127.0.0.1:5400/website-server/?filebrowser=wp-content/index.php

Open wp-content/plugins/index.php at line 1
http://127.0.0.1:5400/website-server/?filebrowser=wp-content/plugins/index.php:1

Blueprint-created plugin file
http://127.0.0.1:5400/website-server/?filebrowser=wp-content%2Fplugins%2Ffilebrowser-query-manual-test%2Findex.php#%7B%22steps%22%3A%5B%7B%22step%22%3A%22mkdir%22%2C%22path%22%3A%22%2Fwordpress%2Fwp-content%2Fplugins%2Ffilebrowser-query-manual-test%22%7D%2C%7B%22step%22%3A%22writeFile%22%2C%22path%22%3A%22%2Fwordpress%2Fwp-content%2Fplugins%2Ffilebrowser-query-manual-test%2Findex.php%22%2C%22data%22%3A%22%3C%3Fphp%5Cn%2F**%5Cn%20*%20Manual%20filebrowser%20query%20API%20test%20fixture.%5Cn%20*%2F%5Cnecho%20%5C%22line%20five%20target%5C%22%3B%5Cnecho%20%5C%22line%20six%20target%5C%22%3B%5Cn%22%7D%5D%7D

Same Blueprint file at line 5
http://127.0.0.1:5400/website-server/?filebrowser=wp-content%2Fplugins%2Ffilebrowser-query-manual-test%2Findex.php%3A5#%7B%22steps%22%3A%5B%7B%22step%22%3A%22mkdir%22%2C%22path%22%3A%22%2Fwordpress%2Fwp-content%2Fplugins%2Ffilebrowser-query-manual-test%22%7D%2C%7B%22step%22%3A%22writeFile%22%2C%22path%22%3A%22%2Fwordpress%2Fwp-content%2Fplugins%2Ffilebrowser-query-manual-test%2Findex.php%22%2C%22data%22%3A%22%3C%3Fphp%5Cn%2F**%5Cn%20*%20Manual%20filebrowser%20query%20API%20test%20fixture.%5Cn%20*%2F%5Cnecho%20%5C%22line%20five%20target%5C%22%3B%5Cnecho%20%5C%22line%20six%20target%5C%22%3B%5Cn%22%7D%5D%7D

Encoded path with spaces, should show missing-file notice
http://127.0.0.1:5400/website-server/?filebrowser=wp-content%2Fplugins%2Fplugin%20with%20spaces%2Findex.php

Missing file notice
http://127.0.0.1:5400/website-server/?filebrowser=wp-content/plugins/filebrowser-query-manual-test/missing.php

Invalid traversal notice
http://127.0.0.1:5400/website-server/?filebrowser=..%2Fwp-config.php

Example:

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for driving the Site Manager’s File Browser selection via a filebrowser URL query parameter (optionally including a :<line> suffix), and wires the UI/editor to honor that state.

Changes:

• Introduces filebrowser query parsing/validation utilities and preserves the param across routing.
• Updates Site Manager/File Browser + editor components to auto-open a target file and optionally place the cursor on a requested line (with notices for errors).
• Expands docs and automated coverage (unit + Playwright) for the query API flow.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/playground/website/src/lib/state/url/router.ts	Adds filebrowser to recognized query params.
packages/playground/website/src/lib/state/url/router.spec.ts	Adds unit tests for filebrowser query parsing/routing.
packages/playground/website/src/lib/state/url/filebrowser-query.ts	New utilities for parsing/validating filebrowser query + resolving under document root.
packages/playground/website/src/lib/state/redux/slice-ui.ts	Opens Site Manager when filebrowser query is requested.
packages/playground/website/src/components/site-manager/site-info-panel/index.tsx	Forces initial tab to “files” and passes parsed filebrowser query into the file browser.
packages/playground/website/src/components/site-manager/site-file-browser/index.tsx	Resolves initial file/line/notice from query and passes them to the editor.
packages/playground/website/playwright/e2e/query-api.spec.ts	Adds E2E coverage for opening file browser, opening a file, and selecting a line.
packages/playground/components/src/PlaygroundFileEditor/playground-file-editor.tsx	Adds initialLine / initialNotice support and notice rendering; applies initial cursor position.
packages/playground/components/src/PlaygroundFileEditor/code-editor.tsx	Adds cursorPosition prop and scroll-to-cursor helper.
packages/docs/site/docs/developers/06-apis/query-api/01-index.md	Documents the new filebrowser query parameter and examples.
.codex/migrate-to-codex-report.txt	Adds Codex migration report artifact (not directly related to filebrowser query).
.codex/config.toml	Adds MCP server and agent configuration (not directly related to filebrowser query).
.codex/agents/ci-monitor-subagent.toml	Adds Codex agent definition (not directly related to filebrowser query).
.agents/skills/nx-workspace/references/AFFECTED.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-workspace/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).
.agents/skills/nx-run-tasks/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).
.agents/skills/nx-plugins/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/VITE.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/TURBOREPO.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/NEXT.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/JEST.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/GRADLE.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/references/ESLINT.md	Adds Nx skill reference docs (not directly related to filebrowser query).
.agents/skills/nx-import/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).
.agents/skills/nx-generate/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).
.agents/skills/monitor-ci/scripts/ci-state-update.mjs	Adds CI monitoring scripts (not directly related to filebrowser query).
.agents/skills/monitor-ci/scripts/ci-poll-decide.mjs	Adds CI monitoring scripts (not directly related to filebrowser query).
.agents/skills/monitor-ci/references/fix-flows.md	Adds CI monitoring docs (not directly related to filebrowser query).
.agents/skills/monitor-ci/SKILL.md	Adds CI monitoring skill docs (not directly related to filebrowser query).
.agents/skills/link-workspace-packages/SKILL.md	Adds Nx skill docs (not directly related to filebrowser query).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adamziel]

This seems to amount to normalizedPath.split('/'), could we simplify it?

[adamziel]

let's document this with a docblock

[adamziel]

I haven't tested it, but you've mentioned you did. The code passes the smell test. I left a few small nitpicks, once they're addressed this is good to go.