@fluojs/studio 1.0.7 → 2.0.0

package/README.ko.md

@@ -2,6 +2,8 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
+<!-- studio-static-live-contract: static=inspect-successful-bootstrap-no-compiled-di-graph; live=node-compiled-di-graph -->
+
 fluo 진단을 위한 CLI sidecar 및 React viewer workflow입니다. Node dev-runner live MVP와 기존 static/report artifact 로딩을 함께 지원합니다.
 
 ## 목차
@@ -21,6 +23,8 @@ fluo 진단을 위한 CLI sidecar 및 React viewer workflow입니다. Node dev-r
 
 대부분의 애플리케이션 프로젝트는 Studio를 개발 전용 의존성으로 설치합니다. CLI가 `fluo dev --studio`, `fluo inspect --mermaid`, 패키징된 viewer 접근을 위해 Studio를 해석하며, 애플리케이션 런타임 자체는 Studio를 직접 import하지 않습니다.
 
+Studio는 Node.js tooling package이며 배포 package의 `engines.node` field와 동일하게 Node.js `>=24.0.0 <27`을 요구합니다. Studio는 runtime-neutral consumer-side diagnostics declaration을 소유하고 `@fluojs/runtime`을 설치하지 않으므로, 이 배포 engine floor는 runtime package로 인해 좁아지지 않습니다. 패키징된 viewer subpath는 Bun, Deno, Cloudflare Workers fallback workflow가 만든 artifact를 표시하는 경우에도 Node package resolution으로 해석합니다.
+
 ```bash
 pnpm add -D @fluojs/studio
 ```
@@ -34,7 +38,8 @@ pnpm add @fluojs/studio
 배포된 패키지는 다음 caller-facing entrypoint를 제공합니다.
 
 - `@fluojs/studio` / `@fluojs/studio/contracts`: canonical snapshot 파싱, 필터링, Mermaid graph 렌더링 헬퍼와 runtime-connected Studio live event 계약
-- `@fluojs/studio/viewer`: 패키징된 React 브라우저 viewer HTML 진입 파일
+- `fluo-studio-viewer`가 공개 실행 경로이며 패키징된 React 브라우저 viewer를 시작합니다.
+- `@fluojs/studio/viewer`는 패키징된 HTML 진입 파일이 필요한 호출자를 위한 통합용 asset-resolution 계약으로만 제공합니다.
 
 ## 릴리스 정책
 
@@ -64,18 +69,20 @@ Live mode는 다음을 보여줍니다.
 
 - connection state(`connecting`, `connected`, `restarting`, `reconnecting`, `stale`, `disconnected`, `error`)
 - module/provider/controller/route graph node와 import/export/ownership/dependency edge
-- HTTP method/path/controller handler route descriptor
+- `react-page`를 일반 `http` handler와 구분하고 effective path parameter name을 보여주는 HTTP method/path/controller handler route descriptor
 - route/handler correlation, success/error, status code, duration을 포함한 최근 request flow
-- bootstrap/restart/request timing summary
+- live 및 static/report 데이터의 bootstrap timing summary
 - severity, target, message, 가능한 fix hint가 포함된 runtime/request diagnostics
 
+Runtime inspection integration은 임의의 문자열 route `kind` marker를 유지할 수 있습니다. Live Studio wire boundary에서는 `react-page`를 별도로 유지하고, 생략된 `kind`만 `http`로 기본 설정합니다. 제공된 모든 `kind`는 문자열이어야 하며 non-string 값은 거부합니다. Studio는 허용된 route kind 문자열을 end-to-end로 보존합니다. 정규화된 각 route는 해당 route graph node의 명시적 correlation key인 `graphNodeId`도 포함하므로 viewer가 Runtime의 private node-ID 정책을 다시 구현하거나 중복될 수 있는 display label로 선택하지 않습니다. Runtime producer는 기존 graph node ID를 변경하지 않고 항상 이 field를 내보냅니다. 저장된 legacy artifact는 이를 생략할 수 있으며, Studio는 해당 input을 parse할 때 이전 `route:<sanitized-route-id>` 값을 한 번만 파생합니다.
+
 MVP request flow는 route/handler와 dependency-graph correlation을 의미합니다. full method-level service call-chain tracing은 아직 포함하지 않습니다.
 
 ## 정적/리포트 호환성
 
