feat(expo-router): add Expo Router support for Screens and navigations and introduce Steps API

- Adds Expo Router integration with a new Screens view and a Steps API to surface screens and their transitions.
- Extends codegraph extraction/resolution to handle namespace objects, React hook bindings for handlers, and Swift RN bridge evidence; introduces per-site guard arguments and trigger metadata, enabling richer flow analysis across JS ↔ native boundaries.
- Introduces UI and data-model changes to represent conditions as words (WHEN/AND/OR/NOT), display per-site call arguments, and show what fires a site (triggers). Adds new utilities (ui/conditions.ts) and updates ScreensView and StepsView to render scenarios with multiple sites and “ways” counts.
- Implements site readers for WHEN/ARGS/TRIGGER, and wiring to expose steps via API endpoints (including /api/steps); enhances tests to cover namespace resolution, useCallback-driven handlers, and inline RN event listeners.
- Updates styling and templates to reflect the new wording, scenario rows, and per-site details, including NOT instead of leading negation strings and multi-way links.
- Documents and reflects changes in changelog and design docs to describe Expo Router integration and the Steps surface.

__tests__/branch-guards.test.ts

@@ -4,7 +4,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { CodeGraph } from '../src';
 import { initGrammars } from '../src/extraction/grammars';
-import { guardsInSource, guardLabel, supportsBranchGuards } from '../src/graph/branch-guards';
+import { callArgumentsInSource, guardsInSource, guardLabel, supportsBranchGuards } from '../src/graph/branch-guards';
 import { buildNode } from '../src/ui-server/api/node';
 import { buildFlow } from '../src/ui-server/api/flow';
 
@@ -48,6 +48,21 @@ export function ItemCard(props) {
     expect(await labelAt(handlePress, 'openObjectDetail(')).toBe('!isUploading && isCollected');
   });
 
+  it('keeps a disjunctive guard in parentheses, so the join stays unambiguous', async () => {
+    const src = `
+function go(object) {
+  if (isUploading) return
+  if (!object?.id || !object?.name) {
+    bail()
+    return
+  }
+  proceed()
+}
+`;
+    expect(await labelAt(src, 'bail(')).toBe('!isUploading && (!object?.id || !object?.name)');
+    expect(await labelAt(src, 'proceed(')).toBe('!isUploading && !(!object?.id || !object?.name)');
+  });
+
   it('turns each earlier early-return into a negated guard, in source order', async () => {
     expect(await labelAt(handlePress, 'handleAddToQueue(')).toBe('!isUploading && !isCollected && queueHasItems');
     expect(await labelAt(handlePress, 'handleStartCapture(')).toBe('!isUploading && !isCollected && !queueHasItems');
@@ -238,3 +253,57 @@ describe('branch guards: on the wire', () => {
     cg.close();
   });
 });
+
+
+// =============================================================================
+// Call arguments — what a site passes
+// =============================================================================
+
+async function argsAt(src: string, needle: string, language: 'tsx' | 'typescript' | 'swift' = 'tsx') {
+  const line = lineOf(src, needle);
+  const column = src.split('\n')[line - 1]!.indexOf(needle);
+  return callArgumentsInSource(src, language, line, column);
+}
+
+describe('call arguments', () => {
+  const login = `
+async function handleLogin(values) {
+  await SecureStore.setItemAsync('userEmail', values.email)
+  const res = await client.post('/auth/login', { email: values.email, password, ...rest })
+  Alert.alert(i18n.t('error_login_failed'), err.message, [{ text: 'OK' }])
+  router.push({ pathname: '/item/[id]', params: { id } })
+  captureView.finalizeCaptureSession()
+  run(() => go(), async (x) => x, new Thing(1))
+  const big = fetch(\`/api/\${id}\`, { method: 'POST', headers, body, mode, cache, credentials })
+}
+`;
+
+  it('keeps literals and names whole, folds objects to their keys, arrays and functions to a shape', async () => {
+    expect(await argsAt(login, 'SecureStore.setItemAsync(')).toBe("'userEmail', values.email");
+    expect(await argsAt(login, 'client.post(')).toBe("'/auth/login', { email, password, ...rest }");
+    expect(await argsAt(login, 'Alert.alert(')).toBe('i18n.t(…), err.message, […]');
+    expect(await argsAt(login, 'router.push(')).toBe('{ pathname, params }');
+    expect(await argsAt(login, 'run(')).toBe('() => …, () => …, new Thing(…)');
+    expect(await argsAt(login, 'fetch(')).toBe('`/api/${id}`, { method, headers, body, mode, … }');
+  });
+
+  it('an empty argument list is an empty string; a position outside a call is null', async () => {
+    expect(await argsAt(login, 'captureView.finalizeCaptureSession(')).toBe('');
+    expect(await argsAt(login, 'async function handleLogin')).toBeNull();
+  });
+
+  it('Swift: labels stay with their values, a trailing closure is a shape', async () => {
+    const src = `
+class CaptureEvents {
+  func emitZipComplete(result: ZipResult) {
+    sendEvent(withName: "onZipComplete", body: ["zipURL": result.url])
+    tracker.setup(side: side, angle: 45)
+    DispatchQueue.main.async { finish() }
+  }
+}
+`;
+    expect(await argsAt(src, 'sendEvent(', 'swift')).toBe('withName: "onZipComplete", body: […]');
+    expect(await argsAt(src, 'tracker.setup(', 'swift')).toBe('side: side, angle: 45');
+    expect(await argsAt(src, 'DispatchQueue.main.async', 'swift')).toBe('{ … }');
+  });
+});

