ASCII Diagram Builder

Safe patterns (no drift):

• Box side edges (│ left and │ right) — both lines use the same character mix (box chars + content), so they track together.
• └───────┘ followed by │ on the next line — the │ is preceded by only spaces, and the ┘ above is a single character. No accumulated drift reaches the │ column.
• └─── label ───┘ spanning between two │ above — works as long as └ and ┘ are at the exact columns of the │ they connect to. Compute the width programmatically.

Broken patterns (drift accumulates):

• ┬ in a box border with │ below on a space-padded line — the ─ chars before ┬ accumulate drift, so ┬ and │ appear misaligned.
• Side-by-side ┐ ┌ on a border line with │ │ on a content line — the space between ┐ and ┌ drifts relative to │ │ below.
• Nested boxes inside an outer box — inner box ┐ drifts from inner box │ because the outer │ + inner ─ mix differently from outer │ + inner content.

How to Generate Diagrams

Always use the bundled helper script rather than hand-drawing boxes. Run it with bun to generate diagram fragments, then paste into markdown.

The Helper Functions

The script at scripts/box-helpers.ts exports these functions:

box(indent, width, lines)     → string[]  // Complete box with ┌┐└┘
padR(str, width)               → string    // Right-pad to exact width
vert(col)                      → string    // │ at exact column
arrow(col)                     → string    // ▼ at exact column
sideBySide(boxes, gap)         → string[]  // Merge boxes horizontally

Usage Pattern

Write a bun -e script that builds the diagram, then copy the output into your markdown:

bun -e '
const { box, vert, arrow } = require("./scripts/box-helpers.ts");

const appBox = box(2, 48, [
  " APPLICATION LAYER",
  " src/application/",
  "",
  " recap.ts: collect → orchestrate → apply",
]);

const out = [
  ...appBox,
  vert(21),      // │ at col 21 (below the box)
  arrow(21),     // ▼ at col 21
];

console.log(out.join("\n"));
'

Connecting Boxes Vertically

Place │ and ▼ on their own lines between boxes. The column should be computed, not hardcoded:

const appBox = box(2, 48, [...]); // left=2, right=49
const center = 2 + Math.floor(48 / 2); // col 26

const out = [
  ...appBox,
  vert(center),
  arrow(center),
  ...nextBox,
];

Flowing a Line Alongside a Box

When a vertical line needs to flow alongside a box (e.g., a timer connection running next to a larger box), pad each box line to the line's column:

const TIMER_COL = 50;
const hooksBox = box(2, 48, [...]);

// Add timer │ to the right of each hooks box line
for (const l of hooksBox) {
  out.push(padR(l, TIMER_COL) + "│");
}

Side-by-Side Boxes

When placing boxes next to each other, use sideBySide:

const left = box(2, 24, [" AppLayer", " (services)", ""]);
const right = box(32, 24, [" Own runtime", " ├─ Handlers", ""]);
const merged = sideBySide([left, right], 6); // 6-char gap

This avoids the ┐ ┌ gap problem by handling padding programmatically.

Nested Content Without Nested Boxes

Instead of nesting boxes inside a box (which causes ─/space drift between the inner box borders and content), use indented text:

Don't:

│ ┌────────────┐ ┌─────────────┐ │
│ │ GitCollect. │ │ ClaudeSess. │ │   ← inner ┐ drifts from │ below
│ │ git log     │ │ ~/.claude/  │ │
│ └────────────┘ └─────────────┘ │

Do:

│   GitCollector     git log, git branch     │
│   ClaudeSession    ~/.claude/projects/     │
│   CodexHistory     ~/.codex/history.jsonl  │

Validation

After generating a diagram, verify alignment by checking that:

1. Every ┌ has a ┐ at the exact column = indent + width - 1
2. Every interior line has │ at both left (indent) and right (indent + width - 1)
3. The └┘ bottom matches the ┌┐ top width exactly
4. No ┬ or ┴ in box borders (use plain └──┘ + │ below)
5. No nested side-by-side boxes inside an outer box
6. Any └───┘ connector has └ and ┘ at the exact │ columns above

If the project has scripts/validate-ascii-diagrams.ts, run it to check.

Style Guidelines

• Maximum line width: 78 characters (leaves room for 2-char markdown indent)
• Use box-drawing characters only: ─ │ ┌ ┐ └ ┘ ├ ┤
• Arrows: ▼ ▲ ▶ ◀ for direction, ──▶ for horizontal connections
• ◀ for incoming connections (e.g., │ inbox │◀────┘)
• Keep text inside boxes left-aligned with 1 space indent
• Empty lines inside boxes for visual grouping
• Labels outside boxes for annotations (e.g., "etch recap run")