@fluojs/studio

CLI sidecar and React viewer workflow for fluo diagnostics, with a Node dev-runner live MVP and backward-compatible static/report artifact loading.

Table of Contents

• Installation
• Release Policy
• Quick Start: Live Devtool
• Static/Report Compatibility
• Local Security Model
• Runtime Support Matrix
• Public API
• Future Direction
• Related Packages
• Example Sources

Installation

Most application projects install Studio as a development-only dependency. The CLI resolves it for fluo dev --studio, fluo inspect --mermaid, and packaged viewer access, while the application runtime itself does not import Studio.

Studio is a Node.js tooling package and requires Node.js >=24.0.0 <27, matching the published package engines.node field. Studio owns runtime-neutral consumer-side diagnostics declarations and does not install @fluojs/runtime, so that published engine floor is not narrowed by the runtime package. The packaged viewer subpath is resolved by Node package resolution even when it displays artifacts produced by Bun, Deno, or Cloudflare Workers fallback workflows.

pnpm add -D @fluojs/studio

Use a regular dependency only when a published package or runtime automation imports @fluojs/studio at runtime:

pnpm add @fluojs/studio

The published package serves these caller-facing entrypoints:

• @fluojs/studio for canonical snapshot parsing, filtering, Mermaid graph rendering helpers, and runtime-connected Studio live event contracts.
• fluo-studio-viewer is the public launch path for the packaged React browser viewer.
• @fluojs/studio/viewer is only the integration asset-resolution contract for callers that need the packaged HTML entry file.

Release Policy

• @fluojs/studio is part of the intended public publish surface for fluo.
• The app-side CLI/viewer contract is development-only installation (pnpm add -D @fluojs/studio); runtime tooling that imports Studio helpers should declare a normal dependency (pnpm add @fluojs/studio). Local repo development still uses pnpm --dir packages/studio dev.
• The public package surface includes a breaking import migration: @fluojs/studio/contracts is removed, so migrate imports to @fluojs/studio. Live devtool contracts, file-first parsing, filtering, graph rendering, and report artifact readers remain supported.

Quick Start: Live Devtool

Run a local app with the runtime-connected Studio sidecar:

fluo dev --studio

fluo dev --studio starts the normal dev process, starts a token-protected local sidecar, injects explicit Studio runtime config into the Node app child before it imports @fluojs/runtime, and prints a URL such as:

[fluo] Studio listening at http://127.0.0.1:51234/?token=...

Open that URL to inspect the live React Studio dashboard. The dashboard is built with Feature-Sliced Design layers under src/app, src/pages, src/widgets, src/features, src/entities, and src/shared; cross-widget rendering helpers used by the static/report viewer live in src/shared/lib rather than root-level viewer files.

Studio is launched as a CLI-owned sidecar/viewer workflow. It is not an application module to mount inside your fluo runtime. The live MVP targets the Node dev-runner path; non-Node projects should use the static/report inspect workflow until dedicated Bun, Deno, or Workers bridges are implemented and verified.

Live mode shows:

• connection state (connecting, connected, restarting, reconnecting, stale, disconnected, error);
• module/provider/controller/route graph nodes and import/export/ownership/dependency edges;
• HTTP method/path/controller handler route descriptors that label react-page separately from ordinary http handlers and show effective path parameter names;
• recent request flow with route/handler correlation, success/error, status code, and duration;
• bootstrap timing summaries for live and static/report data;
• runtime/request diagnostics with severity, target, message, and fix hints where available.

Runtime inspection integrations may retain arbitrary string route kind markers. At the live Studio wire boundary, react-page remains distinct, and omitted kind defaults to http; every supplied kind must be a string, with non-string values rejected. Studio preserves accepted route kind strings end-to-end. Each normalized route also carries graphNodeId, the explicit correlation key for its route graph node, so the viewer never reconstructs Runtime's private node-ID policy or selects by a potentially duplicated display label. Runtime producers always emit this field without changing existing graph node IDs. Persisted legacy artifacts may omit it; Studio derives the previous route:<sanitized-route-id> value once while parsing those inputs.

