codemble 0.5.3__tar.gz → 0.6.1__tar.gz

{codemble-0.5.3 → codemble-0.6.1}/.gitignore

@@ -34,3 +34,4 @@ graphify-out/
 
 # Subagent-driven-development scratch coordination (not product truth)
 .superpowers/
+.remember

{codemble-0.5.3 → codemble-0.6.1}/CHANGELOG.md

@@ -5,6 +5,86 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-07-21
+
+### Fixed
+- **The full learning loop now fits a 320 px window.** A compact Menu replaces
+  the crowded action rail, the architecture Map waits for real layout
+  dimensions before fitting, guidance gets its own row instead of covering Map
+  controls, and Study becomes a full-stage reading sheet. The header, canvas,
+  guidance, and local-only status remain visible without horizontal overflow.
+- **Modules and Find work from the Star chart.** Both global commands now render
+  their surface in chart mode instead of accepting a click into hidden state
+  that only appeared after returning to the galaxy.
+- **First-run guidance no longer competes with Home calibration.** After an
+  audience is chosen, a required Home choice finishes before the three-step
+  coach opens, so there is one decision in the foreground at a time.
+- **Canvas clicks no longer corrupt OrbitControls pointer state.** Codemble's
+  parser-owned node layout is now explicitly non-draggable, preventing the 3D
+  dependency's drag-end bridge from injecting a synthetic touch release into a
+  mouse release. A stale-pointer guard and focused contract pin the fallback.
+
+## [0.6.0] - 2026-07-21
+
+### Added
+- **You can move the camera.** Dragging now orbits around whatever you are
+  looking at, and the wheel zooms. Panning stays off and both rotation and zoom
+  are clamped per level, so the thing you are studying can never leave the
+  screen — "you cannot get lost" still holds. Changing level is now click,
+  Enter, Escape, or the breadcrumb, because one gesture cannot mean both zoom
+  and travel.
+- **Systems have names.** The most important stars carry their filename on the
+  canvas — Home first, then modules you have proved, then the ones most of your
+  project calls — with more names appearing as you zoom in and none allowed to
+  overlap another.
+- **Find any module by name.** `⌘K` / `Ctrl-K` opens a filter-as-you-type jump
+  list, and a new Modules rail lists every file grouped by the import
+  communities the galaxy already places together. Both reach every module,
+  including ones the sky has not charted yet.
+
+### Changed
+- Project selection, project activation, project mapping, the galaxy Name
+  Atlas, and the Learner Projection now each sit behind one focused module
+  interface. The HTTP API, parser graph, checks, persistence, and learner-visible
+  interactions are unchanged; focused contract suites pin each new seam.
+- Learner projections are now dependency-scoped and indexed instead of being
+  recomputed on every session commit. A 1,000-node hover benchmark dropped from
+  about 0.331 ms to 0.001 ms per commit, and hover-only commits preserve the
+  identity of every unaffected graph, map, chart, reveal, hint, and module-index
+  projection so the 3D renderer does not rebuild stable scene data.
+- **The galaxy no longer draws your whole project at once.** It opens on Home
+  and everything within two import routes of it; proving a module reveals what
+  it connects to, so the map is uncovered by understanding. Modules you have not
+  reached are still drawn — faint, unnamed, and without their routes — so the
+  project's real size is never misreported, and they stay clickable. A
+  **Show all** toggle draws everything whenever you want it. On a 90-system
+  project this is 22 systems and their routes instead of 90 and theirs.
+- **The canvas got its stage back.** The display-size heading that covered the
+  left half of the view is now one line of text (`90 systems · 22 charted`), the
+  module path at system level lives in the breadcrumb instead of wrapping across
+  three lines, and the twelve-row legend is behind a **Key** button.
+- **Map boxes say which module they are.** A box is a fixed width, and it used
+  to truncate the dotted module id — so `codemble.server.app` and
+  `codemble.server.runtime` both read `codemble.server…`, two different modules
+  showing identical text. Boxes are now named by the tail of their real path
+  (`server/app.py`, `server/runtime.py`); the full identifier is still in the
+  tooltip and read out to screen readers.
+- **You can zoom and pan the Map.** The architecture diagram is far taller than
+  the window — on this project, nine import layers of which about four were
+  visible. Zoom in and out, drag empty space to pan, or press **Fit** to see the
+  whole shape at once. Every coordinate is still the one the backend computed;
+  zoom only changes how large it is drawn.
+- The 2D Architecture map is now a deterministic layered diagram rather than
+  a straight-line grid: four barycenter sweeps reduce import-edge crossings,
+  backend-assigned ports keep fan-out distinct, weighted arrowed paths expose
+  direction, and cycles or long routes travel around the diagram flank. Possible
+  relationships remain dashed, and React still consumes graph-owned geometry.
+- Galaxy systems now form deterministic constellations from parser-proven
+  import communities instead of scattering solely by identifier hash. The
+  additive `community` region field is exposed in graph schema 5 for later
+  renderers, while progress, Home, and system-internal orbital layout stay
+  unchanged.
+
 ## [0.5.3] - 2026-07-21
 
 ### Fixed

