diy-layout-creator/diylc/docs/plans/explorer-refresh.md

# Project Explorer Refresh Cost

`ExplorerPane` (`diylc-swing/.../plugins/explorer`) rebuilds its whole list on every
`PROJECT_MODIFIED`, `PROJECT_LOADED` and `SELECTION_CHANGED`, even when the panel is collapsed
and even when the change cannot affect what it shows. This plan removes both costs without
touching `diylc-core` or the event contract.

## 1. How the explorer is driven today

- `Presenter` uses `MessageDispatcher<EventType>(true)` — **synchronous**. Every
  `processMessage` runs on the EDT inside the call that changed the project, so explorer work
  adds directly to the latency of the edit that triggered it.
- The dispatcher reads `getSubscribedEventTypes()` **once, at registration**, and there is no
  unregister path on `IPlugInPort`. "Disconnecting" therefore means returning early from
  `processMessage`, which costs one method call per event and is equivalent in practice.
- `ExplorerPlugin.processMessage`:
  - `PROJECT_MODIFIED` / `PROJECT_LOADED` → `ExplorerPane.setComponents(all, selection)`.
  - `SELECTION_CHANGED` → `setSelection(...)`. (It also falls through to `default`; harmless.)
  - `FILE_STATUS_CHANGED` is subscribed but unused.
- What `setComponents` costs, for *n* components:
  1. sort/filter/reverse copy of the component list;
  2. `buildComponentListWithGroups` — a UUID→component map over the whole project plus a
     set per group;
  3. `fireContentsChanged(0, n)` — with no fixed cell height, `BasicListUI` re-measures
     **every row** through the renderer, and most rows are `<html>` labels, so each row is
     an HTML parse. This is the dominant cost;
  4. `setSelection` rebuilds the group map again and does a linear scan per selected item.

### Which interactions reach the explorer

Read from `Presenter`; to be confirmed by measurement (step 0).

| Interaction | Events reaching the explorer | Changes the list? |
| --- | --- | --- |
| Mouse drag of components / control points, per mouse move | none — `dragOver` fires only `REPAINT` | — |
| Drag start (`dragStarted`) | `SELECTION_CHANGED` | selection only |
| Drag end (`dragEnded`) | `SELECTION_CHANGED` + `PROJECT_MODIFIED("Drag")` | no |
| Arrow-key nudge (`nudgeSelection`), per key repeat | `PROJECT_MODIFIED("Move Selection")` | no |
| Rotate / mirror / align / distribute | `PROJECT_MODIFIED` | no |
| Click on canvas (even on the already-selected part) | `SELECTION_CHANGED` | selection only |
| Edit properties (name, value) | `PROJECT_MODIFIED("Edit Selection")` | yes |
| Add / delete / duplicate / paste, z-order, group / ungroup, undo / redo | `PROJECT_MODIFIED` or `PROJECT_LOADED` | yes |

So the explorer does not rebuild on every mouse move; it rebuilds once per *gesture* and once
per *key repeat*, and each rebuild is O(n) HTML layouts. On a large project that is the stall
felt at the start and end of each drag and the lag when holding an arrow key. If profiling in
step 0 shows explorer work *during* a drag, something else is dispatching and needs finding
before this plan is enough.

## 2. Decisions

**Visibility is checked with `isShowing()` and a `HierarchyListener`, not the config key.**
`CollapsiblePanel` hides the pane with `setVisible(false)`; `isShowing()` also covers an
ancestor being hidden and the frame not yet being displayed. `HierarchyEvent.SHOWING_CHANGED`
fires for all of those, whereas listening to `ConfigPlugin.PROJECT_EXPLORER` would miss
everything except the menu toggle.

**A hidden pane keeps no state in sync; it just remembers that it is stale.** On becoming
visible it pulls the current project and selection from `IPlugInPort` rather than replaying
events. On `PROJECT_LOADED` while hidden it also drops its model so it does not pin the
previous project's object graph.

