# Completed: AbstractFlow Compact Node Pin Disclosure

## Metadata
- Created: 2026-06-04
- Status: Completed
- Completed: 2026-06-04

## ADR status
- Governing ADRs: ADR-0035
- ADR impact: None

## Context
AbstractFlow nodes currently expose most pins at all times. This makes workflows noisy, especially
for media generation, LLM Call, Agent, memory, and metadata nodes where provider/model defaults and
generation defaults make many pins optional.

The existing media-only disclosure control renders a selected-only text button labeled `Advanced`
inside media nodes. It hides a small hardcoded set of media pins, but does not provide a general
node abstraction and does not hide unset provider/model or common default tuning pins.

## Current code reality
- `abstractflow/src/components/nodes/BaseNode.tsx` owns node rendering and currently applies
  `getVisibleMediaPins(...)` only for media node types.
- `abstractflow/src/utils/mediaPinDisclosure.ts` contains hardcoded media advanced-pin lists.
- `abstractflow/src/types/flow.ts` defines `Pin` as `id`, `label`, `type`, and optional
  `description`; there is no persisted required/advanced/default visibility metadata.
- `abstractflow/src/types/nodes.ts` defines templates and `createNodeData(...)` default
  `pinDefaults`, including media defaults, Agent `max_iterations`, transcription defaults, and Code
  permissions.
- `abstractflow/src/utils/preflight.ts` hardcodes required media inputs separately from rendering.
- VisualFlow JSON persists full `data.inputs`, `data.outputs`, `pinDefaults`, `effectConfig`, and
  `agentConfig`. Runtime and Gateway depend on those full arrays and configs remaining intact.

## Problem
Canvas readability suffers because nodes show advanced/default pins even when they are unused.
The current `Advanced` pill is visually heavy, media-specific, selected-only, and too narrow. A
naive fix that removes hidden pins from persisted node data would break saved flows, edge handles,
Gateway publishing, and Runtime execution.

## What we want to do
Add a generic AbstractFlow presentation policy that collapses unused/default pins by default while
preserving all serialized pins and runtime behavior.

## Why
Workflow authors should see the pins needed to understand and run a node first. Provider/model,
format, tuning, metadata, debug, and compatibility pins should remain available without making every
node large by default. Existing workflows must continue to load and run unchanged.

## Requirements
- Keep full `data.inputs` and `data.outputs` serialized; hide pins only at render time.
- Always show execution pins.
- Always show minimal/primary pins for the node's purpose.
- Always show connected pins.
- Always show pins with explicit non-default values in `pinDefaults`, `effectConfig`, or
  `agentConfig`.
- Hide unset provider/model pins when Gateway/Core defaults make `Auto` valid.
- Hide default tuning and diagnostic pins unless expanded, connected, or explicitly configured.
- Replace the visible text `Advanced` button with an icon-style bottom chevron disclosure control.
- Preserve React Flow handle correctness by updating node internals after expand/collapse.
- Keep dynamic/configured pins visible when they are generated by node configuration.

## Suggested implementation
- Replace or wrap `mediaPinDisclosure.ts` with a generic `nodePinDisclosure.ts` helper.
- Define an initial policy table by node family and special node type:
  - LLM/Agent primary pins: `system`, `prompt`, primary `response`.
  - Media primary pins: prompt/text/source artifact/audio input and primary artifact/text output.
  - Memory/KG primary pins: main query/assertion/input and primary result output.
  - Small transform/control/literal nodes: keep existing pins unless clearly optional/default.
  - Diagnostic outputs: metadata/raw/artifact ids/success remain hidden unless wired.
- Compare configured values against template defaults so default materialized values do not force
  pins visible.
- Keep current one-off connected-pin preservation for legacy outputs, but move it into the generic
  policy where practical.

## Scope
- AbstractFlow UI and helper logic.
- Focused tests or build checks for compact disclosure behavior.
- Browser validation of representative media and LLM/Agent nodes on the local dev server.