-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가 포함됩니다.
+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가 포함됩니다. 새 snapshot은 compiled `routes`를 포함할 수 있습니다. Studio는 문자열 `kind` 값과 parameter-name-only `params`를 검증하고, `react-page`를 **React page**로 표시하며, 임의의 route kind 문자열을 보존하고, `routes`가 없는 artifact 또는 이 field가 없는 이전 route entry는 ordinary HTTP diagnostic으로 backward-compatible하게 처리합니다. 파싱된 route 결과는 생략된 legacy `kind`를 `http`로, `params`를 `[]`로, `graphNodeId`를 이전 route-node ID 규칙으로 normalize하지만 제공된 유효하지 않은 값은 거부하며 저장된 artifact 호환성을 위해 export된 wire-input field는 optional로 유지합니다.
 
-이 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합니다.
+이 file-first 경로는 CI, support handoff, architecture review, non-Node runtime target을 위한 호환성 및 migration fallback입니다. successful bootstrap 뒤 `fluo inspect`는 `PlatformShell.snapshot()`과 routes를 읽어 보고된 platform component와 dependencies가 담긴 `PlatformShellSnapshot`을 만들며, Node live Studio가 런타임에 만드는 compiled module/provider graph나 provider scope metadata는 만들지 않습니다. Live 경로는 provider scope metadata를 포함한 compiled module, provider, controller, route graph data, 별도 bootstrap timing event, request trace event를 publish합니다. Bun, Deno, Cloudflare Workers 프로젝트는 MVP에서 live sidecar event를 기대하는 대신 inspect/static artifact를 생성하고 패키징된 `fluo-studio-viewer`로 시작해야 합니다. Compiled DI graph가 필요한 workflow는 `fluo dev --studio`를 사용하는 지원되는 Node live 경로에 남아야 합니다. HTML asset 경로가 필요한 integration은 inspected artifact가 non-Node runtime fallback workflow에서 생성된 경우에도 Node 기반 package entrypoint(`node -p "require.resolve('@fluojs/studio/viewer')"`)로 resolve합니다.
 
 1. **Snapshot 내보내기**:
    ```bash
@@ -85,10 +92,10 @@ Studio는 여전히 fluo CLI가 내보낸 JSON 파일을 소비합니다. 런타
 2. **패키징된 Studio viewer 열기**:
    ```bash
    pnpm add -D @fluojs/studio
-   node -p "require.resolve('@fluojs/studio/viewer')"
+   pnpm exec fluo-studio-viewer
    ```
 
-   출력된 `dist/index.html` 경로를 브라우저에서 엽니다. 저장소 내부 Studio 개발에는 다음 명령을 사용합니다.
+   `fluo-studio-viewer` 명령은 패키징된 viewer를 `127.0.0.1`에서 제공하고 HTTP URL을 출력합니다. `dist/index.html`을 직접 여는 대신 그 URL을 브라우저에서 여세요. `@fluojs/studio/viewer`는 패키징된 HTML entry를 resolve하는 호출자를 위한 통합용 asset-resolution 계약으로만 유지합니다. 저장소 내부 Studio 개발에는 다음 명령을 사용합니다.
    ```bash
    pnpm --dir packages/studio dev
    ```
@@ -101,7 +108,7 @@ 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를 거부합니다.
+- Live request event validation은 Studio UI state가 값을 보관하기 전에 privacy-sensitive `body`, `headers`, `payload`, `rawBody`, `requestBody`, `responseBody`를 포함한 body-like payload field를 거부합니다.
 - Runtime Studio instrumentation은 CLI가 제공한 명시적 Studio config가 있을 때만 활성화됩니다. Runtime package source는 `process.env`를 직접 읽지 않으며, 유효한 injected config가 없으면 runtime 동작은 no-op입니다.
 
 ## 런타임 지원 매트릭스
@@ -117,16 +124,18 @@ Studio는 여전히 fluo CLI가 내보낸 JSON 파일을 소비합니다. 런타
 
 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합니다.
 
+Bootstrap timing phase 이름은 `bootstrap_module`, `register_runtime_tokens`, `resolve_lifecycle_instances`, `run_bootstrap_lifecycle`, `create_dispatcher`만 허용하며, 그 밖의 모든 값은 static payload와 live timing event에서 거부됩니다.
+
 | 규격 | 설명 |
 |---|---|
 | `parseStudioPayload(rawJson)` | raw snapshot JSON, standalone timing JSON, snapshot+timing envelope, `fluo inspect --report` artifact를 받아 parsed payload와 원본 JSON string을 반환합니다. |
 | `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를 검증합니다. |
