@fluojs/studio 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -2,7 +2,7 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo 런타임 내보내기의 공유 플랫폼 snapshot을 파일 기반으로 확인하는 뷰어입니다.
+fluo 런타임 내보내기의 공유 플랫폼 snapshot을 파일 기반으로 확인하고 그래프로 렌더링하는 canonical provider입니다.
 
 ## 목차
 
@@ -23,14 +23,14 @@ pnpm add @fluojs/studio
 
 배포된 패키지는 두 가지 caller-facing entrypoint를 제공합니다.
 
-- `@fluojs/studio` / `@fluojs/studio/contracts`: snapshot 파싱, 필터링, Mermaid 내보내기 헬퍼
+- `@fluojs/studio` / `@fluojs/studio/contracts`: canonical snapshot 파싱, 필터링, Mermaid 그래프 렌더링 헬퍼
 - `@fluojs/studio/viewer`: 패키징된 브라우저 뷰어 HTML 진입 파일
 
 ## 릴리스 정책
 
 - `@fluojs/studio`는 fluo의 intended public publish surface에 포함되는 공개 배포 패키지입니다.
 - Studio의 npm 설치 계약은 `pnpm add @fluojs/studio`이며, 저장소 내부 개발 경로는 계속 `pnpm --dir packages/studio dev`를 사용합니다.
-- 이번 릴리스에서 지원하는 공개 패키지 표면은 파일 기반 뷰어와 문서화된 snapshot 소비 계약까지입니다. 내부 workspace 연결 방식은 지원되는 설치 경로가 아닙니다.
+- 이번 릴리스에서 지원하는 공개 패키지 표면은 파일 기반 뷰어와 문서화된 snapshot 소비, 필터링, 그래프 렌더링 계약까지입니다. 내부 workspace 연결 방식은 지원되는 설치 경로가 아닙니다.
 
 ## 사용 시점
 
@@ -41,7 +41,7 @@ pnpm add @fluojs/studio
 
 ## 빠른 시작
 
-Studio는 fluo CLI에서 내보낸 JSON 파일을 소비합니다.
+Studio는 fluo CLI에서 내보낸 JSON 파일을 소비합니다. 런타임은 snapshot을 생산하고, CLI는 검사 데이터를 내보내거나 위임하며, Studio는 뷰어와 자동화 호출자가 사용할 수 있도록 snapshot을 파싱, 필터링, 보기, 렌더링하는 공개 헬퍼를 소유합니다.
 
 1. **Snapshot 내보내기**:
    ```bash
@@ -68,9 +68,11 @@ Studio는 fluo CLI에서 내보낸 JSON 파일을 소비합니다.
 2. 시각화하려는 모듈이나 컴포넌트를 선택합니다.
 3. **Export to Mermaid** 버튼을 사용하여 문서에 사용할 수 있는 텍스트 기반 다이어그램을 가져옵니다.
 
+자동화에서는 `@fluojs/studio` 또는 `@fluojs/studio/contracts`에서 `renderMermaid(snapshot)`을 호출합니다. 이 헬퍼가 지원되는 snapshot-to-Mermaid 계약입니다. 런타임 패키지는 snapshot producer로 남고, Studio는 그래프 렌더링 시 내부 dependency edge와 외부 dependency node를 처리합니다.
+
 ## 공개 API
 
-Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 snapshot 소비 헬퍼도 함께 공개합니다.
+Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/자동화가 사용할 수 있는 snapshot 소비 헬퍼도 함께 공개합니다. `@fluojs/studio`를 snapshot 파싱, 필터링, Mermaid 그래프 렌더링 의미론의 canonical owner로 취급합니다.
 
 | 규격 | 설명 |
 |---|---|
@@ -78,11 +80,11 @@ Studio는 주로 웹 애플리케이션이지만, 배포된 패키지는 도구/
 | `PlatformDiagnosticIssue` | 플랫폼 오류 보고 및 수정을 위한 스키마입니다. |
 | `parseStudioPayload(rawJson)` | CLI/export JSON을 Studio snapshot/timing envelope로 검증합니다. |
 | `applyFilters(snapshot, filter)` | 원본 snapshot을 변경하지 않고 readiness/severity/query 필터를 적용합니다. |
-| `renderMermaid(snapshot)` | 로드된 플랫폼 그래프를 Mermaid 텍스트로 변환합니다. |
+| `renderMermaid(snapshot)` | 내부 컴포넌트 dependency edge와 외부 dependency node를 포함해 로드된 플랫폼 그래프를 Mermaid 텍스트로 변환합니다. |
 
 ### 배포 패키지 entrypoint
 
-- `@fluojs/studio`: snapshot 파싱/필터링/렌더링용 루트 헬퍼 배럴
+- `@fluojs/studio`: snapshot 파싱/필터링/렌더링 자동화용 루트 헬퍼 배럴
 - `@fluojs/studio/contracts`: 계약 헬퍼를 직접 가져오고 싶은 도구용 명시적 서브패스
 - `@fluojs/studio/viewer`: 브라우저 뷰어 번들의 `dist/index.html` 진입 파일
 

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-File-first shared platform snapshot viewer for fluo runtime exports.
+File-first shared platform snapshot viewer and canonical graph rendering provider for fluo runtime exports.
 
 ## Table of Contents
 
@@ -23,14 +23,14 @@ pnpm add @fluojs/studio
 
 The published package serves two caller-facing entrypoints:
 
-- `@fluojs/studio` / `@fluojs/studio/contracts` for snapshot parsing, filtering, and Mermaid export helpers.
+- `@fluojs/studio` / `@fluojs/studio/contracts` for the canonical snapshot parsing, filtering, and Mermaid graph rendering helpers.
 - `@fluojs/studio/viewer` for the packaged browser viewer HTML entry file.
 
 ## 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`.
