v0.5.3 — fixes a crash on every fresh install

Codemble v0.5.3 — fixes a crash on every fresh install

If you installed Codemble recently and it died on a JavaScript or TypeScript
project, this is why. Please upgrade.

Codemble's dependency range allowed tree-sitter 0.26.0, which is
ABI-incompatible with the newest published grammar wheels
(tree-sitter-javascript 0.25.0 and tree-sitter-typescript 0.23.2 — the only
ones that exist). Partway through parsing a real project the parser died with a
segmentation fault inside node_get_named_children, taking the whole process
down with it.

What that looked like:

• codemble ./my-project exited partway through with no traceback.
• In the app, the local server vanished mid-parse, so the loading screen stopped
  on "Lost contact with the local server" and never recovered.

The core is now pinned <0.26.

Why it escaped every check

An environment that already had tree-sitter 0.25.x kept working, so it was
invisible from a developer checkout and from CI's cache. It only hit people
installing fresh — including through uvx codemble, the documented install
path, which resolves the newest permitted version.

It also could not be caught by a behavioural test. A small snippet parses and
walks its children perfectly well on 0.26.0; the crash needs a corpus of real
size, and every fixture in the suite is small. That is precisely how it reached
a release.

So the guard added here asserts the resolved dependency version rather than
the behaviour: the suite now fails if tree-sitter resolves to the segfaulting
release. Verified both ways — it passes on 0.25.2 and fails on 0.26.0.

Upgrading

uvx codemble@latest        # or: uv tool upgrade codemble

No breaking changes: the CLI, the graph/checks API, and the on-disk progress
format are unchanged, and existing progress in ~/.codemble/ is read as-is.

Honest note

The upper bound is deliberate, not caution. It should be raised only once a
grammar release has been verified against the newer core on a project of real
size — a snippet test will not tell you anything useful here.

v0.5.2 — never trapped on the loading screen

Codemble v0.5.2 — never trapped on the loading screen

Reported from a real run: parsing a JavaScript/TypeScript project, the loading
screen froze on "Lost contact with the local server (Failed to fetch)", and
clicking Cancel and pick another project did nothing. There was no way back
to the picker, and no way to reach the galaxy. The only exit was killing the
tab.

This patch makes that state recoverable. No new features, no breaking changes:
the CLI, the graph/checks API, and the on-disk progress format are unchanged.

Fixed

The escape hatch no longer depends on the server it is escaping

resetProject awaited the server's reset call before doing any local
teardown, and that await was deliberately left uncaught. When the local server
was unreachable, the request rejected, so the code that stops the progress poll
and returns the learner to the picker never ran at all.

The local teardown no longer waits on the server answering:

• A reset the server actively refuses (a real HTTP status) still stays put
  and reports inline — the project genuinely is still bound there, and
  blanking the app would desync from it.
• A reset that never reached a server releases the learner locally and says
  so, because there is no bound project left to disagree with.

The loading screen stops over-reassuring

A single failed poll still says the parse may be running fine — a brief hiccup
really may be nothing. But after eight consecutive failures (about eighteen
seconds with no answer) the screen now says what it actually knows: the local
server has not responded and may have stopped, and it points at cancelling and
running codemble again. It keeps retrying either way.

A load failure with no server on the other end now names the local server and
what to do about it, instead of surfacing the browser's bare "Failed to fetch".

Honest limits

The underlying reason a local server became unreachable mid-parse was not
reproduced — repeated parses of the reported projects, and repeated runs through
the real server and picker flow, all completed cleanly. This release makes that
state visible and recoverable rather than fatal; it does not claim to have
removed its cause.

Two tree-sitter segfaults observed while investigating were traced to a separate
tool running in the background on the same machine, not to Codemble's parser.

v0.5.1 — three post-audit fixes

Codemble v0.5.1 — three small fixes from a post-release audit

A full re-audit of the learner journey after v0.5.0 confirmed the big gaps were
closed, but turned up three smaller ones. This patch lands them. No new
features, no breaking changes: the CLI, the graph/checks API, and the on-disk
progress format are all unchanged.

Fixed

