@fluojs/studio 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.ko.md +71 -53
  2. package/README.md +68 -50
  3. package/dist/assets/index-AjSkQOVN.js +78 -0
  4. package/dist/assets/index-ort96Zw9.css +1 -0
  5. package/dist/contracts.d.ts +142 -0
  6. package/dist/contracts.d.ts.map +1 -1
  7. package/dist/contracts.js +394 -0
  8. package/dist/index.d.ts +1 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.html +2 -2
  11. package/dist/index.js +1 -1
  12. package/package.json +7 -3
  13. package/dist/assets/index-BOSlyIRm.js +0 -171
  14. package/dist/assets/index-RQNFORxf.css +0 -1
package/README.ko.md CHANGED
@@ -2,16 +2,18 @@
2
2
 
3
3
  <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
4
4
 
5
- fluo 런타임 내보내기의 공유 플랫폼 snapshot을 파일 기반으로 확인하고 그래프로 렌더링하는 canonical provider입니다.
5
+ fluo 애플리케이션을 위한 runtime-connected React devtool이며, 기존 static/report artifact 로딩도 계속 지원합니다.
6
6
 
7
7
  ## 목차
8
8
 
9
9
  - [설치](#설치)
10
10
  - [릴리스 정책](#릴리스-정책)
11
- - [사용 시점](#사용-시점)
12
- - [빠른 시작](#빠른-시작)
13
- - [주요 패턴](#주요-패턴)
11
+ - [빠른 시작: Live Devtool](#빠른-시작-live-devtool)
12
+ - [Static/Report 호환성](#staticreport-호환성)
13
+ - [로컬 보안 모델](#로컬-보안-모델)
14
+ - [런타임 지원 매트릭스](#런타임-지원-매트릭스)
14
15
  - [공개 API](#공개-api)
16
+ - [향후 방향](#향후-방향)
15
17
  - [관련 패키지](#관련-패키지)
16
18
  - [예제 소스](#예제-소스)
17
19
 
@@ -21,27 +23,47 @@ fluo 런타임 내보내기의 공유 플랫폼 snapshot을 파일 기반으로
21
23
  pnpm add @fluojs/studio
22
24
  ```
23
25
 
24
- 배포된 패키지는 두 가지 caller-facing entrypoint를 제공합니다.
26
+ 배포된 패키지는 다음 caller-facing entrypoint를 제공합니다.
25
27
 
26
- - `@fluojs/studio` / `@fluojs/studio/contracts`: canonical snapshot 파싱, 필터링, Mermaid 그래프 렌더링 헬퍼
27
- - `@fluojs/studio/viewer`: 패키징된 브라우저 뷰어 HTML 진입 파일
28
+ - `@fluojs/studio` / `@fluojs/studio/contracts`: canonical snapshot 파싱, 필터링, Mermaid graph 렌더링 헬퍼와 runtime-connected Studio live event 계약
29
+ - `@fluojs/studio/viewer`: 패키징된 React 브라우저 viewer HTML 진입 파일
28
30
 
29
31
  ## 릴리스 정책
30
32
 
31
33
  - `@fluojs/studio`는 fluo의 intended public publish surface에 포함되는 공개 배포 패키지입니다.
32
34
  - Studio의 npm 설치 계약은 `pnpm add @fluojs/studio`이며, 저장소 내부 개발 경로는 계속 `pnpm --dir packages/studio dev`를 사용합니다.
33
- - 이번 릴리스에서 지원하는 공개 패키지 표면은 파일 기반 뷰어와 문서화된 snapshot 소비, 필터링, 그래프 렌더링 계약까지입니다. 내부 workspace 연결 방식은 지원되는 설치 경로가 아닙니다.
35
+ - 공개 패키지 표면은 additive입니다. live devtool 계약을 추가하면서도 file-first parsing, filtering, graph rendering, report artifact 호환성을 유지합니다.
34
36
 
35
- ## 사용 시점
37
+ ## 빠른 시작: Live Devtool
36
38
 
37
- - **시각화**: 애플리케이션의 모듈 그래프와 의존성 체인을 탐색할 때.
38
- - **진단**: 가이드된 힌트를 사용하여 플랫폼 수준의 설정 문제를 식별하고 해결할 때.
39
- - **성능 분석**: 부트스트랩 타이밍을 분석하고 초기화 병목 지점을 찾을 때.
40
- - **문서화**: 애플리케이션 아키텍처의 Mermaid 다이어그램을 생성할 때.
39
+ 로컬 앱을 runtime-connected Studio sidecar와 함께 실행합니다.
41
40
 
42
- ## 빠른 시작
41
+ ```bash
42
+ fluo dev --studio
43
+ ```
44
+
45
+ `fluo dev --studio`는 일반 dev process를 실행하고, token-protected local sidecar를 시작하며, 앱이 `@fluojs/runtime`을 import하기 전에 명시적인 Studio runtime config를 Node 앱 child에 주입하고 다음과 같은 URL을 출력합니다.
46
+
47
+ ```text
48
+ [fluo] Studio listening at http://127.0.0.1:51234/?token=...
49
+ ```
50
+
51
+ 그 URL을 열면 live React Studio dashboard에서 런타임 상태를 볼 수 있습니다. Dashboard 코드는 `src/app`, `src/pages`, `src/widgets`, `src/features`, `src/entities`, `src/shared`의 Feature-Sliced Design layer로 구성됩니다.
52
+
53
+ Live mode는 다음을 보여줍니다.
43
54
 
44
- Studio는 fluo CLI에서 내보낸 JSON 파일을 소비합니다. 런타임은 snapshot을 생산하고, CLI는 artifact export/write/delegation을 소유하며, Studio는 사람과 자동화 호출자가 사용할 수 있도록 snapshot을 파싱, 필터링, 검사, 렌더링하는 공개 헬퍼와 viewer surface를 소유합니다. 지원되는 inspect artifact에는 raw snapshot, snapshot-plus-timing envelope, `fluo inspect --report`가 생성한 report artifact, legacy standalone timing diagnostics가 포함됩니다.
55
+ - connection state(`connecting`, `connected`, `restarting`, `reconnecting`, `stale`, `disconnected`, `error`)
56
+ - module/provider/controller/route graph node와 import/export/ownership/dependency edge
57
+ - HTTP method/path/controller handler route descriptor
58
+ - route/handler correlation, success/error, status code, duration을 포함한 최근 request flow
59
+ - bootstrap/restart/request timing summary
60
+ - severity, target, message, 가능한 fix hint가 포함된 runtime/request diagnostics
61
+
62
+ MVP request flow는 route/handler와 dependency-graph correlation을 의미합니다. full method-level service call-chain tracing은 아직 포함하지 않습니다.
63
+
64
+ ## Static/Report 호환성
65
+
66
+ Studio는 여전히 fluo CLI가 내보낸 JSON 파일을 소비합니다. 런타임은 snapshot을 생산하고, CLI는 artifact export/write/delegation을 소유하며, Studio는 사람과 자동화 호출자가 사용할 수 있도록 snapshot을 파싱, 필터링, 검사, 렌더링하는 공개 헬퍼와 viewer surface를 소유합니다. 지원되는 inspect artifact에는 raw snapshot, snapshot-plus-timing envelope, `fluo inspect --report`가 생성한 report artifact, legacy standalone timing diagnostics가 포함됩니다.
45
67
 
46
68
  1. **Snapshot 내보내기**:
47
69
  ```bash
@@ -54,68 +76,64 @@ Studio는 fluo CLI에서 내보낸 JSON 파일을 소비합니다. 런타임은
54
76
  node -p "require.resolve('@fluojs/studio/viewer')"
55
77
  ```
56
78
 
57
- 출력된 `dist/index.html` 경로를 브라우저에서 엽니다. 패키징된 viewer entry는 `@fluojs/studio/viewer`로 export되는 정적 HTML artifact이며, 모노레포 개발 서버를 시작하지 않습니다.
58
-
59
- 저장소 내부 Studio 개발에는 다음 명령을 사용합니다.
79
+ 출력된 `dist/index.html` 경로를 브라우저에서 엽니다. 저장소 내부 Studio 개발에는 다음 명령을 사용합니다.
60
80
  ```bash
61
81
  pnpm --dir packages/studio dev
62
82
  ```
63
83
 
64
84
  3. **파일 로드**: Studio 웹 인터페이스에 `snapshot.json` 파일을 드래그 앤 드롭합니다. Search와 filter control은 graph, connection explorer, diagnostics, summary가 갱신되는 동안 focus를 유지합니다.
65
85
 
66
- ## 주요 패턴
86
+ ## 로컬 보안 모델
67
87
 
68
- ### 초기화 문제 해결
69
- **Diagnostics issues** 섹션을 사용하여 런타임 부트스트랩 과정에서 수집된 이슈들을 확인합니다.
70
- - 심각도(Error, Warning)별로 필터링합니다.
71
- - `fixHint`를 통해 문제를 해결하기 위한 구체적인 조치 방법을 확인합니다.
72
- - `docsUrl`은 절대 `http:` 또는 `https:` URL일 때만 연결된 문서를 열 수 있습니다. 안전하지 않은 scheme과 상대 경로 또는 URL이 아닌 문자열은 클릭할 수 없으며, Studio는 이를 escaped text로 렌더링합니다.
73
- - `dependsOn`을 통해 어떤 컴포넌트가 실패 지점을 차단하고 있는지 확인합니다.
88
+ - Studio sidecar는 기본적으로 `127.0.0.1`에 bind됩니다.
89
+ - Runtime ingestion과 browser state/SSE API는 실행마다 생성되는 token을 요구합니다.
90
+ - Sidecar는 기본적으로 CORS를 활성화하지 않습니다.
91
+ - Request body는 기본적으로 수집하지 않습니다. Live request event는 method/path/url/request id/route/handler/status/duration/error metadata만 포함합니다.
92
+ - Runtime Studio instrumentation은 CLI가 제공한 명시적 Studio config가 있을 때만 활성화됩니다. Runtime package source는 `process.env`를 직접 읽지 않으며, 유효한 injected config가 없으면 runtime 동작은 no-op입니다.
74
93
 
75
- ### 아키텍처 다이어그램 내보내기
76
- 1. **Platform dependency graph** 섹션을 사용합니다.
77
- 2. 시각화하려는 모듈이나 컴포넌트를 선택합니다.
78
- 3. **Copy Mermaid** 버튼을 사용하여 문서에 사용할 수 있는 텍스트 기반 다이어그램을 가져옵니다.
94
+ ## 런타임 지원 매트릭스
79
95
 
80
- ### 컴포넌트 연결 탐색
81
- 그래프 노드를 선택한 뒤 **Connection explorer**를 사용하면 선택한 컴포넌트의 내부 의존성, 외부 의존성, 역방향 dependent, 관련 diagnostics를 확인할 수 있습니다. 이 흐름은 snapshot 생산을 Studio로 옮기지 않고 Devtools 스타일 탐색을 제공합니다. 런타임은 계속 producer로 남고, CLI는 export boundary로 남으며, Studio는 inspection과 rendering surface로 남습니다.
82
-
83
- 자동화에서는 `@fluojs/studio` 또는 `@fluojs/studio/contracts`에서 `renderMermaid(snapshot)`을 호출합니다. 이 헬퍼가 지원되는 snapshot-to-Mermaid 계약입니다. 런타임 패키지는 snapshot producer로 남고, Studio는 그래프 렌더링 시 내부 dependency edge와 외부 dependency node를 처리합니다.
96
+ | Runtime target | MVP expectation |
97
+ | --- | --- |
98
+ | Node dev runner | `fluo dev --studio`를 통한 full support target입니다. |
99
+ | Bun | 이번 MVP에서는 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Bun 프로젝트를 거부합니다. |
100
+ | Deno | 이번 MVP에서는 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Deno 프로젝트를 거부합니다. |
101
+ | Cloudflare Workers | 별도 worker bridge를 구현하고 검증하지 않는 한 이번 MVP에서는 unsupported입니다. |
84
102
 
85
103
  ## 공개 API
86
104
 
87
- Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 snapshot 소비 헬퍼도 함께 공개합니다. `@fluojs/studio`를 snapshot 파싱, 필터링, Mermaid 그래프 렌더링 의미론의 canonical owner로 취급합니다.
105
+ Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 계약도 함께 공개합니다. `@fluojs/studio`를 snapshot parsing, filtering, Mermaid graph rendering, live Studio event validation 의미론의 canonical owner로 취급합니다.
88
106
 
89
107
  | 규격 | 설명 |
90
108
  |---|---|
91
- | `PlatformShellSnapshot` | 애플리케이션 상태를 나타내는 핵심 데이터 구조입니다. |
92
- | `PlatformDiagnosticIssue` | 플랫폼 오류 보고 및 수정을 위한 스키마입니다. |
93
109
  | `parseStudioPayload(rawJson)` | raw snapshot JSON, standalone timing JSON, snapshot+timing envelope, `fluo inspect --report` artifact를 받아 parsed payload와 원본 JSON string을 반환합니다. |
94
- | `ParsedPayload` | `parseStudioPayload(...)`가 반환하는 parsed Studio payload shape입니다. |
95
- | `StudioPayload` | `parseStudioPayload(...)`가 반환하는 정규화된 parsed payload envelope이며, 선택적 `report`, `snapshot`, `timing` 필드를 포함합니다. |
96
- | `StudioReportArtifact` | CI/support 자동화를 위해 summary, snapshot, timing 데이터를 함께 보존한 `fluo inspect --report` artifact입니다. |
97
- | `StudioReportSummary` | report artifact에 포함되는 summary block입니다. |
98
- | `FilterState` | `applyFilters(...)`가 받는 filter configuration입니다. |
99
- | `PlatformReadinessStatus` | component filter에서 사용하는 readiness status union입니다. |
100
- | `PlatformDiagnosticSeverity` | filter와 issue에서 사용하는 diagnostic severity union입니다. |
101
- | `applyFilters(snapshot, filter)` | 원본 snapshot을 변경하지 않고 readiness/severity/query 필터를 적용합니다. |
102
- | `renderMermaid(snapshot)` | 내부 컴포넌트 dependency edge와 외부 dependency node를 포함해 로드된 플랫폼 그래프를 Mermaid 텍스트로 변환합니다. |
110
+ | `applyFilters(snapshot, filter)` | 원본 snapshot을 변경하지 않고 readiness/severity/query filter를 적용합니다. |
111
+ | `renderMermaid(snapshot)` | 내부 component dependency edge와 외부 dependency node를 포함해 로드된 platform graph를 Mermaid text로 변환합니다. |
112
+ | `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | UI state가 사용하기 전에 runtime-connected sidecar/SSE envelope를 검증합니다. |
113
+ | `isStudioLiveEvent(value)` | parsing 또는 dispatch 전에 sidecar/SSE envelope를 확인하는 runtime-safe type guard입니다. |
114
+ | `StudioLiveSnapshot` | React UI가 소비하는 live graph/routes/requests/timing/diagnostics snapshot입니다. |
115
+ | `StudioLiveEvent` | `snapshot`, `request`, `timing`, `diagnostic`, `restart`, `disconnect`, `heartbeat`를 위한 versioned live event envelope입니다. |
116
+ | `StudioPayload` / `StudioReportArtifact` / `StudioReportSummary` | Static/report 호환성 계약입니다. |
103
117
 
104
118
  ### 배포 패키지 entrypoint
105
119
 
106
- - `@fluojs/studio`: snapshot 파싱/필터링/렌더링 자동화용 루트 헬퍼 배럴
107
- - `@fluojs/studio/contracts`: 계약 헬퍼를 직접 가져오고 싶은 도구용 명시적 서브패스
108
- - `@fluojs/studio/viewer`: 브라우저 뷰어 번들의 `dist/index.html` 진입 파일
120
+ - `@fluojs/studio`: snapshot parsing/filtering/rendering과 live contract용 root helper barrel
121
+ - `@fluojs/studio/contracts`: 계약 헬퍼를 직접 가져오고 싶은 도구용 명시적 subpath
122
+ - `@fluojs/studio/viewer`: React 브라우저 viewer bundle의 `dist/index.html` entrypoint
109
123
 
110
- `@fluojs/studio`와 `@fluojs/studio/contracts`는 동등한 helper barrel을 노출합니다.
111
124
  `@fluojs/studio/viewer`는 asset-only manifest subpath입니다. 호출자는 JavaScript module이나 TypeScript declaration entrypoint가 아니라 패키징된 HTML 파일 경로를 resolve합니다.
112
125
 
126
+ ## 향후 방향
127
+
128
+ MVP는 local runtime-connected devtool입니다. 향후 릴리스에서는 cloud-hosted Studio, accounts/auth, team sharing, production monitoring dashboard, 더 풍부한 bidirectional command, VS Code extension 가능성을 제공해야 합니다. 이 기능들은 현재 shipped claim이 아닙니다.
129
+
113
130
  ## 관련 패키지
114
131
 
115
- - **[@fluojs/cli](../cli/README.ko.md)**: Studio 호환 데이터를 생성하기 위한 `inspect` 명령을 제공합니다.
116
- - **[@fluojs/runtime](../runtime/README.ko.md)**: 진단 및 snapshot 데이터를 생성하는 엔진입니다.
132
+ - **[@fluojs/cli](../cli/README.ko.md)**: `fluo dev --studio`와 inspect/export 명령을 제공합니다.
133
+ - **[@fluojs/runtime](../runtime/README.ko.md)**: live snapshot, request trace, timing, diagnostics를 생산합니다.
117
134
 
118
135
  ## 예제 소스
119
136
 
120
- - [main.ts](./src/main.ts) - 애플리케이션 진입점.
121
- - [contracts.ts](./src/contracts.ts) - snapshot 소비를 위한 타입 정의.
137
+ - [main.ts](./src/main.ts) - 테스트 호환 애플리케이션 진입점
138
+ - [main.tsx](./src/main.tsx) - React 브라우저 viewer 진입점
139
+ - [contracts.ts](./src/contracts.ts) - static/live Studio 계약 정의
package/README.md CHANGED
@@ -2,16 +2,18 @@
2
2
 
3
3
  <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
4
4
 
5
- File-first shared platform snapshot viewer and canonical graph rendering provider for fluo runtime exports.
5
+ Runtime-connected React devtool for fluo applications, with backward-compatible static/report artifact loading.
6
6
 
7
7
  ## Table of Contents
8
8
 
9
9
  - [Installation](#installation)
10
10
  - [Release Policy](#release-policy)
11
- - [When to Use](#when-to-use)
12
- - [Quick Start](#quick-start)
13
- - [Common Patterns](#common-patterns)
11
+ - [Quick Start: Live Devtool](#quick-start-live-devtool)
12
+ - [Static/Report Compatibility](#staticreport-compatibility)
13
+ - [Local Security Model](#local-security-model)
14
+ - [Runtime Support Matrix](#runtime-support-matrix)
14
15
  - [Public API](#public-api)
16
+ - [Future Direction](#future-direction)
15
17
  - [Related Packages](#related-packages)
16
18
  - [Example Sources](#example-sources)
17
19
 
@@ -21,27 +23,47 @@ File-first shared platform snapshot viewer and canonical graph rendering provide
21
23
  pnpm add @fluojs/studio
22
24
  ```
23
25
 
24
- The published package serves two caller-facing entrypoints:
26
+ The published package serves these caller-facing entrypoints:
25
27
 
26
- - `@fluojs/studio` / `@fluojs/studio/contracts` for the canonical snapshot parsing, filtering, and Mermaid graph rendering helpers.
27
- - `@fluojs/studio/viewer` for the packaged browser viewer HTML entry file.
28
+ - `@fluojs/studio` / `@fluojs/studio/contracts` for canonical snapshot parsing, filtering, Mermaid graph rendering helpers, and runtime-connected Studio live event contracts.
29
+ - `@fluojs/studio/viewer` for the packaged React browser viewer HTML entry file.
28
30
 
29
31
  ## Release Policy
30
32
 
31
33
  - `@fluojs/studio` is part of the intended public publish surface for fluo.
32
34
  - The npm install contract for Studio is `pnpm add @fluojs/studio`; local repo development still uses `pnpm --dir packages/studio dev`.
33
- - Studio's public package surface in this release is the file-first viewer and its documented snapshot-consumption, filtering, and graph rendering contracts. Internal workspace wiring is not a supported install path.
35
+ - The public package surface is additive: live devtool contracts are added while file-first parsing, filtering, graph rendering, and report artifacts remain supported.
34
36
 
35
- ## When to Use
37
+ ## Quick Start: Live Devtool
36
38
 
37
- - **Visualization**: To explore your application's module graph and dependency chains.
38
- - **Diagnostics**: To identify and fix platform-level configuration issues using guided hints.
39
- - **Performance**: To analyze bootstrap timing and identify initialization bottlenecks.
40
- - **Documentation**: To generate Mermaid diagrams of your application architecture.
39
+ Run a local app with the runtime-connected Studio sidecar:
41
40
 
42
- ## Quick Start
41
+ ```bash
42
+ fluo dev --studio
43
+ ```
44
+
45
+ `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:
46
+
47
+ ```text
48
+ [fluo] Studio listening at http://127.0.0.1:51234/?token=...
49
+ ```
50
+
51
+ 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`.
52
+
53
+ Live mode shows:
43
54
 
44
- Studio consumes 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. Supported inspect artifacts include raw snapshots, snapshot-plus-timing envelopes, report artifacts produced by `fluo inspect --report`, and legacy standalone timing diagnostics.
55
+ - connection state (`connecting`, `connected`, `restarting`, `reconnecting`, `stale`, `disconnected`, `error`);
56
+ - module/provider/controller/route graph nodes and import/export/ownership/dependency edges;
57
+ - HTTP method/path/controller handler route descriptors;
58
+ - recent request flow with route/handler correlation, success/error, status code, and duration;
59
+ - bootstrap/restart/request timing summaries;
60
+ - runtime/request diagnostics with severity, target, message, and fix hints where available.
61
+
62
+ MVP request flow intentionally means route/handler and dependency-graph correlation, not full method-level service call-chain tracing.
63
+
64
+ ## Static/Report Compatibility
65
+
66
+ 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. Supported inspect artifacts include raw snapshots, snapshot-plus-timing envelopes, report artifacts produced by `fluo inspect --report`, and legacy standalone timing diagnostics.
45
67
 
46
68
  1. **Export a snapshot**:
47
69
  ```bash
@@ -54,68 +76,64 @@ Studio consumes JSON exports from the fluo CLI. Runtime produces snapshots, the
54
76
  node -p "require.resolve('@fluojs/studio/viewer')"
55
77
  ```
56
78
 
57
- Open the printed `dist/index.html` path in a browser. The packaged viewer entry is a static HTML artifact exported as `@fluojs/studio/viewer`; it does not start the monorepo development server.
58
-
59
- For repo-local Studio development, use:
79
+ Open the printed `dist/index.html` path in a browser. For repo-local Studio development, use:
60
80
  ```bash
61
81
  pnpm --dir packages/studio dev
62
82
  ```
63
83
 
64
84
  3. **Load the file**: Drag and drop `snapshot.json` into the Studio web interface. Search and filter controls preserve focus while the graph, connection explorer, diagnostics, and summary update.
65
85
 
66
- ## Common Patterns
86
+ ## Local Security Model
67
87
 
68
- ### Troubleshooting Initialization
69
- Use the **Diagnostics issues** section to see issues collected during the runtime bootstrap process.
70
- - Filter by severity (Error, Warning).
71
- - Use `fixHint` to get actionable advice on how to resolve the issue.
72
- - Use `docsUrl` to open linked documentation when it is an absolute `http:` or `https:` URL. Unsafe schemes and relative or non-URL strings are not clickable; Studio renders them as escaped text instead.
73
- - View `dependsOn` to see which components are blocking the failing one.
88
+ - The Studio sidecar binds `127.0.0.1` by default.
89
+ - Runtime ingestion and browser state/SSE APIs require generated per-run tokens.
90
+ - The sidecar does not enable CORS by default.
91
+ - Request bodies are not captured by default. Live request events include method/path/url/request id/route/handler/status/duration/error metadata only.
92
+ - 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.
74
93
 
75
- ### Exporting Architecture Diagrams
76
- 1. Use the **Platform dependency graph** section.
77
- 2. Select the modules or components you want to visualize.
78
- 3. Use the **Copy Mermaid** button to get a text-based diagram for your documentation.
94
+ ## Runtime Support Matrix
79
95
 
80
- ### Exploring Component Connections
81
- Use the **Connection explorer** after selecting a graph node to inspect the selected component's internal dependencies, external dependencies, reverse dependents, and related diagnostics. This mirrors the Devtools-style workflow without moving snapshot production into Studio: runtime remains the producer, CLI remains the export boundary, and Studio remains the inspection and rendering surface.
82
-
83
- For automation, call `renderMermaid(snapshot)` from `@fluojs/studio` or `@fluojs/studio/contracts`. The helper is the supported snapshot-to-Mermaid contract: runtime packages remain snapshot producers, and Studio handles internal dependency edges plus external dependency nodes when rendering the graph.
96
+ | Runtime target | MVP expectation |
97
+ | --- | --- |
98
+ | Node dev runner | Full support target through `fluo dev --studio`. |
99
+ | Bun | Not enabled for this MVP; `fluo dev --studio` rejects Bun projects until a dedicated bridge is implemented and verified. |
100
+ | Deno | Not enabled for this MVP; `fluo dev --studio` rejects Deno projects until a dedicated bridge is implemented and verified. |
101
+ | Cloudflare Workers | Unsupported for this MVP unless a dedicated worker bridge is implemented and tested. |
84
102
 
85
103
  ## Public API
86
104
 
87
- Studio is primarily a web application, but the published package also exposes the documented snapshot-consumption helpers used by tooling and automation. Treat `@fluojs/studio` as the canonical owner of snapshot parsing, filtering, and Mermaid graph rendering semantics.
105
+ Studio is primarily a web application, 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.
88
106
 
89
107
  | Contract | Description |
90
108
  |---|---|
91
- | `PlatformShellSnapshot` | The core data structure representing the application state. |
92
- | `PlatformDiagnosticIssue` | Schema for reporting and fixing platform errors. |
93
109
  | `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. |
94
- | `ParsedPayload` | Parsed Studio payload shape returned by `parseStudioPayload(...)`. |
95
- | `StudioPayload` | Normalized parsed payload envelope returned by `parseStudioPayload(...)`, with optional `report`, `snapshot`, and `timing` fields. |
96
- | `StudioReportArtifact` | Preserved `fluo inspect --report` artifact with summary, snapshot, and timing data for CI/support automation. |
97
- | `StudioReportSummary` | Summary block included in report artifacts. |
98
- | `FilterState` | Filter configuration accepted by `applyFilters(...)`. |
99
- | `PlatformReadinessStatus` | Readiness status union used by component filters. |
100
- | `PlatformDiagnosticSeverity` | Diagnostic severity union used by filters and issues. |
101
110
  | `applyFilters(snapshot, filter)` | Applies readiness/severity/query filters without mutating the source snapshot. |
102
111
  | `renderMermaid(snapshot)` | Produces Mermaid graph text from the loaded platform graph, including internal component dependency edges and external dependency nodes. |
112
+ | `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | Validate runtime-connected sidecar/SSE envelopes before UI state consumes them. |
113
+ | `isStudioLiveEvent(value)` | Runtime-safe type guard for checking sidecar/SSE envelopes before parsing or dispatch. |
114
+ | `StudioLiveSnapshot` | Live graph/routes/requests/timing/diagnostics snapshot consumed by the React UI. |
115
+ | `StudioLiveEvent` | Versioned live event envelope for `snapshot`, `request`, `timing`, `diagnostic`, `restart`, `disconnect`, and `heartbeat`. |
116
+ | `StudioPayload` / `StudioReportArtifact` / `StudioReportSummary` | Static/report compatibility contracts. |
103
117
 
104
118
  ### Published package entrypoints
105
119
 
106
- - `@fluojs/studio`: root helper barrel for snapshot parsing/filtering/rendering automation.
120
+ - `@fluojs/studio`: root helper barrel for snapshot parsing/filtering/rendering and live contracts.
107
121
  - `@fluojs/studio/contracts`: explicit helper subpath for tooling that wants the contract helpers directly.
108
- - `@fluojs/studio/viewer`: packaged `dist/index.html` entrypoint for the browser viewer bundle.
122
+ - `@fluojs/studio/viewer`: packaged `dist/index.html` entrypoint for the React browser viewer bundle.
109
123
 
110
- `@fluojs/studio` and `@fluojs/studio/contracts` expose equivalent helper barrels.
111
124
  `@fluojs/studio/viewer` is an asset-only manifest subpath: callers resolve the packaged HTML file path, not a JavaScript module or TypeScript declaration entrypoint.
112
125
 
126
+ ## Future Direction
127
+
128
+ 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.
129
+
113
130
  ## Related Packages
114
131
 
115
- - **[@fluojs/cli](../cli/README.md)**: Provides the `inspect` command to generate Studio-compatible exports.
116
- - **[@fluojs/runtime](../runtime/README.md)**: The engine that generates the diagnostic and snapshot data.
132
+ - **[@fluojs/cli](../cli/README.md)**: Provides `fluo dev --studio` and inspect/export commands.
133
+ - **[@fluojs/runtime](../runtime/README.md)**: Produces live snapshots, request traces, timing, and diagnostics.
117
134
 
118
135
  ## Example Sources
119
136
 
120
- - [main.ts](./src/main.ts) - Application entry point.
121
- - [contracts.ts](./src/contracts.ts) - Type definitions for snapshot consumption.
137
+ - [main.ts](./src/main.ts) - Test-compatible application entry point.
138
+ - [main.tsx](./src/main.tsx) - React browser viewer entry point.
139
+ - [contracts.ts](./src/contracts.ts) - Static and live Studio contract definitions.