**"Does this change affect the list" is decided by comparing a snapshot of what the list
shows, not by the action string.** `PROJECT_MODIFIED` carries a description (`"Drag"`,
`"Move Selection"`, …) that could be whitelisted, but those strings are scattered through
`Presenter`, are not a contract, and a missed one shows stale data. A snapshot is robust:
the pane records exactly the inputs its model and renderer read, and skips the rebuild when
they are unchanged. Capturing it is O(n) plain field reads, far cheaper than O(n) HTML
layouts.

The snapshot is a small private record (per `typed-records-over-string-keyed-maps`), holding
copies, not live references, because `Presenter` mutates components and groups in place:

- the component list **by identity, in z-order**;
- per component: `getName()`, `toString()` (used by the NAME/TYPE sorts) and
  `getValueForDisplay()`;
- per group: name and set of member UUIDs (`ComponentGroup` has no `equals`, and a rename
  mutates the existing instance).

The layer badge comes from `ComponentType.getZOrder()`, which is static per class, so it is
covered by identity.

**Selection sync is O(selected), not O(n).** `refresh()` builds a
`Map<IDIYComponent<?>, Integer>` from component to row index alongside the row list.
`setSelection` uses it instead of rebuilding the group map and scanning rows. The existing
"selection already matches" early-out stays.

**Rows get a fixed height.** `setFixedCellHeight` from the font metrics stops `BasicListUI`
from measuring every row through the HTML renderer whenever contents change. Rows are a
single line, so nothing is lost. This also speeds up the rebuilds that remain necessary.

**No debounce timer for now.** With the snapshot check, a nudge burst costs one O(n)
comparison per repeat and no layout. A `javax.swing.Timer` coalescer would add latency to
genuine edits for little gain; revisit only if step 0 shows the comparison itself matters.

## 3. Changes

All in `diylc-swing/src/main/java/org/diylc/swing/plugins/explorer/`. No core, library or
file-format changes; no regression-suite impact (the explorer is not rendered in exports).

1. **`ExplorerPane`**
   - Field `boolean stale`; method `refreshIfStale()` that, when showing, calls
     `setComponents(plugInPort.getCurrentProject().getComponents(),
     plugInPort.getSelectedComponents())`.
   - `HierarchyListener` in the constructor: on `SHOWING_CHANGED` with `isShowing()`, call
     `refreshIfStale()`.
   - `setComponents`: build the snapshot; if equal to the previous one, skip
     `ComponentListModel.setComponents` and go straight to `setSelection`.
   - `ComponentListModel.refresh()`: also build the component→row map.
   - `setSelection`: use the row map.
   - `getComponentList()`: `setFixedCellHeight(...)`.
   - Snapshot record declared at the bottom of the file with the other nested types.
2. **`ExplorerPlugin.processMessage`**
   - First line: if `!explorerPane.isShowing()`, mark the pane stale (and on `PROJECT_LOADED`
     clear its model), then return.
   - Add the missing `break` after `SELECTION_CHANGED`.
   - Drop `FILE_STATUS_CHANGED` from `getSubscribedEventTypes()`.

Search and sort changes call `refresh()` directly and bypass the snapshot
check; the snapshot only gates the event-driven path.

## 4. Status and next steps

Everything in §3 is implemented in the working tree and `diylc-swing` compiles. Not yet done:

1. **Measure.** On a large project (several hundred components), time `setComponents` and
   `setSelection`, or run a profiler, while dragging, holding an arrow key and editing a
   value. Compare against `master` to confirm the table in §1 and the gain.
2. **Manual check in the running app.** Collapse the explorer, edit, then expand: the list and
   selection should be correct. Repeat with undo/redo and file open while it is collapsed.
   Also check: rename and value edits in the property editor; group, rename the group, then
   ungroup; z-order drag inside the explorer; search and sort while visible; row height
   looks right under each look-and-feel/theme.
3. Add a debounce only if step 1 shows the snapshot comparison itself is significant.