{codemble-0.5.3 → codemble-0.6.1}/CLAUDE.md

@@ -167,13 +167,29 @@ Polish, then the coordinated launch (Show HN / X; lit-galaxy GIF as hero).
 
 ## Current State **[AGENT-MAINTAINED]**
 
-**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-20 ·
-Session note: architecture-deepening maintenance is complete after the verified
-v0.2.0 release; all four report recommendations are merged in phases while issue
-#13 remains open for human tester evidence. The public site was then redesigned
-to the Formal Edo palette and Edo star-atlas genre, with an expanding Pagefind
-search shared by the landing and docs; no parser, graph, checks, persistence, or
-app behaviour was touched. A tester-run rehearsal of the shipped loop then
+**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-21 ·
+Session note: v0.6.1 closes the four verified user-flow gaps from the
+2026-07-21 usability audit: the 320 px shell reserves a usable map/study stage,
+Modules and Find render from the Star chart, required Home calibration finishes
+before coach marks begin, and parser-owned 3D nodes no longer install drag
+controls that can corrupt OrbitControls pointer state. The release is verified
+against the real bundled app at desktop and 320 px widths; the milestone does
+not advance because issue #13 still requires human tester evidence. The v0.6.0
+architecture-depth pass is complete in five
+behavior-preserving waves: project selection owns the home-jailed filesystem
+policy; project activation atomically owns parse-to-live binding and graph/map
+caches; project mapping owns picker attempts, polling, retry, outage, stale
+responses, and release; the Name Atlas owns deterministic plate placement; and
+the indexed Learner Projection reuses every unaffected derived view. The
+1,000-node hover benchmark moved from ~0.331 ms to ~0.001 ms per commit, while
+the HTTP, graph, check, persistence, and UI contracts stayed fixed. The current
+milestone does not advance: issue #13 still requires human tester evidence.
+Earlier architecture-deepening maintenance completed after the verified v0.2.0
+release; all four report recommendations merged in phases. The public site was
+then redesigned to the Formal Edo palette and Edo star-atlas genre, with an
+expanding Pagefind search shared by the landing and docs; no parser, graph,
+checks, persistence, or app behaviour was touched. A tester-run rehearsal of
+the shipped loop then
 verified Home calibration, study source, checks, illumination, and restart
 persistence end to end, and found one real defect: multi-answer checks with four
 or more answers offered no wrong option, so select-all lit a region without
@@ -230,7 +246,42 @@ rebind a released project. Phase C plus that gap-fix wave shipped as **v0.5.0**;
 the parse work collided with an independent implementation of the same three
 foundational commits on `main`, reconciled by taking the branch's verified
 superset while preserving main's unique `CODEMBLE_DATA_DIR`/config-isolation