MVP request flow intentionally means route/handler and dependency-graph correlation, not full method-level service call-chain tracing.

Static/Report Compatibility

Studio still accepts JSON exports from the fluo CLI. Runtime produces snapshots, the CLI owns artifact export/write/delegation, and Studio owns the public helpers and viewer surface that parse, filter, inspect, and render those snapshots for people and automation callers. Use the versioned report artifact from fluo inspect --report as the default recipe for newly stored artifacts. Raw snapshots, snapshot-plus-timing envelopes, and legacy standalone timing diagnostics remain supported readers for compatibility. New snapshots may include compiled routes; Studio validates string kind values and parameter-name-only params, displays react-page as React page, preserves arbitrary route kind strings, and keeps artifacts without routes or older route entries without those fields backward compatible as ordinary HTTP diagnostics. Parsed route results normalize omitted legacy kind to http, params to [], and graphNodeId to the previous route-node ID convention, while invalid supplied values are rejected and the exported wire-input fields remain optional for persisted artifact compatibility.

This file-first path is the compatibility and migration fallback for CI, support handoffs, architecture reviews, and non-Node runtime targets. After a successful bootstrap, fluo inspect reads PlatformShell.snapshot() and routes to produce a PlatformShellSnapshot with reported platform components and their dependencies; it does not contain the compiled module/provider graph or provider scope metadata that Node live Studio derives at runtime. The live path publishes compiled module, provider, controller, and route graph data (including provider scope metadata), separate bootstrap timing events, and request trace events. Bun, Deno, and Cloudflare Workers projects should generate inspect/static artifacts and launch them with the packaged fluo-studio-viewer instead of expecting live sidecar events in the MVP. Workflows that need that compiled DI graph must stay on the supported Node live path with fluo dev --studio. Integrations that need the HTML asset path resolve the Node-based package entrypoint (node -p "require.resolve('@fluojs/studio/viewer')") even when the inspected artifact came from a non-Node runtime fallback workflow.

1. Export a versioned report artifact:

   fluo inspect ./src/app.module.ts --report --output inspect-report.json

2. Open the packaged Studio viewer:

   pnpm add -D @fluojs/studio
   pnpm exec fluo-studio-viewer

   The fluo-studio-viewer command serves the packaged viewer from 127.0.0.1 and prints its HTTP URL. Open that URL in a browser instead of opening dist/index.html directly. @fluojs/studio/viewer remains only the integration asset-resolution contract for callers that resolve the packaged HTML entry. For repo-local Studio development, use:

   pnpm --dir packages/studio dev

3. Load the file: Drag and drop inspect-report.json into the Studio web interface. Search and filter controls preserve focus while the graph, connection explorer, diagnostics, and summary update.

Local Security Model

• The Studio sidecar binds 127.0.0.1 by default.
• Runtime ingestion and browser state/SSE APIs require generated per-run tokens.
• The sidecar does not enable CORS by default.
• Request bodies are not captured by default. Live request events include method/path/url/request id/route/handler/status/duration/error metadata only.
• Live request event validation rejects body-like payload fields, including privacy-sensitive body, headers, payload, rawBody, requestBody, and responseBody, before Studio UI state can retain them.
• Runtime Studio instrumentation is activated only by explicit CLI-provided Studio config. Runtime package source does not read process.env directly; without valid injected config, runtime behavior is a no-op.

Runtime Support Matrix

