vintage-frames 0.6.1 → 0.7.0

package/custom-elements.json

@@ -2349,7 +2349,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-desktop>` — the full-bleed classic desktop container.\n\nRenders the desktop pattern — the classic 50% dither by default, or any of\nthe standard patterns by name (`pattern`, System 7's General Controls\nsetting) — and manages the stacking order and `active` state of slotted\n`vf-window` children: a `pointerdown` or\n`focusin` (keyboard focus) anywhere inside a window brings it to the front\nand makes it the single active window. The windows' light-DOM order is kept\nin step with the stacking order (bottom-most first, synced in a task once\nany pointer gesture has ended), so tabbing walks the stack the way the eye\ndoes and Shift+Tab is its exact mirror.\n\nUtility windows (`vf-window[variant=\"utility\"]`) stack in a floating tier\nabove every document-tier window, restack only among themselves, and stand\noutside the single-active invariant entirely — clicking a palette neither\ndeactivates the active document window nor greys the palette, exactly as\nSystem 7's floating windoids behaved while their application was frontmost.\nA slotted `vf-menu-bar` (or a free-standing `vf-menu`) sits on a tier\nabove both, so its dropped menus cover palettes and document windows\nalike; only the screen-corner mask is in front of it.\n\n**Deactivation.** On a real System 7 machine clicking the desktop clicked\nthe *Finder* — the frontmost application's windows lost their stripes.\nclearActive is that gesture's handler: it clears `active` from\nthe whole document tier, and **zero active windows is a legal state**,\nheld until a press or keyboard focus re-enters a document window (or a\nnew one is slotted, which activates it — opening a window brings its\napplication forward). The desktop never takes this decision itself: its\nfurniture is slotted light DOM (an icon layer, say), so only the page\nknows which of its children — or which presses on the bare dither — mean\n\"the Finder\", and it routes those through `clearActive()`. Left alone,\nthe classic always-one-active behavior is unchanged. activeWindow\nreads the current holder, and every change of holder — including to and\nfrom none — fires `vf-activate`.\n\nThe desktop is a raster with an explicit size, always: **`width` and\n`height`**, in system px, the way a WIND resource declared a window's —\nthe host box renders at the declared screen plus `2 × bezel` per axis, a\nwhole number of system pixels by construction (default 512×342, the\ncompact Mac's screen). Pure CSS sizing is not supported; the page sets\nthe numbers — directly, or via VfDesktop.fitWithin on\n`resize`/`onScaleChange` for a viewport-filling desktop — and positions\nthe sized box with its own stylesheet, keeping any sub-system-pixel\nslack on its side. `bezel` (system px) draws the black screen surround —\nthe CRT's unlit margin — around the screen, rounding its top corners\nwith the classic corner mask.\n\n**`pattern`** names the desktop pattern — `gray-50` (the dither) by\ndefault, any of the 38 standard patterns (docs/PATTERNS.md), or sixteen\nhex digits stating a custom 8×8 pattern, as on `vf-container`. It is\npainted as the screen's own background: black ink on an opaque white\npaper, one whole-surface raster at one image px per system px, 1-bit at\nevery density and zoom (src/pattern-fill.ts).\n\nCustom properties:\n- `--vf-desktop-pattern` — a consumer's own tile art in place of the\n  pattern (the kit's default is a 1-bit 50% checker, opaque\n  black-on-white on a 30-system-px tile). Set, it wins over `pattern` and\n  renders as a placed tile grid at that same 30-px geometry\n  (src/tile-grid.ts); a token swapped at runtime without touching the\n  component wants a `requestUpdate()`.\n- `--vf-desktop` — base color painted *under* the pattern (default\n  `#808080`). The pattern's paper is opaque, so this only becomes visible\n  when `--vf-desktop-pattern` is overridden with a tile that has\n  transparent cells (or with `none`).",
+          "description": "`<vf-desktop>` — the full-bleed classic desktop container.\n\nRenders the desktop pattern — the classic 50% dither by default, or any of\nthe standard patterns by name (`pattern`, System 7's General Controls\nsetting) — and manages the stacking order and `active` state of slotted\n`vf-window` children: a `pointerdown` or\n`focusin` (keyboard focus) anywhere inside a window brings it to the front\nand makes it the single active window. The windows' light-DOM order is kept\nin step with the stacking order (bottom-most first, synced in a task once\nany pointer gesture has ended), so tabbing walks the stack the way the eye\ndoes and Shift+Tab is its exact mirror.\n\nUtility windows (`vf-window[variant=\"utility\"]`) stack in a floating tier\nabove every document-tier window, restack only among themselves, and stand\noutside the single-active invariant entirely — clicking a palette neither\ndeactivates the active document window nor greys the palette, exactly as\nSystem 7's floating windoids behaved while their application was frontmost.\nA slotted `vf-menu-bar` (or a free-standing `vf-menu`) sits on a tier\nabove both, so its dropped menus cover palettes and document windows\nalike; only the screen-corner mask is in front of it.\n\n**Deactivation.** On a real System 7 machine clicking the desktop clicked\nthe *Finder* — the frontmost application's windows lost their stripes.\nclearActive is that gesture's handler: it clears `active` from\nthe whole document tier, and **zero active windows is a legal state**,\nheld until a press or keyboard focus re-enters a document window (or a\nnew one is slotted, which activates it — opening a window brings its\napplication forward). The desktop never takes this decision itself: its\nfurniture is slotted light DOM (an icon layer, say), so only the page\nknows which of its children — or which presses on the bare dither — mean\n\"the Finder\", and it routes those through `clearActive()`. Left alone,\nthe classic always-one-active behavior is unchanged. activeWindow\nreads the current holder, and every change of holder — including to and\nfrom none — fires `vf-activate`.\n\nThe desktop is a raster with an explicit size, always: **`width` and\n`height`**, in system px, the way a WIND resource declared a window's —\nthe host box renders at the declared screen plus `2 × bezel` per axis, a\nwhole number of system pixels by construction (default 512×342, the\ncompact Mac's screen). Pure CSS sizing is not supported; the page sets\nthe numbers — directly, or via VfDesktop.fitWithin on\n`resize`/`onScaleChange` for a viewport-filling desktop — and positions\nthe sized box with its own stylesheet, keeping any sub-system-pixel\nslack on its side. `bezel` (system px) draws the black screen surround —\nthe CRT's unlit margin — around the screen, rounding its top corners\nwith the classic corner mask.\n\n**`pattern`** names the desktop pattern — `gray-50` (the dither) by\ndefault, any of the 38 standard patterns (docs/PATTERNS.md), or sixteen\nhex digits stating a custom 8×8 pattern, as on `vf-container`. It is\npainted as the screen's own background: black ink on an opaque white\npaper, one whole-surface raster at one image px per system px, 1-bit at\nevery density and zoom (src/pattern-fill.ts).\n\n**The drag surface.** The Finder dragged an icon as a dotted outline drawn\non the *screen*, clipped at its edge and phase-locked to its raster, so\nthe screen hosts the layer that outline draws on: a full-bleed child of\nthe screen, `pointer-events: none` (never a hit for the page's\n`elementsFromPoint`), whose children paint one tier above the menu bar\nand under the corner mask — the layer itself is deliberately no stacking\ncontext, since a blend inside one would composite against nothing. An\nicon reaches it without an import, the menu-handshake idiom: on a drag's\nfirst step it dispatches `vf-drag-surface-request` (bubbles, non-composed,\n`detail.surface` null), and the nearest desktop on its light-DOM path\nfills the detail with the layer. Not the top layer: stable Safari cannot\nblend an element there against the page (src/cursor.ts), and a second\nkit entry in the top layer would need a re-promotion handshake.\n\nCustom properties:\n- `--vf-desktop-pattern` — a consumer's own tile art in place of the\n  pattern (the kit's default is a 1-bit 50% checker, opaque\n  black-on-white on a 30-system-px tile). Set, it wins over `pattern` and\n  renders as a placed tile grid at that same 30-px geometry\n  (src/tile-grid.ts); a token swapped at runtime without touching the\n  component wants a `requestUpdate()`.\n- `--vf-desktop` — base color painted *under* the pattern (default\n  `#808080`). The pattern's paper is opaque, so this only becomes visible\n  when `--vf-desktop-pattern` is overridden with a tile that has\n  transparent cells (or with `none`).",
           "name": "VfDesktop",
           "cssProperties": [
             {
@@ -2439,6 +2439,30 @@
               ],
               "description": "Size the screen to the largest whole-system-px raster whose host box —\nbezel included — fits a CSS-px bound, and return what was set. The\npage's half of the sizing contract: it owns the viewport, so it\nmeasures the box and hands it here on `resize` and `onScaleChange`\n(zoom and density moves change how many CSS px a system px costs),\nand the sub-system-pixel remainder stays on the page, behind the\nbezel. The epsilon forgives float error in the division so an\nexact-fit bound never drops a whole system pixel."
             },
+            {
+              "kind": "method",
+              "name": "placementAt",
+              "return": {
+                "type": {
+                  "text": "{ left: number; top: number }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "clientX",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "clientY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "A viewport point (CSS px) as a placement on the screen — `{ left, top }`\nin whole system px on the placement lattice, measured from the raster's\ncorner with the bezel excluded: the pair a child dropped onto the desktop\nis written with. The screen sits in the shadow tree, which is why the\nconversion is a method here."
+            },
             {
               "kind": "field",
               "name": "_windows",
@@ -2504,6 +2528,16 @@
               "readonly": true,
               "description": "The screen surface the pattern paints on; exists from the first render."
             },
+            {
+              "kind": "field",
+              "name": "dragSurface",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "The layer a dragged icon's outline draws on; exists from the first render."
+            },
             {
               "kind": "field",
               "name": "patternFill",
@@ -2707,6 +2741,12 @@
               "privacy": "private",
               "description": "The press ended (or was cancelled) — schedule the DOM-order sync.\nUnconditional rather than only-if-raised: the sync no-ops when order\nalready agrees, and running it after every gesture is what heals the\nstaleness a keyboard-only stretch leaves behind (focus-driven raises\nchange z but never move nodes — see _raise)."
             },
+            {
+              "kind": "field",
+              "name": "_onDragSurfaceRequest",
+              "privacy": "private",
+              "description": "A dragged icon asking for the screen's drag surface (see the class\ndoc). Non-composed, so it reaches here only through the light-DOM path\nthe icon is slotted on — a window body included. The nearest desktop\nanswers; an outer one leaves a filled detail alone."
+            },
             {
               "kind": "field",
               "name": "_onFocusIn",
@@ -2995,7 +3035,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming). Both\nare the same dBoxProc double frame — 1px outer rule, 2px gap, 2px inner\nband, no shadow (vfModalFrame):\n\n- **Default:** the movable modal (movableDBoxProc) — the striped title bar\n  set into the top of that frame, with a centered title over a white body.\n  Drag the title bar to move it. `closable` adds the standard close box\n  (left of the bar) — the HIG's own figures disagree on whether a movable\n  modal carries one (Figure 5-1 says yes, Figure 6-1 and the Chapter 6 text\n  say no), so the component enables either reading rather than enforcing\n  one.\n- **`frame=\"plain\"`:** the modal dialog box — the bare frame, no title bar —\n  and immovable, like the original. A `heading` renders as a centered\n  display-face heading at the top of the body (the reference art's \"Dialog\n  title\"); `closable` is ignored, there being no bar to carry the widget.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`. With `light-dismiss`, a click outside the frame\ncloses it too, with `{ reason: 'outside' }` — for the About box; off by\ndefault, since the classic modal ignored an outside click.",
+          "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming). Both\nare the same dBoxProc double frame — 1px outer rule, 2px gap, 2px inner\nband, no shadow (vfModalFrame):\n\n- **Default:** the movable modal (movableDBoxProc) — the striped title bar\n  set into the top of that frame, with a centered title over a white body.\n  Drag the title bar to move it. `closable` adds the standard close box\n  (left of the bar) — the HIG's own figures disagree on whether a movable\n  modal carries one (Figure 5-1 says yes, Figure 6-1 and the Chapter 6 text\n  say no), so the component enables either reading rather than enforcing\n  one.\n- **`frame=\"plain\"`:** the modal dialog box — the bare frame, no title bar —\n  and immovable, like the original. A `heading` renders as a centered\n  display-face heading at the top of the body (the reference art's \"Dialog\n  title\"); `closable` is ignored, there being no bar to carry the widget.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`. With `light-dismiss`, a click outside the frame\ncloses it too, with `{ reason: 'outside' }` — for the About box; off by\ndefault, since the classic modal ignored an outside click.\n\nKeyboard, the classic Dialog Manager's two rules (VfModalDialog):\non open, focus goes to the first text-entry control — a slotted control\nwith `autofocus` first — or, with none, to the default button\n(`vf-button variant=\"default\"`). Return or Enter activates the default\nbutton from anywhere in the dialog, a focused Cancel included; Space\npresses the focused control. A link keeps its own Enter, and in a\nmulti-line editor Return inserts the newline while the keypad's Enter\nactivates the button.",
           "name": "VfDialog",
           "cssProperties": [
             {
@@ -3379,11 +3419,64 @@
             },
             {
               "kind": "field",
-              "name": "#dismissListeners",
+              "name": "#openListeners",
               "privacy": "private",
               "readonly": true,
-              "default": "new DocumentListenersController(this, () => [ [this._dialog, 'pointerdown', this.#onDialogPointerDown], [this._dialog, 'pointerup', this.#onDialogPointerUp], [this._dialog, 'pointercancel', this.#onDialogPointerCancel], ])",
-              "description": "The light-dismiss listeners, on the `<dialog>` itself and only while it is\nopen. The `::backdrop` hit-tests as its dialog, and the frame the subclass\nrenders fills the dialog's box, so the dialog is an event's *target* only\nwhen the pointer was outside the frame — no rect arithmetic, no\ncomposedPath. Attached whether or not lightDismiss is set: the\nhandlers read the property at the release, so it can be toggled on an\nopen dialog.",
+              "default": "new DocumentListenersController(this, () => [ [this._dialog, 'pointerdown', this.#onDialogPointerDown], [this._dialog, 'pointerup', this.#onDialogPointerUp], [this._dialog, 'pointercancel', this.#onDialogPointerCancel], [this._dialog, 'keydown', this.#onDialogKeydown], ])",
+              "description": "The while-open listeners, on the `<dialog>` itself: the light-dismiss\npointer trio and the Return/Enter routing.\n\nLight dismiss: the `::backdrop` hit-tests as its dialog, and the frame the\nsubclass renders fills the dialog's box, so the dialog is an event's\n*target* only when the pointer was outside the frame — no rect arithmetic,\nno composedPath. Attached whether or not lightDismiss is set: the\nhandlers read the property at the release, so it can be toggled on an\nopen dialog.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "defaultButton",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "protected",
+              "description": "The dialog's default button — the one wearing the bold ring\n(`vf-button[variant=\"default\"]`) — or null with none, or none enabled.\nLooked for among the slotted content first, then in the shadow tree, so a\nconsumer's own modal that renders its buttons itself is covered too.\nOverride to name it some other way.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "initialFocusTarget",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "protected",
+              "description": "Where focus lands on open. The classic Dialog Manager put the insertion\npoint in the first editable text item and gave nothing else focus at all;\nthe web needs a focused control for the keyboard to have anywhere to be,\nso with no text field the default button takes it (which is also what\nmakes Return and Space work there without a Tab). In order:\n\n1. a slotted control carrying `autofocus` — the author's say;\n2. the first enabled text-entry control (`vf-text-field`,\n   `vf-number-field`, `vf-text-area`, or a native text input/textarea);\n3. the defaultButton;\n4. null — leave the browser's own choice alone.\n\nLeft to itself, `showModal()` focuses the first focusable thing in flat\ntree order, which for a Cancel/OK row is Cancel, and for a body with a\nlink in it is the link — so Return did the one thing a classic dialog's\nReturn never did. Override to choose differently.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#focusInitial",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Hand focus to initialFocusTarget, right after `showModal()`'s own\nfocusing steps have run (so this is the last word, not a race).",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogKeydown",
+              "privacy": "private",
+              "description": "Return and Enter activate the default button from anywhere in the\ndialog, the way the classic Dialog Manager routed them — including from a\nfocused Cancel button, where Space is the key that presses the focused\ncontrol. Bubble phase, and only an uncancelled press: a control that\ntakes Enter for itself (`vf-select`'s list, `vf-list`, an icon's rename, a\ntext field whose form ran its implicit submission) cancels the keydown\nand is left alone. Two more keep their own Enter: a link, which follows\nit, and a multi-line editor, where Return inserts a newline and only the\nkeypad's Enter key fires the button — the same split a TextEdit item in a\nclassic dialog drew between the two keys.",
               "inheritedFrom": {
                 "name": "VfModalDialog",
                 "module": "src/modal-dialog.ts"
@@ -4352,52 +4445,16 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/vf-icon.ts",
+      "path": "src/components/vf-icon-field.ts",
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-icon>` — a Finder icon: pixel art in a reserved cell with its name on a\nplate below, selectable, movable and renameable in place.\n\nIt is the one composite in the kit whose parts already existed separately —\n`vf-img` draws the art, `vf-list-item` inverts on selection, `vf-window`\ndrags — and the reason to have it anyway is that the *icon* is the unit the\nFinder actually manipulates. A picture and a caption that select together,\nmove together and rename together is a control, not a layout.\n\n### The art arrives by slot\n\nTwo slots, one per resource size — `large` is the 32×32 `ICN#` and `small`\nthe 16×16 `ics#` — each holding a `vf-img` around the consumer's own `<img>`:\n\n```html\n<vf-icon label=\"Macintosh HD\" selectable movable editable>\n  <vf-img slot=\"large\"><img src=\"hd-32.png\" alt=\"\"></vf-img>\n  <vf-img slot=\"small\"><img src=\"hd-16.png\" alt=\"\"></vf-img>\n</vf-icon>\n```\n\nSlots rather than `src` properties, for the reason `vf-img` exists at all:\nthe kit ships no raster files and never builds an `<img>` on a consumer's\nbehalf, so the graphic stays a real element in the light DOM with its own\n`alt`, `srcset`, loading behavior and asset URLs. A `src` string can express\nnone of that, and it could not hold an inline `<svg>` or a `<canvas>` either.\n`vf-list-item`'s `icon` slot makes the same trade.\n\nThe cost is that both files fetch even though one paints — pay it with two\ndata URIs, or slot only the size that view uses.\n\n### The cell is reserved, the art is registered in it\n\n`size` picks which slot paints *and* the cell it paints in: 32×32 or 16×16,\nheld whether or not there is art for it. A folder is 32×20 of ink and a\ndocument 25×32, and a row of them keeps one baseline only because the cell —\nnot the ink — is the unit, which is what an icon resource always was.\n\n### Everything centered lands on a whole pixel, by parity\n\nThe frame centers two things over one axis — the art cell and the name — and\na centered child sits at `(box − child) / 2`. That is a whole number exactly\nwhen the box and the child have the **same parity**. Half a system pixel is\nwhat fringes 1-bit art: the glyph stems smear across two device columns and\ngo gray, while the plate behind them stays sharp, because backgrounds are\npixel-snapped by the compositor and glyphs are not. A crisp plate under a\ngrey name is the signature of exactly this.\n\nSo the component makes the parities agree instead of correcting afterwards.\nThe cell is 32 or 16, and #measurePlate sizes the name plate to a\nwhole **even** number of system px — measured from the text, rounded up. Both\nchildren are then even, and so is every offset, at every display density and\nwhether or not a `width` is declared. Nothing is snapped, nothing leans on\nthe rasterizer, and `verify:icon` asserts both the geometry and that a field\nof names renders without a single gray pixel — with the kit's normal\nantialiasing left on, since a run on whole pixels gives it nothing to smooth.\n\nYour side of it is one rule: **a declared `width` must be even**, since the\ncomponent cannot round a number you chose. Supply art at the cell size too —\nwhich \"one image pixel is one system pixel\" already implies — because art\ndiffering from its cell by an odd number centers the same way.\n\n### Selection inverts, because the art is a 1-bit mask\n\nA System 7 icon is black ink and opaque white on a transparent surround —\nprecisely an image plus its mask — so inverting it flips ink and fill and\nleaves the surround alone, which is the whole of the classic selected\nappearance. `filter: invert(1)` reproduces it exactly for 1-bit art. Color\nart would invert into a photographic negative, which was never what\nSystem 7 showed: declare `color` and selection **darkens** the art\ninstead — Icon Utilities' ttSelected transform, every color blended\nhalfway toward black (`brightness(0.5)`), whites going gray, the\ntransparent surround still untouched. The declaration is the consumer's\nbecause the component cannot tell color art from a mask by looking at a\nslotted image. It covers whatever the cell shows, the derived open ghost\nincluded, so a color icon has one selected treatment open or closed. The\nlabel plate inverts to the `--vf-highlight` pair either way, sharing one\nselection color with `vf-list-item` — the selected name was inverted\nwhatever the art.\n\n### Open is derived, not shipped\n\nWith `open`, the art redraws as the Finder's open ghost: the outline held\nin solid black, the interior re-filled with the kit's loose 25% dither (the\nscrollbar trough's lattice), the transparent surround untouched. There is\nno second raster and no second fetch — the same alpha channel that makes\nselection an inversion makes the ghost derivable, and `src/open-art.ts`\nderives it from the slotted art by canvas compositing alone. No pixels are\never read back, so a cross-origin image that taints its canvas still works:\ntaint forbids reading, not drawing or displaying.\n\nThe ghost keeps the shape selection expects — ink and opaque white on a\ntransparent surround — so a selected open icon inverts exactly as a closed\none does, with no second treatment. The slot stays in the tree while the\nghost paints, hidden (it is where the art loads, and re-loads, from), and\nart the pipeline cannot draw — nothing slotted yet, a failed load, an\ninline `<svg>` — keeps rendering as itself rather than vanishing behind a\nstate it cannot show.\n\n### `movable`, not `draggable`\n\n`draggable` is a global HTML attribute *and* an `HTMLElement` accessor, so\ndeclaring it would both shadow a platform member and hand the element to the\nbrowser's own drag-and-drop machinery. This is the `align` trap from\n`vf-stack` in a second costume — `align`, `hidden`, `dir`, `draggable` and\n`title` all carry behavior a custom element never asked for. The kit already\nspells this parameter `movable` on `vf-window`, so the icon does too, and it\nmoves the same way: `DragController` tracks the gesture and\n`PlacementController` writes the result into `left`/`top` in whole system px,\nthe art's own unit — the same pair markup places an icon with, so a moved\nicon is still where it was dropped after a zoom.\n\nDragging is a pointer gesture with no keyboard equivalent, which is the kind\nof gap the kit closes rather than inherits (SPEC §1): a focused movable icon\nalso moves under the arrow keys, one system px at a time and eight with\nShift. Focus is what `selectable` grants, so the keyboard half of `movable`\nand `editable` presupposes it — see the role section below.\n\nOpening gets the same treatment. The double-click is the pointer gesture,\nand its keyboard route is ⌘O / ⌘↓ — the System 7 Open shortcuts, with Ctrl\nstanding in for ⌘ off the Mac. Return is deliberately not one of them: the\nFinder's Return renamed, never opened, so on an editable icon it starts the\nedit and on a non-editable one it does nothing at all.\n\n### The name and the art are one target, and the second click decides\n\nA double-click opens the icon *wherever it lands* — the name is as much the\nicon as the picture is, and the Finder never made you aim at the 32 pixels of\nart. But the name is also where a single click renames, so the two gestures\nbegin with the same press and only the second one tells them apart.\n\nSo the rename waits for it. A press on the plate of an already-selected icon\narms the field rather than opening it, and the next press inside\nRENAME_DELAY_MS calls it off — leaving the double-click to open, with\nno rename box flashing up behind it. Nothing needs to *undo* an edit that\nbegan: the press that starts one and the press that opens are the same\npress, so the only thing that can be got right is not committing early.\n\nThe window is generous in the one direction that is cheap. Reading a lone\nclick as a pair costs a wait before the box appears; reading a pair as a lone\nclick renames when the user asked to open. The same reasoning covers a press\nthat turns into a drag, a press elsewhere, and any key — each calls the\npending rename off, because none of them is the click it is waiting for.\n\n### An icon alone is a picture; an icon in a field is an option\n\n`role=\"option\"` is only meaningful inside a `listbox` that owns it. Written\nunconditionally it is not merely untidy — the browser *drops* it, and\n`aria-selected` with it, so a `selectable` icon announced as a bare generic\nand its selection state reached assistive tech nowhere at all.\n\nSo the role follows the container. Owned, the icon is an `option` that names\nitself from its plate and publishes `aria-selected`. Unowned, it degrades to\n`role=\"img\"` with a name — the same vocabulary the derived open ghost uses,\nand true of what it is. Deliberately not `button`: that would promise Enter\nand Space activate, and here Return *renames* while the open route is ⌘O / ⌘↓.\n\nDeclaring the owner is one attribute on whatever already holds the field, and\nit is what buys the selection state back:\n\n```html\n<div role=\"listbox\" aria-label=\"Desktop\" aria-multiselectable=\"true\">\n  <vf-icon label=\"Macintosh HD\" selectable movable editable>…</vf-icon>\n  <vf-icon label=\"Trash\" selectable movable editable>…</vf-icon>\n</div>\n```\n\nA `vf-desktop` cannot be that container itself: it also holds windows and a\nmenu bar, and a non-`option` child of a listbox is invalid the same way the\norphaned option was. The plain wrapper above is layout-neutral — placed icons\nanchor to the nearest *positioned* ancestor, which is still the desktop's\nraster. One divergence from the APG listbox is deliberate: its options share\na single roving tab stop, while these stay one stop each, the way a Finder\nicon is reached on its own.\n\n**`selectable` is what makes an icon focusable**, and `movable`/`editable`\npresuppose it. That is the Finder's own model — you cannot move or rename\nwhat you have not selected — and the pointer path already assumed it: the\nrename opens on a press on the plate of an *already-selected* icon. A\n`movable`-only icon is a picture you can drag, not a widget.\n\n### The label is a property, because it is editable\n\nThe caption is `label` rather than slotted content: renaming means the\ncomponent owns the string and hands it back on `vf-change`, and it cannot own\ntext that lives in the consumer's DOM. An empty `label` draws no plate at\nall — that *is* the \"no label\" parameter, in preference to a second attribute\nthat could disagree with it. `editable` then lets a click on the plate of an\nalready-selected icon open the rename box a moment later, as the Finder's\ndoes (see above), with Return committing, Escape reverting, and the plate\nwidening as you type.\n\n### A name is never abbreviated, and never folded\n\nThere is no ellipsis, no clipping and no wrapping: one line, always. System 7\nsolved the long-name problem at the *other* end — HFS capped a filename at 31\ncharacters — so the Finder could afford to always draw the name in full, and\ndid. A name wider than its cell simply overflows it, centered, the way a name\nwider than a 32-pixel icon always did.\n\nStaying on one line is also what keeps the name on the grid: a single run has\na single measured width, so the even-plate rule above is one number rather\nthan one per line, each with its own parity. `width` is therefore the cell —\nthe grid pitch — not a bound on the name.\n\n`maxlength` (31) bounds the rename field rather than the `label` property:\nthe name belongs to the consumer's model, and truncating one handed to us\nwould lose data.\n\nThe box hugs its text while you type it, not only once you are done, which is\nwhat keeps the name from moving when the edit commits: the plate is the same\nwidth either side of it, so the glyphs stay exactly where they were.\n\nA file also has to be called *something*, so a rename committed empty — or\nas nothing but spaces — is refused rather than applied, and the previous name\ncomes back, which is what System 7 did. An empty `label` is still a perfectly\ngood state to *start* in, though: a freshly made icon has no name until it is\ngiven one. Such an icon draws no plate but stays selectable, focusable and\nrenameable — Return opens a field, and an edit with nothing in it yet is the\none time the box stops hugging and reserves a cell's width, since a field you\ncannot see is one you cannot type into.",
-          "name": "VfIcon",
-          "cssProperties": [
-            {
-              "description": "Space between the art cell and the name plate",
-              "name": "--vf-icon-gap"
-            },
-            {
-              "description": "The name plate's line box",
-              "name": "--vf-icon-label-height"
-            }
-          ],
-          "cssParts": [
-            {
-              "description": "The icon and its label plate, stacked.",
-              "name": "frame"
-            },
-            {
-              "description": "The reserved art cell.",
-              "name": "icon"
-            },
-            {
-              "description": "The name block; its lines are centered under the art.",
-              "name": "label"
-            },
-            {
-              "description": "The inked run behind the name, which each wrapped line gets its own of (inverts when selected).",
-              "name": "plate"
-            },
-            {
-              "description": "The rename field, while editing.",
-              "name": "input"
-            }
-          ],
+          "description": "`<vf-icon-field>` — the container a field of `vf-icon`s sits in: a desktop's\nicons, a folder window's contents.\n\nEvery other set in the kit has its container — `vf-list` owns\n`vf-list-item`, `vf-radio-group` owns `vf-radio`, `vf-menu` owns\n`vf-menu-item`, `vf-select` owns `vf-option` — and `vf-icon` was the one\nitem whose container the consumer wrote by hand: a bare\n`<div role=\"listbox\" aria-multiselectable=\"true\">`, because an `option` is\nonly valid inside a `listbox` that owns it, and every kit container is a\npositioning anchor by design, so nothing in the kit was neutral enough to\nstand in. A consumer who forgot the role got icons that silently degraded\nto pictures. This is that container, as kit furniture:\n\n```html\n<vf-desktop width=\"512\" height=\"342\">\n  <vf-icon-field label=\"Desktop\" fill-width fill-height>\n    <vf-icon label=\"Macintosh HD\" width=\"64\" selectable movable editable left=\"16\" top=\"24\">…</vf-icon>\n    <vf-icon label=\"Trash\" width=\"64\" selectable movable editable left=\"16\" top=\"280\">…</vf-icon>\n  </vf-icon-field>\n  <vf-window heading=\"Documents\" width=\"320\" height=\"201\" scrollbars=\"both\" top=\"40\" left=\"120\">\n    <vf-icon-field label=\"Documents\">\n      <vf-icon label=\"Read Me\" width=\"64\" selectable movable editable left=\"16\" top=\"16\">…</vf-icon>\n    </vf-icon-field>\n  </vf-window>\n</vf-desktop>\n```\n\n### Semantics through internals\n\n`role=\"listbox\"` and `aria-multiselectable=\"true\"` always — the Finder was\nalways multi-select, so there is no attribute for it — and `label` as the\naccessible name, the way `vf-scroll-area` takes one. Internals values are\ndefaults (SPEC §2): a consumer's own `role`/`aria-*` on the tag still wins.\nA `selectable` icon inside becomes a real `option` carrying `aria-selected`;\n`vf-icon` matches this tag directly, since a role written through internals\nnever lands as an attribute for `closest()` to find.\n\n### Layout-neutral, exactly what the div was\n\nAn in-flow block with no size, no inset and no position of its own,\npainting nothing — the `vf-stack` posture. A field whose icons are all\nplaced is a zero-height block, so the icons keep anchoring to the desktop's\nraster or the window's plane, stored coordinates mean what they meant, and\na press on the bare dither still reaches the desktop. It takes `top`/`left`\nand `width`/`height` like the other declared-box containers, so a page that\nwants the field to be a box places and sizes it, at which point it becomes\nthe anchor — the placement working, as documented for everything.\n`fill-width`/`fill-height` are the other way to give it a box, read about\nthe host the way `vf-stack` and `vf-container` read them: a filled field\nstays in flow and static, so its icons keep their anchor, and it has a\nsurface to press — which is what the rubber band needs.\n\n### The rubber band\n\nA press on the field's own background — not on an icon — dragged across\nthe field draws the Finder's dotted selection rectangle from the press to\nthe pointer, and the selection follows it live by the Finder's one rule:\n**an icon is selected exactly when it was selected at the press XOR the\nrectangle touches it.** The press fixes that anchor: a plain press has\nalready cleared everything (the way any press outside an icon does), so\nthe rectangle simply selects what it touches and releases what it leaves;\nwith Shift or ⌘ held the selection survives the press and the rectangle\n*toggles* against it — an icon already selected deselects while the\nrectangle covers it and comes back when it leaves, one that was not\nselects. Each change reports `vf-select` as a press would. \"Touches\"\nmeans the icon's art cell or its name plate (VfIcon.touches), not\nthe empty cell beside them, so a rectangle through the gap between two\nicons selects neither. The release keeps the result; Escape or a\n`pointercancel` cancels, the rectangle vanishes and the selection goes\nback to the anchor. A press that never leaves its system pixel draws\nnothing.\n\nThe rectangle is drawn with the drag outline's pen (* paintSelectionRect: the dotted one-pixel outline, `filter: invert(1)`\nunder `mix-blend-mode: difference`) at the field's own level, which is\nwhere the Finder drew its marquee — on the desktop under the windows, in a\nwindow body over that window's content and under any window above it —\npositioned against the viewport from the field's own shadow, since a\nlayout-neutral field has no box of its own to anchor to. It reaches no\nfurther than the field, inside every clip above the field (a window body,\na scroll viewport, the raster's edge), so it never paints outside the\nregion the icons are visible in. Its dots are phased against the field's\nown box; a field at the screen's origin shares the desktop dither's phase.\n\nOnly a field with a box can be pressed: fill it, or place and size it. An\nunplaced, unfilled field of placed icons is zero-height and draws no band.\n`touch-action` is left alone, so on a touch screen a drag on the\nbackground pans a scrolling window as it always did; the band is a mouse\nand pen gesture.\n\n### `size` is the view's\n\n`large` or `small`, written onto every icon in the field when set and\nwhenever it changes, so View → by Small Icon is one attribute instead of a\nloop over every icon. Unset, each icon keeps its own.\n\n### The desktop uses it, and renders none\n\nA desktop's icons sit in a field slotted into `vf-desktop` beside the\nwindows, written by the page; a folder window's icons sit in one slotted\ninto the window body. `vf-desktop` builds no field of its own: its furniture\nis slotted light DOM and the page decides what it is, a desktop with no\nicons should carry no empty listbox, and a field inside the desktop's\nshadow is one `closest()` could not reach.",
+          "name": "VfIconField",
           "slots": [
             {
-              "description": "The 32×32 art, normally a `vf-img` around an `<img>`.",
-              "name": "large"
-            },
-            {
-              "description": "The 16×16 art, shown under `size=\"small\"`.",
-              "name": "small"
+              "description": "The icons.",
+              "name": ""
             }
           ],
           "members": [
@@ -4408,151 +4465,659 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "The icon's name. Empty draws no plate — that is the \"no label\" setting.",
+              "description": "Accessible name for the field — \"Desktop\", the folder's name — applied as\nthe listbox's `aria-label` through internals, so a consumer's own\n`aria-label` on the tag still wins.",
               "attribute": "label"
             },
             {
               "kind": "field",
               "name": "size",
               "type": {
-                "text": "VfIconSize"
+                "text": "VfIconSize | null | undefined"
               },
-              "default": "'large'",
-              "description": "Which member of the icon family paints, and the cell it is registered in:\n`large` (32×32) or `small` (16×16).",
+              "description": "The view's icon size, `large` or `small`, written onto every icon in the\nfield — View → by Small Icon as one attribute. Unset, each icon keeps\nits own `size`.",
               "attribute": "size",
               "reflects": true
             },
             {
               "kind": "field",
-              "name": "selectable",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Clicking selects. Set `selected` yourself to drive selection some other way.\n\nThis is also the flag that makes an icon focusable and gives it a role, so\nthe keyboard halves of movable and editable presuppose it —\nas the Finder did. A container carrying `role=\"listbox\"` turns the role from\n`img` into a real `option`; see the class doc.",
-              "attribute": "selectable",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "selected",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether the icon is selected: the art inverts and the plate goes black.",
-              "attribute": "selected",
-              "reflects": true
+              "name": "scale",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new ScaleController(this)",
+              "description": "Default-on display scaling (true 72dpi size); see src/scale.ts. A lone\nfield with a declared size on a plain page would otherwise resolve that\nsize against the `var(--vf-scale, 1)` fallback while its icons\nself-scaled around it — the vf-stack reasoning."
             },
             {
               "kind": "field",
-              "name": "color",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Declares the slotted art a **color icon**, so selection darkens it — the\nttSelected transform, every color blended halfway toward black — instead\nof inverting it into a photographic negative (see the class doc). Yours\nto declare because the component cannot tell color art from a 1-bit mask\nby looking at a slotted image. The label plate inverts either way.",
-              "attribute": "color",
-              "reflects": true
+              "name": "#internals",
+              "privacy": "private",
+              "readonly": true,
+              "description": "ARIA goes through internals, never `setAttribute` on the host: internals\nvalues are *defaults*, so a consumer's own `role`/`aria-*` on the tag wins\n— the platform's own precedence. See SPEC §2."
             },
             {
               "kind": "field",
-              "name": "open",
+              "name": "#band",
+              "privacy": "private",
               "type": {
-                "text": "boolean"
+                "text": "Band | null"
               },
-              "default": "false",
-              "description": "The icon's window is on screen, so the art paints as the Finder's open\nghost — outline held, interior re-filled with the kit's loose dither —\nderived in the client from the slotted art itself (see the class doc).\nSet it when handling `vf-open`, clear it when the window goes away.\nSelection inverts the ghost exactly as it inverts the art.",
-              "attribute": "open",
-              "reflects": true
+              "default": "null",
+              "description": "The rubber band in flight, or null between gestures."
             },
             {
               "kind": "field",
-              "name": "movable",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Drag to move — `movable`, never `draggable`, which is a platform attribute\nand accessor (see the class doc). Arrow keys move a focused icon too, which\nmeans pairing this with selectable: focus is what that grants.",
-              "attribute": "movable",
-              "reflects": true
+              "name": "#escape",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DocumentListenersController(this, () => [ [document, 'keydown', this.#onKeyDown, true], ])",
+              "description": "Escape mid-band cancels — the in-flight-gesture idiom `vf-icon`'s drag\nuses, on the document because the field never takes focus. Capture\nphase, and the key is stopped there, so an enclosing `vf-dialog` never\nreads it as a dismissal."
             },
             {
               "kind": "field",
-              "name": "editable",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "The name can be renamed in place: click a selected plate, or press Return.\nPair with selectable — both routes start from a selected icon.\n\nThe pointer route opens the field once the double-click window has passed\n(RENAME_DELAY_MS), so double-clicking the *name* opens the icon the\nway double-clicking its art does. Return opens it at once — a keypress has\nno second half to wait for.",
-              "attribute": "editable",
-              "reflects": true
+              "name": "#onSlotChange",
+              "privacy": "private",
+              "description": "Icons arriving after the view was set take the view's size."
             },
             {
-              "kind": "field",
-              "name": "width",
-              "type": {
-                "text": "number | undefined"
+              "kind": "method",
+              "name": "#applySize",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "description": "The cell width in whole system px — the grid pitch, and it must be\n**even**: the component rounds its own plate to keep every centered offset\nwhole, but it cannot round a number you chose (see the class doc).\n\nIt is not a bound on the name. Left off, the box is as wide as the wider of\nthe art cell and the name; set, a longer name overflows it, centered.\nDeclaring one is what keeps a field of icons on a single pitch, and what\nkeeps a text-sized box off a fractional origin (contract rule 3).",
-              "attribute": "width"
+              "description": "Push the view's size onto every icon in the field. Descendants rather\nthan direct children, so an icon inside a wrapper is one of the field's\ntoo; a property write, which Lit keeps for an icon that has not upgraded\nyet. Unset means hands off."
             },
             {
-              "kind": "field",
-              "name": "maxlength",
-              "type": {
-                "text": "number"
+              "kind": "method",
+              "name": "#icons",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "VfIcon[]"
+                }
               },
-              "default": "31",
-              "description": "The most characters the rename field will accept — 31, the HFS filename\nlimit every System 7 name was cut to, which is also why the Finder could\nafford to always draw the whole name. Going past it fires\n`vf-name-too-long` with what was tried, so a host can say so rather than\nlet characters vanish.\n\nIt bounds *typing* only: a `label` set from your own data is displayed as\ngiven and fires nothing, since the name belongs to your model and silently\ntruncating it would lose data.",
-              "attribute": "maxlength"
+              "description": "The icons the band can select: every selectable one in the field."
             },
             {
               "kind": "field",
-              "name": "scale",
+              "name": "#onPointerDown",
               "privacy": "private",
-              "readonly": true,
-              "default": "new ScaleController(this)",
-              "description": "Default-on display scaling (true 72dpi size); see src/scale.ts."
+              "description": "A press on the field's own background. `event.target` is the host only\nwhen nothing slotted was hit — a press on an icon reaches here with the\nicon as its target, and that press is the icon's own gesture. The\nanchor is read after the icons' outside-press listeners have run\n(document capture, ahead of this): what they left selected is what\nShift or ⌘ kept — nothing, after a plain press."
             },
             {
               "kind": "field",
-              "name": "gridSnap",
+              "name": "#onPointerMove",
               "privacy": "private",
-              "readonly": true,
-              "default": "new GridSnapController(this)",
-              "description": "Device-pixel grid snapping; see src/grid-snap.ts."
+              "description": "A step of the band. The first step whose point differs from the press\nstarts it — a stationary press draws nothing and changes nothing beyond\nwhat the press itself did. Each changed rectangle is redrawn and the\nicons under it re-read."
             },
             {
               "kind": "field",
-              "name": "focusRule",
-              "privacy": "private",
-              "readonly": true,
-              "default": "new FocusRuleController(this)",
-              "description": "Whether to wear the dashed focus rule; see src/focus-modality.ts."
+              "name": "#onPointerUp",
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "_editing",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "private",
-              "default": "false",
-              "description": "True while the rename field is open."
+              "name": "#onKeyDown",
+              "privacy": "private"
             },
             {
-              "kind": "field",
-              "name": "_draft",
-              "type": {
-                "text": "string"
-              },
+              "kind": "method",
+              "name": "#end",
               "privacy": "private",
-              "default": "''",
-              "description": "The name as typed. The hidden plate renders it, so the box tracks it."
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "cancelled",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "The release, or a cancel. A band that never started (a click) has\nnothing to undo. A release keeps the selection the band made; a cancel\nputs the anchor back."
             },
             {
-              "kind": "field",
+              "kind": "method",
+              "name": "#point",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ x: number; y: number }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "PointerEvent"
+                  }
+                },
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                },
+                {
+                  "name": "scale",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "reach",
+                  "type": {
+                    "text": "Band['reach']"
+                  }
+                }
+              ],
+              "description": "A pointer position as a point in system px from the field's box, whole\nand held inside the band's reach."
+            },
+            {
+              "kind": "method",
+              "name": "#reach",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Band['reach']"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                },
+                {
+                  "name": "scale",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "How far the band may reach: the field's own box, intersected with every\nancestor that clips — a window body, a scroll viewport, the desktop's\nraster — found by walking the flat tree, slots and shadow hosts\nincluded. In system px from the field's box, whole, rounded inward."
+            },
+            {
+              "kind": "method",
+              "name": "#makeCanvas",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLCanvasElement"
+                }
+              },
+              "description": "The band's canvas: the drag outline's XOR pen, positioned against the\nviewport from the field's own shadow — a layout-neutral field has no\npositioned box of its own for it to anchor to — and never a hit."
+            },
+            {
+              "kind": "method",
+              "name": "#paint",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "band",
+                  "type": {
+                    "text": "Band"
+                  }
+                },
+                {
+                  "name": "scale",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Draw the rectangle where it lands: whole system px from the field's box,\nwhich sits on the device grid, so the band does too. The checker's\nphase follows the rectangle's own corner parity in the field's box."
+            },
+            {
+              "kind": "method",
+              "name": "#selectUnder",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "band",
+                  "type": {
+                    "text": "Band"
+                  }
+                },
+                {
+                  "name": "scale",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The selection under the band — the Finder's rule, re-evaluated for\nevery selectable icon on every changed rectangle: selected exactly when\nit was in the anchor XOR the rectangle touches it (its art cell or its\nplate, the icon's own reading). A plain press left an empty anchor, so\nthe rectangle selects what it touches and releases what it leaves; a\nShift or ⌘ press kept one, so the rectangle toggles against it. Each\nchange goes through the icon's own gesture route so `vf-select` reports\nit."
+            },
+            {
+              "kind": "field",
+              "name": "role",
+              "type": {
+                "text": "string"
+              },
+              "default": "'listbox'"
+            },
+            {
+              "kind": "field",
+              "name": "ariaMultiSelectable",
+              "type": {
+                "text": "string"
+              },
+              "default": "'true'"
+            },
+            {
+              "kind": "field",
+              "name": "width",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Width in whole system px. What the number means is the component's own\naffair — the measure a paragraph wraps to, a caption column, a window's\nbox — but the mechanics are shared: the length lands on the host as a\nlive `calc(var(--vf-scale, 1) * Npx)`, so the box scales with the\ndisplay and sits on the device-pixel grid by construction. Remove it\nand the width returns to layout.",
+              "attribute": "width",
+              "inheritedFrom": {
+                "name": "VfSized",
+                "module": "src/size.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "height",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Height in whole system px; see width. Content that outgrows a\ndeclared height overflows the box rather than growing it — the number\nis the layout, and content that doesn't fit is a number to raise.",
+              "attribute": "height",
+              "inheritedFrom": {
+                "name": "VfSized",
+                "module": "src/size.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "top",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Offset from the top of the positioning parent, in whole system px.\nSetting this (or `left`) absolutely positions the element within its\nparent; the coordinate left unset is 0. Remove both to return the\nelement to normal flow.",
+              "attribute": "top",
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "left",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Offset from the left of the positioning parent, in whole system px.\nSee top.",
+              "attribute": "left",
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fixed",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hold the placement against the visible region of the nearest scrolling\nancestor: the element keeps its stated `top`/`left` while the content\nscrolls under it, and the flag alone places it at (0,0). It comes\nbefore the flow content in its parent. Where nothing scrolls it renders\nexactly as placed.",
+              "attribute": "fixed",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Accessible name for the field — \"Desktop\", the folder's name — applied as\nthe listbox's `aria-label` through internals, so a consumer's own\n`aria-label` on the tag still wins.",
+              "fieldName": "label"
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "VfIconSize | null | undefined"
+              },
+              "description": "The view's icon size, `large` or `small`, written onto every icon in the\nfield — View → by Small Icon as one attribute. Unset, each icon keeps\nits own `size`.",
+              "fieldName": "size"
+            },
+            {
+              "name": "width",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Width in whole system px. What the number means is the component's own\naffair — the measure a paragraph wraps to, a caption column, a window's\nbox — but the mechanics are shared: the length lands on the host as a\nlive `calc(var(--vf-scale, 1) * Npx)`, so the box scales with the\ndisplay and sits on the device-pixel grid by construction. Remove it\nand the width returns to layout.",
+              "fieldName": "width",
+              "inheritedFrom": {
+                "name": "VfSized",
+                "module": "src/size.ts"
+              }
+            },
+            {
+              "name": "height",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Height in whole system px; see width. Content that outgrows a\ndeclared height overflows the box rather than growing it — the number\nis the layout, and content that doesn't fit is a number to raise.",
+              "fieldName": "height",
+              "inheritedFrom": {
+                "name": "VfSized",
+                "module": "src/size.ts"
+              }
+            },
+            {
+              "name": "top",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Offset from the top of the positioning parent, in whole system px.\nSetting this (or `left`) absolutely positions the element within its\nparent; the coordinate left unset is 0. Remove both to return the\nelement to normal flow.",
+              "fieldName": "top",
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            },
+            {
+              "name": "left",
+              "type": {
+                "text": "number | null | undefined"
+              },
+              "description": "Offset from the left of the positioning parent, in whole system px.\nSee top.",
+              "fieldName": "left",
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            },
+            {
+              "name": "fixed",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hold the placement against the visible region of the nearest scrolling\nancestor: the element keeps its stated `top`/`left` while the content\nscrolls under it, and the flag alone places it at (0,0). It comes\nbefore the flow content in its parent. Where nothing scrolls it renders\nexactly as placed.",
+              "fieldName": "fixed",
+              "inheritedFrom": {
+                "name": "VfPositioned",
+                "module": "src/position.ts"
+              }
+            }
+          ],
+          "mixins": [
+            {
+              "name": "VfSized",
+              "module": "/src/size.js"
+            },
+            {
+              "name": "VfPositioned",
+              "module": "/src/position.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vf-icon-field",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "VfIconField",
+          "declaration": {
+            "name": "VfIconField",
+            "module": "src/components/vf-icon-field.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "vf-icon-field",
+          "declaration": {
+            "name": "VfIconField",
+            "module": "src/components/vf-icon-field.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/vf-icon.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`<vf-icon>` — a Finder icon: pixel art in a reserved cell with its name on a\nplate below, selectable, movable and renameable in place.\n\nIt is the one composite in the kit whose parts already existed separately —\n`vf-img` draws the art, `vf-list-item` inverts on selection, `vf-window`\ndrags — and the reason to have it anyway is that the *icon* is the unit the\nFinder actually manipulates. A picture and a caption that select together,\nmove together and rename together is a control, not a layout.\n\n### The art arrives by slot\n\nTwo slots, one per resource size — `large` is the 32×32 `ICN#` and `small`\nthe 16×16 `ics#` — each holding a `vf-img` around the consumer's own `<img>`:\n\n```html\n<vf-icon label=\"Macintosh HD\" selectable movable editable>\n  <vf-img slot=\"large\"><img src=\"hd-32.png\" alt=\"\"></vf-img>\n  <vf-img slot=\"small\"><img src=\"hd-16.png\" alt=\"\"></vf-img>\n</vf-icon>\n```\n\nSlots rather than `src` properties, for the reason `vf-img` exists at all:\nthe kit ships no raster files and never builds an `<img>` on a consumer's\nbehalf, so the graphic stays a real element in the light DOM with its own\n`alt`, `srcset`, loading behavior and asset URLs. A `src` string can express\nnone of that, and it could not hold an inline `<svg>` or a `<canvas>` either.\n`vf-list-item`'s `icon` slot makes the same trade.\n\nThe cost is that both files fetch even though one paints — pay it with two\ndata URIs, or slot only the size that view uses.\n\n### The cell is reserved, the art is registered in it\n\n`size` picks which slot paints *and* the cell it paints in: 32×32 or 16×16,\nheld whether or not there is art for it. A folder is 32×20 of ink and a\ndocument 25×32, and a row of them keeps one baseline only because the cell —\nnot the ink — is the unit, which is what an icon resource always was.\n\n### Everything centered lands on a whole pixel, by parity\n\nThe frame centers two things over one axis — the art cell and the name — and\na centered child sits at `(box − child) / 2`. That is a whole number exactly\nwhen the box and the child have the **same parity**. Half a system pixel is\nwhat fringes 1-bit art: the glyph stems smear across two device columns and\ngo gray, while the plate behind them stays sharp, because backgrounds are\npixel-snapped by the compositor and glyphs are not. A crisp plate under a\ngrey name is the signature of exactly this.\n\nSo the component makes the parities agree instead of correcting afterwards.\nThe cell is 32 or 16, and #measurePlate sizes the name plate to a\nwhole **even** number of system px — measured from the text, rounded up. Both\nchildren are then even, and so is every offset, at every display density and\nwhether or not a `width` is declared. Nothing is snapped, nothing leans on\nthe rasterizer, and `verify:icon` asserts both the geometry and that a field\nof names renders without a single gray pixel — with the kit's normal\nantialiasing left on, since a run on whole pixels gives it nothing to smooth.\n\nYour side of it is one rule: **a declared `width` must be even**, since the\ncomponent cannot round a number you chose. Supply art at the cell size too —\nwhich \"one image pixel is one system pixel\" already implies — because art\ndiffering from its cell by an odd number centers the same way.\n\n### Selection inverts, because the art is a 1-bit mask\n\nA System 7 icon is black ink and opaque white on a transparent surround —\nprecisely an image plus its mask — so inverting it flips ink and fill and\nleaves the surround alone, which is the whole of the classic selected\nappearance. `filter: invert(1)` reproduces it exactly for 1-bit art. Color\nart would invert into a photographic negative, which was never what\nSystem 7 showed: declare `color` and selection **darkens** the art\ninstead — Icon Utilities' ttSelected transform, every color blended\nhalfway toward black (`brightness(0.5)`), whites going gray, the\ntransparent surround still untouched. The declaration is the consumer's\nbecause the component cannot tell color art from a mask by looking at a\nslotted image. It covers whatever the cell shows, the derived open ghost\nincluded, so a color icon has one selected treatment open or closed. The\nlabel plate inverts to the `--vf-highlight` pair either way, sharing one\nselection color with `vf-list-item` — the selected name was inverted\nwhatever the art.\n\n### Open is derived, not shipped\n\nWith `open`, the art redraws as the Finder's open ghost: the outline held\nin solid black, the interior re-filled with the kit's loose 25% dither (the\nscrollbar trough's lattice), the transparent surround untouched. There is\nno second raster and no second fetch — the same alpha channel that makes\nselection an inversion makes the ghost derivable, and `src/open-art.ts`\nderives it from the slotted art by canvas compositing alone. No pixels are\never read back, so a cross-origin image that taints its canvas still works:\ntaint forbids reading, not drawing or displaying.\n\nThe ghost keeps the shape selection expects — ink and opaque white on a\ntransparent surround — so a selected open icon inverts exactly as a closed\none does, with no second treatment. The slot stays in the tree while the\nghost paints, hidden (it is where the art loads, and re-loads, from), and\nart the pipeline cannot draw — nothing slotted yet, a failed load, an\ninline `<svg>` — keeps rendering as itself rather than vanishing behind a\nstate it cannot show.\n\n### `movable`, not `draggable`\n\n`draggable` is a global HTML attribute *and* an `HTMLElement` accessor, so\ndeclaring it would both shadow a platform member and hand the element to the\nbrowser's own drag-and-drop machinery. This is the `align` trap from\n`vf-stack` in a second costume — `align`, `hidden`, `dir`, `draggable` and\n`title` all carry behavior a custom element never asked for. The kit already\nspells this parameter `movable` on `vf-window`, so the icon does too, and it\nmoves the same way: `DragController` tracks the gesture and\n`PlacementController` writes the result into `left`/`top` in whole system px,\nthe art's own unit — the same pair markup places an icon with, so a moved\nicon is still where it was dropped after a zoom.\n\nDragging is a pointer gesture with no keyboard equivalent, which is the kind\nof gap the kit closes rather than inherits (SPEC §1): a focused movable icon\nalso moves under the arrow keys, one system px at a time and eight with\nShift. Focus is what `selectable` grants, so the keyboard half of `movable`\nand `editable` presupposes it — see the role section below.\n\n### The drag is an outline; the icon stays put\n\nThe Finder dragged an icon as a dotted outline — the mask's boundary and\nthe name's rectangle — drawn over everything with the XOR pen, the icon\nitself staying put until the drop. The kit draws it from what it already\nhas: deriveDragOutline finds the ring the way the open ghost does\n(the silhouette from the art's alpha, eroded by one pixel, the ring the\nerosion removes), adds the plate's rectangle, and dotOutline dots\nit against a 2×2 checker — compositing only, so cross-origin art derives\ntoo, and art the pipeline cannot draw falls back to the cell's rectangle.\nThe canvas paints with the cursor's XOR recipe, `filter: invert(1)` under\n`mix-blend-mode: difference`: a dotted black line over a white window\nbody, and over the desktop dither the composition QuickDraw's pattern pen\ngave, because the checker's phase is taken from where the outline lands\non the *screen* — its dots share the dither's own phase wherever it goes.\n\nIt draws on the desktop's drag surface: a layer in the screen's shadow,\nover windows, palettes and the menu bar alike, clipped at the raster's\nedge like everything else, reached through the `vf-drag-surface-request`\nhandshake (bubbles, non-composed — it travels up the slots the icon is\nassigned to, so it works from inside a window body). With no desktop the\ncanvas lives in the icon's own frame instead, translated by the delta,\nclipped by whatever clips the icon; the gesture and its events are the\nsame either way. Its origin is a whole count of system px from the\nsurface's, written as a live `sysLength()`, so a scale change mid-gesture\ncannot smear it.\n\n### The drag reports, the page files\n\nThe kit ships no filing semantics — folders are the page's own catalog —\nso a drag is a stream of events and a cancelable commit, on the icon:\n\n- `vf-drag-start` `{ left, top }` on the first lattice step away from the\n  press (a plain click never starts one, and never fires a drop);\n- `vf-drag` `{ clientX, clientY, left, top, x, y }` on every step that\n  changed the snapped proposal;\n- `vf-drop`, the same shape at the release, **cancelable**: its default\n  action is the move, the proposal written through `left`/`top` and\n  clamped whole in the container measured at the press. `preventDefault()`\n  writes nothing — the page re-parents or places the icon itself, the\n  outline's origin converted with the destination's `placementAt`;\n- `vf-drag-cancel` `{}` on Escape or a `pointercancel`: nothing written.\n\n`left`/`top` in the detail are the *proposal*, unclamped — the origin plus\nthe lattice-snapped delta — and only the default action clamps, so a page\nthat cancels gets the raw gesture. `x`/`y` are the outline's top-left in\nviewport CSS px: the frame's box at the press translated by the delta,\nthe press offset already inside it, so an icon placed at the\ndestination's `placementAt(x, y)` lands exactly where the outline was.\n\n### The selection travels\n\nA drag that begins on a *selected* icon takes every other selected,\nmovable icon of its field with it — the Finder outlined the whole\nselection under a drag on any member. Each follower draws its own outline\n(followDrag), moved by the same lattice delta as the leader's, and\nthe leader's events carry the set as `detail.icons`, itself first. The\ndefault action of the drop clamps the delta once for the whole group —\nthe arrangement is kept, and the group stops when its outermost member\nmeets the container's edge — then writes each member's origin plus that\ndelta. A cancel takes every outline down and writes nothing. A press on\nan unselected icon makes it the selection first (the outside listeners\nclear the others), so it drags alone; a Shift press that deselects the\npressed icon drags it alone too, the rest staying where they are.\n\nFor the selection to travel, a plain press on one of its members must not\ncollapse it: the other icons' outside-press listeners leave a selection\nalone when the press landed on an icon already selected in the same\nfield. A *click* on such an icon — released with no drag — collapses the\nselection to it on the release, so a click still single-selects and the\nsame press could have dragged them all.\n\nEscape is heard by a document listener scoped to the gesture rather than\nby the icon's own key handler, because a `movable`-only icon never takes\nfocus — an addition in the kit's idiom (a pointer-only gesture with no way\nout is the kind of gap SPEC §1 closes), not a claim about the Finder.\n\n`target` is the destination highlight the page sets on the folder under a\ndrag: the selected treatment of the art alone — inverted, or darkened\nunder `color` — with none of `selected`'s semantics: no event, no outside\nlistener, no `aria-selected`, the plate untouched.\n\nOpening gets the same treatment. The double-click is the pointer gesture,\nand its keyboard route is ⌘O / ⌘↓ — the System 7 Open shortcuts, with Ctrl\nstanding in for ⌘ off the Mac. Return is deliberately not one of them: the\nFinder's Return renamed, never opened, so on an editable icon it starts the\nedit and on a non-editable one it does nothing at all.\n\n### The name and the art are one target, and the second click decides\n\nA double-click opens the icon *wherever it lands* — the name is as much the\nicon as the picture is, and the Finder never made you aim at the 32 pixels of\nart. But the name is also where a single click renames, so the two gestures\nbegin with the same press and only the second one tells them apart.\n\nSo the rename waits for it. A press on the plate of an already-selected icon\narms the field rather than opening it, and the next press inside\nRENAME_DELAY_MS calls it off — leaving the double-click to open, with\nno rename box flashing up behind it. Nothing needs to *undo* an edit that\nbegan: the press that starts one and the press that opens are the same\npress, so the only thing that can be got right is not committing early.\n\nThe window is generous in the one direction that is cheap. Reading a lone\nclick as a pair costs a wait before the box appears; reading a pair as a lone\nclick renames when the user asked to open. The same reasoning covers a press\nthat turns into a drag, a press elsewhere, and any key — each calls the\npending rename off, because none of them is the click it is waiting for.\n\n### An icon alone is a picture; an icon in a field is an option\n\n`role=\"option\"` is only meaningful inside a `listbox` that owns it. Written\nunconditionally it is not merely untidy — the browser *drops* it, and\n`aria-selected` with it, so a `selectable` icon announced as a bare generic\nand its selection state reached assistive tech nowhere at all.\n\nSo the role follows the container. Owned, the icon is an `option` that names\nitself from its plate and publishes `aria-selected`. Unowned, it degrades to\n`role=\"img\"` with a name — the same vocabulary the derived open ghost uses,\nand true of what it is. Deliberately not `button`: that would promise Enter\nand Space activate, and here Return *renames* while the open route is ⌘O / ⌘↓.\n\nThe owner is `vf-icon-field`, the container a field of icons sits in, and\nit is what buys the selection state back:\n\n```html\n<vf-icon-field label=\"Desktop\">\n  <vf-icon label=\"Macintosh HD\" selectable movable editable>…</vf-icon>\n  <vf-icon label=\"Trash\" selectable movable editable>…</vf-icon>\n</vf-icon-field>\n```\n\nA `vf-desktop` cannot be that container itself: it also holds windows and a\nmenu bar, and a non-`option` child of a listbox is invalid the same way the\norphaned option was. The field is layout-neutral — placed icons anchor to\nthe nearest *positioned* ancestor, which is still the desktop's raster. An\nelement of your own carrying `role=\"listbox\"` still owns an icon the same\nway. One divergence from the APG listbox is deliberate: its options share\na single roving tab stop, while these stay one stop each, the way a Finder\nicon is reached on its own.\n\n**`selectable` is what makes an icon focusable**, and `movable`/`editable`\npresuppose it. That is the Finder's own model — you cannot move or rename\nwhat you have not selected — and the pointer path already assumed it: the\nrename opens on a press on the plate of an *already-selected* icon. A\n`movable`-only icon is a picture you can drag, not a widget.\n\n### The label is a property, because it is editable\n\nThe caption is `label` rather than slotted content: renaming means the\ncomponent owns the string and hands it back on `vf-change`, and it cannot own\ntext that lives in the consumer's DOM. An empty `label` draws no plate at\nall — that *is* the \"no label\" parameter, in preference to a second attribute\nthat could disagree with it. `editable` then lets a click on the plate of an\nalready-selected icon open the rename box a moment later, as the Finder's\ndoes (see above), with Return committing, Escape reverting, and the plate\nwidening as you type.\n\n### A name is never abbreviated, and never folded\n\nThere is no ellipsis, no clipping and no wrapping: one line, always. System 7\nsolved the long-name problem at the *other* end — HFS capped a filename at 31\ncharacters — so the Finder could afford to always draw the name in full, and\ndid. A name wider than its cell simply overflows it, centered, the way a name\nwider than a 32-pixel icon always did.\n\nStaying on one line is also what keeps the name on the grid: a single run has\na single measured width, so the even-plate rule above is one number rather\nthan one per line, each with its own parity. `width` is therefore the cell —\nthe grid pitch — not a bound on the name.\n\n`maxlength` (31) bounds the rename field rather than the `label` property:\nthe name belongs to the consumer's model, and truncating one handed to us\nwould lose data.\n\nThe box hugs its text while you type it, not only once you are done, which is\nwhat keeps the name from moving when the edit commits: the plate is the same\nwidth either side of it, so the glyphs stay exactly where they were.\n\nA file also has to be called *something*, so a rename committed empty — or\nas nothing but spaces — is refused rather than applied, and the previous name\ncomes back, which is what System 7 did. An empty `label` is still a perfectly\ngood state to *start* in, though: a freshly made icon has no name until it is\ngiven one. Such an icon draws no plate but stays selectable, focusable and\nrenameable — Return opens a field, and an edit with nothing in it yet is the\none time the box stops hugging and reserves a cell's width, since a field you\ncannot see is one you cannot type into.",
+          "name": "VfIcon",
+          "cssProperties": [
+            {
+              "description": "Space between the art cell and the name plate",
+              "name": "--vf-icon-gap"
+            },
+            {
+              "description": "The name plate's line box",
+              "name": "--vf-icon-label-height"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The icon and its label plate, stacked.",
+              "name": "frame"
+            },
+            {
+              "description": "The reserved art cell.",
+              "name": "icon"
+            },
+            {
+              "description": "The name block; its lines are centered under the art.",
+              "name": "label"
+            },
+            {
+              "description": "The inked run behind the name, which each wrapped line gets its own of (inverts when selected).",
+              "name": "plate"
+            },
+            {
+              "description": "The rename field, while editing.",
+              "name": "input"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The 32×32 art, normally a `vf-img` around an `<img>`.",
+              "name": "large"
+            },
+            {
+              "description": "The 16×16 art, shown under `size=\"small\"`.",
+              "name": "small"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The icon's name. Empty draws no plate — that is the \"no label\" setting.",
+              "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "size",
+              "type": {
+                "text": "VfIconSize"
+              },
+              "default": "'large'",
+              "description": "Which member of the icon family paints, and the cell it is registered in:\n`large` (32×32) or `small` (16×16).",
+              "attribute": "size",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "selectable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Clicking selects. Set `selected` yourself to drive selection some other way.\n\nThis is also the flag that makes an icon focusable and gives it a role, so\nthe keyboard halves of movable and editable presuppose it —\nas the Finder did. A container carrying `role=\"listbox\"` turns the role from\n`img` into a real `option`; see the class doc.",
+              "attribute": "selectable",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the icon is selected: the art inverts and the plate goes black.",
+              "attribute": "selected",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "The destination highlight: this icon is the folder under a drag, and its\nart paints the selected treatment — inverted, or darkened under\ncolor — with none of `selected`'s semantics: no `vf-select`, no\noutside-press listener, no `aria-selected`, the plate untouched. The page\nsets it on the folder a `vf-drag` reports the pointer over and clears it\nwhen the pointer leaves or the drop lands.",
+              "attribute": "target",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "color",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Declares the slotted art a **color icon**, so selection darkens it — the\nttSelected transform, every color blended halfway toward black — instead\nof inverting it into a photographic negative (see the class doc). Yours\nto declare because the component cannot tell color art from a 1-bit mask\nby looking at a slotted image. The label plate inverts either way.",
+              "attribute": "color",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "The icon's window is on screen, so the art paints as the Finder's open\nghost — outline held, interior re-filled with the kit's loose dither —\nderived in the client from the slotted art itself (see the class doc).\nSet it when handling `vf-open`, clear it when the window goes away.\nSelection inverts the ghost exactly as it inverts the art.",
+              "attribute": "open",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "movable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Drag to move — `movable`, never `draggable`, which is a platform attribute\nand accessor (see the class doc). Arrow keys move a focused icon too, which\nmeans pairing this with selectable: focus is what that grants.",
+              "attribute": "movable",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "editable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "The name can be renamed in place: click a selected plate, or press Return.\nPair with selectable — both routes start from a selected icon.\n\nThe pointer route opens the field once the double-click window has passed\n(RENAME_DELAY_MS), so double-clicking the *name* opens the icon the\nway double-clicking its art does. Return opens it at once — a keypress has\nno second half to wait for.",
+              "attribute": "editable",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "width",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "The cell width in whole system px — the grid pitch, and it must be\n**even**: the component rounds its own plate to keep every centered offset\nwhole, but it cannot round a number you chose (see the class doc).\n\nIt is not a bound on the name. Left off, the box is as wide as the wider of\nthe art cell and the name; set, a longer name overflows it, centered.\nDeclaring one is what keeps a field of icons on a single pitch, and what\nkeeps a text-sized box off a fractional origin (contract rule 3).",
+              "attribute": "width"
+            },
+            {
+              "kind": "field",
+              "name": "maxlength",
+              "type": {
+                "text": "number"
+              },
+              "default": "31",
+              "description": "The most characters the rename field will accept — 31, the HFS filename\nlimit every System 7 name was cut to, which is also why the Finder could\nafford to always draw the whole name. Going past it fires\n`vf-name-too-long` with what was tried, so a host can say so rather than\nlet characters vanish.\n\nIt bounds *typing* only: a `label` set from your own data is displayed as\ngiven and fires nothing, since the name belongs to your model and silently\ntruncating it would lose data.",
+              "attribute": "maxlength"
+            },
+            {
+              "kind": "field",
+              "name": "scale",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new ScaleController(this)",
+              "description": "Default-on display scaling (true 72dpi size); see src/scale.ts."
+            },
+            {
+              "kind": "field",
+              "name": "gridSnap",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new GridSnapController(this)",
+              "description": "Device-pixel grid snapping; see src/grid-snap.ts."
+            },
+            {
+              "kind": "field",
+              "name": "focusRule",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new FocusRuleController(this)",
+              "description": "Whether to wear the dashed focus rule; see src/focus-modality.ts."
+            },
+            {
+              "kind": "field",
+              "name": "_editing",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "True while the rename field is open."
+            },
+            {
+              "kind": "field",
+              "name": "_draft",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The name as typed. The hidden plate renders it, so the box tracks it."
+            },
+            {
+              "kind": "field",
               "name": "#plateWidth",
               "privacy": "private",
               "type": {
@@ -4595,9 +5160,29 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "Whether a container is claiming this icon as one item of a set — the\n`vf-menu` `#inBar` idiom. `option` is invalid without a `listbox` that owns\nit: unowned, the browser drops the role and `aria-selected` with it, which\nis how a selectable icon reached assistive tech as a bare `generic` in\nevery configuration the kit shipped.\n\nMatched on the attribute because that is what the recipe writes\n(`<div role=\"listbox\">` — see the class doc). A `vf-list` is deliberately\nnot a match: it holds `vf-list-item` rows, and its own `listbox` role now\nlives in internals rather than on the tag anyway.",
+              "description": "Whether a container is claiming this icon as one item of a set — the\n`vf-menu` `#inBar` idiom. `option` is invalid without a `listbox` that owns\nit: unowned, the browser drops the role and `aria-selected` with it, which\nis how a selectable icon reached assistive tech as a bare `generic` in\nevery configuration the kit shipped.\n\nMatched on the `vf-icon-field` tag — its `listbox` role lives in\ninternals, which never lands as an attribute for `closest()` to find —\nand on the attribute a consumer's own element writes. A `vf-list` is\ndeliberately not a match: it holds `vf-list-item` rows, and its own\n`listbox` role lives in internals rather than on the tag anyway.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "#field",
+              "privacy": "private",
+              "type": {
+                "text": "Element | null"
+              },
+              "description": "The field this icon is one item of — its selection's boundary — or null.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "#collapseOnRelease",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "A plain press landed on this icon while it was already selected in a\nfield, and no drag has begun: the selection was kept for the drag's\nsake, and the release with no drag collapses it to this icon (see\n#onOutsidePointerDown)."
+            },
             {
               "kind": "field",
               "name": "#ghostKey",
@@ -4653,29 +5238,288 @@
               "description": "Where a moved icon is allowed to end up, in system px. Unlike `vf-window`,\nwhich only keeps a grabbable strip on screen, an icon is small enough to\nhold whole — losing half of one to an edge reads as a bug rather than as a\nwindow pushed aside."
             },
             {
-              "kind": "field",
-              "name": "#placement",
+              "kind": "field",
+              "name": "#placement",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new PlacementController(this, (x, y, bounds) => this.#keepWhole(x, y, bounds) )",
+              "description": "Drag and nudge placement: the origin lands in `top`/`left` in system px,\nso a moved icon is placed the way an authored one is and holds its spot\nthrough a zoom (see src/position.ts)."
+            },
+            {
+              "kind": "field",
+              "name": "#gesture",
+              "privacy": "private",
+              "type": {
+                "text": "DragGesture | null"
+              },
+              "default": "null",
+              "description": "The in-flight drag, or null between gestures."
+            },
+            {
+              "kind": "field",
+              "name": "#drag",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DragController(this, { onDragStart: (event: PointerEvent): { x: number; y: number } | null => { if (!this.movable || event.button !== 0 || this._editing) return null this.#warnIfUnplaced() const origin = this.#placement.seed() this.#gesture = { origin, frame: this.#frameRect(), pointer: { clientX: event.clientX, clientY: event.clientY }, proposal: null, outline: null, followers: [], size: this.#sysSize(), } return origin }, onDrag: (x: number, y: number, event: PointerEvent): void => { this.#onDragStep(x, y, event) }, onDragEnd: (event: PointerEvent | undefined, cancelled: boolean): void => { this.#onDragEnd(event, cancelled) }, })",
+              "description": "Drag-to-move, on the same delegate shape as `vf-window`: the placement\ncontroller seeds the origin — from the in-flow offset the first time —\nand the drag controller hands back each step snapped onto the lattice.\nWhat the icon does with a step is #onDragStep; the release is\n#onDragEnd, where the drop is reported and, uncancelled, written."
+            },
+            {
+              "kind": "field",
+              "name": "#escape",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DocumentListenersController(this, () => [ [document, 'keydown', this.#onDragKeyDown, true], ])",
+              "description": "Escape mid-drag cancels. A document listener scoped to the gesture (the\nin-flight-gesture idiom) rather than the icon's own key handler, because\na `movable`-only icon never takes focus. Capture phase, and the key is\nstopped there, so an enclosing `vf-dialog` never reads it as a dismissal\n— the rule the rename box's Escape follows."
+            },
+            {
+              "kind": "field",
+              "name": "#onDragKeyDown",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#frameRect",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "DOMRect"
+                }
+              },
+              "description": "The frame's viewport box — what the outline is a translation of."
+            },
+            {
+              "kind": "method",
+              "name": "#sysSize",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ width: number; height: number }"
+                }
+              },
+              "description": "The icon's own box in system px, for the clamp."
+            },
+            {
+              "kind": "method",
+              "name": "followDrag",
+              "return": {
+                "type": {
+                  "text": "VfIconDragFollower | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "surface",
+                  "type": {
+                    "text": "HTMLElement | null"
+                  }
+                }
+              ],
+              "description": "Join another icon's drag as a follower (see the class doc): seed the\norigin the drop will add the delta to, draw this icon's own outline on\n`surface` (the desktop's, as the leader's handshake found it) or in its\nown frame, and hand back the handle the leader moves, drops and ends.\nNull when this icon cannot move. Internal to the kit's group drag."
+            },
+            {
+              "kind": "method",
+              "name": "#gatherFollowers",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "VfIconDragFollower[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "surface",
+                  "type": {
+                    "text": "HTMLElement | null"
+                  }
+                }
+              ],
+              "description": "The icons a drag beginning here carries: this one, then — when it is\nitself selected — every other selected, movable icon of its field, in\ndocument order, each joined as a follower. An icon outside any field,\nor not selected, drags alone."
+            },
+            {
+              "kind": "method",
+              "name": "#dragIcons",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "VfIcon[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "gesture",
+                  "type": {
+                    "text": "DragGesture"
+                  }
+                }
+              ],
+              "description": "The set a drag's events report: the leader first."
+            },
+            {
+              "kind": "method",
+              "name": "#onDragStep",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "PointerEvent"
+                  }
+                }
+              ],
+              "description": "A lattice step of the drag. The first step whose snapped origin differs\nfrom the seed is the start — a stationary press reports jitter, and every\none of those steps snaps back onto the same system px, so a plain click\nnever starts a drag and never fires a drop. Moving an icon is not\nrenaming it, so the start calls off the rename the press armed."
+            },
+            {
+              "kind": "method",
+              "name": "#onDragEnd",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "PointerEvent | undefined"
+                  }
+                },
+                {
+                  "name": "cancelled",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "The release, or a cancel. A gesture that never started (a click) reports\nnothing. A cancel — Escape, `pointercancel` — drops every outline and\nsays so; nothing was written. A release reports the drop, and the\ndefault action of an uncancelled `vf-drop` is the move itself, the whole\ngroup by one delta. Dispatched with the outlines gone, the drag state\ncleared and the pointer capture released, so a handler may re-parent\nthe icons freely."
+            },
+            {
+              "kind": "method",
+              "name": "#dropGroup",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "gesture",
+                  "type": {
+                    "text": "DragGesture"
+                  }
+                },
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "VfIconDragDetail"
+                  }
+                }
+              ],
+              "description": "The drop's default action. Alone, the proposal clamped whole by\n#keepWhole. As a group, one delta for all: clamped so that the\nmember nearest each edge stays whole — the group stops when its\noutermost icon meets the container, and the arrangement is kept — then\neach member's origin plus that delta. A group no edge can hold (a member\nwider than the container) is held off the near edge only, the\nsingle-icon rule."
+            },
+            {
+              "kind": "method",
+              "name": "#requestSurface",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement | null"
+                }
+              },
+              "description": "The handshake: a desktop on the light-DOM path hands over its drag\nsurface; null with no desktop, and the outline draws in the frame."
+            },
+            {
+              "kind": "method",
+              "name": "#buildOutline",
               "privacy": "private",
-              "readonly": true,
-              "default": "new PlacementController(this, (x, y, bounds) => this.#keepWhole(x, y, bounds) )",
-              "description": "Drag and nudge placement: the origin lands in `top`/`left` in system px,\nso a moved icon is placed the way an authored one is and holds its spot\nthrough a zoom (see src/position.ts)."
+              "return": {
+                "type": {
+                  "text": "DragOutline | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                },
+                {
+                  "name": "surface",
+                  "type": {
+                    "text": "HTMLElement | null"
+                  }
+                }
+              ],
+              "description": "Build this icon's outline for a drag, and put it where it draws: the\ndesktop's drag surface when the leader's handshake found one, else the\nicon's own frame. The geometry is measured off the rendered parts —\nthe frame (`at`, its box at the press), the art as it paints (the ghost\nwhile `open`), the cell and the plate — in system px relative to the\nframe, so the ring lands on the pixels the frame paints. Null when\nthere is nothing to draw with."
             },
             {
-              "kind": "field",
-              "name": "#dragOrigin",
+              "kind": "method",
+              "name": "#placeOutlineAt",
               "privacy": "private",
-              "type": {
-                "text": "object"
+              "return": {
+                "type": {
+                  "text": "void"
+                }
               },
-              "default": "{ x: 0, y: 0 }",
-              "description": "Where the in-flight drag started, so a move can be told from jitter."
+              "parameters": [
+                {
+                  "name": "outline",
+                  "type": {
+                    "text": "DragOutline"
+                  }
+                },
+                {
+                  "name": "dx",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "dy",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Move an outline by the drag's delta: the frame's offset plus the delta,\na whole count of system px from the surface's origin, re-dotted at the\nparity that lands on the screen — `x + y` even where the desktop dither\nis inked, so the two share one phase wherever the outline goes."
             },
             {
-              "kind": "field",
-              "name": "#drag",
+              "kind": "method",
+              "name": "#dragDetail",
               "privacy": "private",
-              "readonly": true,
-              "default": "new DragController(this, { onDragStart: (event: PointerEvent): { x: number; y: number } | null => { if (!this.movable || event.button !== 0 || this._editing) return null this.#warnIfUnplaced() return (this.#dragOrigin = this.#placement.seed()) }, onDrag: (x: number, y: number): void => { // Moving an icon is not renaming it, so a press that travels calls off // the rename it armed. Measured against the seeded origin rather than // taken from the move itself: a stationary press still reports jitter, // and every one of those steps snaps back onto the same system px. if (x !== this.#dragOrigin.x || y !== this.#dragOrigin.y) this.#disarmRename() this.#placement.moveTo(x, y) }, })"
+              "return": {
+                "type": {
+                  "text": "VfIconDragDetail"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "gesture",
+                  "type": {
+                    "text": "DragGesture"
+                  }
+                }
+              ],
+              "description": "The detail of `vf-drag` and `vf-drop`: the pointer, the proposal in the\ncontainer — unclamped — and the outline's top-left in the viewport: the\nframe's box at the press translated by the proposal's delta."
             },
             {
               "kind": "field",
@@ -4862,6 +5706,42 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "setSelected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "next",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Select or deselect as a press would: the state changes and `vf-select`\nreports it. A `selected` write from code is silent, the way a value set\nfires no `vf-change`; this is the route for a gesture a container runs\non the icon's behalf — `vf-icon-field`'s rubber band. A no-op when the\nstate already matches."
+            },
+            {
+              "kind": "method",
+              "name": "touches",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "{ left: number; top: number; right: number; bottom: number }"
+                  }
+                }
+              ],
+              "description": "Whether a viewport box (CSS px) touches the icon the way the Finder's\nselection rectangle asked: its art cell or its name plate. The empty\ncell around narrower art and the frame's margin beside the plate count\nfor nothing — a rectangle dragged through the gap between two icons\nselects neither. `vf-icon-field`'s rubber band reads it."
+            },
             {
               "kind": "field",
               "name": "#onPointerDown",
@@ -4873,6 +5753,12 @@
               "privacy": "private",
               "description": "The whole icon opens, name included: the handler is bound to the frame, and\nthe press path is what keeps the plate from having spent the gesture on a\nrename before the second click gets here.\n\nStill guarded on the field: a double-click inside an open rename box is a\nword being selected, not an icon being opened."
             },
+            {
+              "kind": "field",
+              "name": "#onPointerUp",
+              "privacy": "private",
+              "description": "The release of a press on this icon. The drag controller hears it first\n(a started drag ends there); then a press that was kept from collapsing\nthe selection — a plain press on an already-selected member of a field —\ncollapses it now, if no drag ever began: a click on one of several\nselected icons selects that one alone, on the release rather than the\npress, so the same press could have dragged them all. A cancel collapses\nnothing."
+            },
             {
               "kind": "field",
               "name": "#onOutsidePointerDown",
@@ -4979,6 +5865,22 @@
             {
               "description": "A rename was committed with no name in it, so the edit was dropped and the old name put back. `detail: { attempted, kept, reason: 'empty' }`. A `vf-change` is *not* fired alongside it — nothing changed.",
               "name": "vf-name-rejected"
+            },
+            {
+              "description": "A drag began: the first lattice step away from the press. `detail: { left, top, icons }` — the origin, whole system px in the icon's container, and every icon the drag carries (this one first).",
+              "name": "vf-drag-start"
+            },
+            {
+              "description": "A step that changed the proposal. `detail: { clientX, clientY, left, top, x, y, icons }` — the pointer in viewport CSS px, the proposed origin in the container (whole system px on the lattice), the outline's top-left in viewport CSS px, and the icons travelling.",
+              "name": "vf-drag"
+            },
+            {
+              "description": "The release; cancelable. The same detail as `vf-drag`. Its default action writes the proposal through `left`/`top` — every icon in `icons` by the same delta, clamped whole in the container as a group; `preventDefault()` writes nothing.",
+              "name": "vf-drop"
+            },
+            {
+              "description": "The drag was abandoned — Escape, or a `pointercancel` — and nothing was written. `detail: {}`.",
+              "name": "vf-drag-cancel"
             }
           ],
           "attributes": [
@@ -5018,6 +5920,15 @@
               "description": "Whether the icon is selected: the art inverts and the plate goes black.",
               "fieldName": "selected"
             },
+            {
+              "name": "target",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "The destination highlight: this icon is the folder under a drag, and its\nart paints the selected treatment — inverted, or darkened under\ncolor — with none of `selected`'s semantics: no `vf-select`, no\noutside-press listener, no `aria-selected`, the plate untouched. The page\nsets it on the folder a `vf-drag` reports the pointer over and clears it\nwhen the pointer leaves or the drop lands.",
+              "fieldName": "target"
+            },
             {
               "name": "color",
               "type": {
@@ -8470,10 +9381,10 @@
               "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
-              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.",
+              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.\n\nReturns whether a form owner took the press — true even when a disabled\ndefault button meant no submission, since HTML gave the press to the form\neither way. The callers cancel the keydown on true, so a modal shell\n(`VfModalDialog`) sees the press as spoken for and does not also route it\nto the dialog's default button; with no form the press goes on to the\ndialog untouched.",
               "inheritedFrom": {
                 "name": "VfTextControlBase",
                 "module": "src/text-control.ts"
@@ -11344,7 +12255,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-scroll-area>` — a container whose scrollbars look like System 7.\n\nWhite box with a 1px black frame, an inner scrolling viewport, and scroll\nrails the kit draws itself as shadow DOM (the shared `vfScrollRail` recipe):\nboxed arrow buttons at each end, a loose 1-bit dot-dither trough, and the\nclassic fixed 16px thumb. The native scrollbar is hidden, never the native\nscrolling — wheel, trackpad momentum, keyboard, touch and assistive-tech\nscrolling stay the platform's, and ScrollRailController keeps the\nrail in sync while driving the classic interactions (thumb drag, trough\npaging, arrow stepping with auto-repeat). Every engine renders the same\nrail — there is no Firefox fallback skin anymore.\n\nEach reserved scroll rail is a permanent placeholder: arrow buttons on an\nempty white channel sit in the gutter even when the content fits, the\ndither and thumb filling in only once that axis overflows (System 7 drew\nan active window's no-overflow bar as arrows on a bare channel; driven\nby ScrollStateController). Which rails are reserved is set by\naxis; when both are reserved the bottom-right corner joins them,\nand corner reserves that cell on a single-axis rail too — the\nrail stops 15px short of the frame, for a grow box to land in.\n\nSize the host (width/height) from the outside; the viewport fills it.\nContent runs to the frame and the rails — the area adds no inset of its\nown; an inset is the content's (a `vf-stack pad`).\n\nThe scrolled plane sizes to its content — never narrower than the\nviewport, as wide as content that cannot wrap — so the rails follow a row\nthat grows sideways the way they follow copy that grows down, and a\n`slotchange` re-measures. measure covers a scroll range that\nchanges with no box changing (a placed child moved through `top`/`left`).",
+          "description": "`<vf-scroll-area>` — a container whose scrollbars look like System 7.\n\nWhite box with a 1px black frame, an inner scrolling viewport, and scroll\nrails the kit draws itself as shadow DOM (the shared `vfScrollRail` recipe):\nboxed arrow buttons at each end, a loose 1-bit dot-dither trough, and the\nclassic fixed 16px thumb. The native scrollbar is hidden, never the native\nscrolling — wheel, trackpad momentum, keyboard, touch and assistive-tech\nscrolling stay the platform's, and ScrollRailController keeps the\nrail in sync while driving the classic interactions (thumb drag, trough\npaging, arrow stepping with auto-repeat). Every engine renders the same\nrail — there is no Firefox fallback skin anymore.\n\nEach reserved scroll rail is a permanent placeholder: arrow buttons on an\nempty white channel sit in the gutter even when the content fits, the\ndither and thumb filling in only once that axis overflows (System 7 drew\nan active window's no-overflow bar as arrows on a bare channel; driven\nby ScrollStateController). Which rails are reserved is set by\naxis; when both are reserved the bottom-right corner joins them,\nand corner reserves that cell on a single-axis rail too — the\nrail stops 15px short of the frame, for a grow box to land in.\n\nSize the host (width/height) from the outside; the viewport fills it.\nContent runs to the frame and the rails — the area adds no inset of its\nown; an inset is the content's (a `vf-stack pad`).\n\nThe scrolled plane sizes to its content — never narrower than the\nviewport, as wide as content that cannot wrap — so the rails follow a row\nthat grows sideways the way they follow copy that grows down, and a\n`slotchange` re-measures. A placed child moved through `top`/`left` is\nheard too: every such write is announced as `vf-placement-change`\n(src/position.ts), and the area re-measures on it — a drop, an arrow\nnudge, a page's own `icon.left = …`, with no code on the page. * measure covers a scroll range that changes with no box and no placement\nchanging (a transform).\n\nplacementAt converts a viewport point into the plane's own\nplacement coordinates, for a drop that lands in this area from elsewhere.",
           "name": "VfScrollArea",
           "cssProperties": [
             {
@@ -11458,6 +12369,35 @@
               "default": "false",
               "description": "Whether the content actually overflows the viewport (either axis)."
             },
+            {
+              "kind": "field",
+              "name": "#onPlacementChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "placementAt",
+              "return": {
+                "type": {
+                  "text": "{ left: number; top: number }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "clientX",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "clientY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "A viewport point (CSS px) as a placement on the scrolled plane —\n`{ left, top }` in whole system px on the placement lattice, the pair a\nchild dropped here is written with. The plane travels with the scroll,\nso its box already carries the scroll offset and the border-floor\npadding; nothing is left for the caller to add."
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -11485,7 +12425,7 @@
                   "text": "void"
                 }
               },
-              "description": "Re-measure overflow and re-sync the rails. The area tracks its content's\nbox and its slot by itself; call this for a scroll range that changes\nwith no box changing anywhere — a placed child moved through\n`top`/`left`, a transform — the way the kit's own fields re-measure on\ninput."
+              "description": "Re-measure overflow and re-sync the rails. The area tracks its content's\nbox, its slot and every placement write by itself; call this for a\nscroll range that changes with none of those — a transform — the way the\nkit's own fields re-measure on input."
             },
             {
               "kind": "method",
@@ -16004,10 +16944,10 @@
               "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
-              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.",
+              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.\n\nReturns whether a form owner took the press — true even when a disabled\ndefault button meant no submission, since HTML gave the press to the form\neither way. The callers cancel the keydown on true, so a modal shell\n(`VfModalDialog`) sees the press as spoken for and does not also route it\nto the dialog's default button; with no form the press goes on to the\ndialog untouched.",
               "inheritedFrom": {
                 "name": "VfTextControlBase",
                 "module": "src/text-control.ts"
@@ -16871,7 +17811,7 @@
                   }
                 }
               ],
-              "description": "Enter in a single-line field triggers the associated form's implicit\nsubmission. The native `<input>` is shadow-encapsulated, so its form owner\nis null and the browser won't do this itself."
+              "description": "Enter in a single-line field triggers the associated form's implicit\nsubmission. The native `<input>` is shadow-encapsulated, so its form owner\nis null and the browser won't do this itself. A press the form took is\ncancelled, so an enclosing modal does not route it again."
             },
             {
               "kind": "field",
@@ -17130,10 +18070,10 @@
               "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
-              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.",
+              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.\n\nReturns whether a form owner took the press — true even when a disabled\ndefault button meant no submission, since HTML gave the press to the form\neither way. The callers cancel the keydown on true, so a modal shell\n(`VfModalDialog`) sees the press as spoken for and does not also route it\nto the dialog's default button; with no form the press goes on to the\ndialog untouched.",
               "inheritedFrom": {
                 "name": "VfTextControlBase",
                 "module": "src/text-control.ts"
@@ -18185,6 +19125,26 @@
               "default": "false",
               "description": "Whether the `status` slot has assigned content (drives the strip)."
             },
+            {
+              "kind": "field",
+              "name": "body",
+              "type": {
+                "text": "HTMLDivElement | null"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "The content region — the placed-child anchor; exists from the first render."
+            },
+            {
+              "kind": "field",
+              "name": "scrollArea",
+              "type": {
+                "text": "VfScrollArea | null"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "The built-in edge scroll area, while `scrollbars` is set."
+            },
             {
               "kind": "field",
               "name": "scale",
@@ -18269,6 +19229,40 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "method",
+              "name": "placementAt",
+              "return": {
+                "type": {
+                  "text": "{ left: number; top: number }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "clientX",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "clientY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "A viewport point (CSS px) as a placement in the window's content region\n— `{ left, top }` in whole system px on the placement lattice, the pair a\nchild dropped into this window is written with: the body's corner, or\nunder `scrollbars` the scrolled plane, scroll offset included. The anchor\nsits in the shadow tree, which is why the conversion is a method here\nrather than the page's own `toSysExact` against a rect."
+            },
+            {
+              "kind": "method",
+              "name": "measure",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Re-measure the built-in scroll area's overflow and re-sync its rails —\na no-op without `scrollbars`. The area re-measures by itself on its\ncontent's box, its slot and every placement write; this is the escape\nhatch for a scroll range that changes with none of those, the way\n`vf-scroll-area.measure()` is."
+            },
             {
               "kind": "field",
               "name": "#warnedNoSize",
@@ -19835,10 +20829,10 @@
               "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
-              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML."
+              "description": "Emulates the form's implicit submission for a plain Enter press. HTML\ndefines it as *activating the form's default button* — the first submit\nbutton in tree order — so the submission carries that button's submitter\nidentity and name/value. A bare `requestSubmit()` carries neither\n(`event.submitter === null`), which made Enter and a click on the same\nform produce different payloads. `click()` is the activation: a native\nbutton becomes the real submitter, and a `vf-button` forwards it to its\ninner button, which runs the same transient-proxy path a pointer does. A\ndisabled default button means no submission at all, as in HTML; a form\nwith no submit button falls back to the bare call, also as in HTML.\n\nReturns whether a form owner took the press — true even when a disabled\ndefault button meant no submission, since HTML gave the press to the form\neither way. The callers cancel the keydown on true, so a modal shell\n(`VfModalDialog`) sees the press as spoken for and does not also route it\nto the dialog's default button; with no form the press goes on to the\ndialog untouched."
             },
             {
               "kind": "method",
@@ -20778,7 +21772,7 @@
         },
         {
           "kind": "class",
-          "description": "Base class for the modal shell `vf-dialog` — and for a consumer's own\nmodal (an alert box, say) authored against the kit.\n\nOwns the native `<dialog>` lifecycle every modal shares: `open` sync, `show()` /\n`close()`, the top/left placement (stated or centered) and the\nsingle `close` funnel that drops the written origin and fires `vf-close` with\nthe reason. Because every close path — Escape, `close()`, the opt-in\nlightDismiss click outside — routes through the native `close`\nevent, an Escape-close no longer leaves a stale origin behind, so the next\nopen re-derives it.\n\nRemoving an open modal from the DOM is a close path too. HTML's dialog\n*removing steps* take the element out of the top layer **without** running\nthe close algorithm — no `close` event, no focus restoration — which is\nexactly what the standard framework pattern of unmounting a dialog instead\nof calling `close()` does. `disconnectedCallback` routes that path through\nthe same funnel: the removed element still fires `vf-close` (heard by\nlisteners on the element itself — it has left the tree, so nothing\nbubbles), `open` and the pinned margins reconcile so a re-append mounts it\nclosed and re-centered, and focus returns to the element that was focused\nwhen the modal opened.\n\nSubclasses supply only the frame chrome: a `render()` returning\n`<dialog",
+          "description": "Base class for the modal shell `vf-dialog` — and for a consumer's own\nmodal (an alert box, say) authored against the kit.\n\nOwns the native `<dialog>` lifecycle every modal shares: `open` sync, `show()` /\n`close()`, the top/left placement (stated or centered) and the\nsingle `close` funnel that drops the written origin and fires `vf-close` with\nthe reason. Because every close path — Escape, `close()`, the opt-in\nlightDismiss click outside — routes through the native `close`\nevent, an Escape-close no longer leaves a stale origin behind, so the next\nopen re-derives it.\n\nIt also owns the two keyboard rules every classic dialog followed (see\ndefaultButton and initialFocusTarget): Return or Enter\nactivates the default button from anywhere in the dialog, and the box opens\nwith the insertion point in its first text field — or, with none, focus on\nthe default button.\n\nRemoving an open modal from the DOM is a close path too. HTML's dialog\n*removing steps* take the element out of the top layer **without** running\nthe close algorithm — no `close` event, no focus restoration — which is\nexactly what the standard framework pattern of unmounting a dialog instead\nof calling `close()` does. `disconnectedCallback` routes that path through\nthe same funnel: the removed element still fires `vf-close` (heard by\nlisteners on the element itself — it has left the tree, so nothing\nbubbles), `open` and the pinned margins reconcile so a re-append mounts it\nclosed and re-centered, and focus returns to the element that was focused\nwhen the modal opened.\n\nSubclasses supply only the frame chrome: a `render()` returning\n`<dialog",
           "name": "VfModalDialog",
           "members": [
             {
@@ -20908,11 +21902,48 @@
             },
             {
               "kind": "field",
-              "name": "#dismissListeners",
+              "name": "#openListeners",
               "privacy": "private",
               "readonly": true,
-              "default": "new DocumentListenersController(this, () => [ [this._dialog, 'pointerdown', this.#onDialogPointerDown], [this._dialog, 'pointerup', this.#onDialogPointerUp], [this._dialog, 'pointercancel', this.#onDialogPointerCancel], ])",
-              "description": "The light-dismiss listeners, on the `<dialog>` itself and only while it is\nopen. The `::backdrop` hit-tests as its dialog, and the frame the subclass\nrenders fills the dialog's box, so the dialog is an event's *target* only\nwhen the pointer was outside the frame — no rect arithmetic, no\ncomposedPath. Attached whether or not lightDismiss is set: the\nhandlers read the property at the release, so it can be toggled on an\nopen dialog."
+              "default": "new DocumentListenersController(this, () => [ [this._dialog, 'pointerdown', this.#onDialogPointerDown], [this._dialog, 'pointerup', this.#onDialogPointerUp], [this._dialog, 'pointercancel', this.#onDialogPointerCancel], [this._dialog, 'keydown', this.#onDialogKeydown], ])",
+              "description": "The while-open listeners, on the `<dialog>` itself: the light-dismiss\npointer trio and the Return/Enter routing.\n\nLight dismiss: the `::backdrop` hit-tests as its dialog, and the frame the\nsubclass renders fills the dialog's box, so the dialog is an event's\n*target* only when the pointer was outside the frame — no rect arithmetic,\nno composedPath. Attached whether or not lightDismiss is set: the\nhandlers read the property at the release, so it can be toggled on an\nopen dialog."
+            },
+            {
+              "kind": "field",
+              "name": "defaultButton",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "protected",
+              "description": "The dialog's default button — the one wearing the bold ring\n(`vf-button[variant=\"default\"]`) — or null with none, or none enabled.\nLooked for among the slotted content first, then in the shadow tree, so a\nconsumer's own modal that renders its buttons itself is covered too.\nOverride to name it some other way.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "initialFocusTarget",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "protected",
+              "description": "Where focus lands on open. The classic Dialog Manager put the insertion\npoint in the first editable text item and gave nothing else focus at all;\nthe web needs a focused control for the keyboard to have anywhere to be,\nso with no text field the default button takes it (which is also what\nmakes Return and Space work there without a Tab). In order:\n\n1. a slotted control carrying `autofocus` — the author's say;\n2. the first enabled text-entry control (`vf-text-field`,\n   `vf-number-field`, `vf-text-area`, or a native text input/textarea);\n3. the defaultButton;\n4. null — leave the browser's own choice alone.\n\nLeft to itself, `showModal()` focuses the first focusable thing in flat\ntree order, which for a Cancel/OK row is Cancel, and for a body with a\nlink in it is the link — so Return did the one thing a classic dialog's\nReturn never did. Override to choose differently.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "#focusInitial",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Hand focus to initialFocusTarget, right after `showModal()`'s own\nfocusing steps have run (so this is the last word, not a race)."
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogKeydown",
+              "privacy": "private",
+              "description": "Return and Enter activate the default button from anywhere in the\ndialog, the way the classic Dialog Manager routed them — including from a\nfocused Cancel button, where Space is the key that presses the focused\ncontrol. Bubble phase, and only an uncancelled press: a control that\ntakes Enter for itself (`vf-select`'s list, `vf-list`, an icon's rename, a\ntext field whose form ran its implicit submission) cancels the keydown\nand is left alone. Two more keep their own Enter: a link, which follows\nit, and a multi-line editor, where Return inserts a newline and only the\nkeypad's Enter key fires the button — the same split a TextEdit item in a\nclassic dialog drew between the two keys."
             },
             {
               "kind": "field",
@@ -21271,7 +22302,7 @@
         },
         {
           "kind": "mixin",
-          "description": "Explicit placement — `top`/`left` in whole system px, on **every** component.\n\nNo exceptions, deliberately. These are web components, and a consumer may put\none wherever they like; the kit does not get to decide that a `vf-option` is\nonly ever a popup row. The rows a container normally owns (`vf-option`,\n`vf-menu-item`, `vf-list-item`) and a bar's `vf-menu` take the pair on the\nsame terms as anything else — and stating an origin on one *inside* its\nmanaging parent does take it out of that parent's flow layout, which is the\nplacement working, not failing. Each of those components documents what its\ncontainer stops doing for it. `vf-dialog` takes the pair in viewport\ncoordinates, the one difference the platform forces (see modal-dialog.ts).\n\nA DITL resource laid a dialog out as a list of items, each with a rectangle\nin the window's own coordinates; arranging controls by stating where they go\nis as native to System 7 as stacking them. This mixin is that mechanism:\ndeclaring `top` or `left` takes the element out of normal flow and\nabsolutely positions it within its parent, both coordinates in the art's own\nunit so the position scales with the display like every other metric. A\nwindow or dialog body can be laid out either way — a tree of `vf-stack`s, or\npositioned children — with no stylesheet in either case.\n\nMechanics, mirroring how `vf-stack` writes its declared size:\n\n- Setting either property writes `position: absolute` and both offsets onto\n  the host's inline style as `calc(var(--vf-scale, 1) * Npx)` — live against\n  the display, resolved at paint time. The coordinate left unset is 0.\n- `right`/`bottom` are released to `auto` and `margin` zeroed, so the stated\n  offsets are the whole story — an auto-width box with both edges set would\n  stretch rather than sit (the `vf-icon` seed logic, generalized).\n- Unsetting both returns the element to normal flow: every inline\n  declaration this wrote is removed, and stylesheet values resume.\n\nThe anchor is CSS's own: the nearest positioned ancestor's padding box. The\nkit's containers are all deliberate anchors — a desktop's raster, a window's\ncontent region (the frame's inner edge, below the title bar — the 12px body\ninset governs flow content only, exactly the DITL convention), a dialog's\ncontent area, a stack's box, a fieldset's border box, a scroll area's\nscrolled plane. In a non-kit parent, give the parent `position: relative`,\nthe one line of CSS this feature can't write for you.\n\nThe writing rides a ReactiveController (`hostUpdated`) rather than\nan `updated()` override, for a lifecycle reason worth keeping in the source:\nthe mixin sits *under* each component class, and most components override\n`updated()` without calling `super.updated()` — Lit's base is a no-op, so\nnothing ever forced the call — which would silently shadow a mixin-level\noverride. A controller is invoked by ReactiveElement itself, after every\nupdate, no matter what the subclass does.\n\nA gesture writes **through these properties**: `vf-window`'s title-bar drag\nand `vf-icon`'s drag and arrow nudge hand their new origin to a\nPlacementController, which snaps it onto the placement lattice and\nsets `left`/`top`. A moved element is therefore placed exactly the way an\nauthored one is — a live `calc()` in the art's own unit — and stays where it\nwas dropped when the zoom or the display changes what a system px costs.\n\nIt did not always. Writing the resolved CSS px straight to the inline style\nfroze the coordinate in the wrong unit: `--vf-scale` moved under it at every\nzoom step and the same constant read back as a different number of system px,\nso moved windows and icons slid off the grid the rest of the kit stayed on\n(by `3z / round(3z)` — 10% at 110% zoom, where nothing else moves at all).\n\nSetting a property yourself is still the deliberate way to re-place a moved\nelement. The controller re-applies **only when the values changed**, so an\nunrelated update — a heading change, a desktop toggling `active` — never\nre-asserts a coordinate and costs nothing.\n\n**`fixed`** holds the placement against the *visible* region of the nearest\nscrolling ancestor instead of its scrolled plane — a tool strip over a\ndocument, a column header over rows — and the flag alone places at (0,0).\nThe engine underneath is `position: sticky`, the one way the platform holds\na box against a scrollport from inside it on the compositor (a scroll\nlistener counter-translating lags a frame; a layer outside the scroller\nstops wheel and touch over it). Sticky boxes stay in flow, which is not\nwhat a placement is, so the controller erases the footprint: the host is\nblockified (no line box), shrink-wrapped, and given a negative right/bottom\nmargin equal to its own box — a 0×0 margin box that flow content lays out\nas if it weren't there, measured by a ResizeObserver so a relabel or a zoom\nstep keeps it exact. `z-index: 1` puts it over the plane's placed children,\nwhich is where a fixed strip belongs. Two facts of the engine that the\ndocs state as rules: sticky only ever pushes a box *down* from where the\nflow put it, so a fixed child comes before the flow content in its parent;\nand a scroll container that never scrolls (a plain window body is\n`overflow: hidden`) holds it exactly where placement would.",
+          "description": "Explicit placement — `top`/`left` in whole system px, on **every** component.\n\nNo exceptions, deliberately. These are web components, and a consumer may put\none wherever they like; the kit does not get to decide that a `vf-option` is\nonly ever a popup row. The rows a container normally owns (`vf-option`,\n`vf-menu-item`, `vf-list-item`) and a bar's `vf-menu` take the pair on the\nsame terms as anything else — and stating an origin on one *inside* its\nmanaging parent does take it out of that parent's flow layout, which is the\nplacement working, not failing. Each of those components documents what its\ncontainer stops doing for it. `vf-dialog` takes the pair in viewport\ncoordinates, the one difference the platform forces (see modal-dialog.ts).\n\nA DITL resource laid a dialog out as a list of items, each with a rectangle\nin the window's own coordinates; arranging controls by stating where they go\nis as native to System 7 as stacking them. This mixin is that mechanism:\ndeclaring `top` or `left` takes the element out of normal flow and\nabsolutely positions it within its parent, both coordinates in the art's own\nunit so the position scales with the display like every other metric. A\nwindow or dialog body can be laid out either way — a tree of `vf-stack`s, or\npositioned children — with no stylesheet in either case.\n\nMechanics, mirroring how `vf-stack` writes its declared size:\n\n- Setting either property writes `position: absolute` and both offsets onto\n  the host's inline style as `calc(var(--vf-scale, 1) * Npx)` — live against\n  the display, resolved at paint time. The coordinate left unset is 0.\n- `right`/`bottom` are released to `auto` and `margin` zeroed, so the stated\n  offsets are the whole story — an auto-width box with both edges set would\n  stretch rather than sit (the `vf-icon` seed logic, generalized).\n- Unsetting both returns the element to normal flow: every inline\n  declaration this wrote is removed, and stylesheet values resume.\n\nThe anchor is CSS's own: the nearest positioned ancestor's padding box. The\nkit's containers are all deliberate anchors — a desktop's raster, a window's\ncontent region (the frame's inner edge, below the title bar — the 12px body\ninset governs flow content only, exactly the DITL convention), a dialog's\ncontent area, a stack's box, a fieldset's border box, a scroll area's\nscrolled plane. In a non-kit parent, give the parent `position: relative`,\nthe one line of CSS this feature can't write for you.\n\nThe writing rides a ReactiveController (`hostUpdated`) rather than\nan `updated()` override, for a lifecycle reason worth keeping in the source:\nthe mixin sits *under* each component class, and most components override\n`updated()` without calling `super.updated()` — Lit's base is a no-op, so\nnothing ever forced the call — which would silently shadow a mixin-level\noverride. A controller is invoked by ReactiveElement itself, after every\nupdate, no matter what the subclass does.\n\nA gesture writes **through these properties**: `vf-window`'s title-bar drag\nand `vf-icon`'s drag and arrow nudge hand their new origin to a\nPlacementController, which snaps it onto the placement lattice and\nsets `left`/`top`. A moved element is therefore placed exactly the way an\nauthored one is — a live `calc()` in the art's own unit — and stays where it\nwas dropped when the zoom or the display changes what a system px costs.\n\nIt did not always. Writing the resolved CSS px straight to the inline style\nfroze the coordinate in the wrong unit: `--vf-scale` moved under it at every\nzoom step and the same constant read back as a different number of system px,\nso moved windows and icons slid off the grid the rest of the kit stayed on\n(by `3z / round(3z)` — 10% at 110% zoom, where nothing else moves at all).\n\nSetting a property yourself is still the deliberate way to re-place a moved\nelement. The controller re-applies **only when the values changed**, so an\nunrelated update — a heading change, a desktop toggling `active` — never\nre-asserts a coordinate and costs nothing.\n\n**Every write it makes is announced** as `vf-placement-change` (bubbles,\n`composed: false`, detail `{ left, top }` — nulls on a return to flow). It\nis an internal coordination event on the terms of the menu handshakes:\nparent and child share one light tree, and a kit protocol must not leak out\nof a consumer's shadow boundary. `vf-scroll-area` listens for it and\nre-measures, because a placed child moved through `top`/`left` changes the\nscroll range with no box changing anywhere a ResizeObserver can see — the\nplane's box is never grown by an absolutely positioned child. One funnel\ncovers a drop, an arrow nudge and a page's own `icon.left = …` alike.\n\n**`fixed`** holds the placement against the *visible* region of the nearest\nscrolling ancestor instead of its scrolled plane — a tool strip over a\ndocument, a column header over rows — and the flag alone places at (0,0).\nThe engine underneath is `position: sticky`, the one way the platform holds\na box against a scrollport from inside it on the compositor (a scroll\nlistener counter-translating lags a frame; a layer outside the scroller\nstops wheel and touch over it). Sticky boxes stay in flow, which is not\nwhat a placement is, so the controller erases the footprint: the host is\nblockified (no line box), shrink-wrapped, and given a negative right/bottom\nmargin equal to its own box — a 0×0 margin box that flow content lays out\nas if it weren't there, measured by a ResizeObserver so a relabel or a zoom\nstep keeps it exact. `z-index: 1` puts it over the plane's placed children,\nwhich is where a fixed strip belongs. Two facts of the engine that the\ndocs state as rules: sticky only ever pushes a box *down* from where the\nflow put it, so a fixed child comes before the flow content in its parent;\nand a scroll container that never scrolls (a plain window body is\n`overflow: hidden`) holds it exactly where placement would.",
           "name": "VfPositioned",
           "members": [
             {
@@ -21340,6 +22371,43 @@
             }
           ]
         },
+        {
+          "kind": "function",
+          "name": "placementIn",
+          "return": {
+            "type": {
+              "text": "{ left: number; top: number }"
+            }
+          },
+          "parameters": [
+            {
+              "name": "anchor",
+              "type": {
+                "text": "Element"
+              }
+            },
+            {
+              "name": "clientX",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "clientY",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "scaleAt",
+              "default": "anchor",
+              "type": {
+                "text": "Element"
+              }
+            }
+          ],
+          "description": "A viewport point as a placement in `anchor`'s coordinates: `{ left, top }`\nin whole system px on the placement lattice, measured from the anchor's\nbox the way a placed child's `top`/`left` are — the unit and lattice a\ndrag lands on, so the result can be written straight to a child's pair.\n\nThe three containers whose anchor sits in shadow DOM (`vf-window`'s\ncontent region, `vf-desktop`'s screen, `vf-scroll-area`'s plane) expose it\nas `placementAt(clientX, clientY)`; everywhere else the anchor is the\nelement's own padding box, and `toSysExact` against\n`getBoundingClientRect()` is the documented conversion. The anchor is\nexpected to carry no border of its own (the three do not), so its border\nbox is its padding box; `scaleAt` is the element whose `--vf-scale` the\nconversion reads — the component's host."
+        },
         {
           "kind": "class",
           "description": "The gesture half of placement: the piece a *movable* host adds on top of\nVfPositioned, so a drag ends up in the same `top`/`left` system-px\nproperties an author would have written.\n\nTwo things it owns, both consequences of storing the origin in the art's own\nunit rather than in resolved CSS px:\n\n- **Seeding.** A gesture starts from wherever the host already is, which may\n  be a coordinate nobody stated in system px — an authored `left: 10%`, a\n  `right`-anchored Trash icon, or plain normal flow. seed reads the\n  *used* position and converts it once; from then on the properties are the\n  whole truth.\n- **The lattice.** Every write is snapped to snapSys — whole art\n  pixels, the way QuickDraw moved windows, and the k-system-px run that also\n  lands the edge on a whole CSS px (scale.ts explains why that second half\n  matters to a scroll rail).\n\nIt holds no state the host's own properties don't already hold, so it takes\nno lifecycle and is not a ReactiveController: the writes it makes are\nordinary property sets, and `VfPositioned`'s controller renders them.\n\nAnd one thing it deliberately does **not** do: re-snap a placed host when the\nscale changes. The lattice moves with the scale (k is 2 at dpr 2, 3 at that\ndisplay's 150%), so a coordinate dropped on one rung sits between two on the\nnext — but re-rounding it there is worse than leaving it. It is lossy, and it\ncompounds: 62 → 63 at 150% → 64 at 200%, a window walking away from where it\nwas dropped one zoom step at a time, which is a milder version of the exact\nbug this class exists to fix (`verify:zoom` group (e) fails on it). Whole\nsystem px is whole *device* px at every rung by the scale contract, so the\nart stays crisp regardless; only the whole-CSS-px edge is given up, and an\nauthored `left=\"10\"` gives that up already. A dropped coordinate is therefore\nas immutable as an authored one — which is the whole claim.",
@@ -21393,6 +22461,15 @@
               "description": "Whether a gesture has placed this host (as opposed to markup or CSS).",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "bounds",
+              "type": {
+                "text": "PlacementBounds"
+              },
+              "description": "The box the gesture is clamped into, in system px: the one seed\nmeasured, or a fresh measurement before any gesture. A group drag reads\nit to clamp a whole selection's delta at once.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "seed",
@@ -21488,6 +22565,14 @@
             "module": "src/position.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "placementIn",
+          "declaration": {
+            "name": "placementIn",
+            "module": "src/position.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "PlacementController",