fix(website): review the graph doc pages and fix the 3D viewer edge-kind mapping#309
Merged
Conversation
`ttscgraph dump` emits the fine-grained wire kinds (calls, instantiates, renders, accesses, type_ref, extends, implements), but the 3D viewers color and label edges by the three display families (value-call, type-ref, heritage). None of the reduce implementations mapped between the two, so a freshly dumped graph rendered every edge with the fallback color and the legend matched nothing. Collapse the wire kinds into the display families in all three mirrored reduces (bundled CLI, website, experimental); pre-reduced payloads and unknown kinds pass through. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N3Cn3zmu1uUVkYJfwyPFeJ
A pass over the four /docs/graph pages built from the launch post, fixing what read abrupt, thin, or stale: - Overview: correct the resident-graph claim (the native binary dumps once; the Node server answers from the in-memory graph, there is no warm checker), say graph not map, add the source-crawl hero image, a diagnostics bullet, and embed the live 3D viewer. - Design: explain the `clarify` follow-up action, move the prosthesis-to-hammer image here where CoT compliance is actually defined, and drop the last map wording. - Comparison: replace the out-of-context CoT-compliance image with a prose pointer to Design. - Viewer: correct the dump description (project-relative ids, no absolute-path keying), document the view flags, name the example repos, tie the three edge families to the full edge-kind set, and spell out the reduction (external, git-ignored, degree cap, orphans). - Setup: same map -> graph wording fix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N3Cn3zmu1uUVkYJfwyPFeJ
Contributor
There was a problem hiding this comment.
Pull request overview
This PR does a focused refresh of the Graph documentation pages and fixes a real viewer defect where newly dumped graphs (with fine-grained edge kinds like calls, type_ref, etc.) rendered with fallback styling because the 3D viewer expects the three display families (value-call, type-ref, heritage).
Changes:
- Add an explicit edge-kind “wire → display family” mapping in all three mirrored reduction pipelines (package CLI/server, website viewer, benchmark tooling).
- Update
/docs/graph/*pages and the setup docs for clarity/correctness (resident-graph wording, viewer usage/flags, reduction steps, and updated cross-references). - Embed the live 3D viewer component on the Graph overview page and improve viewer doc explanations (examples, edge-family meanings, reduction order).
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| website/src/content/docs/setup.mdx | Updates wording from “map” to “graph” for @ttsc/graph setup docs. |
| website/src/content/docs/graph/viewer.mdx | Clarifies viewer usage (view flags, dump semantics), edge families vs kinds, and reduction steps. |
| website/src/content/docs/graph/index.mdx | Fixes resident-graph explanation, adds hero image, diagnostics bullet, and embeds the live 3D viewer. |
| website/src/content/docs/graph/design.mdx | Adds/relocates the CoT compliance image and clarifies the clarify follow-up action; tweaks wording. |
| website/src/content/docs/graph/compare.mdx | Replaces an out-of-place image block with a prose pointer to the Design page. |
| website/src/components/graph/TtscWebsiteGraphReduce.ts | Maps fine-grained dumped edge kinds into the viewer’s three display families during reduction. |
| packages/graph/src/reduce.ts | Mirrors the same edge-kind family mapping in the Node-side reducer used by @ttsc/graph view. |
| experimental/benchmark/graph/viewer.mjs | Mirrors the same mapping in the benchmark viewer reducer to keep pipelines consistent. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
samchon
changed the title
…g it Loading three.js, the force-graph engine, and a multi-megabyte example graph on the docs overview page is too heavy for an entry page that already carries the interactive benchmark chart. Replace the embedded viewer with a static TypeORM render linking to the dedicated viewer page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N3Cn3zmu1uUVkYJfwyPFeJ
Owner
Author
|
Follow-up: dropped the embedded 3D viewer from the overview page (three.js + a multi-MB example graph is too heavy for an entry page) and replaced it with a static TypeORM render linking to the dedicated viewer page. |
…embedding it" This reverts commit 1fcdb0b.
Owner
Author
|
Correction: the previous follow-up was a misread of the review feedback. The embedded 3D viewer on the overview page is intentional and is now restored (revert of 1fcdb0b). Final state: the overview embeds the live viewer component in section 3.2. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
A self-contained review pass over the four
/docs/graphpages (built from the launch post), fixing what read abrupt, thin, or factually stale, plus one real defect the review surfaced in the 3D viewer pipeline.Scope
Viewer edge-kind mapping (fix).
ttscgraph dumpemits fine-grained wire kinds (calls,instantiates,renders,accesses,type_ref,extends,implements), but the 3D viewers color and label edges by the three display families (value-call,type-ref,heritage). No reduce mapped between the two, so a freshly dumped graph uploaded to the viewer rendered every edge with the fallback color and the legend matched nothing (the shipped example payloads predate the fine-grained kinds, which hid it). The mapping is added to all three mirrored reduces:packages/graph/src/reduce.ts,website/src/components/graph/TtscWebsiteGraphReduce.ts,experimental/benchmark/graph/viewer.mjs.Docs.
clarifyfollow-up action, move the CoT-compliance image here where the concept is defined.viewflags, name the example repos, tie the three edge families to the full edge-kind set, and spell out the reduction steps.Deferred
website/public/graph/*.jsonstill carry the old family kinds; they render correctly (pre-reduced payloads bypass the mapping) and were not regenerated.Test plan
tsc --noEmitpasses inpackages/graphandwebsite.calls/type_ref/extends/accessesedges reduces tovalue-call/type-ref/heritage/value-call(was: kinds passed through and rendered colorless).🤖 Generated with Claude Code
https://claude.ai/code/session_01N3Cn3zmu1uUVkYJfwyPFeJ