| Runtime target | MVP expectation | | --- | --- | | Node dev-runner | Live sidecar support target through fluo dev --studio; the CLI injects explicit Studio runtime config into the Node app child and streams snapshot/request/timing/diagnostic lifecycle events. Static inspect artifacts remain supported. | | Bun | Live sidecar events are not enabled for this MVP; fluo dev --studio rejects Bun projects until a dedicated bridge is implemented and verified. Use fluo inspect JSON/report artifacts, Mermaid output, and the packaged viewer as the migration fallback. | | Deno | Live sidecar events are not enabled for this MVP; fluo dev --studio rejects Deno projects until a dedicated bridge is implemented and verified. Use fluo inspect JSON/report artifacts, Mermaid output, and the packaged viewer as the migration fallback. | | Cloudflare Workers | Live sidecar events are unsupported for this MVP unless a dedicated worker bridge is implemented and tested. Use static inspect/report artifacts and the packaged viewer as the migration fallback. |

Public API

Studio is primarily a CLI-launched sidecar and browser viewer, but the published package also exposes documented contracts used by tooling and automation. Treat @fluojs/studio as the canonical owner of snapshot parsing, filtering, Mermaid graph rendering, and live Studio event validation semantics. The root export directly owns every public helper and type.

Bootstrap timing phase names accept only bootstrap_module, register_runtime_tokens, resolve_lifecycle_instances, run_bootstrap_lifecycle, and create_dispatcher; all other values are rejected in static payloads and live timing events.

| Contract | Description | |---|---| | parseStudioPayload(rawJson) | Accepts raw snapshot JSON, standalone timing JSON, snapshot+timing envelopes, and fluo inspect --report artifacts; returns the parsed payload plus the original JSON string. | | applyFilters(snapshot, filter) | Applies readiness/severity/query filters without mutating the source snapshot. | | renderMermaid(snapshot) | Produces Mermaid graph text from the loaded platform graph, including internal component dependency edges and external dependency nodes. Filtered snapshots render deterministically, producing identical Mermaid text before and after JSON serialization. | | parseStudioLiveEvent(rawJson) / validateStudioLiveEvent(value) | Validate runtime-connected sidecar/SSE envelopes and return normalized route entries before UI state consumes them. | | isStudioLiveEvent(value) | Runtime-safe type guard for checking sidecar/SSE envelopes before parsing or dispatch. | | StudioLiveSnapshot | Live graph/routes/requests/timing/diagnostics snapshot consumed by the React UI. | | StudioLiveEvent | Versioned live event envelope for snapshot, request, timing, diagnostic, restart, disconnect, and heartbeat. | | StudioPayload / StudioInspectionSnapshot / StudioReportArtifact / StudioReportSummary | Static/report compatibility contracts, including optional compiled route diagnostics; Studio renders report artifacts with their canonical seven-field summary and derives the same view from raw snapshots or snapshot-plus-timing envelopes, marking unavailable raw-snapshot timing explicitly. |

Root type exports

