github/codegraph
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ui): the Steps tab lays a screen out in clusters and says a far link in words; a <Card/> is the Card its file imports (#1817)

Browse Source 
* fix(ui): a screen's steps read as clusters, and a link too far to follow is said in words

The mobile app's /capture came back as a web: 100 boxes in a 1,227x5,588
ribbon, 113 lines drawn at rest crossing each other 652 times, each one
running over about five other boxes' names. Measured, not guessed — three
separate causes, very unequal.

The region grouping had nothing to divide there (98 of 100 boxes take their
region from one memoized component), so the picture fell back to a single
719px column. But the region dimension was not the lever. The lever was that
`packRegions` packed every step of one distance onto shared rows and wrapped
those rows at a fixed 720px, so a box and the thing it fires landed seven
lines apart: 70 of the 113 lines joined boxes ONE step apart. That is what
the crossings were made of.

So a region is now packed as CLUSTERS — a step, then the steps it sets in
motion on the line under it, stepped in — while the starting points that fire
nothing still share a line, because a screen's handlers are siblings and
giving each its own line turned a flat region into a column. A region's line
width is earned rather than fixed (sqrt(total * pitch), clamped 720..2600),
so a big screen comes out about as wide as it is tall.

Clustering makes most links local but not all: a step reached from two places
is drawn under whichever reached it first, so the other way in still crosses
the picture. Those are now said in WORDS at both ends — `-> resumeInference`
under the box that leads there, `<- CaptureView` under the box it arrives at,
capped at three with `+N more` — rather than drawn. This is not a hiding: the
link is stated, which says more than a line vanishing off the edge of the
screen does, and selecting the box draws every one of its real lines exactly
as before. It is the one at-rest cut that does not produce the "box that leads
somewhere and draws nothing" every earlier cut produced.

Also fixed while here, and predicted by the earlier region work: the in-region
row relaxation had no cycle guard, so a region holding one loop pushed 65 of
its boxes to rows 294-301 while the rest sat at 0-2. `forwardLinks` sets
cycle-closing links aside first, as the order reading's `withoutBackEdges`
already did.

/capture: 1,227x5,588 -> 2,279x4,356, at-rest crossings 652 -> 1,
lines-over-boxes 553 -> 26, with half the links still drawn as real lines and
every quiet box still one the screen itself fires directly. The order reading
is untouched (it keeps every line).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTUFNN5bH3aPw2gi2LqbYD

* fix(ui): a stub names its box without the mark the box wears for its kind

`← ⇠ onCaptureProgress +2` reads as two arrows arguing: the stub already
leads with a direction, and the box's own kind mark was competing with it.
Verified in the live canvas. The box keeps its mark, where nothing competes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTUFNN5bH3aPw2gi2LqbYD

* fix(ui): the screen's line into each of its parts stops sweeping the picture

Audited all 51 screens of the mobile app on this branch. 96 lines — the
screen's own stand-in line into each region — were 17% of everything drawn
and caused 79% of every crossing left. A screen with ten regions tiles them
into bands, so the line into a region two bands down travelled the height of
the whole picture.

Two causes, both fixed. The entry the line lands on was the walk's first
member of the region; clustering moves a step that fires something BELOW the
ones that fire nothing, so that box could sit lines down inside the region
and the line had to reach past everything above it. It now lands on the box
nearest the region's top-left that the screen actually leads to. And the
stand-in line is no longer exempt from the stub rule — when the region is
still too far to follow, the link is said in words like any other. The rest
of the anchor's fan stays quiet as before: it is already stood in for.

Across the 51 screens: crossings 47 -> 10, no screen above 10 (worst was 19,
now 2); lines-over-boxes 236 -> 182; boxes with neither a line nor a word
150 -> 135.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTUFNN5bH3aPw2gi2LqbYD

* fix(ui): a screen's parts fill the canvas instead of squaring off into rows

Audited the app's 28 regioned screens: the median canvas was 55% region and
45% nothing, and /home was 44% — 4,860px tall to hold about 2,160px of
picture. The cause is that regions were tiled a row at a time with each row
as tall as its tallest member, so one short region beside a tall one left the
rest of that row blank, and a reader scrolls through the blank.

Each region now goes as high as it can and then as far left as it can, over a
skyline of what is already placed. Reading order is untouched: regions are
still walked in the screen's own source order, so an earlier one is never
pushed below a later one — a short one just tucks under another short one
rather than waiting for the tall one beside it. Layering now comes from the
finished geometry rather than a band counter, since once regions drop
independently what a reader sees as one row IS one row.

/home 4,860px -> 3,584px, aspect 0.59 -> 0.94. Tallest screen in the app
4,860 -> 4,356. Crossings 10 -> 13 across all 51 screens, still none above 10.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTUFNN5bH3aPw2gi2LqbYD

* fix(ui): the width a picture wraps at is tried, not estimated

A region's line width came from sqrt(total * pitch) — the width at which
total/width lines come out square. That estimate is wrong for how these
pictures are drawn: a cluster spends lines on its own structure (a hub gets a
line to itself, and what it fires starts another), so it undercounts a
region's lines badly and wrapped /capture's 98 boxes into a 4,356px column.

Laying a picture out is cheap and exact, so the widths are tried instead:
layoutAt runs the whole pack at each of eight widths and the best finished
canvas wins (~2ms for the model, all eight included). It has to be scored on
the CANVAS, not per region — squaring each region off individually leaves
fewer of them side by side, which took /home from 3,584px to 5,624px while
every region looked better on its own.

Also measured and rejected while here: dropping a region's CLUSTERS side by
side the way the regions drop onto the canvas. Total height 42,084 -> 39,756px
(-6%), but lines-over-boxes 120 -> 134 and crossings 5 -> 8, because two
clusters side by side put each one's lines through the other. Height is cheap
to scroll; a crossed line is what made this picture unreadable. The reasoning
is recorded in the code so it is not re-tried blindly. Regions differ — they
sit far enough apart that few lines run between them.

Across the app's 51 screens: tallest picture 4,356 -> 3,796px, total height
45,744 -> 42,084px, lines-over-boxes 184 -> 120, crossings 13 -> 5, and no
screen is a tall ribbon any more.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTUFNN5bH3aPw2gi2LqbYD

* stuff

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
2026-09-09 00:54:15 -05:00
committed by GitHub
co-authored by Claude Opus 5
parent 7a23648db9
commit 3ed73bc127
11 changed files with 1044 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
__tests__/jsx-child-disambiguation.test.ts
+131
View File
@@ -0,0 +1,131 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { CodeGraph } from '../src';
/**
* A JSX tag names ONE component, and the file it is written in says which:
* the one that file declares, or the one it imports. The synthesizer used to
* take the first node of that name in the whole graph, which is a coin flip as
* soon as a name repeats — and repeated component names are the norm, not the
* exception (`Section`, `Picker`, `FrameCard`, one per feature folder).
*
* Getting it wrong costs twice: the parent gains an edge to a component it
* never renders, and the component it DOES render is left with no caller, so
* every walk back from that subtree — Screens' navigation attribution,
* `getCallers`, an impact radius — dead-ends there. On an Expo app that showed
* up as a navigation standing alone on the Screens tab with no screen behind
* it, while the edge pointed at an unrelated card in another sheet.
*
* Each decoy here is deliberately named to sort BEFORE the right answer, so a
* first-match resolver picks it and the test fails.
*/
describe('JSX child disambiguation among same-named components', () => {
let dir: string;
let cg: any;
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsx-child-'));
fs.writeFileSync(path.join(dir, 'package.json'), '{"dependencies":{"react":"^18.0.0"}}');
});
afterEach(() => {
cg?.close?.();
fs.rmSync(dir, { recursive: true, force: true });
});
const write = (rel: string, body: string) => {
const p = path.join(dir, rel);
fs.mkdirSync(path.dirname(p), { recursive: true });
fs.writeFileSync(p, body);
};
async function index() {
cg = await CodeGraph.init(dir, { silent: true });
await cg.indexAll();
return (cg as any).db.db;
}
/** The files a jsx-render edge out of `parent` points into. */
const rendersFrom = (db: any, parent: string): string[] =>
db
.prepare(
`SELECT t.file_path AS f FROM edges e
JOIN nodes s ON s.id = e.source
JOIN nodes t ON t.id = e.target
WHERE s.name = ? AND json_extract(e.metadata, '$.synthesizedBy') = 'jsx-render'
ORDER BY f`
)
.all(parent)
.map((r: any) => r.f);
it('follows the import when the same name is declared in another file', async () => {
write('a-decoy/card.tsx', `export function Card() { return <div>decoy</div>; }\n`);
write('real/card.tsx', `export function Card() { return <div>real</div>; }\n`);
write(
'grid.tsx',
`import { Card } from './real/card';
export function Grid() { return <div><Card /></div>; }
`
);
const db = await index();
expect(rendersFrom(db, 'Grid')).toEqual(['real/card.tsx']);
});
it('follows a tsconfig path alias the same way a relative import is followed', async () => {
fs.writeFileSync(
path.join(dir, 'tsconfig.json'),
JSON.stringify({ compilerOptions: { baseUrl: '.', paths: { '@/*': ['src/*'] } } })
);
write('src/a-decoy/row.tsx', `export function Row() { return <li>decoy</li>; }\n`);
write('src/real/row.tsx', `export function Row() { return <li>real</li>; }\n`);
write(
'src/list.tsx',
`import { Row } from '@/real/row';
export function List() { return <ul><Row /></ul>; }
`
);
const db = await index();
expect(rendersFrom(db, 'List')).toEqual(['src/real/row.tsx']);
});
it('prefers a component declared in the same file over a same-named import elsewhere', async () => {
write('a-decoy/pill.tsx', `export function Pill() { return <span>decoy</span>; }\n`);
write(
'toolbar.tsx',
`function Pill() { return <span>local</span>; }
export function Toolbar() { return <div><Pill /></div>; }
`
);
const db = await index();
expect(rendersFrom(db, 'Toolbar')).toEqual(['toolbar.tsx']);
});
it('prefers a JS component over a same-named class in the app’s native half', async () => {
// A React Native app: `<CaptureSettings/>` is the TS component the screen
// imports, never the Swift type that happens to share its name.
write('a-ios/CaptureSettings.swift', `class CaptureSettings {\n func sync() {}\n}\n`);
write('ui/capture-settings.tsx', `export function CaptureSettings() { return <div />; }\n`);
write(
'ui/overlay.tsx',
`import { CaptureSettings } from './capture-settings';
export function Overlay() { return <div><CaptureSettings /></div>; }
`
);
const db = await index();
expect(rendersFrom(db, 'Overlay')).toEqual(['ui/capture-settings.tsx']);
});
it('still links a name that appears exactly once', async () => {
write('only/badge.tsx', `export function Badge() { return <b>1</b>; }\n`);
write(
'header.tsx',
`import { Badge } from './only/badge';
export function Header() { return <h1><Badge /></h1>; }
`
);
const db = await index();
expect(rendersFrom(db, 'Header')).toEqual(['only/badge.tsx']);
});
});
__tests__/ui-steps-model.test.ts
+198 -5
View File
@@ -278,15 +278,60 @@ describe('a screen laid out by region', () => {
it('keeps a step above what it sets in motion, inside its region', () => {
expect(at(anchor.id).y).toBeLessThan(at(a1.id).y);
expect(at(a1.id).y).toBe(at(a2.id).y);
expect(at(a3.id).y).toBeGreaterThan(at(a1.id).y);
// A step that fires something is drawn as a cluster of its own — itself,
// then what it fires under it, stepped in. A step that fires nothing does
// not need one, so the two are no longer on the same line.
expect(at(a3.id).x).toBeGreaterThan(at(a1.id).x);
});
it('spreads the steps that fire nothing along one line, and clusters the ones that do', () => {
// A screen's handlers are siblings, not a hierarchy: giving each its own
// line turned a flat region into a column. Only a step that sets something
// in motion earns a cluster.
const D = { id: 'component:PanelD', label: 'PanelD' };
const root = step('/', 'screen', 0, { anchor: true });
const flat = [0, 1, 2].map((i) => step(`tap${i}`, 'trigger', 1, { order: i, region: D }));
const hub = step('tapRun', 'trigger', 1, { order: 3, region: D });
const under = step('runThing', 'store', 2, { order: 4, region: D, node: ref('runThing', 'src/d.storage.ts') });
const m = buildStepsModel(
payload(
[root, ...flat, hub, under],
[...[...flat, hub].map((s) => link(root, s)), link(hub, under, { kind: 'store' })]
)
);
const y = (id: string) => m.layout.nodes.find((n) => n.id === id)!.y;
expect(new Set(flat.map((s) => y(s.id))).size).toBe(1);
expect(y(hub.id)).toBeGreaterThan(y(flat[0]!.id));
expect(y(under.id)).toBeGreaterThan(y(hub.id));
});
it('settles a region that holds a cycle instead of running to the bound', () => {
// Relaxation over a cyclic graph never stops moving: one real screen sent
// sixty-five of its boxes to rows 294-301 while the rest sat at 0-2.
const E = { id: 'component:PanelE', label: 'PanelE' };
const root = step('/', 'screen', 0, { anchor: true });
const p1 = step('one', 'trigger', 1, { order: 0, region: E });
const p2 = step('two', 'trigger', 2, { order: 1, region: E });
const p3 = step('three', 'trigger', 3, { order: 2, region: E });
const m = buildStepsModel(
payload([root, p1, p2, p3], [link(root, p1), link(p1, p2), link(p2, p3), link(p3, p1)])
);
const ys = [p1, p2, p3].map((s) => m.layout.nodes.find((n) => n.id === s.id)!.y);
const pitch = 40 + m.layerGap;
// Three boxes, so at most three lines of them — not one line per pass.
expect((Math.max(...ys) - Math.min(...ys)) / pitch).toBeLessThanOrEqual(2);
});
it('at rest hides only the screen’s own fan and what points back up; every other lead-to draws', () => {
expect(model.regionEntries).toEqual(new Set([a1.id, b1.id]));
// The screen's one line into a region lands on the box nearest the region's
// top-left that the screen leads to — `tapUndo`, which fires nothing and so
// sits on the region's first line, not `tapSave`, which clustering moves
// below it because it fires the store.
expect(model.regionEntries).toEqual(new Set([a2.id, b1.id]));
// One line from the screen into each region stands in for its whole fan.
expect(stepEdgeVisible(model, edge(anchor.id, a1.id), null)).toBe(true);
expect(stepEdgeVisible(model, edge(anchor.id, a2.id), null)).toBe(false);
expect(stepEdgeVisible(model, edge(anchor.id, a2.id), null)).toBe(true);
expect(stepEdgeVisible(model, edge(anchor.id, a1.id), null)).toBe(false);
expect(stepEdgeVisible(model, edge(anchor.id, b1.id), null)).toBe(true);
// A region's internal line, and another region's way into a shared step.
expect(stepEdgeVisible(model, edge(a1.id, a3.id), null)).toBe(true);
@@ -295,7 +340,7 @@ describe('a screen laid out by region', () => {
expect(stepEdgeVisible(model, edge(a1.id, b1.id), null)).toBe(false);
// Selecting a step brings out everything that touches it, and only that.
expect(stepEdgeVisible(model, edge(a1.id, b1.id), a1.id)).toBe(true);
expect(stepEdgeVisible(model, edge(anchor.id, a2.id), a1.id)).toBe(false);
expect(stepEdgeVisible(model, edge(anchor.id, b1.id), a1.id)).toBe(false);
});
it('stacks a handler above the store it calls, even when both are one hop from the screen', () => {
@@ -320,3 +365,151 @@ describe('a screen laid out by region', () => {
expect(plain.regionEntries).toBeNull();
});
});
describe('a link too far to draw is said in words', () => {
// Two chains in one region, and a link from the tail of the first to the
// tail of the second. The clusters are drawn one under the other, so that
// one link has to cross the whole region — the kind of line that, times a
// hundred, crossed itself six hundred and fifty-two times on a real screen.
const G = { id: 'component:PanelG', label: 'PanelG' };
const anchor = step('/', 'screen', 0, { anchor: true });
const chain = (p: string) =>
[0, 1, 2, 3].map((i) => step(`${p}${i}`, 'trigger', i + 1, { order: i, region: G, node: ref(`${p}${i}`, 'src/g.tsx') }));
const a = chain('a');
const b = chain('b');
const links = [
link(anchor, a[0]!),
link(anchor, b[0]!),
...a.slice(1).map((s, i) => link(a[i]!, s)),
...b.slice(1).map((s, i) => link(b[i]!, s)),
// The long one, from the bottom of the first cluster to the bottom of the second.
link(a[3]!, b[3]!),
];
const model = buildStepsModel(payload([anchor, ...a, ...b], links));
const far = model.layout.edges.find((e) => e.source === a[3]!.id && e.target === b[3]!.id)!;
const near = model.layout.edges.find((e) => e.source === a[0]!.id && e.target === a[1]!.id)!;
it('draws the hop a reader can follow and words the one they cannot', () => {
expect(stepEdgeVisible(model, near, null)).toBe(true);
expect(stepEdgeVisible(model, far, null)).toBe(false);
expect(model.stubbed.has(far.id)).toBe(true);
expect(model.stubbed.has(near.id)).toBe(false);
});
it('says it at BOTH ends, so neither box reads as wired to nothing', () => {
expect(model.stubs.get(a[3]!.id) ?? []).toContainEqual(
expect.objectContaining({ edge: far.id, dir: 'out', label: 'b3' })
);
expect(model.stubs.get(b[3]!.id) ?? []).toContainEqual(
expect.objectContaining({ edge: far.id, dir: 'in', label: 'a3' })
);
});
it('draws every one of a box\u2019s real lines again when it is selected', () => {
expect(stepEdgeVisible(model, far, a[3]!.id)).toBe(true);
expect(stepEdgeVisible(model, far, b[3]!.id)).toBe(true);
// ...and still not for an unrelated selection.
expect(stepEdgeVisible(model, far, a[1]!.id)).toBe(false);
});
it('never words the screen\u2019s own fan \u2014 that is already one line per region', () => {
for (const list of model.stubs.values()) {
for (const stub of list) expect(stub.other).not.toBe(anchor.id);
}
});
it('leaves a picture whose every line is local alone', () => {
const plain = buildStepsModel(
payload([step('/x', 'screen', 0, { anchor: true }), step('go', 'trigger', 1)], [
link(step('/x', 'screen', 0, { anchor: true }), step('go', 'trigger', 1)),
])
);
expect(plain.stubbed.size).toBe(0);
expect(plain.stubs.size).toBe(0);
});
});
describe('a stub names the box without its kind mark', () => {
it('drops the ⇢ / ⇠ a bridge or an event wears, so the direction reads alone', () => {
const H = { id: 'component:PanelH', label: 'PanelH' };
const anchor = step('/', 'screen', 0, { anchor: true });
const mk = (p: string) => [
step(`${p}0`, 'trigger', 1, { order: 0, region: H, node: ref(`${p}0`, 'src/h.tsx') }),
step(`${p}1`, 'trigger', 2, { order: 1, region: H, node: ref(`${p}1`, 'src/h.tsx') }),
step(`${p}2`, 'trigger', 3, { order: 2, region: H, node: ref(`${p}2`, 'src/h.tsx') }),
step(`${p}3`, 'bridge', 4, { order: 3, region: H, node: ref(`${p}3`, 'ios/H.swift', 'swift') }),
];
const a = mk('a');
const b = mk('b');
const links = [
link(anchor, a[0]!),
link(anchor, b[0]!),
...a.slice(1).map((s, i) => link(a[i]!, s)),
...b.slice(1).map((s, i) => link(b[i]!, s)),
link(a[3]!, b[3]!),
];
const m = buildStepsModel(payload([anchor, ...a, ...b], links));
expect(stepLabel(b[3]!)).toBe('⇢ b3');
expect(m.stubs.get(a[3]!.id) ?? []).toContainEqual(
expect.objectContaining({ dir: 'out', label: 'b3' })
);
});
});
describe('regions fill the canvas instead of squaring off into rows', () => {
it('lets a short region tuck under another short one, without reordering them', () => {
// Squaring the regions into rows made every row as tall as its tallest
// member: one real screen's canvas came out 44% region and 56% nothing.
const anchor = step('/', 'screen', 0, { anchor: true });
const region = (n: string) => ({ id: `component:${n}`, label: n });
const short = (n: string, order: number) =>
step(n, 'trigger', 1, { order, region: region('R' + n), node: ref(n, `src/${n}.tsx`) });
// One tall region (a chain), then several short ones beside it.
const tallR = region('Tall');
const chain = [0, 1, 2, 3, 4, 5].map((i) =>
step(`t${i}`, 'trigger', i + 1, { order: i, region: tallR, node: ref(`t${i}`, 'src/t.tsx') })
);
const a = short('alpha', 10), b = short('beta', 11), c = short('gamma', 12);
const steps = [anchor, ...chain, a, b, c];
const links = [
...[chain[0]!, a, b, c].map((s) => link(anchor, s)),
...chain.slice(1).map((s, i) => link(chain[i]!, s)),
];
const m = buildStepsModel(payload(steps, links));
const zone = (n: string) => m.regions!.find((z) => z.label === n)!;
const tall = zone('Tall');
// The short regions are laid out after the tall one and do not wait for it.
for (const n of ['Ralpha', 'Rbeta', 'Rgamma']) {
expect(zone(n).y).toBeLessThan(tall.y + tall.height);
}
// …and the order still reads left to right: an earlier region is never
// pushed below a later one.
expect(zone('Ralpha').y).toBeLessThanOrEqual(zone('Rgamma').y);
// The canvas is not taller than the tall region needs it to be.
const H = Math.max(...m.layout.nodes.map((n) => n.y + n.height));
expect(H).toBeLessThan(tall.y + tall.height + 200);
});
});
describe('the width a picture wraps at is tried, not estimated', () => {
it('lets a wide spread run wide instead of wrapping into a column', () => {
// A cluster spends lines on its own structure, so `total width / line
// width` badly under-counts the lines a region takes: a formula tuned on
// that estimate wrapped a 98-box region into a 4,356px column. The widths
// are cheap to try exactly, so they are tried.
const R = { id: 'component:Wide', label: 'Wide' };
const anchor = step('/', 'screen', 0, { anchor: true });
const hub = step('startEverything', 'trigger', 1, { order: 0, region: R, node: ref('startEverything', 'src/w.tsx') });
const leaves = Array.from({ length: 24 }, (_, i) =>
step(`writeSomeValue${i}`, 'store', 2, { order: i + 1, region: R, node: ref(`writeSomeValue${i}`, 'src/w.storage.ts') })
);
const m = buildStepsModel(
payload([anchor, hub, ...leaves], [link(anchor, hub), ...leaves.map((l) => link(hub, l, { kind: 'store' }))])
);
const W = Math.max(...m.layout.nodes.map((n) => n.x + n.width));
const H = Math.max(...m.layout.nodes.map((n) => n.y + n.height));
// At a fixed 720px these twenty-four boxes wrapped into eight lines and the
// picture came out taller than wide; it should now be at least as wide.
expect(W).toBeGreaterThan(H);
});
});