-fix, which lived in files the branch never touched.
+fix, which lived in files the branch never touched. The Architecture map now
+uses deterministic barycenter ordering and backend-routed, directional,
+weight-scaled SVG paths; cycle and long-span routes use clear flank corridors,
+while possible relationships remain dashed and React remains a pure renderer.
+Galaxy regions now place in deterministic constellations derived only from
+parser-proven import communities, with the community ID exposed in graph schema
+5 and progress signatures remaining coordinate-independent. A tester then
+reported the 169-system galaxy unnavigable and undifferentiated, which resolved
+into four separate defects: the camera could not move at all, no star carried a
+name and there was no search or index, every region route drew unconditionally
+so the mesh outshone the stars, and a display-size heading plus a twelve-row
+always-on legend covered the stage. All four are fixed — bounded orbit,
+progressive reveal keyed to a new `hops_from_home` graph field (schema 6),
+ranked and decluttered name plates, a command palette plus an index sidebar over
+one shared module index, and chrome demoted to a single line with the legend
+behind a disclosure. On this repository the default galaxy went from 90 systems
+with their whole route mesh to 22 charted with the rest drawn faint, unnamed and
+edgeless; nothing was removed from the graph and no region re-dimmed. Four
+defects were caught by running it rather than by the suite: a sprite map cleared
+by an effect that ran after the one that filled it, an undefined constant that
+threw inside the declutter timer and silently erased every name, plates that
+claimed one screen cell regardless of their real width, and an open sidebar
+occluding the system panel's primary action. A fifth followed: labels offered
+only one position each, directly above their star, so at galaxy zoom nearly
+every plate lost its slot to a neighbour and a 90-system sky carried one name.
+Names now try a short list of slots around the star and collision-test where the
+plate actually draws rather than where its star sits — 1 name became roughly 24
+with everything shown, 9 by default. The same navigation and clarity pass was
+then applied to the Map layer, where two of the three galaxy problems turned out
+to exist in a sharper form: a fixed-width box truncated the dotted region id, so
+`codemble.server.app` and `codemble.server.runtime` both rendered as
+`codemble.server…` — identical text for different modules — and a 960x2640
+diagram sat in a plain scroll box showing four of its nine import layers. Boxes
+are now named by the tail of their real path (map schema 3, zero visible-text
+collisions across all 90 boxes on this repository) and the Map gained zoom, Fit,
+and drag-to-pan. Progressive reveal was deliberately not extended to the Map.
 
 ### M0 — Repo, docs & website scaffold ✅ (2026-07-19)
 - [x] Root: README, LICENSE (Apache-2.0), CoC, SECURITY, CONTRIBUTING,
@@ -396,6 +447,23 @@ interactive galaxy; re-fetching the graph does not re-sort the world; the scale
 prompt is actionable entirely in-app; generated check suites are byte-identical
 to before the index change.
 
+### M14 — Architecture depth and indexed learner views ✅ (2026-07-21)
+- [x] Put canonical browse-root resolution, folder listing, and recent-project
+      filtering behind `ProjectSelector`
+- [x] Make parse-to-live binding, stale-worker refusal, release, and graph/map
+      cache lifetime atomic behind `ProjectActivation`
+- [x] Put picker attempts, parse polling/backoff, retry, outage, reset, and
+      stale-response guards behind one Project Mapping Run
+- [x] Put name ranking, camera budget, projection, slots, collision cells,
+      sprite metadata, and cleanup behind one deterministic Name Atlas
+- [x] Index learner projections by their real dependencies and prove hover-only
+      commits reuse stable outputs; benchmark the 1,000-node case
+
+**Acceptance:** public HTTP payloads and parser/check/persistence contracts are
+unchanged; focused module suites and the existing end-to-end session/server
+suites pass; the production SPA is rebuilt; the 1,000-node projection benchmark
+shows lower repeated-commit work without changing derived values.
+
 ## Decision Log **[AGENT-MAINTAINED — append only]**
 
 | Date | Decision | Why |
@@ -462,10 +530,25 @@ to before the index change.
 | 2026-07-20 | Progress reporting is a thread-scoped per-file hook (`note_file_parsed`) bound by `ProjectParser`, not a new `LanguageAdapter` parameter | The public adapter seam must stay unchanged for Phase 2 languages; one hook site per adapter also gives cancellation its exact "between files" meaning |
 | 2026-07-20 | Phase C adds `DELETE /api/progress`, the `CLEAR_PROGRESS` session event, and a `clearProgress` adapter method beyond the shared contract's Phase C rows | The contract's Phase C rows covered parse progress only, while the no-reset-progress-control gap is mapped to Phase C by the spec; recorded here rather than silently widened |
 | 2026-07-20 | Generated check suites are pinned by a committed golden fixture before any performance work touches `checks/service.py` | The Correctness Contract makes suite drift top-severity, and a refactor that changes an answer is invisible without a byte-level pin |
