# 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
