Add local Streams development support and stream browser improvements (#1478)

* Add local Streams development wiring

* Add stream aggregation rollup panel

* Expand stream diagnostics, search, and demo runtime support

* Stabilize stream polling and search progress

* Add resizable Studio sidebar

* Unify sidebar stream filtering and refresh

* Add routing key browsing to stream view

* fix(table): preserve page index when staging edits

Avoid resetting pagination when row-search apply receives the current term.

Adds regression tests for unchanged and changed row-search applies.

* feat: improve WAL history and stream diagnostics

* chore: update Prisma dev runtime to latest published build

* chore: add release changeset

Author: sorenbs

.changeset/green-rabbits-obey.md

@@ -0,0 +1,5 @@
+---
+"@prisma/studio-core": minor
+---
+
+Expand Prisma Streams support across Studio with a dedicated stream browser, live stream aggregations, stream diagnostics, routing-key browsing, WAL history handoff from tables, and a more flexible demo/runtime setup for local and external Streams servers.

.pnpmfile.cjs

@@ -0,0 +1,15 @@
+const {
+  patchStudioDevPackages,
+} = require("./scripts/dev/local-streams-override.cjs");
+
+module.exports = {
+  hooks: {
+    readPackage(pkg) {
+      return patchStudioDevPackages(pkg, {
+        env: process.env,
+        logger: console,
+        rootDir: __dirname,
+      });
+    },
+  },
+};

Architecture/demo-compute-bundling.md

@@ -6,9 +6,12 @@ The `demo/ppg-dev` server has two runtime modes:
 
 - local development mode, where it rebuilds browser assets from source and watches the repo
 - deploy mode, where it serves prebuilt browser assets from a bundled artifact
+- external data-source mode, where the demo keeps serving the Studio shell locally but proxies Streams to a caller-provided upstream server and runs direct TCP queries against a caller-provided PostgreSQL connection string instead of starting local Prisma Dev
 
 The deploy path exists because the demo server is not just a Bun server entrypoint. In development it expects the Studio repo checkout so it can rebuild `client.tsx` and `ui/index.css` at runtime.
 
+Bundled deploy mode uses the embedded local Prisma Streams runtime exactly as published by `@prisma/streams-local`, so Studio does not carry a second demo-local memory autotune layer on top of Streams' own defaults.
+
 ## Build Responsibilities
 
 `demo/ppg-dev/build-compute.ts` is the production packager for the demo.
@@ -55,3 +58,54 @@ This is an explicit exception to the "no manual runtime asset copying" rule abov
 - If the import fails, the server falls back to local development mode.
 
 That keeps one server implementation for both workflows without adding a separate production-only server entrypoint.
+
+## Local Development Shutdown
+
+In local development mode, `demo/ppg-dev/server.ts` also owns the lifecycle of the Prisma Dev child runtime, including the local Prisma Streams server.
+
+- The first shutdown signal MUST start orderly cleanup for the Bun HTTP server, Prisma Dev runtime, Postgres client, and file watchers.
+- If cleanup stalls, a repeated shutdown signal MUST force the demo process to exit instead of being ignored.
+- The demo process SHOULD also force-exit after a short timeout if cleanup never finishes, so orphaned Prisma Dev and Streams listeners do not block the next `pnpm demo:ppg` run.
+
+## External Demo Mode
+
+The `pnpm demo:ppg` entrypoint MAY also be launched against external data sources:
+
+- `pnpm demo:ppg -- --streams-server-url <streams-url>`
+- `pnpm demo:ppg -- --database-url <postgres-url> --streams-server-url <streams-url>`
+
+When `--streams-server-url` is provided, Studio MUST treat the run as external mode.
+
+- It MUST NOT start local Prisma Dev.
+- It MUST NOT start a local Prisma Streams server.
+- It MUST NOT set up local `prisma-wal` wiring, because that is part of the colocated Prisma Dev + Streams startup path.
+- If `--database-url` is also provided, it MUST connect the BFF executor directly to that PostgreSQL URL.
+- If `--database-url` is omitted, the demo MUST run in streams-only mode and MUST NOT expose database-driven Studio navigation or views.
+- The browser config MUST continue to expose Streams through Studio's own `/api/streams` proxy path so the UI contract stays unchanged.
+- The demo shell MUST NOT claim the database was locally seeded when external mode is active.
+
+## Local Streams Development Override
+
+Studio keeps `@prisma/dev` as the only runtime dependency in source, but local
+development MAY temporarily override both the root `@prisma/dev` dependency and
+that package's transitive `@prisma/streams-local` dependency through the
+repo-level `.pnpmfile.cjs` hook.
+
+- The override MUST remain opt-in through `STUDIO_USE_LOCAL_STREAMS=1`.
+- `pnpm streams:use-local` MUST point Studio's root `@prisma/dev` dependency at
+  the sibling `../team-expansion/dev/server` package (or a caller-provided
+  `STUDIO_LOCAL_PRISMA_DEV_PACKAGE_DIR`) so local `@prisma/dev` source changes
+  are exercised directly from this checkout.
+- Default installs MUST continue to resolve the published npm package.
+- `pnpm streams:use-local` MUST build `../streams/dist/npm/streams-local` (or a
+  caller-provided override path) and reinstall dependencies with `--no-lockfile`
+  so the repo can switch implementations without persisting a machine-local
+  path to `pnpm-lock.yaml`.
+- `pnpm streams:use-local` MUST also build or otherwise validate the linked
+  local `@prisma/dev` package before reinstalling Studio, because the linked
+  package's published entrypoints resolve from its `dist/` directory.
+- `pnpm streams:use-npm` MUST restore the published npm dependencies with the
+  same `--no-lockfile` behavior.
+- Because `build-compute.ts` resolves `@prisma/streams-local` from the installed
+  `@prisma/dev` dependency tree, bundled demo artifacts MUST follow whichever
+  local or published streams package is currently installed.

Architecture/navigation-url-state.md

@@ -10,6 +10,9 @@ This architecture governs:
 
 - active Studio view (`table`, `schema`, `console`, `sql`, `stream`)
 - active schema/table/stream
+- active stream follow mode
+- active stream aggregation-panel visibility
+- active stream aggregation range while the aggregation panel is open
 - pagination URL state
 - sorting URL state
 - column pinning URL state
@@ -38,6 +41,9 @@ Only keys declared in [`ui/hooks/nuqs.ts`](../ui/hooks/nuqs.ts) are allowed:
 - `schema`
 - `table`
 - `stream`
+- `streamFollow`
+- `aggregations`
+- `streamAggregationRange`
 - `filter`
 - `sort`
 - `pin`
@@ -48,12 +54,15 @@ Only keys declared in [`ui/hooks/nuqs.ts`](../ui/hooks/nuqs.ts) are allowed:
 
 Notes:
 
-- `search` is row-search term state for active table view.
+- `search` is shared search term state for the active data view. In table view it drives row search, and in stream view it drives stream-event search when the selected stream advertises search capability.
 - `searchScope` is legacy URL state and is not used for table-name navigation filtering.
 - `pin` stores left-pinned data columns for the grid as a comma-separated list (for example `pin=id,bigint_col`).
 - `pin` order is authoritative and MUST be updated when users drag-reorder pinned columns.
 - `pageIndex` remains URL-backed for table navigation.
 - `pageSize` remains a supported hash key for compatibility, but table rendering now takes its authoritative rows-per-page preference from `studioUiCollection.tablePageSize` in [`Architecture/ui-state.md`](ui-state.md).
+- `streamFollow` stores the active stream follow mode (`paused`, `live`, or `tail`).
+- `aggregations` is an open-only flag for the active stream aggregation strip; when present it MUST be serialized as a bare key with no explicit value.
+- `streamAggregationRange` stores the active stream aggregation range, but MUST only be serialized while `aggregations` is present.
 
 Adding a new URL key requires updating `StateKey` in `nuqs.ts` first.
 
@@ -70,6 +79,14 @@ Adding a new URL key requires updating `StateKey` in `nuqs.ts` first.
 - `searchScope`: `"table"` (legacy default)
 - `view`: `"table"`
 - `stream`: no default; only meaningful when `view=stream`
+- `streamFollow`: no global default in `useNavigation`; the active stream view MUST resolve an absent value to `tail` and materialize that into the hash
+- `aggregations`: no global default in `useNavigation`; the active stream view MUST treat an absent flag as closed and MUST NOT materialize that closed state into the hash
+- `streamAggregationRange`: no standalone default; the active stream view MUST clear it whenever `aggregations` is absent, and MUST materialize its default range only after the aggregation panel is opened
+
+When Studio is running without a database connection but with Streams enabled:
+
+- the resolved default `view` MUST become `"stream"` instead of `"table"`
+- stale database-oriented views such as `table`, `schema`, `console`, and `sql` MUST resolve back to the stream view instead of trying to render database-only UI against a disabled database session
 
 When URL params are stale from a previous DB, invalid `schema`/`table` values MUST be resolved to valid current defaults.
 Shared table page size and infinite-scroll mode are not derived from URL defaults; they are restored through Studio UI state and then mirrored into query behavior by `usePagination`.

Architecture/non-standard-ui.md

@@ -77,8 +77,74 @@ It deliberately excludes:
   - `Skeleton`
 - Why it stays non-standard:
   - The stream view needs a dense multi-column summary row with inline expansion, single-open-row behavior, clipped preview text, and infinite-scroll loading inside one scroll container.
+  - The same custom row composite also carries the short-lived highlight animation for newly revealed events, which needs to live on the exact row shell that preserves stream-scroll anchoring.
+  - The surrounding stream chrome now also mixes a control-only header, a fixed footer summary cluster, follow-mode-specific scroll behavior, and a search-only footer progress fill with a scroll-trigger loading pulse that standard ShadCN layout primitives do not model as one reusable component.
   - No stock ShadCN component provides that event-log interaction model, so Studio keeps a custom composite while still building it from standard ShadCN primitives.
 
+### Inline Stream Search Validation Message
+
+- Canonical component:
+  - [`ui/studio/input/ExpandableSearchControl.tsx`](ui/studio/input/ExpandableSearchControl.tsx)
+- Closest standard ShadCN alternatives:
+  - `Command`
+  - `Popover`
+  - `Alert`
+- Why it stays non-standard:
+  - The stream header search needs syntax feedback and context-aware suggestions that stay visually attached to the expanding inline field without introducing a portal-backed overlay or a full alert block inside the header chrome.
+  - Studio therefore keeps a custom anchored assist panel directly under the input, while still building the suggestion list from standard ShadCN `Command` primitives.
+  - Keeping the feedback and suggestions inline avoids the layering and focus issues of a separate popover in this compact header layout, and it lets the suggestion list open immediately with starter field suggestions, stay content-sized above the sticky header row, hold partial field prefixes locally, preserve a stable keyboard selection during background refreshes, and still draw value candidates from remembered rows even when the currently visible filtered result set is empty.
+
+### Stream Routing Key Selector
+
+- Canonical components:
+  - [`ui/studio/views/stream/StreamRoutingKeySelector.tsx`](ui/studio/views/stream/StreamRoutingKeySelector.tsx)
+  - [`ui/hooks/use-stream-routing-keys.ts`](../ui/hooks/use-stream-routing-keys.ts)
+- Closest standard ShadCN alternatives:
+  - `Popover`
+  - `Command`
+  - `Input`
+- Why it stays non-standard:
+  - The stream header needs a compact routing-key picker that can sit beside the expanding search field, page through a potentially massive lexicographically sorted keyspace, and still support keyboard-first selection without rendering every key at once.
+  - The API only exposes cursor-based routing-key pages, and the selector now also owns a clearable selected-key state that must work even when the stream has no search schema.
+  - When a key is selected, the closed trigger also needs to expand into a compact inline pill that keeps the chosen routing key visible without stealing the full search-field slot.
+  - Studio therefore keeps a custom popover composite with a prefix input, a virtualized infinite list, and a hover-only clear affordance on the trigger itself instead of trying to force that behavior into a stock `Command` list.
+
+### Stream Aggregation Strip
+
+- Canonical components:
+  - [`ui/studio/views/stream/StreamAggregationsPanel.tsx`](ui/studio/views/stream/StreamAggregationsPanel.tsx)
+  - [`ui/studio/views/stream/StreamView.tsx`](ui/studio/views/stream/StreamView.tsx)
+- Closest standard ShadCN alternatives:
+  - `Card`
+  - `Button`
+  - `Popover`
+- Why it stays non-standard:
+  - The stream view needs a compact, single-band aggregation surface that mixes horizontally scrollable metric cards, inline sparkline backgrounds, quick time-range toggles, follow-mode-driven refresh behavior, and a small custom-range popover directly above an independently scrollable event log.
+  - No stock ShadCN component covers that event-log-adjacent observability layout, especially once each metric column has to support fixed-width horizontal scrolling, stacked percentile cards with plain-text secondary labels, auto-scaled unit display, TanStack DB-backed per-series preferences that survive range switches and stream navigation, hover-revealed dropdown controls without reflowing the card chrome, and a tighter split date/time absolute-range editor instead of the browser's native `datetime-local` chrome.
+- Required internals:
+  - `Badge`
+  - `Button`
+  - `Card`
+  - `DropdownMenu`
+  - `Input`
+  - `Label`
+  - `Popover`
+  - `Skeleton`
+
+### Stream Footer Diagnostics Popover
+
+- Canonical components:
+  - [`ui/studio/views/stream/StreamDiagnosticsPopover.tsx`](ui/studio/views/stream/StreamDiagnosticsPopover.tsx)
+  - [`ui/studio/views/stream/StreamView.tsx`](ui/studio/views/stream/StreamView.tsx)
+- Closest standard ShadCN alternatives:
+  - `Popover`
+  - `Card`
+  - `Badge`
+- Why it stays non-standard:
+  - Studio needs a compact, stream-specific diagnostics surface anchored to the footer summary itself, mixing logical payload size, explicit object-storage and local-storage buckets, node-local request accounting, search-family coverage, and state-aware run-accelerator status in one dense popover.
+  - The storage breakdowns also need collapsible ledger-style accounting boxes whose headers surface the section totals when folded shut, plus faint shared-cap annotations that sit beside right-aligned byte values and one shared cap marker spanning both Routing and Exact cache rows, which is not a stock ShadCN pattern.
+  - No stock ShadCN pattern covers that descriptor-driven observability layout, especially when the UI must distinguish logical bytes from physical storage signals, separate search coverage from historical run indexes, hide unconfigured routing rows, and keep the remaining cost caveats explicit instead of inventing unavailable totals.
+
 ## Standardization Candidates
 
 These are the current high-signal places where Studio is bypassing a plausible standard ShadCN component or composition pattern.
@@ -122,7 +188,7 @@ These are the current high-signal places where Studio is bypassing a plausible s
 - Files:
   - [`ui/studio/Navigation.tsx`](ui/studio/Navigation.tsx)
 - Current UI:
-  - Custom sidebar sections, custom table search disclosure, custom sidebar item primitive.
+  - Custom sidebar sections, shared inline search-and-refresh disclosure for both tables and streams, custom sidebar item primitive, and a draggable resize separator on the sidebar edge.
 - Plausible standard ShadCN alternative:
   - `Sidebar`
   - standard sidebar/menu composition