# How Successor Diffs Render Minimal UI Changes versus Full Folded Views in pi-computer-use

> Explore how successor diffs in pi-computer-use display minimal UI changes compared to full folded views for efficient updates.

- Repository: [injaneity/pi-computer-use](https://github.com/injaneity/pi-computer-use)
- Tags: deep-dive
- Published: 2026-07-16

---

**Successor diffs in pi-computer-use render only trustworthy, budget-constrained changes between snapshots, falling back to full folded views when root identity changes, confidence is low, or the diff exceeds configured limits.**

The pi-computer-use repository implements an intelligent UI observation system that dynamically selects between minimal diff rendering and complete folded views. This optimization reduces token consumption while maintaining accurate representation of interface mutations through confidence-based decision logic defined in the bridge and view layers.

## Determining the View Mode in bridge.ts

The entry point for view selection resides in [`src/bridge.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/bridge.ts), where the system evaluates whether to generate a successor diff or a full folded view based on the transition state:

```typescript
// src/bridge.ts (excerpt)
const useDiff = transition && transition.changes && transition.changes.length > 0
               && !transition.fallbackToFull;
const view = useDiff ? "diff" : "full";

```

The `transition.changes` array originates from [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts) via the `diffState` function, while `transition.fallbackToFull` acts as a safety flag. When `useDiff` evaluates to true, the system transmits only the minimal changes; otherwise, it renders the entire folded outline.

## Fallback Conditions in view.ts

The `shouldRenderDiff` function in [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts) returns `false`—triggering a full view—when any of three confidence or budget conditions occur:

### Root Identity Changed

When the root element receives a new reference, indicating an entire window replacement rather than incremental updates, the system cannot reliably compute successors. This condition forces a full folded view to ensure the UI representation remains coherent.

### Insufficient Confident Matches

The successor algorithm requires stable node references to generate trustworthy diffs. When `diffState` encounters too many ambiguous nodes without confident identity matches, the resulting diff would be unreliable. In these cases, `fallbackToFull` is set to true.

### Change Budget Exceeded

The system enforces strict resource limits through `maxNodes` and `maxDepth` parameters. If the computed diff would exceed these configured budgets, rendering the full folded view becomes more efficient than transmitting a partial, oversized diff.

## Rendering a Minimal Diff

When all confidence checks pass, [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts) constructs a concise representation containing only added, updated, and removed nodes:

```typescript
// src/view.ts (excerpt)
if (useDiff) {
  const changes = computeChanges(base, successor);
  return {
    view: "diff",
    changes,
    renderedOutline: foldChanges(changes, successor.outline)
  };
}

```

The `computeChanges` function traverses both element trees, matching nodes by stable references and recording only those with confident identity matches. Subsequently, `foldChanges` applies the same budget constraints used for full views, but restricts the output to changed branches only. The resulting minimal diff appears as:

```

▸ (3) added: @e12, @e13, @e14
▸ (2) updated: @e5, @e9
▸ (1) removed: @e3

```

## Rendering a Full Folded View

When fallback conditions trigger, the bridge renders the complete UI outline through [`src/outline.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/outline.ts):

```typescript
// src/bridge.ts (excerpt)
const folded = foldToBudget(result.outline);   // full outline folded to budget
return {
  view: "full",
  renderedOutline: folded.text,
  // … other fields
};

```

The `foldToBudget` function recursively traverses the entire outline, collapsing children beyond `maxDepth` or `maxNodes` limits while appending folded summaries (e.g., `▸ (12)`) for hidden subtrees. This ensures the UI receives a complete yet compact representation when diffs are unavailable or inappropriate.

## Runtime State Management

Regardless of the rendering mode selected, [`src/runtime.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/runtime.ts) stores the complete resulting state immutably. This architectural guarantee ensures that subsequent tool calls—including `search_ui`, `expand_ui`, and `inspect_ui`—always operate on the full snapshot, even when the initial observation returned only a minimal diff.

## Summary

- **Successor diffs** render only trustworthy changes between base and successor snapshots, significantly reducing payload size for minor UI updates.
- **Full folded views** activate when the root element changes, confidence matches are insufficient, or the diff would exceed configured `maxNodes`/`maxDepth` budgets.
- The decision logic resides in [`src/bridge.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/bridge.ts) and [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts), with `shouldRenderDiff` and `diffState` handling confidence calculations.
- `foldToBudget` in [`src/outline.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/outline.ts) manages recursive collapsing for both rendering modes.
- [`src/runtime.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/runtime.ts) maintains complete immutable snapshots regardless of the view mode transmitted to the client.

## Frequently Asked Questions

### What triggers a fallback to full folded view in pi-computer-use?

The system falls back to a full folded view when [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts) detects a root identity change, insufficient confident node matches, or a diff size exceeding the configured budget. These conditions prevent unreliable partial updates by ensuring the client receives a complete, trustworthy representation.

### How does the change budget affect successor diff rendering?

The change budget, defined by `maxNodes` and `maxDepth` parameters, limits the size of both diff and full views. If `computeChanges` generates a diff that would exceed these limits, the system discards the partial result and renders the full folded outline instead, ensuring consistent token usage.

### Where is the view mode decision made?

The final view mode decision occurs in [`src/bridge.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/bridge.ts) through the `useDiff` boolean evaluation, which checks `transition.changes` and `transition.fallbackToFull`. However, the underlying confidence logic and diff computation reside in [`src/view.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/view.ts), specifically within the `shouldRenderDiff` and `diffState` functions.

### Does the runtime store the full UI state even when showing a minimal diff?

Yes. According to [`src/runtime.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/runtime.ts), the system stores the complete immutable snapshot regardless of whether the `observe_ui` call returns a `"diff"` or `"full"` view. This ensures that subsequent tool invocations like `expand_ui` or `search_ui` can access the entire interface state, not just the previously rendered changes.