+| 2026-07-20 | Architecture map edges get backend-computed ports, barycenter ordering, arrowheads, and weight-scaled strokes; `MAP_SCHEMA_VERSION` 2; directory groups stay payload metadata | Within-layer order was arbitrary and direction was invisible in 2D while being parser truth; ordering stays deterministic (fixed sweeps, sorted ties); group containers wait for hierarchical layout |
+| 2026-07-20 | Galaxy regions place by deterministic import-community constellations (pure-Python label propagation in `layout.py`); `community` is an additive Region field; layout bytes change once | Hash-order placement scattered coupled modules; communities are parser-truth-derived and deterministic; progress signatures hash file content so nothing re-dims (M12 precedent) |
+| 2026-07-21 | **Bounded orbit** replaces the fixed camera, amending the free-flight Non-Goal: `controlType('orbit')` with panning disabled, per-level distance clamps, and clamped polar angle. The wheel becomes zoom; level changes move to click/Enter/Escape/breadcrumb | Approved by UD after a tester reported the galaxy unnavigable. Panning is the one degree of freedom that can strand a learner in empty space with nothing to navigate back by, so it stays off — rotation and zoom are clamped instead, which keeps "you cannot get lost" true. One gesture cannot mean both zoom and change-level, so the wheel's old meaning had to move |
+| 2026-07-21 | Galaxy uses **progressive reveal**: floor (within 2 import hops of Home) ∪ neighbours of every lit region ∪ the current selection's neighbours, with a persisted Show-all toggle. An unrevealed region is drawn faint, unnamed, edgeless — never removed | Approved by UD. 169 systems and their whole route mesh was the hairball; dropping the *edges* of what is not yet charted thins the sky without a separate density control. Regions stay drawn and clickable because hiding one would misreport the project's size, which is precisely the kind of wrong a learner cannot detect. Reveal is recomputed from proven progress, never stored, so it cannot drift out of step with it |
+| 2026-07-21 | `Region.hops_from_home` is graph-layer truth (schema 6): undirected BFS from Home over proven import routes, `None` when unreachable; `with_entrypoint` recomputes it | Reveal is game logic and belongs in `LearnerSession`, but the *distance* is a fact about the project and belongs in the graph. The frontend was already re-walking this exact BFS for the Easy-mode hint, so the two could in principle have disagreed about one number; there is now one source. `None` is never softened to a large number, or "unreachable" would read as "very far" |
+| 2026-07-21 | Canvas name plates are ranked (Home → lit → centrality), budgeted by camera distance, and decluttered by claiming the full screen-cell rectangle each plate covers | A name is the cheapest differentiation there is and the sky had none. Claiming one cell per plate let a wide name cover three neighbours, and claiming only a row let two plates straddling a boundary collide — the rectangle is the only version that actually holds. Plate geometry is published on the sprite by the module that sizes it, so the constant is not duplicated across files |
+| 2026-07-21 | Finding a module is a command palette **and** an index sidebar over one shared `moduleIndex`; sidebar rows show each path minus its group's shared prefix | Approved by UD. Progressive reveal makes targeted retrieval mandatory — a thinned sky must never hide a module from someone who knows its name — and both surfaces reach every module whether charted or not. Basenames alone are useless in a Python project where every package carries an `__init__.py`, so rows keep enough real path to be told apart |
+| 2026-07-21 | Progressive reveal stays **galaxy-only**; the Map always draws every module | Approved by UD when the navigation work was extended to the Map. The Map's job is "how it all fits together", and a layered import diagram with holes in it teaches less than a complete one; the galaxy already offers the thinned view for learners who want it |
+| 2026-07-21 | Architecture boxes are named by the tail of their file path (`short_label`, map schema 3); `label` keeps the full identifier for title and aria | A box is a fixed width, so its text always truncates on a real project — and truncating a dotted region id rendered `codemble.server.app` and `codemble.server.runtime` as the same glyphs. Identical text for different modules is worse than no label, and it is exactly the kind of wrong a learner cannot detect. The path tail also survives the `__init__.py` collision a basename alone cannot |
+| 2026-07-21 | The Map gains zoom, Fit, and drag-to-pan; panning rides the container's own scroll and zoom only scales the rendered size | The 2D counterpart of bounded orbit: a 960x2640 diagram in a plain scroll box showed four of nine layers and no way to see the whole shape. Scroll-based panning keeps native scrollbars, keyboard scrolling and screen-reader behaviour intact, and because every coordinate inside the SVG stays backend-computed, React remains a pure renderer of graph-owned geometry. It opens at true size rather than auto-fitting: fitting on mount measured the scroller before layout settled and landed on a scale that was neither fitted nor honest |
+| 2026-07-21 | v0.6.0 deepens five private boundaries without changing the HTTP, graph, check, persistence, or learner-visible contracts: Project Selection, Project Activation, Project Mapping Run, Name Atlas, and Learner Projection | Approved by UD as five behavior-preserving waves in one release PR. The deletion test now holds at each seam, stale activation and mapping responses lose atomically, and dependency-scoped learner projections measured ~0.331 ms → ~0.001 ms per hover commit on a synthetic 1,000-node project while preserving derived outputs |
+| 2026-07-21 | v0.6.1 treats Modules and Find as global surfaces, sequences first-run decisions as audience → required Home → coach, and makes the 3D parser-owned layout explicitly non-draggable | Approved by UD as implementation of every verified user-flow audit finding. Global commands must never accept hidden state, onboarding must expose one foreground decision at a time, and learners orbit the immutable graph rather than editing its coordinates. The compact shell is a structural breakpoint of the existing Formal Edo interface, not a new visual system |
 
 ## Non-Goals — do NOT build (point here when asked)
 