__tests__/ui-conditions.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Conditions as a reader says them: the joins we add (`&&` between guards,
+ * `||` between a link's scenarios, `!(…)` around a negated guard) become
+ * and / or / not, the code inside a guard stays code, and a link with several
+ * call sites is several scenarios with their shared clauses said once.
+ */
+import { describe, it, expect } from 'vitest';
+import { clauseWords, clauses, restWords, scenarios, splitTop, whenWords } from '../ui/src/lib/conditions';
+
+describe('conditions', () => {
+  it('splits at the top level only, respecting brackets and strings', () => {
+    expect(splitTop('a && (b || c) && "x && y" && d', ' && ')).toEqual(['a', '(b || c)', '"x && y"', 'd']);
+    expect(splitTop('a && b || c && d', ' || ')).toEqual(['a && b', 'c && d']);
+    expect(clauses('!busy && isCollected')).toEqual(['!busy', 'isCollected']);
+    // A merged condition has no single innermost clause: it comes back whole.
+    expect(clauses('a && b || c')).toEqual(['a && b || c']);
+  });
+
+  it('says NOT for our negations and leaves the code inside alone', () => {
+    expect(clauseWords('!busy')).toBe('NOT busy');
+    expect(clauseWords('!user?.organization_id')).toBe('NOT user?.organization_id');
+    expect(clauseWords('!(isUploadInProgress || elapsed < 5000)')).toBe('NOT (isUploadInProgress || elapsed < 5000)');
+    // `!(a) || b` is not a negated whole: untouched.
+    expect(clauseWords('!(a) || b')).toBe('!(a) || b');
+    expect(clauseWords('(!object?.id || !object?.name)')).toBe('(!object?.id || !object?.name)');
+    expect(clauseWords('selectedDetectionItems.length === 1')).toBe('selectedDetectionItems.length === 1');
+  });
+
+  it('words a whole condition: AND within a scenario, OR between scenarios', () => {
+    expect(whenWords('!(busy || late) && user?.organization_id && !object?.id')).toBe(
+      'NOT (busy || late) AND user?.organization_id AND NOT object?.id'
+    );
+    expect(whenWords('!x && y || !x && !y')).toBe('NOT x AND y OR NOT x AND NOT y');
+    // The same guard met twice along a chain is said once.
+    expect(whenWords('ctl && !(!ctl || done) && !(!ctl || done) && ready')).toBe('ctl AND NOT (!ctl || done) AND ready');
+    expect(scenarios([{ when: 'a && a && b' }]).common).toEqual(['a', 'b']);
+    expect(whenWords('')).toBe('');
+  });
+
+  it('factors the clauses every scenario shares, and keeps each row’s own tail', () => {
+    const sites = [
+      { line: 248, when: '!(busy || late) && !user?.organization_id' },
+      { line: 257, when: '!(busy || late) && user?.organization_id && (!object?.id || !object?.name)' },
+      { line: 292, when: '!(busy || late) && user?.organization_id && !(!object?.id || !object?.name) && items.length === 1' },
+      { line: 306, when: '!(busy || late) && user?.organization_id && !(!object?.id || !object?.name) && !items.length' },
+    ];
+    const sc = scenarios(sites);
+    expect(sc.common).toEqual(['!(busy || late)']);
+    expect(sc.rows.map((r) => r.rest)).toEqual([
+      ['!user?.organization_id'],
+      ['user?.organization_id', '(!object?.id || !object?.name)'],
+      ['user?.organization_id', '!(!object?.id || !object?.name)', 'items.length === 1'],
+      ['user?.organization_id', '!(!object?.id || !object?.name)', '!items.length'],
+    ]);
+    expect(restWords(sc.rows[0]!.rest, true)).toBe('AND NOT user?.organization_id');
+    expect(restWords(sc.rows[2]!.rest, true)).toBe(
+      'AND user?.organization_id AND NOT (!object?.id || !object?.name) AND items.length === 1'
+    );
+  });
+
+  it('one site is one scenario with nothing left to say; no shared prefix says when', () => {
+    expect(scenarios([{ when: 'a && b' }])).toEqual({ common: ['a', 'b'], rows: [{ site: { when: 'a && b' }, rest: [] }] });
+    const sc = scenarios([{ when: 'a' }, { when: 'b' }, { when: '' }]);
+    expect(sc.common).toEqual([]);
+    expect(restWords(sc.rows[0]!.rest, false)).toBe('WHEN a');
+    expect(restWords(sc.rows[2]!.rest, false)).toBe('always');
+    expect(scenarios([])).toEqual({ common: [], rows: [] });
+  });
+});

__tests__/ui-screens-model.test.ts

@@ -190,7 +190,7 @@ describe('edgeLabel', () => {
     const collect = edgeLabel([link('/home', '/capture/collect', `${chain}guide.dontShowAgain.captureGuide`)]);
     const intro = edgeLabel([link('/home', '/guide', `${chain}!guide.dontShowAgain.captureGuide`)]);
     expect(collect).toBe('…guide.dontShowAgain.captureGuide');
-    expect(intro).toBe('…!guide.dontShowAgain.captureGuide');
+    expect(intro).toBe('…NOT guide.dontShowAgain.captureGuide');
     // The whole point: two arms of a fork no longer read the same.
     expect(collect).not.toBe(intro);
   });

__tests__/ui-steps-api.test.ts

@@ -73,6 +73,7 @@ beforeAll(async () => {
       '  const handleZipComplete = useCallback(async (data: { uri: string }) => {\n' +
       '    setZipUri(data.uri)\n' +
       '    await uploadARCapture(data.uri)\n' +
+      "    Alert.alert('Uploaded', data.uri, [{ text: 'OK' }])\n" +
       "    if (unlimited) router.replace('/')\n" +
       '  }, [unlimited])\n' +
       '  useEffect(() => {\n' +
@@ -192,6 +193,7 @@ describe('buildSteps', () => {
 
     const link = (from: string, to: string) =>
       payload.links.find((l) => l.from === byLabel.get(from)!.id && l.to === byLabel.get(to)!.id);
+    const req = link('handleZipComplete', 'client.post +1');
     expect(link('/capture/review', 'handleApprove')?.kind).toBe('handler');
     expect(link('handleApprove', 'finalizeCaptureSession')?.kind).toBe('bridge');
     const evt = link('finalizeCaptureSession', 'handleZipComplete');
@@ -200,14 +202,26 @@ describe('buildSteps', () => {
     expect(evt?.via.map((v) => v.name)).toEqual(['emitZipComplete']);
     expect(evt?.when).toBe('result');
     expect(evt?.label).toContain('event onZipComplete');
-    expect(link('handleZipComplete', 'setZipUri')?.kind).toBe('store');
-    const req = link('handleZipComplete', 'client.post +1');
+    const storeLink = link('handleZipComplete', 'setZipUri');
+    expect(storeLink?.kind).toBe('store');
+    // Every call-shaped site says what it passes.
+    expect(storeLink?.sites[0]?.args).toBe('data.uri');
+    expect(link('handleApprove', 'finalizeCaptureSession')?.sites[0]?.args).toBe('');
+    // One call behind an effect box: the box says it. Several: the panel does.
+    const alert = payload.steps.find((s) => s.kind === 'effect' && s.effect?.category === 'device')!;
+    expect(alert.label).toBe("Alert.alert('Uploaded', data.uri, […])");
+    expect(network.label).toBe('client.post +1');
+    expect(req?.sites.map((s) => `${s.text}(${s.args})`)).toEqual(["client.post('/frames', { uri })", "client.get('/frames/status')"]);
     expect(req?.kind).toBe('effect');
     expect(req?.via.map((v) => v.name)).toEqual(['uploadARCapture']);
     const nav = link('handleZipComplete', '/');
     expect(nav?.kind).toBe('navigates');
     expect(nav?.when).toBe('unlimited');
     expect(nav?.sites[0]?.text).toBe('replace /');
+    // Every site carries the whole condition it runs under — one scenario each.
+    expect(nav?.sites[0]?.when).toBe('unlimited');
+    expect(evt?.sites[0]?.when).toBe('result');
+    expect(storeLink?.sites[0]?.when).toBe('');
 
     // Rows: the anchor on 0, then one more step away each. The listener is
     // registered BY the screen (`addListener('onZipComplete', handleZipComplete)`),

__tests__/ui-steps-model.test.ts

@@ -70,7 +70,7 @@ describe('steps model', () => {
     const edges = [...model.edges.values()];
     expect(edges).toHaveLength(6);
     const toBridge = edges.find((e) => e.to === bridge.id)!;
-    expect(toBridge.label).toBe('!busy');
+    expect(toBridge.label).toBe('NOT busy');
     expect(toBridge.kind).toBe('bridge');
     const toEvent = edges.find((e) => e.to === event.id)!;
     expect(toEvent.synthesized).toBe(true);