## Non-goals
- Do not change Gateway or Runtime execution contracts for this collapse feature.
- Do not edit Core/Gateway route defaults from Flow.
- Do not remove or rename persisted pin IDs.
- Do not make LLM/Agent prompt a hard preflight requirement just because it is primary.
- Do not solve every future metadata schema question in this item.

## Dependencies and related tasks
- ADR-0035 capability routing defaults.
- Completed item `0172_explicit_multimodal_default_fallback_routing.md`.
- Completed item `0177_flow_route_aware_model_selection.md`.
- Planned item `0179_llm_agent_model_input_artifacts.md` may add future primary artifact-list pins.

## Expected outcomes
- Newly placed media, LLM, Agent, memory, and metadata-heavy nodes are compact by default.
- Existing connected pins stay visible and usable.
- Explicitly configured non-default pins stay visible after collapse.
- The old `Advanced` text/count pill is gone.
- Expanded nodes expose hidden advanced pins through a bottom chevron control.
- Saved VisualFlow JSON remains compatible with Gateway and Runtime.

## Validation
- `npm run build` in `abstractflow`.
- Focused tests for disclosure policy if a lightweight TS test harness is available or added.
- Manual browser check on the local AbstractFlow dev server:
  - create or inspect Generate Image, Edit Image, Generate Voice, Transcribe Audio, LLM Call, and
    Agent nodes;
  - confirm compact default pins;
  - connect an advanced/default-hidden pin and confirm it becomes visible;
  - expand and collapse with the bottom chevron;
  - confirm no visible `Advanced` text pill remains.

## Progress checklist
- [x] Add generic disclosure policy helper.
- [x] Integrate policy into `BaseNode`.
- [x] Replace the old media `Advanced` UI with a bottom chevron.
- [x] Classify representative node families and high-noise node types.
- [x] Add or run focused tests/build checks.
- [x] Validate in browser with screenshots.
- [x] Record completion evidence before moving to `completed/`.

## Guidance for the implementing agent
Re-check current code before editing. Treat collapse as a rendering concern unless new evidence
proves otherwise. Preserve pending user changes, avoid saved-flow migrations unless strictly
necessary, and report any mismatch between backlog assumptions and code reality.

## Completion report

### Date
2026-06-04

### Summary
AbstractFlow now uses a generic UI-only node pin disclosure policy. Compactable nodes render only
their execution handles, primary purpose pins, connected pins, and explicitly non-default configured
pins by default. Optional provider/model, tuning, metadata, diagnostic, and compatibility pins remain
serialized and become visible when the node is expanded, connected, or configured away from
template defaults.

The previous media-only visible `Advanced` pill was replaced with an icon-style bottom chevron. The
control uses accessible `aria-label`/`title` text and an optional numeric badge, but no visible
`Advanced` label.

### Files and symbols touched
- `abstractflow/src/utils/nodePinDisclosure.ts`
  - Added `getNodePinDisclosure(...)`, `hasNonDefaultConfiguredPinValue(...)`, and
    `isMediaPresentationNode(...)`.
  - Added a node-type policy table for high-noise media, LLM, Agent, memory, event, data, and
    metadata nodes, while leaving small transform/control nodes uncollapsed.
- `abstractflow/src/components/nodes/BaseNode.tsx`
  - Integrated the generic disclosure result into rendered input/output data pins.
  - Preserved full persisted `data.inputs` and `data.outputs`.
  - Calls `updateNodeInternals(...)` after rendered pin changes and disclosure toggles.
  - Replaced the selected-only media disclosure button with a generic bottom chevron.
- `abstractflow/src/styles/nodes.css`
  - Restyled disclosure as a compact icon-only bottom control with a count badge.
- `abstractflow/src/utils/nodePinDisclosure.test.ts`
  - Added focused policy tests for media, LLM, connected hidden pins, non-default defaults, small
    nodes, and VisualFlow serialization preservation.
- `abstractflow/package.json` and `abstractflow/package-lock.json`
  - Added `vitest` and `npm test` so disclosure policy behavior can be checked without a browser.
- `docs/backlog/overview.md`
  - Moved this item from active planned work to recent completed work.

### Behavior changes
- Newly rendered media generation, media editing, transcription, voice generation, LLM Call, Agent,
  and similar high-noise nodes are compact by default.
- Connected optional pins remain visible after collapse.
- Explicit non-default provider/model/tuning/config values remain visible after collapse.
- Materialized template defaults, such as default image steps or format, do not force pins visible.
- Provider/model pins can stay hidden when unset because Gateway/Core defaults are valid.
- Runtime and Gateway contracts are unchanged; saved VisualFlow JSON still carries all pins.

### Validation
- `cd abstractflow && npm test`
  - Passed: 1 test file, 8 tests.
- `cd abstractflow && npm run build`
  - Passed. Vite emitted the existing large-chunk warning only.
- `cd abstractflow && npm run lint`
  - Passed.
- Static UI text check:
  - Confirmed there is no visible `Advanced`/`Hide advanced` disclosure text in the edited node UI;
    only internal variable names and accessible labels remain.
- Browser QA:
  - Existing full local stack was running on `http://127.0.0.1:3000` with Gateway on `8080`.
  - A headless Chrome screenshot of `http://127.0.0.1:3000/` was captured at
    `/tmp/abstractflow-compact-pins-port3000.png`; the fresh profile reached the Flow sign-in gate.
  - A separate isolated Flow dev server on `http://127.0.0.1:3003` was verified with Playwright.
    Screenshots were saved:
    - `/tmp/abstractflow-compact-pins-domdrop-compact.png`
    - `/tmp/abstractflow-compact-pins-domdrop-expanded.png`
    - `/tmp/abstractflow-compact-pins-connected-expanded.png`
    - `/tmp/abstractflow-compact-pins-connected-collapsed.png`
  - Browser checks confirmed compact defaults for Generate Image, Generate Voice, Transcribe Audio,
    LLM Call, and Agent; expand/collapse behavior; no visible `Advanced` text; and connected hidden
    pin preservation (`String.value -> Generate Image.negative` stayed visible after collapse).

### ADR impact
None. This is a Flow presentation-policy change that enforces ADR-0035-era default-provider routing
assumptions without changing Core/Gateway/Runtime ownership or capability-routing contracts.

### Residual risks
- The policy table is intentionally conservative. Future node types may need explicit entries if
  they become visually noisy.
- Browser capture on port `3000` could only prove the app/auth gate in the fresh headless Chrome
  profile; the functional canvas proof came from the isolated authenticated/dev Playwright path.

### Follow-ups
- Planned item `0179_llm_agent_model_input_artifacts.md` should update this policy when LLM/Agent
  artifact-list pins are introduced, likely treating those artifact-list pins as primary only when
  the selected model route supports the corresponding input modalities.

## Refinement report

### Date
2026-06-04

### Summary
Tightened the compact disclosure behavior after canvas review:
- removed the visible chevron count badge;
- kept Agent `tools` visible as a primary pin;
- stopped collapsing nodes when only one optional pin would be hidden;
- rendered `answer_user.level` as a fixed dropdown (`message`, `warning`, `error`);
- rendered `thinking` as a dropdown backed by selected-model capability metadata when available,
  and suppressed the pin for non-reasoning selected models unless a prior explicit value needs to be
  surfaced;
- added generated-video coverage so default width/height/frames/fps/format/steps/guidance values
  do not make optional pins visible while compact.

### Validation
- `cd abstractflow && npm test`
  - Passed: 1 test file, 13 tests.
- `cd abstractflow && npm run lint`
  - Passed.
- `cd abstractflow && npm run build`
  - Passed. Vite emitted the existing large-chunk warning only.
