Optionalroot: CommandScope | null
The command tree root to read on the focus walk (pull discovery — regions record via CommandScope.attachElement). Omit for a standalone tracker whose regions register directly into it (tests/stories).
OptionalinitialAnchor: FocusActivationInitial
Optional initial anchor. Two forms:
Element resolved
through the same region walk a real focus takes (retried a few frames — the region may register
just after the consumer resolves, e.g. a first-paint callback racing the registration effect), or a
Promise the consumer settles at its own moment (the studio: post-load, pre-reveal). Seeds once;
inert if real focus set the anchor first.Start tracking focus within rootElement (its region of interest).
The nearest registered scope at or above element (a dynamic-leaf source is resolved to its
current value). undefined if none is registered on the bounded walk.
The nearest registered anchor source at or above element, bounded by the attached root.
Pure DOM-tree walk; undefined if none, or if element is outside the attached root.
The focus-driven anchor (null until the initial anchor / first focus lands). A dynamic-leaf
source (a getter) is evaluated live each call, so a pane always anchors at its current chain top.
The attached region (or null before attach). Keystroke handling binds here.
Associate a DOM element with an AnchorSource (a provider calls this with its element ref).
Pass a getter for a dynamic leaf (a pane's Stage → its live chain top); a fixed scope for an
ordinary region (the editor's own element).
Fires when the anchor changes — and, for region trackers, when the region attaches/detaches.
A focus-driven ActivationTracker: the anchor follows DOM focus within the region it's attached to. The new-model counterpart of
CommandGroup._activate— the element walk and de-dupe guard are kept (therelatedTarget === null"just for testing" bail is dropped, so a first focus-in still activates).It is region-scoped:
findScopeis bounded by the attached root, so focus outside that root never changes the anchor. That's how "main toolbar tracks focus anywhere" (attach to the app root) and "scripting toolbar tracks focus only in the editor" (attach to the editor element) are the same class with different attach points — focus leaving the editor simply leaves the scripting tracker's anchor untouched.The anchor starts
nulland there is no standing "default" slot. A consumer that wants a live anchor before the user ever focuses supplies an initial anchor to the constructor — a value or aPromiseit resolves at its own lifecycle moment (the studio: the loaded grid's center pane, right before the loading reveal). The initial anchor is a synthetic first focus: it lands in the same single slot real focus writes to (anElementis resolved through the same region walk afocusintakes), does nothing if focus got there first, and is advanced by later focus like any other anchor. Grids never steal real focus for this.Destruction fallback — a recallable provider (COMMAND-DESIGN.md open-Q5). If the initial anchor is supplied as a function, it is a default-anchor provider: invoked once for cold-start AND re-invoked whenever the live anchor's element is destroyed — e.g. a resize that shrinks the grid past its min unmounts the focused pane, dropping DOM focus to
<body>with nofocusinto observe. Left alone,getAnchor()would keep resolving through the now- detached region (the "anchor out of the root" symptom). Instead getAnchor notices the anchored element is no longer connected, drops it, and asks the provider for a fresh default (the studio: the pane focus would land on — last-focused, else center). The consumer owns that policy; the tracker only owns when to ask. A one-shot value/Promisecannot be re-run, so it seeds once with no recall — pass a function to opt into the fallback.Leaf-only, two producers (design/COMMAND-DESIGN.md §"resolution model"). This is the
Focusproducer; ManualActivation is the other. A chain change bumps the root version, so a CommandResolver — which also subscribes to scope changes — re-resolves and re-reads the live top; no effective-region subscription is needed here.