Cancelling a parse now stops the slow stage too

Returning to the picker during a parse used to stop only the file-reading loop.
The resolving stage — the slowest one on a large project — ran to completion
regardless, so a cancel there left a worker burning CPU, and starting a second
project could run two parses at once. Each resolving sub-step is now a
cancellation checkpoint, matching the per-file one, so a cancel is noticed
promptly at every stage.

Clicking a module on the 2D Map no longer looks like nothing happened

Easy mode opens on the 2D Map, where a module is a single box. Clicking one
selected it but drew no change, so the click looked broken. The selected box now
highlights in the interaction accent (never the amber that means "understood"),
and the system-level copy says plainly that the module's internal structures are
drawn as planets in the Galaxy layer, and that the Map shows how modules connect,
not what is inside them.

That copy is deliberately careful: it does not point the learner at the
Workflow tab, because a module the program never reaches has no rows there — a
promise the learner would have caught as wrong. Codemble never claims something
the view cannot show.

Known limits, unchanged

• Projects past roughly 1,000 supported source files still need scoping to a
  subdirectory; level-of-detail and clustering remain later-phase work.
• The layer choice (Galaxy vs Map) still returns to the mode default on reload —
  view state is intentionally session-only.

v0.5.0 — scale to ~1,000 files, with an honest loading screen

Codemble v0.5.0 — bigger projects, an honest loading screen

Anything much past a few hundred files hit a wall. The old cap refused the
project outright, and when you scoped in, the browser tab froze: the whole graph
parsed on the request thread with no feedback, so a slow project looked like a
hung app. Meanwhile the first-run surfaces added last release — coach-marks, the
footer hint, the Map — still assumed you were on the galaxy, even though Easy,
the default audience, opens on the 2D Map.

This release parses in the background behind a staged, honest loading screen,
raises the cap to roughly 1,000 supported source files, and lines the first-run
experience up with the layer the learner is actually on.

No breaking changes: the CLI, the graph/checks API, and the on-disk progress
format are unchanged, and existing ~/.codemble/ progress is read as-is.

Highlights

Larger projects, without the frozen tab

• Parsing moved off the request thread. POST /api/picker/select answers
  202 {"state": "parsing"} immediately, a worker thread does the work, and the
  app polls GET /api/picker/progress
• A staged loading screen names the stage it is in — discovering, parsing,
  resolving, checks, layout — and shows a real file count while files are
  read. The count moves during parsing only, because that is the only stage
  measured per file; resolving, the slowest stage, instead narrates its own
  real sub-steps (resolving imports, resolving calls, building the galaxy map,
  composing the project) rather than inventing a percentage it does not have
• Cancellable: returning to the picker stops the parse at the next file boundary
  and re-arms the picker. A crashed parse becomes an in-app error carrying the
  parser's own message with a one-click retry — never a hung server
• The scale cap moved from 300 to ~1,000 supported source files. Over the
  cap, the picker names the busiest subdirectories as buttons and accepts a
  typed path, both still jailed to your home directory; a piped, non-interactive
  run prints those same scopes instead of a bare refusal

Faster where it was slow

• Check generation used to walk every graph edge up to four times per region and
  rebuild its lookups per region; it now builds one index per bind in a single
  pass — ~16x faster at 1,000 files, with a committed golden fixture proving
  the generated suites and answers are byte-identical
• GET /api/graph and GET /api/map used to re-hydrate progress and re-sort
  every node and edge on every request; the serialized document is now cached and
  dropped only when a region lights up, Home changes, or the project is rebound —
  ~25-26x faster warm
• A Python-adapter hotspot that resolved a node's owning module with an
  O(definitions × modules) scan now walks the node id's dotted prefixes in
  O(depth) — a further 1.56x on total parse wall-clock, output byte-identical

First-run experience, aligned to the layer you are on