-- Studio's public package surface in this release is the file-first viewer and its documented snapshot-consumption contracts. Internal workspace wiring is not a supported install path.
+- 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.
 
 ## When to Use
 
@@ -41,7 +41,7 @@ The published package serves two caller-facing entrypoints:
 
 ## Quick Start
 
-Studio consumes JSON exports from the fluo CLI.
+Studio consumes JSON exports from the fluo CLI. Runtime produces snapshots, the CLI exports or delegates inspection data, and Studio owns the public helpers that parse, filter, view, and render those snapshots for viewer and automation callers.
 
 1. **Export a snapshot**:
    ```bash
@@ -68,9 +68,11 @@ Use the **Diagnostics** tab to see issues collected during the runtime bootstrap
 2. Select the modules or components you want to visualize.
 3. Use the **Export to Mermaid** button to get a text-based diagram for your documentation.
 
+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.
+
 ## Public API
 
-Studio is primarily a web application, but the published package also exposes the documented snapshot-consumption helpers used by tooling and automation.
+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.
 
 | Contract | Description |
 |---|---|
@@ -78,11 +80,11 @@ Studio is primarily a web application, but the published package also exposes th
 | `PlatformDiagnosticIssue` | Schema for reporting and fixing platform errors. |
 | `parseStudioPayload(rawJson)` | Validates CLI/exported JSON into the Studio snapshot/timing envelope. |
 | `applyFilters(snapshot, filter)` | Applies readiness/severity/query filters without mutating the source snapshot. |
-| `renderMermaid(snapshot)` | Produces Mermaid graph text from the loaded platform graph. |
+| `renderMermaid(snapshot)` | Produces Mermaid graph text from the loaded platform graph, including internal component dependency edges and external dependency nodes. |
 
 ### Published package entrypoints
 
-- `@fluojs/studio`: root helper barrel for snapshot parsing/filtering/rendering.
+- `@fluojs/studio`: root helper barrel for snapshot parsing/filtering/rendering automation.
 - `@fluojs/studio/contracts`: explicit helper subpath for tooling that wants the contract helpers directly.
 - `@fluojs/studio/viewer`: packaged `dist/index.html` entrypoint for the browser viewer bundle.
 

package/dist/contracts.d.ts

@@ -1,5 +1,12 @@
 import type { BootstrapTimingDiagnostics, PlatformDiagnosticIssue, PlatformShellSnapshot, PlatformSnapshot } from '@fluojs/runtime';
+export type { PlatformDiagnosticIssue, PlatformShellSnapshot } from '@fluojs/runtime';
+/**
+ * Readiness statuses supported by Studio snapshot filtering and graph annotations.
+ */
 export type PlatformReadinessStatus = PlatformSnapshot['readiness']['status'];
+/**
+ * Diagnostic severities supported by Studio snapshot filtering.
+ */
 export type PlatformDiagnosticSeverity = PlatformDiagnosticIssue['severity'];
 /**
  * Serializable Studio payload envelope built from inspect snapshot/timing exports.
@@ -42,6 +49,11 @@ export declare function applyFilters(snapshot: PlatformShellSnapshot, filter: Fi
 /**
  * Renders the loaded platform snapshot as a Mermaid dependency graph.
  *
+ * @remarks
+ * `@fluojs/studio` owns the snapshot consumption and graph rendering contract. Runtime packages remain the
+ * snapshot producers, while automation and viewer callers use this helper to turn a loaded snapshot into a
+ * stable Mermaid graph.
+ *
  * @param snapshot - The platform snapshot to render.
  * @returns Mermaid graph text suitable for docs or clipboard export.
  */

package/dist/contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,MAAM,CAAC,EAAE,0BAA0B,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IAC7C,UAAU,EAAE,0BAA0B,EAAE,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAmID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAkBjE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,WAAW,GAAG,qBAAqB,CAwCxG;AAyBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAsErE"}
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,MAAM,CAAC,EAAE,0BAA0B,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IAC7C,UAAU,EAAE,0BAA0B,EAAE,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAmID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAkBjE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,WAAW,GAAG,qBAAqB,CAwCxG;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAsErE"}

package/dist/contracts.js

@@ -1,3 +1,11 @@
+/**
+ * Readiness statuses supported by Studio snapshot filtering and graph annotations.
+ */
+
+/**
+ * Diagnostic severities supported by Studio snapshot filtering.
+ */
+
 /**
  * Serializable Studio payload envelope built from inspect snapshot/timing exports.
  */
@@ -168,6 +176,11 @@ function createExternalMermaidNodeId(value) {
 /**
  * Renders the loaded platform snapshot as a Mermaid dependency graph.
  *
+ * @remarks
+ * `@fluojs/studio` owns the snapshot consumption and graph rendering contract. Runtime packages remain the
+ * snapshot producers, while automation and viewer callers use this helper to turn a loaded snapshot into a
+ * stable Mermaid graph.
+ *
  * @param snapshot - The platform snapshot to render.
  * @returns Mermaid graph text suitable for docs or clipboard export.
  */

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { applyFilters, parseStudioPayload, renderMermaid, type FilterState, type ParsedPayload, type PlatformDiagnosticSeverity, type PlatformReadinessStatus, type StudioPayload, } from './contracts.js';
+export { applyFilters, parseStudioPayload, renderMermaid, type FilterState, type ParsedPayload, type PlatformDiagnosticIssue, type PlatformDiagnosticSeverity, type PlatformReadinessStatus, type PlatformShellSnapshot, type StudioPayload, } from './contracts.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -9,7 +9,7 @@
     "module-graph",
     "devtools"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "license": "MIT",
   "repository": {