@bluelibs/runner-dev 5.1.0 → 5.3.0

package/AI.md

@@ -13,6 +13,8 @@ Runner-Dev is a powerful development toolkit for applications built with the **@
 - **MCP Integration**: AI-native development environment
 - **Tags (first-class)**: Discover Tag objects and reverse usage via GraphQL (`tags`, `tag(id)`).
 - **Documentation UI Overviews**: Sortable and searchable overview tables with a `Used By` counter column for faster cross-element inspection.
+- **Visibility Awareness**: Every element exposes `isPrivate` (based on Runner `exports()` boundaries), and resources expose `exports`.
+- **Task Interceptor Introspection**: Tasks expose `interceptorCount` and `hasInterceptors` for runtime `task.intercept(...)` registrations.
 
 ## Available GraphQL Queries
 
@@ -23,18 +25,39 @@ Runner-Dev is a powerful development toolkit for applications built with the **@
 query SystemOverview {
   all {
     id
+    isPrivate
     meta {
       title
       description
     }
     filePath
   }
+  runOptions {
+    mode
+    debug
+    debugMode
+    logsEnabled
+    logsPrintThreshold
+    logsPrintStrategy
+    logsBuffer
+    errorBoundary
+    shutdownHooks
+    dryRun
+    lazy
+    initMode
+    runtimeEventCycleDetection
+    hasOnUnhandledError
+    rootId
+  }
 }
 
 # Get specific element types
 query Architecture {
   tasks {
     id
+    isPrivate
+    interceptorCount
+    hasInterceptors
     meta {
       title
       description
@@ -47,6 +70,8 @@ query Architecture {
   }
   resources {
     id
+    isPrivate
+    exports
     meta {
       title
       description
@@ -146,6 +171,28 @@ query LiveTelemetry {
 }
 ```
 
+### SSE Live Streaming
+
+Server-Sent Events endpoint at `GET /live/stream` for near-instant push instead of polling:
+
+- **`telemetry`** event: `{ logs, emissions, errors, runs }` pushed ~100ms after each record (debounced)
+- **`health`** event: `{ memory, cpu, eventLoop, gc }` every 2s
+- Heartbeat comment every 15s to keep proxies alive
+- `Live.onRecord(callback)` fires synchronously on each `record*` call; returns an unsubscribe function
+- The built-in Live Panel auto-uses SSE and falls back to configurable-interval polling (500ms–10s)
+
+### Correlation ID Trace View
+
+The Live Panel includes a built-in **Trace View** — a unified timeline showing every log, event emission, error, and task run sharing a single `correlationId`, ordered chronologically. Click any correlationId badge (shown on logs, events, errors, and runs) to open the trace modal. This provides an in-process "distributed tracing" experience (like Jaeger).
+
+### Unified Modal System
+
+All UI modals (CodeModal, ExecuteModal, TraceView, RecentLogs, OverviewStatsPanel) are built on a shared `BaseModal` primitive (`src/ui/src/components/Documentation/components/modals/`). It provides:
+
+- **Stacking**: A `ModalStackContext` tracks open modals and assigns ascending z-indexes (base 10 000 + 10 per layer). Global Escape closes the topmost modal first.
+- **Consistent UX**: Portal to `document.body`, backdrop blur, scroll lock, focus trap, slide-up animation, ARIA `role="dialog"`.
+- **Sizes**: `sm | md | lg | xl | fullscreen` with responsive fallback to fullscreen on small viewports.
+
 ### Diagnostics & Health
 
 ```graphql
@@ -262,9 +309,11 @@ npx @bluelibs/runner-dev new <project-name>
 # Example
 npx @bluelibs/runner-dev new my-awesome-app
 ```
+
 This command creates a new Runner project with a complete TypeScript setup, Jest for testing, and all necessary dependencies.
 
 Key flags for `new`:
+
 - `--install`: Install dependencies after scaffolding.
 - `--run-tests`: Run the generated test suite after installation.
 - `--run`: Start the dev server after installation.
@@ -274,11 +323,13 @@ Key flags for `new`:
 All commands can be prefixed with environment variables like `ENDPOINT` and `HEADERS`.
 
 **Ping the server:**
+
 ```bash
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev ping
 ```
 
 **Execute a GraphQL query (Remote Mode):**
+
 ```bash
 # Simple query
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev query 'query { tasks { id } }'
@@ -306,11 +357,13 @@ npx @bluelibs/runner-dev query 'query { tasks { id } }' \
 ```
 
 Selection logic:
+
 - If `--entry-file` is provided, dry-run mode is used (no server; requires ts-node).
 - Otherwise, the CLI uses a remote endpoint via `--endpoint` or `ENDPOINT/GRAPHQL_ENDPOINT`.
 - If neither is provided, the command errors.
 
 **Generate a project overview:**
+
 ```bash
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev overview --details 10
 ```
@@ -339,7 +392,6 @@ ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev schema json
 
 This direct CLI access provides a powerful way for AI assistants with shell access to script complex interactions, perform detailed introspection, and validate application state without relying on MCP tools.
 
-
 ## Common Use Cases
 
 ### 1. Understanding System Architecture
@@ -479,7 +531,10 @@ Minimal workflow setup pattern:
 
 ```ts
 import { r } from "@bluelibs/runner";
-import { durableWorkflowTag, memoryDurableResource } from "@bluelibs/runner/node";
+import {
+  durableWorkflowTag,
+  memoryDurableResource,
+} from "@bluelibs/runner/node";
 
 const durable = memoryDurableResource.fork("app.durable");
 const durableRegistration = durable.with({});
@@ -496,10 +551,7 @@ const workflow = r
   })
   .build();
 
-const app = r
-  .resource("app")
-  .register([durableRegistration, workflow])
-  .build();
+const app = r.resource("app").register([durableRegistration, workflow]).build();
 ```
 
 ## Best Practices for AI Assistants

package/README.md

@@ -40,7 +40,10 @@ const app = resource({
 
 - Fully-featured UI with AI assistance to explore your app, call tasks, emit events, diagnostics, logs and more.
 - Overview tables across UI sections now include sortable and searchable columns (`ID`, `Title`, `Description`, `Used By`) with per-element usage counters.
+- Overview tables now include `Visibility` (`Public`/`Private`) derived from Runner resource `exports()` boundaries.
 - Introspector: programmatic API to inspect tasks, hooks, resources, events, middleware, and diagnostics (including file paths, contents)
+- Task introspection includes runtime `interceptorCount` / `hasInterceptors` (registered via `taskDependency.intercept(...)` in resource init).
+- Resource introspection includes `exports` (resolved list of ids exposed by `.exports([...])`).
 - Live: in-memory logs and event emissions
 - Live File Previews and Saving.
 - GraphQL server: deep graph navigation over your app’s topology and live data
@@ -86,6 +89,7 @@ Once your application is running with the `dev` resource, you can access the vis
 🚀 **Open [http://localhost:1337](http://localhost:1337) in your browser.**
 
 Inside the UI, you can:
+
 - Explore the resource graph.
 - Manually invoke tasks with custom inputs.
 - Inspect live logs and event emissions in real-time.
@@ -318,13 +322,13 @@ Precedence:
 
 ### CLI Summary
 
-| Category | Description |
-| --- | --- |
-| **New Project** | `runner-dev new <project-name>` |
+| Category        | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| **New Project** | `runner-dev new <project-name>`                           |
 | **Scaffolding** | `runner-dev new <resource\|task\|event\|tag\|middleware>` |
-| **Queries** | `runner-dev query 'query { ... }'` |
-| **Overview** | `runner-dev overview --details 10` |
-| **Schema** | `runner-dev schema sdl` |
+| **Queries**     | `runner-dev query 'query { ... }'`                        |
+| **Overview**    | `runner-dev overview --details 10`                        |
+| **Schema**      | `runner-dev schema sdl`                                   |
 
 ---
 
@@ -547,6 +551,41 @@ Notes:
 - `cpu.usage` is a ratio; `loadAverage` is 1‑minute OS load.
 - `eventLoop.lag` may be 0 if `monitorEventLoopDelay` is unavailable.
 
+### SSE Live Streaming
+
+In addition to GraphQL polling, the server exposes a **Server-Sent Events** endpoint at `GET /live/stream` for near-instant telemetry delivery:
+
+```http
+GET /live/stream
+Accept: text/event-stream
+```
+
+The endpoint pushes two event types:
+
+| Event       | Cadence                                      | Payload                                                     |
+| ----------- | -------------------------------------------- | ----------------------------------------------------------- |
+| `telemetry` | ~100ms after each `record*` call (debounced) | `{ logs, emissions, errors, runs }` (delta since last push) |
+| `health`    | Every 2s                                     | `{ memory, cpu, eventLoop, gc }`                            |
+
+A heartbeat comment (`: heartbeat`) is sent every 15s to keep the connection alive through proxies.
+
+**JavaScript client example:**
+
+```js
+const es = new EventSource("http://localhost:1337/live/stream");
+es.addEventListener("telemetry", (e) => {
+  const { logs, emissions, errors, runs } = JSON.parse(e.data);
+  // merge into your state
+});
+es.addEventListener("health", (e) => {
+  const { memory, cpu, eventLoop, gc } = JSON.parse(e.data);
+});
+```
+
+The built-in Live Panel UI automatically uses SSE when available and falls back to configurable-interval polling (500ms–10s slider) when SSE is not supported.
+
+**Programmatic notification hook:** The `Live` interface exposes `onRecord(callback)` which fires synchronously whenever a `record*` method is called, returning an unsubscribe function. This is the mechanism the SSE endpoint uses internally.
+
 ### Correlation and call chains
 
 - What is correlationId? An opaque UUID (via `crypto.randomUUID()`) created for the first task in a run chain.
@@ -583,6 +622,14 @@ query TraceByCorrelation($ts: Float, $cid: String!) {
 }
 ```
 
+#### Trace View (UI)
+
+The Live Panel includes a built-in **Trace View** — click any `correlationId` badge in the Logs, Events, Errors, or Runs sub-tabs to open a unified timeline modal showing every entry that shares that ID, ordered chronologically. Each entry is color-coded by kind (log, event, error, run) with a vertical timeline gutter, relative offset labels, and expandable details. This provides an in-process "distributed tracing" experience similar to Jaeger or Zipkin, but entirely within the Dev UI.
+
+#### Unified Modal System
+
+All Dev UI modals (code viewer, execute, trace view, log details, stats overlay) share a common `BaseModal` primitive that provides portal rendering, backdrop blur, focus trap, scroll lock, slide-up animation, and ARIA dialog semantics. A `ModalStackContext` manages stacking so modals can open on top of other modals — each layer gets a higher z-index and the global <kbd>Esc</kbd> key always closes the topmost one first.
+
 ## Emitting Events (Runner-native)
 
 - Define an event:
@@ -683,6 +730,18 @@ export const app = resource({
 
 #### Queries
 
+**Get the effective run options (how the app was started):**
+
+```graphql
+query {
+  runOptions {
+    mode
+    debug
+    rootId
+  }
+}
+```
+
 **Get currently swapped tasks:**
 
 ```graphql