[jgrodziski]

Second step of milestone M19b in PLAN.md §20 (word cloud / glossary, #6). Stacked on #31 (itself on #30, #29, #28, #27 and #26): review those first; this PR's diff is the eight commits after #31.

It adds the navigator's Vocabulary tab and the two server routes behind it: /vocabulary.json, the artifact, and /carriers.json, a lookup of the names that carry a word.

The carriers (carriers.ts)

• One counting rule. The rule that turns an entity's name into weighted words moved out of aggregate.ts into reading.ts, so the artifact and the carriers read a name the same way. The artifact's snapshots are unchanged.
• A row is the sum of its carriers. For a scope and a word, the carriers' weights, occurrences and count add up to the word's row in the artifact. A property checks it for every word of every scope in the six fixtures.
• Same options or no answer. An artifact counted under other weights, another technical list or another view is refused, and so is one built from another model.
• Who a carrier is. Types and modules carry their id. A method, field or parameter carries an owner instead (its type, else its module), as in the navigator, which has no node for it.
• The query. No scope means the corpus. limit defaults to 200 and total always counts them all. A word that two languages classify differently is ambiguous, and the answer lists the classes to pick from with class.

On the Java fixture, order at the corpus has 12 carriers of total weight 40, which matches the hand count in the fixture README.

The routes (codegraph serve)

• /vocabulary.json is built from the same model, view and name as the navigator and the city, so a scope's id is the navigator node's id.
• /carriers.json?term=…[&class=…][&scope=…][&limit=…] answers 200 when found, 400 for a bad request or an ambiguous word, and 404 for an unknown scope or word. Bad parameters are refused before anything is built.
• The index is built on the first answerable request, reading every kept entity once, and the graph is released then. A page nobody clicks costs nothing.
• The desktop app's daemon builds vocabulary.json beside the navigator and the city, and rebuilds the page when one is missing. It has no /carriers.json, because it keeps no model between jobs (it serves no explanations either). The tab shows the counts there and says why the names are missing.

The tab (navigator-ui)

• The cloud and a table of the scope selected in Navigate. A method or field shows its type's words. A breadcrumb steps up to the module and the corpus.
• Class toggles, a top-N slider (5 to 200, default 40), and the same legend as the SVG.
• Clicking a word lists its carriers, heaviest first, each with its role, weight and file. Clicking a carrier opens it in Navigate.
• The layout is the same code as --svg. It comes through a new @codegraph/vocabulary/cloud entry, cloud.ts alone, which imports nothing. The guard test allows that one specifier and keeps the package's index types-only for the page; the page's constants are restated and pinned to the package's. The built bundle contains none of the Node pipeline.
• No colour. Words are bright, dimmed or faint by class, because the page's four colours already mean incoming, outgoing, inferred and selected. The page measures with measureText in its monospace face.
• The tab mounts on first visit and then stays alive while hidden, like the City tab.

Worth a look in review:

• The daemon has no carriers route (above). The alternative was keeping each job's model in memory.
• Carriers are capped at 200 per answer. Broadleaf's order has 3,303; the tab says "the 200 heaviest of 3,303".
• The navigator tutorial on the website lists four tabs and already lacked City. Updating it means re-running its gson model for real numbers, so it moves to the next PR's website section.

Verification

• pnpm -r build and pnpm -r typecheck green; eslint clean on every changed file; pnpm run gen:schemas leaves schemas/ unchanged; the Hugo site builds.
• vocabulary 324 tests, cli 987, navigator-ui 105; every other package passes except the Node 26 node:sqlite warning test noted on feat(core): language lexicons on profiles (M19a) #26.
• 17 deliberate mutations, one at a time, of the carriers, the browser entry's type-only check, the CLI wiring and the page's model; the tests caught each.
• In the browser (headless Chrome at 1600×1000, on BroadleafCommerce):
  • The corpus cloud reads order item customer offer product…, and ProductImpl reads product category sale sku parent.
  • catalog.domain with product picked lists 239 carriers, and clicking a parameter among them opened Category in Navigate.
  • A page served with no carriers route shows the counts and the explanation.
  • No console error.
• The single-executable (./build.sh --ts --sea) serves both new routes, and its smoke checks pass.

PLAN §20.2 records the carriers and the tab as built; §20.4's serve and tab items are checked.

Part of #6.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	codegraph	67ae45d	Commit Preview URL Branch Preview URL	Oct 27 2026, 03:05 PM