+| `renderMermaid(snapshot)` | 내부 component dependency edge와 외부 dependency node를 포함해 로드된 platform graph를 Mermaid text로 변환합니다. 필터링된 snapshot은 JSON 직렬화 전후에 동일한 Mermaid text로 결정론적으로 렌더링됩니다. |
+| `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | UI state가 사용하기 전에 runtime-connected sidecar/SSE envelope를 검증하고 normalized route entry를 반환합니다. |
 | `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 호환성 계약입니다. |
+| `StudioPayload` / `StudioInspectionSnapshot` / `StudioReportArtifact` / `StudioReportSummary` | Optional compiled route diagnostics를 포함하는 static/report 호환성 계약이며, Studio는 report artifact의 canonical seven-field summary를 렌더링하고 raw snapshot 또는 snapshot-plus-timing envelope에서는 같은 view를 파생하며 raw snapshot에 timing이 없음을 명시적으로 표시합니다. |
 
 ### Root type export
 
@@ -134,10 +143,11 @@ Studio는 주로 CLI가 실행하는 sidecar와 browser viewer이지만, 배포
 |---|---|
 | `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입니다. |
+| `PlatformDiagnosticIssue` | Studio 소비자를 위한 Studio-owned runtime-neutral diagnostic issue 계약입니다. |
 | `PlatformDiagnosticSeverity` | Filter와 live diagnostic에서 사용하는 diagnostic severity union입니다. |
 | `PlatformReadinessStatus` | Filter와 graph annotation에서 사용하는 readiness status union입니다. |
-| `PlatformShellSnapshot` | Inspect artifact를 위해 `@fluojs/runtime`에서 다시 export하는 runtime-produced snapshot type입니다. |
+| `PlatformShellSnapshot` | Inspect artifact를 위한 Studio-owned runtime-neutral snapshot 계약입니다. |
+| `StudioInspectionSnapshot` | 검증된 compiled route descriptor를 optional로 포함하는 static inspect snapshot입니다. |
 | `StudioPayload` | Snapshot, timing diagnostics, report artifact를 담을 수 있는 static artifact envelope입니다. |
 | `StudioReportArtifact` | `fluo inspect --report`가 생성하는 CI/support report artifact입니다. |
 | `StudioReportSummary` | Report artifact에 포함되는 stable summary field입니다. |
@@ -157,15 +167,19 @@ Studio는 주로 CLI가 실행하는 sidecar와 browser viewer이지만, 배포
 | `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입니다. |
+| `StudioRouteDescriptor` | `kind`, method/effective path, parameter name, controller-handler identity, optional legacy-compatible `graphNodeId` correlation을 포함하는 live/static wire-input route descriptor입니다. |
+| `StudioRouteKind` | Studio validator와 Runtime producer가 수용하는 open string route kind입니다. 임의의 문자열 marker는 보존하고, 생략된 입력은 `http`로 기본 설정하며, non-string 입력은 거부합니다. |
+| `StudioNormalizedRouteDescriptor` | 필수 `graphNodeId` correlation과 legacy `kind`, `params` default가 materialize된 parsed route descriptor입니다. |
+| `StudioParsedInspectionSnapshot` / `StudioParsedLiveSnapshot` / `StudioParsedPayload` / `StudioParsedLiveEvent` | Legacy optional wire-input contract을 보존하면서 normalized route entry를 노출하는 parsed output입니다. |
 
 ### 배포 패키지 진입점
 
 - `@fluojs/studio`: snapshot parsing/filtering/rendering과 live contract용 root helper barrel
 - `@fluojs/studio/contracts`: 계약 헬퍼를 직접 가져오고 싶은 도구용 명시적 subpath
-- `@fluojs/studio/viewer`: React 브라우저 viewer bundle의 `dist/index.html` entrypoint
+- `fluo-studio-viewer`: 패키징된 React 브라우저 viewer bundle을 위한 공개 CLI 실행 경로
+- `@fluojs/studio/viewer`: 패키징된 `dist/index.html` 파일을 위한 integration asset-resolution subpath
 