| Type export | Description | |---|---| | FilterState | Query, readiness status, and diagnostic severity filters applied by Studio without mutating the source snapshot. | | ParsedPayload | Return shape from parseStudioPayload(rawJson), including the parsed StudioPayload and original JSON string. | | BootstrapTimingDiagnostics / BootstrapTimingPhase | Versioned bootstrap timing artifact contract; timing may be omitted, but present malformed or non-finite values are rejected. | | PlatformCheckResult | One named readiness or health check outcome in a platform report. | | PlatformDiagnosticIssue | Studio-owned runtime-neutral diagnostic issue contract for Studio consumers. | | PlatformDiagnosticSeverity | Diagnostic severity union used by filters and live diagnostics. | | PlatformHealthReport / PlatformHealthStatus | Aggregate health result and its status union. | | PlatformReadinessStatus | Readiness status union used by filters and graph annotations. | | PlatformReadinessReport | Aggregate readiness result for a platform snapshot. | | PlatformShellSnapshot | Studio-owned runtime-neutral snapshot contract for inspect artifacts. | | PlatformSnapshot / PlatformState | Per-component snapshot contract and lifecycle state union. | | StudioInspectionSnapshot | Static inspect snapshot that optionally carries validated compiled route descriptors. | | StudioPayload | Static artifact envelope containing a snapshot, timing diagnostics, and/or report artifact. | | StudioReportArtifact | CI/support report artifact produced by fluo inspect --report. | | StudioReportSummary | Stable summary fields embedded in a report artifact. | | StudioConnectionState | UI-side connection state for live or static Studio sessions. | | StudioConnectionStatus | Connection status union, including live lifecycle states and static. | | StudioDisconnectPayload | Live disconnect lifecycle payload. | | StudioGraphEdge | Serializable edge in the runtime-connected Studio dependency graph. | | StudioGraphEdgeKind | Edge kind union for imports, ownership, route exposure, dependency, and export relationships. | | StudioGraphNode | Serializable node in the runtime-connected Studio dependency graph. | | StudioGraphNodeKind | Node kind union for modules, providers, controllers, routes, platform nodes, and external dependencies. | | StudioHeartbeatPayload | Live heartbeat payload used to keep sidecar/UI sessions fresh. | | StudioLiveDiagnostic | Runtime diagnostic shape surfaced by the live diagnostics panel. | | StudioLiveEvent | Versioned sidecar/SSE event union for snapshots, requests, timing, diagnostics, restarts, disconnects, and heartbeats. | | StudioLiveEventBase | Generic base envelope shared by all live Studio events. | | StudioLiveEventSource | App/runtime source metadata attached to live Studio events. | | StudioLiveSnapshot | Live graph/routes/requests/timing/diagnostics snapshot consumed by the React UI. | | StudioRequestStatus | Request lifecycle status union used by live request traces. | | StudioRequestTrace | Request trace metadata emitted without request or response bodies. | | StudioRestartPayload | Runtime/app restart lifecycle payload emitted by CLI-owned dev supervision. | | StudioRouteDescriptor | Live/static wire-input route descriptor with kind, method/effective path, parameter names, controller-handler identity, and optional legacy-compatible graphNodeId correlation. | | StudioRouteKind | Open string route kind accepted by Studio validators and Runtime producers; arbitrary string markers are preserved, omitted input defaults to http, and non-string input is rejected. | | StudioNormalizedRouteDescriptor | Parsed route descriptor with required graphNodeId correlation and legacy kind and params defaults materialized. | | StudioParsedInspectionSnapshot / StudioParsedLiveSnapshot / StudioParsedPayload / StudioParsedLiveEvent | Parsed outputs that expose normalized route entries while preserving the legacy optional wire-input contract. |

Published package entrypoints

• @fluojs/studio: root helper barrel for snapshot parsing/filtering/rendering and live contracts.
• fluo-studio-viewer: public CLI launch path for the packaged React browser viewer bundle.
• @fluojs/studio/viewer: integration asset-resolution subpath for the packaged dist/index.html file.

@fluojs/studio/viewer is only the integration asset-resolution contract: callers resolve the packaged HTML file path, not a JavaScript module or TypeScript declaration entrypoint.

Migration from the removed contracts subpath

@fluojs/studio/contracts is no longer exported. Replace every helper and type import with @fluojs/studio; the helper behavior and the wire-input optional fields versus normalized parsed-output required fields are unchanged. For newly persisted inspect artifacts, write a versioned report with fluo inspect <module-path> --report --output <path>; existing raw snapshot and timing artifact readers remain supported.

Future Direction

The MVP is local and runtime-connected. Future releases should consider, but do not yet ship, cloud-hosted Studio, accounts/auth, team sharing, production monitoring dashboards, richer bidirectional commands, and a possible VS Code extension.

Related Packages

• @fluojs/cli: Provides fluo dev --studio and inspect/export commands.
• @fluojs/runtime: Produces live snapshots, request traces, timing, and diagnostics.

Example Sources

• main.tsx - React browser viewer entry point.
• contracts.ts - Static and live Studio contract definitions.