Skip to content

feat(terminal): auto-abbreviate to short codes + legend on overflow - #20

Merged
bigboateng merged 1 commit into
render-json-examplefrom
terminal-legend-overflow
Jul 29, 2026
Merged

feat(terminal): auto-abbreviate to short codes + legend on overflow#20
bigboateng merged 1 commit into
render-json-examplefrom
terminal-legend-overflow

Conversation

@bigboateng

Copy link
Copy Markdown
Contributor

Stacked on #19 (base is render-json-example, since skills/cmg/SKILL.md is introduced there). Merge #19 first, then rebase this onto main.

What

In the default auto direction, when a compact chain or diamond would exceed the column budget, node labels are replaced with short, deterministic codes and a Legend block mapping each code back to its full name is appended. A near-linear flow now stays one readable row instead of collapsing into the stacked vertical node-list + Edges fallback.

┌────┐    ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐
│ CT │───▶│ CMG │───▶│ MGR │───▶│ GRT │───▶│ RRV │
└────┘    └─────┘    └─────┘    └─────┘    └─────┘

Legend
  CT = createTransform
  CMG = createModelGraph
  MGR = ModelGraph run
  GRT = GraphRun trace
  RRV = renderRun view

How

  • Codes derive from the names — word initials, or first-letter + leading consonants for a single word — de-duped in node order with the shortest numeric suffix on collision. Nothing is invented; the legend is just the node's own label.
  • Scoped to auto. Explicit direction:"horizontal" keeps its strict requires N columns error contract; explicit vertical is untouched. The behavior slots into a previously-uncovered middle column band, so no existing test moves.
  • Fallback preserved — if codes still don't fit, it falls to the vertical list exactly as before.

Parity & tests

  • Mirrored byte-identically in the Python twin (terminal/__init__.py) per the language-parity law; verified TS↔Python identical on chain-overflow, diamond-overflow, and narrow-vertical-fallback.
  • One new parity test in each suite (terminal.test.ts 18 ✓, test_terminal.py 10 ✓). Typecheck clean; example-19 snapshot unchanged.

Skill doc

skills/cmg/SKILL.md gains a note that full names are now fine in auto mode (the renderer abbreviates + legends automatically). This diff also folds in the earlier, still-uncommitted "paste inside a code fence" rendering guidance (fixes the proportional-font wrapping seen in GUI chats like Codex).

When a compact chain or diamond would exceed the column budget in the
default `auto` direction, node labels are replaced with short, deterministic
codes and a `Legend` block mapping each code to its full name is appended —
so a near-linear flow stays one readable row instead of collapsing to the
stacked vertical list. Codes derive from the names (word initials, or
first-letter + consonants for a single word), de-duped in node order;
nothing is invented. Explicit `direction:"horizontal"` keeps its strict
error contract, so the change slots into a previously-uncovered column band
and moves no existing test.

Mirrored byte-identically in the Python twin (language-parity law) with a
new parity test in each suite. Skill doc notes the behavior so callers can
pass full names and let the renderer decide.
@bigboateng
bigboateng merged commit 81fdfa1 into render-json-example Jul 29, 2026
bigboateng added a commit that referenced this pull request Jul 29, 2026
* feat(examples): render a diagram from a JSON spec (example 19)

Add a JSON->diagram loader so tools and agents that hold a graph as
plain data can render it deterministically. Reads a spec (file path or
stdin), builds the graph with identity transforms, and prints via the
terminal viewer. TypeScript + byte-identical Python twin.

* feat(skills): cmg skill — terminal system diagrams from any chat context

Drives example 19: maps whatever is in context (an architecture, a
pipeline, a Locus model/verdict, two designs) to a JSON graph spec and
renders it with the deterministic terminal viewer. Source of truth for
the byte-identical installs under ~/.claude/skills and ~/.codex/skills.

* feat(terminal): auto-abbreviate to short codes + legend on overflow (#20)

When a compact chain or diamond would exceed the column budget in the
default `auto` direction, node labels are replaced with short, deterministic
codes and a `Legend` block mapping each code to its full name is appended —
so a near-linear flow stays one readable row instead of collapsing to the
stacked vertical list. Codes derive from the names (word initials, or
first-letter + consonants for a single word), de-duped in node order;
nothing is invented. Explicit `direction:"horizontal"` keeps its strict
error contract, so the change slots into a previously-uncovered column band
and moves no existing test.

Mirrored byte-identically in the Python twin (language-parity law) with a
new parity test in each suite. Skill doc notes the behavior so callers can
pass full names and let the renderer decide.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant