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

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, where the system evaluates whether to generate a successor diff or a full folded view based on the transition state:

// 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 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 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 constructs a concise representation containing only added, updated, and removed nodes:

// 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:

// 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 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 and src/view.ts, with shouldRenderDiff and diffState handling confidence calculations.
• foldToBudget in src/outline.ts manages recursive collapsing for both rendering modes.
• 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 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 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}