-- ❌ Free-flight 3D navigation — semantic zoom only
+- ❌ ~~Free-flight 3D navigation~~ — superseded 2026-07-21: **bounded orbit** is
+  approved (see Decision Log). The camera may rotate and zoom around the current
+  subject; panning, free translation, and any control that can leave the subject
+  off screen remain out
 - ❌ XP, streaks, levels, leaderboards
 - ❌ ~~A second 2D renderer/toggle in v1~~ — superseded 2026-07-19: the 2D Map layer is approved (see Decision Log); free-form/client-computed 2D layouts remain out
 - ❌ Accounts, cloud hosting, multi-user; share link waits for Phase 3

codemble-0.6.1/CONTEXT.md

@@ -0,0 +1,28 @@
+# Codemble domain model
+
+## Project Selection
+
+The learner's choice of one local folder, constrained to Codemble's allowed
+browse root, that may become the current project.
+
+## Project Activation
+
+The atomic transition from a successfully parsed project to the live checks,
+study, graph, and map experience. Releasing a project cancels any unfinished
+activation and leaves no project bound.
+
+## Project Mapping Run
+
+The learner-visible run that begins when a selected folder is accepted and
+ends when its project activates, parsing fails, or the learner releases it.
+
+## Name Atlas
+
+The deterministic set of visible names placed around charted stars for the
+current camera view, prioritizing Home, understood systems, and the learner's
+current pointer subject without allowing name plates to collide.
+
+## Learner Projection
+
+The learner-facing view of the current project after language focus, proven
+progress, navigation selection, and view preferences are applied.

