codemble 0.6.4__tar.gz → 0.7.0__tar.gz

{codemble-0.6.4 → codemble-0.7.0}/.gitignore

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

{codemble-0.6.4 → codemble-0.7.0}/CHANGELOG.md

@@ -5,6 +5,74 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-22
+
+### Added
+- **Constellations you can tell apart.** Every parser-proven import community
+  now wears one of eight traditional Japanese colour families (seiji, fuji,
+  koke, asagi, toki, umenezumi, wakatake, kikyō), assigned deterministically
+  from the community id — same code, same sky, same colours. Galaxy stars keep
+  centrality as lightness inside the family hue, planets inherit their
+  system's family, and Architecture boxes tint toward it. Every hue is
+  lightness-capped beneath the unlit ceiling and the amber band is excluded
+  from the wheel, so a lit star stays the brightest object in the sky and
+  nothing unproven can read as understood. The Key gains a colour-family row.
+- **A counted shelf for unreachable modules.** On the Architecture map, modules
+  with no import route from Home fold away behind their exact count with a
+  **Show them** control (auto-folded above eight). On this repository that
+  turns a 1:3.2-tall drawing dominated by 80 test fixtures into a readable
+  connected core — with nothing hidden from the count and every module still
+  one click away.
+- **Class rings.** A structure the parser knows is a class wears a thin ring in
+  the system view — parser fact, not decoration.
+
+### Fixed
+- **Connections are visible.** Routes on both layers used to borrow the border
+  hairline at ~1.6:1 contrast — and the galaxy multiplied it to 32% opacity —
+  so the relationships the app teaches were its least visible marks. Both
+  layers now draw a dedicated route ink (4.0:1), arrowheads included, and a
+  *possible* relationship stays deliberately the more visible claim, dashed on
+  the map as before.
+- **The map's language stripe actually renders.** It set its colour through an
+  SVG presentation attribute, where `var()` is invalid, and silently fell back
+  to the box navy — the Key advertised Python/JS/TS colours the map never
+  drew. The stripe now paints through a style property.
+- **The nebula dawn no longer corrupts the lit system's name plate.** The
+  animation snapshotted one scale axis and restored all three from it, so the
+  celebration squashed the plate into a blurry square until a level change
+  rebuilt it. It now restores the full vector — the one bold moment ends
+  crisp.
+- **Escape steps back from anywhere on the Map.** The handler listened only
+  inside the stage, and the most common Easy path leaves focus on the page
+  body, so the documented recovery silently did nothing; the study exit also
+  said "Back to system" on the Diagram. Escape is now a window-level handler
+  (with dialog and typing guards) and the exit says "Back to the module".
+- **A resize cannot strand you in empty space.** Restored map viewports are
+  replayed only while they still show your focus; shrinking a desktop window
+  to phone width used to keep the desktop scroll and show empty layer bands.
+  Both the restore path and live resizes now re-centre on the parser-backed
+  target.
+- **Fit lands on something readable.** On tall drawings a true fit reached 7% —
+  a thumbnail with no names — so Fit now fits the width and lets the height
+  scroll when the whole shape would be unreadable, and keeps whole-shape fit
+  otherwise. The open Key also no longer covers the zoom controls, and the
+  region panel's actions no longer clip at desktop heights.
+- **Easy mode speaks its own register end to end.** "parser rank 0" became
+  "candidate 1", the checks header reads "Quiz · answers come from your code,
+  not AI", the lit celebration explains what the source hash means instead of
+  naming it, study metadata reads "What it is / Length / Evidence", and the
+  chrome attributes fixture errors to their shared directory ("2 could not be
+  read · all under tests/"). Expert keeps every precise term.
+- **Guidance stops sending beginners into tests first.** The nearest-unlit
+  ranking now charges test-scoped paths a bounded +1.5-hop penalty — a real
+  source module one hop farther wins the tie, an all-tests project is still
+  guided, and the displayed hop count stays the real one. On this repository
+  the second stop changed from `tests.test_python_ast` to
+  `codemble.adapters.project`.
+- **The study panel's connection diagram names its dots.** Six anonymous dots
+  used to decorate the labelled list below; each now carries its structure's
+  own (tail-truncated) name.
+
 ## [0.6.4] - 2026-07-21
 
 ### Fixed

{codemble-0.6.4 → codemble-0.7.0}/CLAUDE.md

@@ -167,8 +167,36 @@ 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-21 ·
-Session note: v0.6.4 closes all twenty findings of a fresh end-to-end user-flow
+**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-22 ·
+Session note: v0.7.0 implements all fourteen findings of a fresh evidence-based
+user-flow audit of the served v0.6.4 build (run as a first-run Easy learner on
+this repository at 1280/375/320, with before/after screenshots) plus the
+approved D1 design direction: parser-proven import communities now wear eight
+deterministic traditional Japanese colour families (galaxy stars, planets, and
+Architecture-box tints), lightness-capped beneath the unlit ceiling with the
+amber band excluded so understanding stays the brightest claim in the sky.
+Routes on both layers moved from the 1.6:1 border hairline to a dedicated
+4.0:1 route ink (possible relationships stay dashed and deliberately more
+visible); the Architecture map folds modules with no route from Home into a
+counted shelf behind a Show-them control; Fit fits width when whole-shape fit
+would be unreadable; and Easy guidance charges test-scoped paths a bounded
++1.5-hop penalty so a learner's own code outranks its test suite at equal
+distance. Mechanical fixes: the nebula dawn restores sprite scale as a vector
+(it squashed the lit system's name plate square), the map's language stripe
+paints via a style property (an SVG fill attribute cannot resolve var() and
+silently rendered navy), Escape on the Map is a window-level handler that
+works with focus on body, stale map viewports re-centre on the focus point on
+restore and on live resizes, the open Key stacks below the zoom controls, the
+region panel's actions no longer clip, study connection dots carry names, and
+the Easy register replaces parser vocabulary end to end ("candidate 1",
+"Quiz · answers come from your code, not AI", "What it is / Length /
+Evidence", fixture errors attributed "all under tests/"). Parser, graph,
+checks, progress, provider, and HTTP contracts are byte-unchanged; the suite
+grew a nebula-dawn scale-restore check plus community-colour, viewport, and
+guidance-penalty contract assertions (241 pytest, ruff clean, 12 frontend
+checks, rebuilt web_dist). Full planet realism explicitly remains a Phase 3
+decision under the game-art Non-Goal. The milestone does not advance: issue
+#13 still requires human tester evidence. Previously: v0.6.4 closes all twenty findings of a fresh end-to-end user-flow
 audit run against the served build on three real projects (Codemble, Golavo,
 FolioOrb) at 1280/375/320 px with a keyboard pass. The headline fix is a
 Correctness Contract one: a missed check printed the parser answer and its
@@ -576,6 +604,10 @@ shows lower repeated-commit work without changing derived values.
 | 2026-07-21 | The audience answer is stored per learner as well as per project (`learner.json` beside progress); a fresh bind seeds from it and skips the gate, while the header toggle still overrides one project | The gate asks who the *learner* is, but the answer lived only under the project key, so every new project re-asked an expert whether they were new to coding. The file carries no `schema_version`, which is what keeps recents from reading it as a project |
 | 2026-07-21 | Home calibration is a native modal sized to the viewport, grouped by the candidates' real top-level scope, with the candidate count stated and "Explore without Home" outside the scrolling list | It is the second step of the same required sequence as the audience gate and deserves the same shape. As a card capped to a share of the stage it showed one candidate of eleven with the escape hatch thousands of pixels below the fold, and a flat list put `tests/fixtures/...` beside the learner's entrypoint with nothing to tell them apart. Scope and rank are parser facts already in the payload; the leading group always opens so a project whose best candidate is rank 1 is never met by an all-collapsed list |
 | 2026-07-21 | Galaxy name plates use the same path-tail rule as map schema 3's `short_label`; the shared module index and the command palette use it too, and the palette's unfiltered order is Home → lit → centrality | Basenames collide hard in a Python project — every package carries an `__init__.py` — so identical plates named different modules, which is precisely the wrong a learner cannot detect, and the palette opened on a screen of indistinguishable rows |
+| 2026-07-22 | **Hue means import community.** Each parser-proven community takes one of eight traditional Japanese colour tokens (`--cm-com-0..7`) by `community id mod 8`; stars, planets and Architecture boxes all read the same arithmetic in `graphData.communityShade`. This amends the M2 encoding row: colour was "language", which is now the nebula/stripe channel only | Approved by UD. The sky had one hue for 109 systems, so nothing could be tracked without reading every plate — and the graph had proven communities since schema 5 that nothing rendered. Guardrails that keep the Correctness Contract intact: every token is lightness-tuned to `--cm-ink-2`'s luminance (0.389) so a lit star at 0.598 always wins, the kohaku band (~40°) is excluded so no community can read as "understood", a missing community id falls back to the old neutral ramp rather than borrowing a hue, and the mapping is pure arithmetic on graph truth so the same code always yields the same sky |
+| 2026-07-22 | Routes get their own ink (`--cm-route`, 4.0:1) on both layers, and it sits deliberately BELOW `--cm-route-possible` (6.4:1) | Edges borrowed `--cm-hairline`, the ink of box borders and panel rules, measuring 1.57:1 on the canvas ground — the relationships the product exists to teach were its least visible marks, which is the literal complaint that opened the audit. Ordering the two inks this way keeps the 2026-07-19 rule that an unproven claim must be the more visible one |
+| 2026-07-22 | Architecture-map modules with no import route from Home fold into a counted shelf behind an explicit control (auto-folded above 8), and Fit fits WIDTH when a whole-shape fit would land below 35% | On this repository 80 of 109 boxes are test fixtures and scripts, making the drawing 1:3.2 tall so the connected core fit at an unreadable 7%. Folding is view state, never truth: the note carries the exact count, **Show them** draws every one, and both surfaces still reach every module. Distinct from progressive reveal, which stays galaxy-only |
+| 2026-07-22 | Easy guidance charges test-scoped paths a bounded +1.5-hop penalty; the displayed hop count stays the real one | A CLI's nearest neighbour is usually its own test suite, so pure hop-distance sent a brand-new learner from Home straight into `tests/`. The penalty is bounded so a non-test module one hop farther wins while a distant one does not, and an all-tests project is still guided. Both inputs stay parser truth (the BFS count and the recorded file path); only the ranking key is biased, never the reported fact |
 
 ## Non-Goals — do NOT build (point here when asked)
 
@@ -588,7 +620,11 @@ shows lower repeated-commit work without changing derived values.
 - ❌ Accounts, cloud hosting, multi-user; share link waits for Phase 3
 - ❌ Extra quest types before Phase 3
 - ❌ GitHub-URL ingestion in v1
-- ❌ Elaborate game art before the loop teaches well
+- ❌ Elaborate game art before the loop teaches well — **still holds**: the
+  2026-07-22 visual pass shipped only encodings that carry parser facts
+  (community hue, class rings). Procedural planet surfaces, atmospheres and
+  rotation ("almost real planets, like a game") remain OUT until Phase 1
+  tester evidence lands, and would need their own Decision Log entry
 
 ## Gotchas
 
@@ -616,6 +652,11 @@ shows lower repeated-commit work without changing derived values.
 - **Canvas colours must be plain values, never `color-mix()`** — WebGL receives
   a custom property's authored text, so a computed token renders black. Add new
   canvas tokens through `readPalette`, which resolves them.
+- **`var()` never works in an SVG presentation attribute** — `fill="var(--x)"`
+  is invalid and falls back to the cascade *silently*, which is how the map's
+  language stripe rendered box-navy for a release while the legend advertised
+  three colours. Use `style={{ fill: … }}` (a CSS property) for any
+  token-driven SVG paint.
 
 ## Edge cases & limits
 

{codemble-0.6.4 → codemble-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemble
-Version: 0.6.4
+Version: 0.7.0
 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
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: eighty dim star systems parsed from real source, with a legend, language focus buttons, and a notice that two files are unchartable because their parser reported a syntax error" width="960">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: 109 star systems parsed from real source, 23 charted and named by file path, constellations wearing their import-community colour families in traditional Japanese hues around an amber lit Home, with language focus buttons, a Key disclosure, and a notice that two files could not be read — all under tests/" width="960">
 </p>
 
 <p align="center"><sub>
@@ -148,7 +148,7 @@ of your own code becomes a sky you understand.
 ## What it looks like
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, showing its functions and classes in orbits with call edges and a keyboard focus reticle" width="900">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, its functions and classes as planets in the system's own colour family, in call-depth orbits with the call edges between them" width="900">
 </p>
 
 <p align="center"><sub>
@@ -156,7 +156,7 @@ of your own code becomes a sky you understand.
 </sub></p>
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/study-panel.png" alt="The study panel for create_app, showing kind, span, 36 callers, a structural summary marked no model needed, guidance for configuring a provider or a local Ollama, and a parser connections diagram with an inbound call citing a real file and line" width="900">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/study-panel.png" alt="The study panel for create_app, showing kind, span, 53 callers, parser-proven resolution, and a structural summary marked no model needed" width="900">
 </p>
 
 <p align="center"><sub>
@@ -188,9 +188,17 @@ computed in the graph layer and served as data.
 | **Map · Workflow** | The call tree from your entrypoint, depth by depth | Seeing what runs first |
 
 The Map is plain SVG, so it still works on a machine that cannot draw WebGL.
-On a compact screen it opens at readable 100% around Home or the selected
-target; **Fit** is an explicit whole-diagram overview. Zoom and pan survive Map
-refreshes and layer switches instead of snapping back after a passed check.
+Click a box and it offers both halves of a step — **Read the source** opens that
+module's real source, lens notes and relationships without leaving the layer,
+and **Prove understanding** starts its checks. Escape steps back a level, as in
+the Galaxy. On a compact screen the Map opens at readable 100% around Home or
+the selected target; **Fit** is an explicit whole-diagram overview. Zoom and pan
+survive Map refreshes and layer switches instead of snapping back after a passed
+check.
+
+In Easy mode these surfaces carry plainer labels — the layer is **Diagram** and
+the tabs are **How it fits together** and **What runs first**. Same views, same
+evidence; only the wording follows the audience.
 
 ## Open a structure, read what the parser knows first
 
@@ -207,10 +215,14 @@ Sections other than the narration never involve a model at all.
 A header toggle changes how Codemble talks to you and how much it puts on
 screen: plain language, larger type, the Map by default, and a hint chip naming
 the nearest unlit region to Home — counted in import hops over the graph, not
-chosen by a model. The hint opens that system, switches from Map to Galaxy when
-its internal structures are the next step, then becomes an instruction rather
-than an enabled no-op. It never changes graph truth, coordinates, progress, or
-how a check is scored.
+chosen by a model, and broken by parser-proven structure count when several sit
+the same distance away. The hint opens that system, offers to read its source,
+then becomes an instruction rather than an enabled no-op. It waits until the
+first-run choices are done before it appears at all, and it never changes graph
+truth, coordinates, progress, or how a check is scored.
+
+Codemble asks which audience you are **once** — the question is about you, not
+about the project — and each project still keeps its own mode.
 
 You can also switch project or change Home without leaving the app.
 
@@ -224,6 +236,7 @@ You can also switch project or change Home without leaving the app.
 | A route or edge | An import or call; approximate calls are labeled **possible** |
 | Size | Lines of code |
 | Brightness and glow | How many **distinct** structures call it |
+| Colour family | Import community — modules that import each other share one of eight traditional Japanese hues |
 | Nebula tint | Language, at galaxy level |
 | Orbit ring | Call depth — the inner ring runs first |
 | Drifting particles | A call the parser proved; a possible call stays still |
@@ -231,9 +244,13 @@ You can also switch project or change Home without leaving the app.
 
 Understanding owns the top of the brightness range: the unlit ramp stops below
 the amber a lit star uses, so a busy module you have not proven can never
-outshine one you have. Pass a region's checks and that system plays a short
-amber "nebula dawn" — after the light is already saved, so the animation marks
-a fact rather than delivering one.
+outshine one you have — every community hue is lightness-capped beneath it, and
+the amber band is excluded from the community wheel entirely. Pass a region's
+checks and that system plays a short amber "nebula dawn" — after the light is
+already saved, so the animation marks a fact rather than delivering one. On the
+flat Map, modules with no import route from Home fold into a counted shelf
+(**Show them** draws every one), so test scaffolding never buries the connected
+core it cannot reach.
 
 Python-only, JavaScript-only, TypeScript-only, and mixed projects share the same
 graph contract. Language focus changes only what you are looking at; it never

{codemble-0.6.4 → codemble-0.7.0}/README.md

@@ -34,7 +34,7 @@
 </p>
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: eighty dim star systems parsed from real source, with a legend, language focus buttons, and a notice that two files are unchartable because their parser reported a syntax error" width="960">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: 109 star systems parsed from real source, 23 charted and named by file path, constellations wearing their import-community colour families in traditional Japanese hues around an amber lit Home, with language focus buttons, a Key disclosure, and a notice that two files could not be read — all under tests/" width="960">
 </p>
 
 <p align="center"><sub>
@@ -116,7 +116,7 @@ of your own code becomes a sky you understand.
 ## What it looks like
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, showing its functions and classes in orbits with call edges and a keyboard focus reticle" width="900">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, its functions and classes as planets in the system's own colour family, in call-depth orbits with the call edges between them" width="900">
 </p>
 
 <p align="center"><sub>
@@ -124,7 +124,7 @@ of your own code becomes a sky you understand.
 </sub></p>
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/study-panel.png" alt="The study panel for create_app, showing kind, span, 36 callers, a structural summary marked no model needed, guidance for configuring a provider or a local Ollama, and a parser connections diagram with an inbound call citing a real file and line" width="900">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/study-panel.png" alt="The study panel for create_app, showing kind, span, 53 callers, parser-proven resolution, and a structural summary marked no model needed" width="900">
 </p>
 
 <p align="center"><sub>
@@ -156,9 +156,17 @@ computed in the graph layer and served as data.
 | **Map · Workflow** | The call tree from your entrypoint, depth by depth | Seeing what runs first |
 
 The Map is plain SVG, so it still works on a machine that cannot draw WebGL.
-On a compact screen it opens at readable 100% around Home or the selected
-target; **Fit** is an explicit whole-diagram overview. Zoom and pan survive Map
-refreshes and layer switches instead of snapping back after a passed check.
+Click a box and it offers both halves of a step — **Read the source** opens that
+module's real source, lens notes and relationships without leaving the layer,
+and **Prove understanding** starts its checks. Escape steps back a level, as in
+the Galaxy. On a compact screen the Map opens at readable 100% around Home or
+the selected target; **Fit** is an explicit whole-diagram overview. Zoom and pan
+survive Map refreshes and layer switches instead of snapping back after a passed
+check.
+
+In Easy mode these surfaces carry plainer labels — the layer is **Diagram** and
+the tabs are **How it fits together** and **What runs first**. Same views, same
+evidence; only the wording follows the audience.
 
 ## Open a structure, read what the parser knows first
 
@@ -175,10 +183,14 @@ Sections other than the narration never involve a model at all.
 A header toggle changes how Codemble talks to you and how much it puts on
 screen: plain language, larger type, the Map by default, and a hint chip naming
 the nearest unlit region to Home — counted in import hops over the graph, not
-chosen by a model. The hint opens that system, switches from Map to Galaxy when
-its internal structures are the next step, then becomes an instruction rather
-than an enabled no-op. It never changes graph truth, coordinates, progress, or
-how a check is scored.
+chosen by a model, and broken by parser-proven structure count when several sit
+the same distance away. The hint opens that system, offers to read its source,
+then becomes an instruction rather than an enabled no-op. It waits until the
+first-run choices are done before it appears at all, and it never changes graph
+truth, coordinates, progress, or how a check is scored.
+
+Codemble asks which audience you are **once** — the question is about you, not
+about the project — and each project still keeps its own mode.
 
 You can also switch project or change Home without leaving the app.
 
@@ -192,6 +204,7 @@ You can also switch project or change Home without leaving the app.
 | A route or edge | An import or call; approximate calls are labeled **possible** |
 | Size | Lines of code |
 | Brightness and glow | How many **distinct** structures call it |
+| Colour family | Import community — modules that import each other share one of eight traditional Japanese hues |
 | Nebula tint | Language, at galaxy level |
 | Orbit ring | Call depth — the inner ring runs first |
 | Drifting particles | A call the parser proved; a possible call stays still |
@@ -199,9 +212,13 @@ You can also switch project or change Home without leaving the app.
 
 Understanding owns the top of the brightness range: the unlit ramp stops below
 the amber a lit star uses, so a busy module you have not proven can never
-outshine one you have. Pass a region's checks and that system plays a short
-amber "nebula dawn" — after the light is already saved, so the animation marks
-a fact rather than delivering one.
+outshine one you have — every community hue is lightness-capped beneath it, and
+the amber band is excluded from the community wheel entirely. Pass a region's
+checks and that system plays a short amber "nebula dawn" — after the light is
+already saved, so the animation marks a fact rather than delivering one. On the
+flat Map, modules with no import route from Home fold into a counted shelf
+(**Show them** draws every one), so test scaffolding never buries the connected
+core it cannot reach.
 
 Python-only, JavaScript-only, TypeScript-only, and mixed projects share the same
 graph contract. Language focus changes only what you are looking at; it never

{codemble-0.6.4 → codemble-0.7.0}/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.6.4"
+__version__ = "0.7.0"