-`@fluojs/studio/viewer`는 asset-only manifest subpath입니다. 호출자는 JavaScript module이나 TypeScript declaration entrypoint가 아니라 패키징된 HTML 파일 경로를 resolve합니다.
+`@fluojs/studio/viewer`는 통합용 asset-resolution 계약으로만 제공됩니다. 호출자는 JavaScript module이나 TypeScript declaration entrypoint가 아니라 패키징된 HTML 파일 경로를 resolve합니다.
 
 ## 향후 방향
 
@@ -178,6 +192,5 @@ MVP는 local runtime-connected devtool입니다. 향후 릴리스에서는 cloud
 
 ## 예제 소스
 
-- [main.ts](./src/main.ts) - 테스트 호환 애플리케이션 진입점
 - [main.tsx](./src/main.tsx) - React 브라우저 viewer 진입점
 - [contracts.ts](./src/contracts.ts) - static/live Studio 계약 정의

package/README.md

@@ -2,6 +2,8 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
+<!-- studio-static-live-contract: static=inspect-successful-bootstrap-no-compiled-di-graph; live=node-compiled-di-graph -->
+
 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
@@ -21,6 +23,8 @@ CLI sidecar and React viewer workflow for fluo diagnostics, with a Node dev-runn
 
 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.
+
 ```bash
 pnpm add -D @fluojs/studio
 ```
@@ -34,7 +38,8 @@ pnpm add @fluojs/studio
 The published package serves these caller-facing entrypoints:
 
 - `@fluojs/studio` / `@fluojs/studio/contracts` for canonical snapshot parsing, filtering, Mermaid graph rendering helpers, and runtime-connected Studio live event contracts.
-- `@fluojs/studio/viewer` for the packaged React browser viewer HTML entry file.
+- `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
 
@@ -64,18 +69,20 @@ 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;
+- 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/restart/request timing summaries;
+- 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. Supported inspect artifacts include raw snapshots, snapshot-plus-timing envelopes, report artifacts produced by `fluo inspect --report`, and legacy standalone timing diagnostics.
+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. 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. 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.
+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 snapshot**:
    ```bash
@@ -85,10 +92,10 @@ This file-first path is the compatibility and migration fallback for CI, support
 2. **Open the packaged Studio viewer**:
    ```bash
    pnpm add -D @fluojs/studio
-   node -p "require.resolve('@fluojs/studio/viewer')"
+   pnpm exec fluo-studio-viewer
    ```
 
-   Open the printed `dist/index.html` path in a browser. For repo-local Studio development, use:
+   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:
    ```bash
    pnpm --dir packages/studio dev
    ```
@@ -101,7 +108,7 @@ This file-first path is the compatibility and migration fallback for CI, support
 - 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.
+- 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
@@ -117,16 +124,18 @@ This file-first path is the compatibility and migration fallback for CI, support
 
 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`.
 
+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. |
-| `parseStudioLiveEvent(rawJson)` / `validateStudioLiveEvent(value)` | Validate runtime-connected sidecar/SSE envelopes before UI state consumes them. |
+| `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` / `StudioReportArtifact` / `StudioReportSummary` | Static/report compatibility contracts. |
+| `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
 
@@ -134,10 +143,11 @@ Studio is primarily a CLI-launched sidecar and browser viewer, but the published
 |---|---|
 | `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. |
+| `PlatformDiagnosticIssue` | Studio-owned runtime-neutral diagnostic issue contract 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. |
+| `PlatformShellSnapshot` | Studio-owned runtime-neutral snapshot contract for inspect artifacts. |
+| `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. |
@@ -157,15 +167,19 @@ Studio is primarily a CLI-launched sidecar and browser viewer, but the published
 | `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. |
+| `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.
 - `@fluojs/studio/contracts`: explicit helper subpath for tooling that wants the contract helpers directly.
-- `@fluojs/studio/viewer`: packaged `dist/index.html` entrypoint for the React browser viewer bundle.
+- `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 an asset-only manifest subpath: callers resolve the packaged HTML file path, not a JavaScript module or TypeScript declaration entrypoint.
+`@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.
 
 ## Future Direction
 
@@ -178,6 +192,5 @@ The MVP is local and runtime-connected. Future releases should consider, but do
 
 ## Example Sources
 
-- [main.ts](./src/main.ts) - Test-compatible application entry point.
 - [main.tsx](./src/main.tsx) - React browser viewer entry point.
 - [contracts.ts](./src/contracts.ts) - Static and live Studio contract definitions.