{codemble-0.5.3 → codemble-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemble
-Version: 0.5.3
+Version: 0.6.1
 Summary: A learning game that turns the code AI wrote for you into a galaxy you light up by understanding it.
 Project-URL: Homepage, https://udhawan97.github.io/Codemble/
 Project-URL: Repository, https://github.com/udhawan97/Codemble
@@ -322,6 +322,13 @@ The [public roadmap](https://udhawan97.github.io/Codemble/roadmap/) separates
 shipped work from planned work. Milestones move only when their acceptance
 evidence exists.
 
+## Acknowledgements
+
+- [dagre](https://github.com/dagrejs/dagre) and [Eclipse ELK](https://github.com/eclipse-elk/elk) for the layered-diagram approach.
+- [tt-a1i/archify](https://github.com/tt-a1i/archify) for 2D architecture-diagram inspiration.
+- [Graphify](https://github.com/Graphify-Labs/graphify) for the community-constellation idea.
+- Codemble's shipped open-source stack: [3d-force-graph](https://github.com/vasturiano/3d-force-graph), [tree-sitter](https://github.com/tree-sitter/tree-sitter), [FastAPI](https://github.com/fastapi/fastapi), [Vite](https://github.com/vitejs/vite), and [React](https://github.com/facebook/react).
+
 ## License
 
 Codemble is released under the [Apache License 2.0](https://github.com/udhawan97/Codemble/blob/main/LICENSE).

{codemble-0.5.3 → codemble-0.6.1}/README.md

@@ -290,6 +290,13 @@ The [public roadmap](https://udhawan97.github.io/Codemble/roadmap/) separates
 shipped work from planned work. Milestones move only when their acceptance
 evidence exists.
 
+## Acknowledgements
+
+- [dagre](https://github.com/dagrejs/dagre) and [Eclipse ELK](https://github.com/eclipse-elk/elk) for the layered-diagram approach.
+- [tt-a1i/archify](https://github.com/tt-a1i/archify) for 2D architecture-diagram inspiration.
+- [Graphify](https://github.com/Graphify-Labs/graphify) for the community-constellation idea.
+- Codemble's shipped open-source stack: [3d-force-graph](https://github.com/vasturiano/3d-force-graph), [tree-sitter](https://github.com/tree-sitter/tree-sitter), [FastAPI](https://github.com/fastapi/fastapi), [Vite](https://github.com/vitejs/vite), and [React](https://github.com/facebook/react).
+
 ## License
 
 Codemble is released under the [Apache License 2.0](https://github.com/udhawan97/Codemble/blob/main/LICENSE).

{codemble-0.5.3 → codemble-0.6.1}/codemble/__init__.py

@@ -1,4 +1,4 @@
 """Codemble — a learning game that turns the code AI wrote for you into a galaxy
 you light up by understanding it. See CLAUDE.md for the agent brief and roadmap."""
 
-__version__ = "0.5.3"
+__version__ = "0.6.1"

{codemble-0.5.3 → codemble-0.6.1}/codemble/adapters/base.py

@@ -89,6 +89,13 @@ class Region:
     x: float
     y: float
     z: float
+    community: int
+    # Undirected breadth-first distance from the Home region over proven import
+    # routes. ``None`` means no route reaches this region -- or that no Home is
+    # selected yet -- and is never softened into a large number, because the
+    # renderer reveals the sky by this distance and a guessed one would quietly
+    # promise a path the parser never found.
+    hops_from_home: int | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -115,7 +122,7 @@ class Graph:
     regions: tuple[Region, ...] = ()
     region_edges: tuple[RegionEdge, ...] = ()
     partial_files: tuple[str, ...] = ()
-    schema_version: int = field(default=4, init=False)
+    schema_version: int = field(default=6, init=False)
 
     def to_dict(self) -> dict[str, object]:
         """Return a JSON-ready representation in canonical collection order."""

{codemble-0.5.3 → codemble-0.6.1}/codemble/graph/layout.py

@@ -24,22 +24,72 @@ def layout_graph(graph: Graph) -> Graph:
     for node in graph.nodes:
         grouped[node.region].append(node)
 
+    node_by_id = {node.id: node for node in graph.nodes}
+
+    routes: dict[tuple[str, str], list[bool]] = defaultdict(list)
+    for edge in graph.edges:
+        if edge.kind != "import" or edge.external:
+            continue
+        src_node = node_by_id.get(edge.src)
+        dst_node = node_by_id.get(edge.dst)
+        if src_node is None or dst_node is None or src_node.region == dst_node.region:
+            continue
+        routes[(src_node.region, dst_node.region)].append(edge.certain)
+
+    # ``all``, deliberately, where ``mapview.py``'s ``_workflow`` uses ``any``
+    # for a call pair.  The two marks claim different things.  A workflow row
+    # asserts only that a relationship exists, so one proven call site settles
+    # it and the ambiguous ones beside it change nothing.  A route is a single
+    # line standing in for ``weight`` imports, so calling it certain asserts
+    # every one of them: one unproven import among them and the whole route
+    # drops to possible.  Under-claiming is the only direction that is safe
+    # when one mark speaks for many edges.
+    region_edges = tuple(
+        RegionEdge(src=src, dst=dst, weight=len(certainties), certain=all(certainties))
+        for (src, dst), certainties in sorted(routes.items())
+    )
+
     region_order = sorted(grouped, key=lambda region_id: (_digest(region_id), region_id))
+    communities = _communities(tuple(grouped), region_edges)
+    community_members: dict[int, list[str]] = defaultdict(list)
+    for region_id in region_order:
+        community_members[communities[region_id]].append(region_id)
+
+    region_positions: dict[str, tuple[float, float, float]] = {}
+    cumulative_members = 0
+    for community in sorted(community_members):
+        members = community_members[community]
+        community_angle = community * _GOLDEN_ANGLE
+        community_radius = 42.0 + 54.0 * math.sqrt(cumulative_members)
+        community_x = math.cos(community_angle) * community_radius
+        community_z = math.sin(community_angle) * community_radius
+        for member_index, region_id in enumerate(members):
+            local_angle = (
+                member_index * _GOLDEN_ANGLE
+                + _fraction(region_id, "phase") * 0.18
+            )
+            local_radius = 16.0 + 12.0 * math.sqrt(member_index)
+            region_positions[region_id] = (
+                _rounded(community_x + math.cos(local_angle) * local_radius),
+                _rounded(((_fraction(region_id, "height") * 2.0) - 1.0) * 28.0),
+                _rounded(community_z + math.sin(local_angle) * local_radius),
+            )
+        cumulative_members += len(members)
+
+    home_region = next(
+        (node.region for node in graph.nodes if node.id == graph.selected_entrypoint),
+        None,
+    )
+    hops = _hops_from_home(tuple(grouped), region_edges, home_region)
+
     regions: list[Region] = []
     positioned_nodes: list[Node] = []
-    node_by_id = {node.id: node for node in graph.nodes}
-
-    for region_index, region_id in enumerate(region_order):
+    for region_id in region_order:
         members = sorted(
             grouped[region_id],
             key=lambda node: (node.kind != "module", node.id),
         )
-        region_angle = region_index * _GOLDEN_ANGLE + _fraction(region_id, "phase") * 0.18
-        region_radius = 42.0 + 54.0 * math.sqrt(region_index)
-        region_x = _rounded(math.cos(region_angle) * region_radius)
-        region_y = _rounded(((_fraction(region_id, "height") * 2.0) - 1.0) * 28.0)
-        region_z = _rounded(math.sin(region_angle) * region_radius)
-
+        region_x, region_y, region_z = region_positions[region_id]
         module_nodes = [node for node in members if node.kind == "module"]
         loc = sum(node.loc for node in module_nodes) or sum(node.loc for node in members)
         regions.append(
@@ -54,6 +104,8 @@ def layout_graph(graph: Graph) -> Graph:
                 x=region_x,
                 y=region_y,
                 z=region_z,
+                community=communities[region_id],
+                hops_from_home=hops.get(region_id),
             )
         )
 
@@ -85,28 +137,6 @@ def layout_graph(graph: Graph) -> Graph:
                     )
                 )
 
-    routes: dict[tuple[str, str], list[bool]] = defaultdict(list)
-    for edge in graph.edges:
-        if edge.kind != "import" or edge.external:
-            continue
-        src_node = node_by_id.get(edge.src)
-        dst_node = node_by_id.get(edge.dst)
-        if src_node is None or dst_node is None or src_node.region == dst_node.region:
-            continue
-        routes[(src_node.region, dst_node.region)].append(edge.certain)
-
-    # ``all``, deliberately, where ``mapview.py``'s ``_workflow`` uses ``any``
-    # for a call pair.  The two marks claim different things.  A workflow row
-    # asserts only that a relationship exists, so one proven call site settles
-    # it and the ambiguous ones beside it change nothing.  A route is a single
-    # line standing in for ``weight`` imports, so calling it certain asserts
-    # every one of them: one unproven import among them and the whole route
-    # drops to possible.  Under-claiming is the only direction that is safe
-    # when one mark speaks for many edges.
-    region_edges = tuple(
-        RegionEdge(src=src, dst=dst, weight=len(certainties), certain=all(certainties))
-        for (src, dst), certainties in sorted(routes.items())
-    )
     return replace(
         graph,
         nodes=tuple(sorted(positioned_nodes, key=lambda node: node.id)),
@@ -115,6 +145,90 @@ def layout_graph(graph: Graph) -> Graph:
     )
 
 
+def _communities(
+    region_ids: tuple[str, ...], routes: tuple[RegionEdge, ...]
+) -> dict[str, int]:
+    """Find deterministic import communities with label propagation.
+
+    Label propagation after Raghavan, Albert & Kumara (2007), "Near linear
+    time algorithm to detect community structures in large-scale networks";
+    constellation idea inspired by graphify. Implemented independently; no
+    code copied.
+    """
+
+    ordered = sorted(region_ids)
+    neighbors: dict[str, set[str]] = {region_id: set() for region_id in ordered}
+    for route in sorted(routes, key=lambda edge: (edge.src, edge.dst)):
+        if route.src not in neighbors or route.dst not in neighbors or route.src == route.dst:
+            continue
+        neighbors[route.src].add(route.dst)
+        neighbors[route.dst].add(route.src)
+
+    labels = {region_id: index for index, region_id in enumerate(ordered)}
+    for _ in range(10):
+        next_labels = dict(labels)
+        for region_id in ordered:
+            if not neighbors[region_id]:
+                continue
+            frequencies: dict[int, int] = defaultdict(int)
+            for neighbor in sorted(neighbors[region_id]):
+                frequencies[labels[neighbor]] += 1
+            highest = max(frequencies.values())
+            next_labels[region_id] = min(
+                label for label, count in frequencies.items() if count == highest
+            )
+        if next_labels == labels:
+            break
+        labels = next_labels
+
+    dense_labels: dict[int, int] = {}
+    communities: dict[str, int] = {}
+    for region_id in ordered:
+        label = labels[region_id]
+        if label not in dense_labels:
+            dense_labels[label] = len(dense_labels)
+        communities[region_id] = dense_labels[label]
+    return communities
+
+
+def _hops_from_home(
+    region_ids: tuple[str, ...],
+    routes: tuple[RegionEdge, ...],
+    home: str | None,
+) -> dict[str, int]:
+    """Return each region's import-route distance from Home.
+
+    Undirected on purpose: an import route is a relationship between two
+    modules, and a learner following it from Home arrives just as surely at the
+    importer as at the imported.  Direction is still parser truth and is still
+    drawn as an arrow -- it just is not what "how far from Home" means.
+
+    Regions absent from the result have no route to Home at all.  The caller
+    stores that as ``None`` rather than a sentinel distance, so "unreachable"
+    can never be mistaken for "very far".
+    """
+
+    if home is None or home not in set(region_ids):
+        return {}
+
+    neighbors: dict[str, set[str]] = {region_id: set() for region_id in region_ids}
+    for route in routes:
+        if route.src not in neighbors or route.dst not in neighbors:
+            continue
+        neighbors[route.src].add(route.dst)
+        neighbors[route.dst].add(route.src)
+
+    hops = {home: 0}
+    queue: deque[str] = deque([home])
+    while queue:
+        current = queue.popleft()
+        for neighbor in sorted(neighbors[current]):
+            if neighbor not in hops:
+                hops[neighbor] = hops[current] + 1
+                queue.append(neighbor)
+    return hops
+
+
 def _call_depths(members: list[Node], edges: tuple[Edge, ...]) -> dict[str, int]:
     """Return each member's orbit ring: call depth from the system's entry node.
 
@@ -169,8 +283,20 @@ def with_entrypoint(graph: Graph, node_id: str) -> Graph:
         raise ValueError(f"entrypoint is not a parser-ranked candidate: {node_id}")
     node_by_id = {node.id: node for node in graph.nodes}
     selected = node_by_id[node_id]
+    # Every distance is measured from Home, so moving Home invalidates all of
+    # them. Coordinates and communities are untouched: they depend on the import
+    # structure, not on which entrypoint the learner chose, so a Home change
+    # must not re-sort the sky or re-dim a region.
+    hops = _hops_from_home(
+        tuple(region.id for region in graph.regions), graph.region_edges, selected.region
+    )
     regions = tuple(
-        replace(region, home=region.id == selected.region) for region in graph.regions
+        replace(
+            region,
+            home=region.id == selected.region,
+            hops_from_home=hops.get(region.id),
+        )
+        for region in graph.regions
     )
     return replace(graph, selected_entrypoint=node_id, regions=regions)