@fluojs/studio 1.0.5 → 1.0.7

package/README.ko.md

@@ -2,14 +2,14 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo 애플리케이션을 위한 runtime-connected React devtool이며, 기존 static/report artifact 로딩도 계속 지원합니다.
+fluo 진단을 위한 CLI sidecar 및 React viewer workflow입니다. Node dev-runner live MVP와 기존 static/report artifact 로딩을 함께 지원합니다.
 
 ## 목차
 
 - [설치](#설치)
 - [릴리스 정책](#릴리스-정책)
-- [빠른 시작: Live Devtool](#빠른-시작-live-devtool)
-- [Static/Report 호환성](#staticreport-호환성)
+- [빠른 시작: 라이브 개발 도구](#빠른-시작-라이브-개발-도구)
+- [정적/리포트 호환성](#정적리포트-호환성)
 - [로컬 보안 모델](#로컬-보안-모델)
 - [런타임 지원 매트릭스](#런타임-지원-매트릭스)
 - [공개 API](#공개-api)
@@ -19,6 +19,14 @@ fluo 애플리케이션을 위한 runtime-connected React devtool이며, 기존
 
 ## 설치
 
+대부분의 애플리케이션 프로젝트는 Studio를 개발 전용 의존성으로 설치합니다. CLI가 `fluo dev --studio`, `fluo inspect --mermaid`, 패키징된 viewer 접근을 위해 Studio를 해석하며, 애플리케이션 런타임 자체는 Studio를 직접 import하지 않습니다.
+
+```bash
+pnpm add -D @fluojs/studio
+```
+
+배포 패키지나 runtime automation이 실행 중에 `@fluojs/studio` 또는 `@fluojs/studio/contracts`를 import하는 경우에만 일반 dependency로 설치합니다.
+
 ```bash
 pnpm add @fluojs/studio
 ```
@@ -31,10 +39,10 @@ pnpm add @fluojs/studio
 ## 릴리스 정책
 
 - `@fluojs/studio`는 fluo의 intended public publish surface에 포함되는 공개 배포 패키지입니다.
-- Studio의 npm 설치 계약은 `pnpm add @fluojs/studio`이며, 저장소 내부 개발 경로는 계속 `pnpm --dir packages/studio dev`를 사용합니다.
+- 애플리케이션 쪽 CLI/viewer 계약은 개발 전용 설치(`pnpm add -D @fluojs/studio`)입니다. Studio helper를 import하는 runtime tooling은 일반 dependency(`pnpm add @fluojs/studio`)로 선언해야 합니다. 저장소 내부 개발 경로는 계속 `pnpm --dir packages/studio dev`를 사용합니다.
 - 공개 패키지 표면은 additive입니다. live devtool 계약을 추가하면서도 file-first parsing, filtering, graph rendering, report artifact 호환성을 유지합니다.
 
-## 빠른 시작: Live Devtool
+## 빠른 시작: 라이브 개발 도구
 
 로컬 앱을 runtime-connected Studio sidecar와 함께 실행합니다.
 
@@ -48,7 +56,9 @@ fluo dev --studio
 [fluo] Studio listening at http://127.0.0.1:51234/?token=...
 ```
 
-그 URL을 열면 live React Studio dashboard에서 런타임 상태를 볼 수 있습니다. Dashboard 코드는 `src/app`, `src/pages`, `src/widgets`, `src/features`, `src/entities`, `src/shared`의 Feature-Sliced Design layer로 구성됩니다.
+그 URL을 열면 live React Studio dashboard에서 런타임 상태를 볼 수 있습니다. Dashboard 코드는 `src/app`, `src/pages`, `src/widgets`, `src/features`, `src/entities`, `src/shared`의 Feature-Sliced Design layer로 구성되며, static/report viewer가 여러 widget에서 공유하는 rendering helper는 root-level viewer file이 아니라 `src/shared/lib`에 둡니다.
+
+Studio는 CLI가 실행하는 sidecar/viewer workflow입니다. fluo runtime 안에 mount하는 application module이 아닙니다. Live MVP는 Node dev-runner 경로를 대상으로 하며, non-Node 프로젝트는 dedicated Bun, Deno, Workers bridge가 구현되고 검증될 때까지 정적/리포트 inspect workflow를 사용해야 합니다.
 
 Live mode는 다음을 보여줍니다.
 
@@ -61,10 +71,12 @@ Live mode는 다음을 보여줍니다.
 
 MVP request flow는 route/handler와 dependency-graph correlation을 의미합니다. full method-level service call-chain tracing은 아직 포함하지 않습니다.
 
-## Static/Report 호환성
+## 정적/리포트 호환성
 
 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가 포함됩니다.
 
+이 file-first 경로는 CI, support handoff, architecture review, non-Node runtime target을 위한 호환성 및 migration fallback입니다. Bun, Deno, Cloudflare Workers 프로젝트는 MVP에서 live sidecar event를 기대하는 대신 inspect/static artifact를 생성하고 패키징된 viewer로 열어야 합니다. 패키징된 viewer는 inspected artifact가 non-Node runtime fallback workflow에서 생성된 경우에도 Node 기반 package entrypoint(`node -p "require.resolve('@fluojs/studio/viewer')"`)로 resolve합니다.
+
 1. **Snapshot 내보내기**:
    ```bash
    fluo inspect ./src/app.module.ts --json > snapshot.json
@@ -89,20 +101,21 @@ Studio는 여전히 fluo CLI가 내보낸 JSON 파일을 소비합니다. 런타
 - Runtime ingestion과 browser state/SSE API는 실행마다 생성되는 token을 요구합니다.
 - Sidecar는 기본적으로 CORS를 활성화하지 않습니다.
 - Request body는 기본적으로 수집하지 않습니다. Live request event는 method/path/url/request id/route/handler/status/duration/error metadata만 포함합니다.
+- Live request event validation은 Studio UI state가 값을 보관하기 전에 `body`, `rawBody`, `requestBody`, `responseBody` 같은 body-like payload field를 거부합니다.
 - Runtime Studio instrumentation은 CLI가 제공한 명시적 Studio config가 있을 때만 활성화됩니다. Runtime package source는 `process.env`를 직접 읽지 않으며, 유효한 injected config가 없으면 runtime 동작은 no-op입니다.
 
 ## 런타임 지원 매트릭스
 
 | Runtime target | MVP expectation |
 | --- | --- |
-| Node dev runner | `fluo dev --studio`를 통한 full support target입니다. |
-| Bun | 이번 MVP에서는 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Bun 프로젝트를 거부합니다. |
-| Deno | 이번 MVP에서는 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Deno 프로젝트를 거부합니다. |
-| Cloudflare Workers | 별도 worker bridge를 구현하고 검증하지 않는 한 이번 MVP에서는 unsupported입니다. |
+| Node dev-runner | `fluo dev --studio`를 통한 live sidecar support target입니다. CLI가 명시적인 Studio runtime config를 Node 앱 child에 주입하고 snapshot/request/timing/diagnostic lifecycle event를 stream합니다. Static inspect artifact도 계속 지원합니다. |
+| Bun | 이번 MVP에서는 live sidecar event를 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Bun 프로젝트를 거부합니다. Migration fallback으로 `fluo inspect` JSON/report artifact, Mermaid output, 패키징된 viewer를 사용합니다. |
+| Deno | 이번 MVP에서는 live sidecar event를 활성화하지 않습니다. Dedicated bridge를 구현하고 검증하기 전까지 `fluo dev --studio`는 Deno 프로젝트를 거부합니다. Migration fallback으로 `fluo inspect` JSON/report artifact, Mermaid output, 패키징된 viewer를 사용합니다. |
+| Cloudflare Workers | 별도 worker bridge를 구현하고 검증하지 않는 한 이번 MVP에서는 live sidecar event가 unsupported입니다. Migration fallback으로 static inspect/report artifact와 패키징된 viewer를 사용합니다. |
 
 ## 공개 API
 
-Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 계약도 함께 공개합니다. `@fluojs/studio`를 snapshot parsing, filtering, Mermaid graph rendering, live Studio event validation 의미론의 canonical owner로 취급합니다.
+Studio는 주로 CLI가 실행하는 sidecar와 browser viewer이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 계약도 함께 공개합니다. `@fluojs/studio`를 snapshot parsing, filtering, Mermaid graph rendering, live Studio event validation 의미론의 canonical owner로 취급합니다. Root `@fluojs/studio` export는 `@fluojs/studio/contracts`의 helper function과 public type을 다시 export합니다.
 
 | 규격 | 설명 |
 |---|---|
@@ -110,11 +123,43 @@ Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/
 | `applyFilters(snapshot, filter)` | 원본 snapshot을 변경하지 않고 readiness/severity/query filter를 적용합니다. |
 | `renderMermaid(snapshot)` | 내부 component dependency edge와 외부 dependency node를 포함해 로드된 platform graph를 Mermaid text로 변환합니다. |
 | `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | UI state가 사용하기 전에 runtime-connected sidecar/SSE envelope를 검증합니다. |
+| `isStudioLiveEvent(value)` | parsing 또는 dispatch 전에 sidecar/SSE envelope를 확인하는 runtime-safe type guard입니다. |
 | `StudioLiveSnapshot` | React UI가 소비하는 live graph/routes/requests/timing/diagnostics snapshot입니다. |
 | `StudioLiveEvent` | `snapshot`, `request`, `timing`, `diagnostic`, `restart`, `disconnect`, `heartbeat`를 위한 versioned live event envelope입니다. |
 | `StudioPayload` / `StudioReportArtifact` / `StudioReportSummary` | Static/report 호환성 계약입니다. |
 
-### 배포 패키지 entrypoint
+### Root type export
+
+| Type export | 설명 |
+|---|---|
+| `FilterState` | 원본 snapshot을 변경하지 않고 Studio가 적용하는 query, readiness status, diagnostic severity filter입니다. |
+| `ParsedPayload` | `parseStudioPayload(rawJson)`의 반환 shape로, parsed `StudioPayload`와 원본 JSON string을 포함합니다. |
+| `PlatformDiagnosticIssue` | Studio 소비자를 위해 `@fluojs/runtime`에서 다시 export하는 runtime diagnostic issue type입니다. |
+| `PlatformDiagnosticSeverity` | Filter와 live diagnostic에서 사용하는 diagnostic severity union입니다. |
+| `PlatformReadinessStatus` | Filter와 graph annotation에서 사용하는 readiness status union입니다. |
+| `PlatformShellSnapshot` | Inspect artifact를 위해 `@fluojs/runtime`에서 다시 export하는 runtime-produced snapshot type입니다. |
+| `StudioPayload` | Snapshot, timing diagnostics, report artifact를 담을 수 있는 static artifact envelope입니다. |
+| `StudioReportArtifact` | `fluo inspect --report`가 생성하는 CI/support report artifact입니다. |
+| `StudioReportSummary` | Report artifact에 포함되는 stable summary field입니다. |
+| `StudioConnectionState` | Live 또는 static Studio session을 위한 UI-side connection state입니다. |
+| `StudioConnectionStatus` | Live lifecycle state와 `static`을 포함하는 connection status union입니다. |
+| `StudioDisconnectPayload` | Live disconnect lifecycle payload입니다. |
+| `StudioGraphEdge` | Runtime-connected Studio dependency graph의 serializable edge입니다. |
+| `StudioGraphEdgeKind` | Import, ownership, route exposure, dependency, export 관계를 나타내는 edge kind union입니다. |
+| `StudioGraphNode` | Runtime-connected Studio dependency graph의 serializable node입니다. |
+| `StudioGraphNodeKind` | Module, provider, controller, route, platform node, external dependency를 나타내는 node kind union입니다. |
+| `StudioHeartbeatPayload` | Sidecar/UI session을 fresh 상태로 유지하는 live heartbeat payload입니다. |
+| `StudioLiveDiagnostic` | Live diagnostics panel에 표시되는 runtime diagnostic shape입니다. |
+| `StudioLiveEvent` | Snapshot, request, timing, diagnostic, restart, disconnect, heartbeat를 위한 versioned sidecar/SSE event union입니다. |
+| `StudioLiveEventBase` | 모든 live Studio event가 공유하는 generic base envelope입니다. |
+| `StudioLiveEventSource` | Live Studio event에 붙는 app/runtime source metadata입니다. |
+| `StudioLiveSnapshot` | React UI가 소비하는 live graph/routes/requests/timing/diagnostics snapshot입니다. |
+| `StudioRequestStatus` | Live request trace에서 쓰는 request lifecycle status union입니다. |
+| `StudioRequestTrace` | Request/response body 없이 emit되는 request trace metadata입니다. |
+| `StudioRestartPayload` | CLI-owned dev supervision이 emit하는 runtime/app restart lifecycle payload입니다. |
+| `StudioRouteDescriptor` | Live Studio UI에 투영되는 route descriptor입니다. |
+
+### 배포 패키지 진입점
 
 - `@fluojs/studio`: snapshot parsing/filtering/rendering과 live contract용 root helper barrel
 - `@fluojs/studio/contracts`: 계약 헬퍼를 직접 가져오고 싶은 도구용 명시적 subpath

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-Runtime-connected React devtool for fluo applications, with backward-compatible static/report artifact loading.
+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
 
@@ -19,6 +19,14 @@ Runtime-connected React devtool for fluo applications, with backward-compatible
 
 ## 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.
+
+```bash
+pnpm add -D @fluojs/studio
+```
+
+Use a regular dependency only when a published package or runtime automation imports `@fluojs/studio` or `@fluojs/studio/contracts` at runtime:
+
 ```bash
 pnpm add @fluojs/studio
 ```
@@ -31,7 +39,7 @@ The published package serves these caller-facing entrypoints:
 ## Release Policy
 
 - `@fluojs/studio` is part of the intended public publish surface for fluo.
-- The npm install contract for Studio is `pnpm add @fluojs/studio`; local repo development still uses `pnpm --dir packages/studio dev`.
+- 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 is additive: live devtool contracts are added while file-first parsing, filtering, graph rendering, and report artifacts remain supported.
 
 ## Quick Start: Live Devtool
@@ -48,7 +56,9 @@ fluo dev --studio
 [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`.
+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:
 
@@ -65,6 +75,8 @@ MVP request flow intentionally means route/handler and dependency-graph correlat
 
 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.
 
+This file-first path is the compatibility and migration fallback for CI, support handoffs, architecture reviews, and non-Node runtime targets. Bun, Deno, and Cloudflare Workers projects should generate inspect/static artifacts and open them with the packaged viewer instead of expecting live sidecar events in the MVP. The packaged viewer is resolved through 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 snapshot**:
    ```bash
    fluo inspect ./src/app.module.ts --json > snapshot.json
@@ -89,20 +101,21 @@ Studio still accepts JSON exports from the fluo CLI. Runtime produces snapshots,
 - 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 such as `body`, `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 | Full support target through `fluo dev --studio`. |
-| Bun | Not enabled for this MVP; `fluo dev --studio` rejects Bun projects until a dedicated bridge is implemented and verified. |
-| Deno | Not enabled for this MVP; `fluo dev --studio` rejects Deno projects until a dedicated bridge is implemented and verified. |
-| Cloudflare Workers | Unsupported for this MVP unless a dedicated worker bridge is implemented and tested. |
+| 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 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.
+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 `@fluojs/studio` export re-exports the helper functions and public types from `@fluojs/studio/contracts`.
 
 | Contract | Description |
 |---|---|
@@ -110,10 +123,42 @@ Studio is primarily a web application, but the published package also exposes do
 | `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. |
 | `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | Validate runtime-connected sidecar/SSE envelopes 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` / `StudioReportArtifact` / `StudioReportSummary` | Static/report compatibility contracts. |
 
+### 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. |
+| `PlatformDiagnosticIssue` | Runtime diagnostic issue type re-exported from `@fluojs/runtime` for Studio consumers. |
+| `PlatformDiagnosticSeverity` | Diagnostic severity union used by filters and live diagnostics. |
+| `PlatformReadinessStatus` | Readiness status union used by filters and graph annotations. |
+| `PlatformShellSnapshot` | Runtime-produced snapshot type re-exported from `@fluojs/runtime` for inspect artifacts. |
+| `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` | Route descriptor projected into the live Studio UI. |
+
 ### Published package entrypoints
 
 - `@fluojs/studio`: root helper barrel for snapshot parsing/filtering/rendering and live contracts.