• The coach-marks and the footer control hint now key on the active layer, so a
  learner who lands on the Map reads map guidance ("click a box or row to study,
  switch tabs") instead of galaxy scroll and camera controls that are not on
  screen
• The audience-mode gate and the first-run coach-marks no longer stack as two
  modals on a genuine first run; the gate resolves first
• With no parser-recognisable entrypoint, both Map tabs state that reason instead
  of pointing at a "Change Home" control that is not rendered
• Language focus now also filters the 2D Map — a frontend projection over the
  immutable graph, dropping other languages' boxes, rows, and edges while
  survivors keep their backend-computed coordinates, so focus means the same
  thing on both layers
• The no-WebGL message now points to the Map/Diagram layer, which needs no WebGL
  and is one switch away

Housekeeping

• A Clear this project's progress control on the star chart, behind a
  confirmation, scoped to the open project only
• CODEMBLE_DATA_DIR now relocates everything Codemble keeps under your home
  directory — saved progress, the narration cache, and the config file — rather
  than progress alone, through one helper. Unset, the default is still
  ~/.codemble
• The test suite no longer inherits the developer's ~/.codemble/config or their
  ANTHROPIC_API_KEY / OPENAI_API_KEY, so a local run can no longer make a
  real, billed API call the way CI would not

Known limits

• The cap is ~1,000 supported source files, not unlimited. Above it you still
  scope to a subdirectory in the picker or with --path. Level-of-detail and
  clustering for larger repositories remain Phase 2 work — they did not ship here
• The resolving stage advances by naming its sub-step, not by a per-file
  counter; only parsing has an honest denominator to count against
• Uncertainty is drawn per layer, unchanged: a "possible" relationship is a
  distinct colour and no drifting particles in the 3D galaxy (which has no
  line-dash support) and a genuinely dashed line in the 2D Map
• Source adapters still cover Python, JavaScript, and TypeScript; unsupported
  languages stay outside the graph rather than being guessed
• The original unaided learner-acceptance issue remains open; this technical
  release does not fabricate human onboarding evidence

v0.4.0 — the galaxy UX overhaul

Codemble v0.4.0 — the galaxy UX overhaul

The galaxy read as flat spheres on a plain background, connections were hard to
follow at any zoom level, and once a project was bound the only way to open a
different one was killing the server. This release lands the redesign, adds a
second way to look at the same graph, and finally puts what the parser already
knew on screen.

No breaking changes: the CLI and the on-disk progress format are unchanged, and
existing ~/.codemble/ progress is read as-is.

Highlights

Seeing the code

• Stars are drawn as light: canvas-generated halos and an UnrealBloomPass
  tuned so understood amber blooms hard while the unlit ramp barely registers
• A background starfield seeded from the project's own file hashes — the same
  code still produces the same sky
• Python, JavaScript, and TypeScript systems sit in a faint language-tinted
  nebula at galaxy level; any other language renders no fog rather than
  borrowing a hue that would imply evidence Codemble does not have
• A visible keyboard focus reticle beside the existing live text readout
• Passing a region's checks plays a 1.2s nebula dawn at galaxy level — amber
  washing out through the system's halo and fog and receding. The lit state is
  saved before the animation runs, so the dawn marks a fact instead of
  delivering one, and prefers-reduced-motion gets the finished lit state with
  no animation at all
• Edge direction arrows below the galaxy level, hover tooltips naming both
  structures, the relationship, its certainty and the line it was seen on, and
  hover/selection highlighting. Studying a structure now keeps its connections
  visible instead of dimming the whole scene
• System members orbit by call depth, so position encodes flow: ring 1 is
  what the module's entry node calls directly plus every member no sibling
  calls, and only certain calls decide placement

A second way to look

• A 2D Map layer beside the 3D galaxy, switchable from the header, with an
  Architecture tab (modules as boxes grouped by directory, layered by import
  distance from Home) and a Workflow tab (the call tree from your
  entrypoint, where the first hop is the parser's defines relation and deeper
  hops are calls)
• Both layouts are computed in codemble/graph/mapview.py and served by a new
  GET /api/map, so the Map and the galaxy cannot disagree
• The Map is plain SVG and needs no WebGL, so a machine that cannot draw the
  galaxy can still read the project

Reading what the parser knows

• The study panel leads with a structural summary rendered from parser facts
  through fixed templates — no model, no key, no network
• Grounded narration now actually reaches the panel; the explanation endpoint
  had shipped but was never called
• A Connections section lists every relationship into and out of the
  selected structure, grouped inbound and outbound, each row carrying direction,
  certainty, and the file:line where that structure is defined, each row
  clickable, above a small SVG diagram of callers → this → callees
• Local narration through Ollama: explicit opt-in, loopback-and-http only
  enforced at construction, no credential sent, and the same grounding
  validation every other provider gets
• Centrality now counts distinct callers rather than call sites, so
  brightness stops overstating a helper called repeatedly from one place. The
  study panel's label follows: "Callers", not "Calls in"

Staying in the app

• Switch project releases the bound project and returns to the picker — no
  more killing the server
• Change Home reopens the entrypoint picker whenever the parser ranked a
  candidate, and the choice now survives a restart
• In-app retry instead of "restart Codemble", a React error boundary, and a
  <noscript> fallback
• Easy/Expert audience mode: Easy uses plain language for narration, check
  questions, panel labels, Lens notes and the legend, reduces visual density,
  opens on the Map, and shows a hint chip naming the nearest unlit region to
  Home by import-route hops. It never changes graph truth, coordinates,
  progress, or how a check is scored
• First-run coach-marks, a clickable breadcrumb, and a legend that describes
  only the encodings the layer on screen actually draws

How uncertainty is drawn, per layer

The Correctness Contract requires an unproven relationship to stay visibly
unproven. The two renderers encode that differently, and the legend swatch
follows whichever layer is on screen:

Layer	A "possible" relationship
3D galaxy	A distinct colour, and no drifting particles. 3d-force-graph has no line-dash support, so 3D edges are never dashed
2D Map (SVG)	Genuinely dashed, plus the same certainty wording
Study panel diagram	Dashed

Drifting particles mark certain call edges only, at system and study level, and
stop entirely under prefers-reduced-motion.

Known limits

• The project scale cap is still ~300 supported source files; above that,
  scope to a subdirectory in the picker or with --path
• No threaded parse and no parse-progress screen in this release. That work,
  along with raising the cap, is specified in
  docs/superpowers/plans/2026-07-19-galaxy-ux-phase-c.md and is planned, not
  shipped
• Language tint is drawn as nebula colour at galaxy level and on the Map's
  Architecture tab only; system and study levels and the Workflow tab carry no
  tint
• Source adapters still cover Python, JavaScript, and TypeScript; unsupported
  languages are not parsed or described
• Dynamic or configuration-dependent JS/TS resolution remains explicitly
  possible rather than promoted to fact
• Syntax-error files remain visible as unchartable raw source
• Narration is optional. With a local model, grounding validation catches an
  invented identifier but not a wrong claim about a real one, and smaller local
  models make that second kind of mistake more often — the structural summary,
  source, Lens, and checks are model-free either way
• The original unaided learner-acceptance issue remains open; this technical
  release does not fabricate human onboarding evidence

v0.3.1 — PyPI packaging metadata

Packaging metadata only — no behavior change. Everything v0.3.0 does, it still does.

uvx codemble            # or: pipx install codemble && codemble

Fixed

• Added PyPI classifiers (Beta, Python 3.11–3.13, developer/education audience, OS independent). v0.3.0 shipped with none, so the project page showed no Python version or maturity and was invisible to classifier search.
• Moved license metadata to the PEP 639 SPDX form (License-Expression: Apache-2.0). v0.3.0 dumped the full ~11KB Apache text into the License field.
• Made README links absolute, so the images and doc links render on the PyPI project page instead of 404ing, and dropped a stray internal tooling comment from the top of the published description.
• Excluded internal tooling directories (.remember, .hallmark, .claude, .superpowers) from the sdist; v0.3.0's sdist carried agent session notes.

Docs that named a specific release now say "Phase 1 tester release" instead, so a patch no longer leaves version labels stale across eight pages.

Full changelog: https://github.com/udhawan97/Codemble/blob/v0.3.1/CHANGELOG.md

v0.3.0 — In-app project picker

Bare codemble now opens your browser to an in-app project picker instead of requiring a path on the command line, and this is the first release published to PyPI.

Install

uvx codemble            # or: pipx install codemble && codemble

Codemble opens your browser — pick your project folder there. To skip the picker, pass a path: codemble ./your-project.

Added

• In-app project picker: reopen a recent project or browse your home folders, then map it without touching the terminal. Over-cap projects prompt for a subdirectory in the UI instead of erroring out.
• The local server rejects foreign Host headers, keeping the picker API reachable only from your own machine.
• Published to PyPI, so installing no longer needs a git URL or tag.

Changed

• codemble with flags but no path serves the picker instead of the current directory; pass a path (or --path) for the previous behaviour.

codemble ./path, --path, and codemble parse are unchanged.

Verification

• CI and Pages green on the tagged commit (5c66045).
• Wheel carries the packaged SPA (13 files under codemble/web_dist); isolated venv install reports codemble 0.3.0 and serves the picker.
• Checksums in SHA256SUMS.

Full changelog: https://github.com/udhawan97/Codemble/blob/v0.3.0/CHANGELOG.md

Codemble v0.2.0 — Phase 1 polyglot tester release

Codemble v0.2.0 — Phase 1 polyglot tester release

Codemble now maps Python, JavaScript, TypeScript, and mixed projects into one
local parser-proven galaxy. The new language focus lets learners reduce a mixed
sky without changing the graph, coordinates, progress, or uncertainty behind it.

Highlights

• One language-neutral project parser composes all supported source files and
  resolves Home across languages without changing Python-only graph bytes
• Official tree-sitter JavaScript, TypeScript, and TSX grammars support .js,
  .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts
• Exact structures, spans, imports, calls, entrypoint candidates, and partial
  syntax recovery stay parser-owned; approximate relationships stay labeled
  possible
• JavaScript/TypeScript Lens notes cover parser-proven async/await, arrows,
  destructuring, optional chaining, nullish coalescing, modules, types,
  interfaces, generics, and JSX
• Language-tagged star-chart concepts prevent same-named Python and TypeScript
  evidence from colliding
• Accessible All/Python/JavaScript/TypeScript focus works at desktop and 320 px,
  preserves external/unresolved edges, and never rewrites the stored graph
• Production SPA assets ship in the wheel; install from the v0.2.0 Git tag
  with pipx or uvx without Node at runtime

Known limits

• Source adapters currently cover Python, JavaScript, and TypeScript; unsupported
  languages are not parsed or described
• Projects above 300 supported source files must select a subdirectory
• Dynamic or configuration-dependent JavaScript/TypeScript resolution remains
  explicitly possible rather than being promoted to fact
• Syntax-error files remain visible as unchartable raw source
• Narration requires a bring-your-own Anthropic or OpenAI key; the galaxy,
  source, Lens, checks, and progress work without one
• The original unaided Python learner-acceptance issue remains open; this
  technical release does not fabricate human onboarding evidence

Codemble v0.1.0 — Phase 0 tester release

Codemble v0.1.0 — Phase 0 tester release

Codemble now completes the first Python learning loop locally: parser-proven
galaxy, source study, evidence-validated optional narration, Python Lens,
graph-only active recall, permanent illumination, and the language star chart.

Highlights

• Deterministic Python graph with explicit uncertain, external, and partial state
• Scripted galaxy → system → study navigation with no free flight
• Exact source and parser-proven Lens notes even without an API key
• Direct Anthropic/OpenAI narration with evidence validation and local caching
• Four graph-only check families with file-scoped, restart-safe illumination
• Honest ambiguous-Home calibration and a 300-file Phase 0 scope guard
• Packaged web assets: install from the v0.1.0 Git tag with pipx or uvx

Known limits

• Python only; TypeScript/JavaScript begins after Phase 0 learner acceptance
• Projects above 300 Python files must select a subdirectory
• Syntax-error files remain visible as unchartable raw source
• Narration requires a bring-your-own Anthropic or OpenAI key; all structural
  learning features work without one
• Human first-run acceptance is still being collected from 3–5 early testers