[thekevinbot]

Fixes #1489

The --frontend page now opens on a useful start screen: the query root, a path-table guide with an editable example, the declared tables with their columns, and config-load diagnostics with restart guidance. Choosing a table loads a quoted, bounded preview query; nothing runs until Run.

Choices

• All of it lives in /frontend.js (loadState, renderState, previewQuery); the inline state script in frontend.html is gone. No new route, no server change: it reads the existing GET /frontend/state once on load and never opens /events.
• Preview query: SELECT * FROM "<name>" LIMIT 100, the name always double-quoted with " doubled. Choosing a table only fills the SQL box and focuses it.
• The path-table guide (root, the seven stat columns with their meanings, lazy content, './' and './**/*.md' examples, and a button that restores the starter query) shows in every ready state, so path queries stay available beside declared tables.
• With no tables, including a functions-only config (the server already returns tables: []), the page shows "No declared tables." With tables, it adds one line on anchoring: declared-table globs anchor at their config file's directory, while path-table queries use the query root.
• Config failure (HTTP 503): an alert heading, the diagnostic in a <pre>, and "Fix the configuration, stop this server (Ctrl+C), and restart it with dirsql server --frontend -c <config>." Other failures (non-503 status, unreachable): "Could not load the server state: ...". The path guide is hidden in both.
• Refresh: one line, "Run again to refresh: path-tables read the filesystem on every query; declared tables reflect the server's index."
• All text goes through textContent/append, never innerHTML. The test fake document moved to tests/frontend/fake-document.mjs and is shared by both Node test files.

Red/green

• Red: 2cf727a, run 38470499672. cli_e2e::frontend_script_offers_table_browsing_and_path_onboarding failed with "loadState missing from the frontend script". On Windows, frontend_js also failed with SyntaxError: ... does not provide an export named 'loadState' from browse.test.mjs. Lint and unit tests passed.
• Green: 5922155.

Hand exercise (real server, headless Chrome via agent-browser)

Built with cargo build --release -p dirsql --features cli and ran dirsql server --frontend --port N against fixtures in /tmp/m1489:

• Configless (plain/): curl /frontend/state returned {"error":null,"root":"/tmp/m1489/plain","tables":[]}. The page showed the root, the seven columns, content, and "No declared tables." Run returned 1 row (a.txt). After echo new > c.txt, Run again returned 2 rows.
• Declared tables (cfg/, -c .dirsql.toml, with posts and an empty "order" table with columns "select" and "two words"): both were listed with their columns and types. Choosing order set the box to SELECT * FROM "order" LIMIT 100 and ran nothing. Run returned "0 rows returned ...". posts returned 1 row. After adding posts/two.json, Run again returned 2 rows from the index. The path example button restored SELECT * FROM './' LIMIT 100, which then ran.
• Functions-only config (fn/): the same start as configless.
• -c missing.toml: "Configuration could not load", failed to resolve missing.toml: No such file or directory (os error 2), and the restart line.

E2E Verification

• Ran e2e suites locally for every affected SDK
• Python SDK e2e: pass (13 targeted CLI/server tests)
• TypeScript SDK e2e: pass (full suite, 18 tests)
• Rust core e2e (if applicable): pass (cargo test -p dirsql --features cli --test cli_e2e --test frontend_js --test cli_integration)
• packages/python/e2e-attestations/bot-1489-frontend-browse-1013.json receipt written
• packages/ts/e2e-attestations/bot-1489-frontend-browse-1013.json receipt written
• Command(s) run: uv run maturin develop --release; testing-conventions e2e attest 'uv run python -m pytest tests/e2e/cli_version_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/extension_package_test.py -x -q' from packages/python; testing-conventions e2e attest 'pnpm test:e2e' from packages/ts; the gated just preflight (0 failing pairs).
• Result summary: all passed.

Changelog / Migrations

• Changelog fragment added under packages/rust/changelog.d/
• Migration fragment with the same slug added under packages/rust/migrations.d/