vintage-frames 0.12.2 → 0.12.4

package/README.md

@@ -2,7 +2,7 @@
 
 A web component kit that rebuilds the classic Apple System 7 interface elements.
 
-View the [Examples Page](https://aportilla.github.io/vintage-frames/) to see every element live, with its full API.
+View the [Examples Page](https://vintage-frames.portill.io/) to see every element live, with its full API.
 
 ```sh
 npm install vintage-frames

package/custom-elements.json

@@ -2453,7 +2453,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 four 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`).",
+          "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 four 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. A window asks the same way and draws\nthere with the same pen: its zoom rects when it opens from a rect\n(`vf-window.show({ from })`), its outline under an `outline-drag`. Not the\ntop 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": [
             {
@@ -2856,7 +2856,7 @@
               "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."
+              "description": "A dragged icon, or a window opening from a rect, asking for the screen's\ndrag surface (see the class doc). Non-composed, so it reaches here only\nthrough the light-DOM path the asker is slotted on — a window body\nincluded. The nearest desktop answers; an outer one leaves a filled\ndetail alone."
             },
             {
               "kind": "field",
@@ -6106,6 +6106,16 @@
               ],
               "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": "method",
+              "name": "cellRect",
+              "return": {
+                "type": {
+                  "text": "DOMRect | null"
+                }
+              },
+              "description": "The reserved art cell's box in the viewport, CSS px: 32×32 system px, or\n16×16 under `size=\"small\"`, centered at the top of the frame — the same\nbox whatever the art, the name, `width`, `open` or `selected`. The\nslotted art is no stand-in for it: `open` hides the slot, so the art\nmeasures nothing. The box to hand anything that opens from the icon or\ncloses to it. Null while the icon is not rendered — out of the\ndocument, or under `display: none`, inside a hidden window say. Before\nthe first render, the host's box."
+            },
             {
               "kind": "method",
               "name": "moveTo",
@@ -19971,7 +19981,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-window>` — the System 7 desktop-window shell.\n\nStriped title bar with optional close box (left) and zoom box (right), a\nsolid-white frame with a hard offset shadow, an optional grow box for\nresizing, optional edge scroll rails (`scrollbars`), and the slim windoid\nchrome (`variant=\"utility\"`). The HIG's window archetypes are parameter\nrecipes over this shell rather than fixed anatomies — the component enables\nHIG compliance, it doesn't enforce it (see docs/LAYOUT.md \"Window archetypes\"):\nthe full document window is `closable zoomable movable resizable\nscrollbars=\"both\"`, a modeless dialog box is `closable movable`, a utility\nwindow is `variant=\"utility\" movable`. Place inside `<vf-desktop>` to get\nclick-to-front stacking and automatic `active` management (utility windows\nfloat above the document tier).\n\nEvery recipe also declares `width` AND `height` (VfSized), in whole\nsystem px — the art's own unit, so the window keeps its proportions to the\nchrome inside it at every display density (a CSS-px size stays put while\nthe components in it triple). A window is a fixed box in both axes, the way\nthe WIND resource carried it: left to layout it takes whatever its\ncontainer or content hands it, which is how a title bar ends up wider than\nthe screen or a dialog reflows as it moves — and a window that grows with\nits body is one the user can neither predict nor (via the grow box) own.\nContent taller than the declared box is clipped at the frame the way the\nclassic content region was; `scrollbars` lets the user reach the rest.\nUnset, the window still renders — normal block layout, as before — and\nsays so once in the console.",
+          "description": "`<vf-window>` — the System 7 desktop-window shell.\n\nStriped title bar with optional close box (left) and zoom box (right), a\nsolid-white frame with a hard offset shadow, an optional grow box for\nresizing, optional edge scroll rails (`scrollbars`), and the slim windoid\nchrome (`variant=\"utility\"`). The HIG's window archetypes are parameter\nrecipes over this shell rather than fixed anatomies — the component enables\nHIG compliance, it doesn't enforce it (see docs/LAYOUT.md \"Window archetypes\"):\nthe full document window is `closable zoomable movable resizable\nscrollbars=\"both\"`, a modeless dialog box is `closable movable`, a utility\nwindow is `variant=\"utility\" movable`. Place inside `<vf-desktop>` to get\nclick-to-front stacking and automatic `active` management (utility windows\nfloat above the document tier).\n\nEvery recipe also declares `width` AND `height` (VfSized), in whole\nsystem px — the art's own unit, so the window keeps its proportions to the\nchrome inside it at every display density (a CSS-px size stays put while\nthe components in it triple). A window is a fixed box in both axes, the way\nthe WIND resource carried it: left to layout it takes whatever its\ncontainer or content hands it, which is how a title bar ends up wider than\nthe screen or a dialog reflows as it moves — and a window that grows with\nits body is one the user can neither predict nor (via the grow box) own.\nContent taller than the declared box is clipped at the frame the way the\nclassic content region was; `scrollbars` lets the user reach the rest.\nUnset, the window still renders — normal block layout, as before — and\nsays so once in the console.\n\n**Opening from a rect.** show clears `hidden`, and given `from` — a\nbox in viewport CSS px, an icon's `cellRect()` or a button's rect — opens\nthe window from it: dotted rectangles grow from that box toward the\nwindow's frame, four on screen at a time, bunched at the box and opening\nout toward the window, drawn with the icon drag outline's XOR pen on the\ndesktop's drag surface; the window draws once they have drained, eighteen\nsteps later. Until then it matches `:state(opening)` and paints nothing —\nstill laid out, focusable and a hit target, so a page can place it, raise\nit and focus into it at once, and a press finishes the rects and lands on\nthe window. Under `prefers-reduced-motion`, with no `vf-desktop` on its\npath, or without `from`, the window shows at once.\n\n**Closing to a rect.** hide sets `hidden`, and given `to` closes\nthe window to it: the same rectangles run the other way, from where the\nframe was in toward the box, the window gone from the first step. A press\nfinishes them, and removing the window leaves them running. Under\n`prefers-reduced-motion`, with no `vf-desktop` on its path, or without\n`to`, the window hides at once. The window knows nothing about icons:\n`from` and `to` are any rect.\n\n**Dragging as an outline.** A `movable` window moves live under the\npointer. With `outline-drag` a press on the title bar draws a dotted\noutline around the window on the desktop's drag surface instead, with the\nsame pen; the drag moves the outline, held where the window can land, and\nthe window moves there on the release. Escape cancels.",
           "name": "VfWindow",
           "cssProperties": [
             {
@@ -20119,6 +20129,17 @@
               "attribute": "movable",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "outlineDrag",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Drag by the title bar as an outline: a press draws a dotted one-pixel\nrectangle around the window on the desktop's drag surface, with the\nicon drag outline's pen; the drag moves it, held where the window can\nland, and the window moves there on the release, in one write. Escape\ncancels and writes nothing, as does a release that never moved it.\nUnset, the window moves live under the pointer; with no `vf-desktop` on\nits path it moves live either way. Only matters with `movable`.",
+              "attribute": "outline-drag",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "resizable",
@@ -20297,7 +20318,7 @@
               "name": "_drag",
               "privacy": "private",
               "readonly": true,
-              "default": "new DragController(this, { onDragStart: (event: PointerEvent): { x: number; y: number } | null => { if (!this.movable || event.button !== 0) return null // Ignore drags that start on the close/zoom widgets. if ( event .composedPath() .some( (node) => node instanceof HTMLElement && node.classList.contains('box') ) ) { return null } this.#warnIfUnplaced() return this._placement.seed() }, onDrag: (x: number, y: number): void => this._placement.moveTo(x, y), })",
+              "default": "new DragController(this, { onDragStart: (event: PointerEvent): { x: number; y: number } | null => { if (!this.movable || event.button !== 0) return null // Ignore drags that start on the close/zoom widgets. if ( event .composedPath() .some( (node) => node instanceof HTMLElement && node.classList.contains('box') ) ) { return null } this.#warnIfUnplaced() const origin = this._placement.seed() this.#startOutlineDrag(origin) return origin }, onDrag: (x: number, y: number): void => { if (this.#outlineDrag) this.#dragOutlineTo(x, y) else this._placement.moveTo(x, y) }, onDragEnd: (_event: PointerEvent | undefined, cancelled: boolean): void => { this.#endOutlineDrag(cancelled) }, })",
               "description": "Title-bar drag-to-move (shared with `vf-dialog` via DragController).\nThe controller owns the pointer bookkeeping and hands over system px; the\nplacement controller seeds the origin and writes the result."
             },
             {
@@ -20350,6 +20371,312 @@
               },
               "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": "method",
+              "name": "show",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "VfWindowShowOptions"
+                  }
+                }
+              ],
+              "description": "Show the window: `hidden` cleared, and with `from` the window opens from\nthat box — the zoom rects, grown from it toward the frame at the cadence\nin src/motion.ts (`WINDOW_RECT_*`), the window drawn once they have\ndrained (see the class doc). A run in flight, a `show()` or a `hide()`,\nis finished first; a press anywhere or Escape finishes this one, and\nremoving the window or a `hide()` takes it down. Resolves once the\nwindow draws: `true` when the rects ran, `false` when it showed at once\n— no `from`, `prefers-reduced-motion`, no `vf-desktop` on its path,\nnothing of the rects on the screen, or not in the DOM — or never drew.\nIt raises and activates nothing: stacking stays the page's\n(`vf-desktop.bringToFront`)."
+            },
+            {
+              "kind": "method",
+              "name": "hide",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "VfWindowHideOptions"
+                  }
+                }
+              ],
+              "description": "Hide the window: `hidden` set, and with `to` the window closes to that\nbox — the rects of show run the other way, from where the frame\nis drawn at the call in toward the box, the window gone from their first\nstep. A `show()` still opening is taken down and says `false`; a second\n`hide()` finishes the first; a press anywhere or Escape finishes the\nrects; removing the window leaves them running, so a page can remove a\nwindow as it closes it. Resolves once the rects are done: `true` when\nthey ran, `false` when the window hid at once — no `to`,\n`prefers-reduced-motion`, no `vf-desktop` on its path, nothing of the\nrects on the screen, not in the DOM, or no frame to close from: already\nhidden, or still opening."
+            },
+            {
+              "kind": "field",
+              "name": "#internals",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Internals, for the `opening` custom state."
+            },
+            {
+              "kind": "field",
+              "name": "#rectsRun",
+              "privacy": "private",
+              "type": {
+                "text": "RectsRun | null"
+              },
+              "default": "null",
+              "description": "The `show({ from })` or `hide({ to })` in flight, or null."
+            },
+            {
+              "kind": "field",
+              "name": "#interrupt",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DocumentListenersController(this, () => [ [document, 'pointerdown', this.#onRectsPress, true], [document, 'keydown', this.#onRectsKeyDown, true], ])",
+              "description": "A press anywhere, or Escape, finishes the rects: an opening window draws\nat once, and the press lands on it. Scoped to the run, on the document,\ncapture phase, Escape stopped there — the walk's rule (`vf-icon.dragTo`),\nfor the same reasons."
+            },
+            {
+              "kind": "field",
+              "name": "#onRectsPress",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "#onRectsKeyDown",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#stopRects",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "how",
+                  "type": {
+                    "text": "'finish' | 'cancel'"
+                  }
+                }
+              ],
+              "description": "End the run in flight now: its rects finished — its call says they ran,\nand an opening window draws at once — or cancelled, when it says they\ndid not. A run whose rects have not started says `false`."
+            },
+            {
+              "kind": "method",
+              "name": "#endRects",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "The run over, the window drawn if it was opening, the finishers gone."
+            },
+            {
+              "kind": "method",
+              "name": "#playOut",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "run",
+                  "type": {
+                    "text": "RectsRun"
+                  }
+                },
+                {
+                  "name": "rects",
+                  "type": {
+                    "text": "Rects"
+                  }
+                }
+              ],
+              "description": "Wait out a run's rects, then take their canvases down: finished —\ndrained, or a press, Escape or the next call — they ran; cancelled,\nthey did not."
+            },
+            {
+              "kind": "method",
+              "name": "#animateRects",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Rects | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "VfViewportBox"
+                  }
+                },
+                {
+                  "name": "frame",
+                  "type": {
+                    "text": "VfViewportBox"
+                  }
+                },
+                {
+                  "name": "closing",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "The rects between `box` and the window's `frame`, on the desktop's drag\nsurface — the one the `vf-drag-surface-request` handshake finds, as a\ndragged icon's outline does. Both in whole system px from the corner of\nits screen; every edge of rect k sits its fraction of the way from the\nbox to the frame (windowRectFraction), the delta truncated toward\nzero. Each rect is a canvas of its own, framed once with the XOR pen at\nits phase on the screen (penPhase) and hidden, with an animation\nthat shows it for WINDOW_RECTS_VISIBLE steps: from step k opening,\nout from the box, and from step 13 − k closing, in toward it. Where two\nrects share a pixel the later one inverts it back: the surface is no\nstacking context, so each canvas blends over the ones before it as well\nas the screen. Null with no desktop on the path, or none of the rects on\nthe screen."
+            },
+            {
+              "kind": "method",
+              "name": "#requestSurface",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement | null"
+                }
+              },
+              "description": "The handshake a dragged icon's outline uses: a desktop on the light-DOM\npath hands over its drag surface. Null with no desktop."
+            },
+            {
+              "kind": "field",
+              "name": "#outlineDrag",
+              "privacy": "private",
+              "type": {
+                "text": "OutlineDrag | null"
+              },
+              "default": "null",
+              "description": "The outline drag in flight, or null — a live drag keeps none."
+            },
+            {
+              "kind": "field",
+              "name": "#dragEscape",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DocumentListenersController(this, () => [ [document, 'keydown', this.#onDragKeyDown, true], ])",
+              "description": "Escape mid outline-drag cancels it: a document listener scoped to the\ngesture, capture phase, the key stopped there — the icon drag's rule, so\nan enclosing dialog never reads it as a dismissal."
+            },
+            {
+              "kind": "field",
+              "name": "#onDragKeyDown",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#startOutlineDrag",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "origin",
+                  "type": {
+                    "text": "{ x: number; y: number }"
+                  }
+                }
+              ],
+              "description": "The press of an outline drag: the outline drawn around the window at\nonce, and Escape armed. A window without `outline-drag`, or with no\ndesktop to draw on, keeps no outline drag, and the gesture moves it live."
+            },
+            {
+              "kind": "method",
+              "name": "#dragOutlineTo",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "A step of an outline drag: the outline to where the release would land\n— the step clamped as a live drag is (PlacementController.resolve)."
+            },
+            {
+              "kind": "method",
+              "name": "#placeOutline",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "outline",
+                  "type": {
+                    "text": "WindowOutline"
+                  }
+                },
+                {
+                  "name": "dx",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "dy",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Put the outline its delta from where the press drew it, whole system px\nfrom the desktop's screen, re-dotted when its phase on the screen changes."
+            },
+            {
+              "kind": "method",
+              "name": "#buildOutline",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "WindowOutline | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "frame",
+                  "type": {
+                    "text": "DOMRect"
+                  }
+                }
+              ],
+              "description": "The outline an outline drag moves: the window's box at the press — its\nframe, border included, shadow not — as a one-pixel ring on the\ndesktop's drag surface, with the drag outline's pen. Null with no desktop."
+            },
+            {
+              "kind": "method",
+              "name": "#endOutlineDrag",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "cancelled",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "The end of an outline drag: the outline down and, released rather than\ncancelled, the window written where it was — one write, one\n`vf-placement-change`. A press released without a step writes nothing."
+            },
             {
               "kind": "field",
               "name": "#warnedNoSize",
@@ -20655,6 +20982,15 @@
               "description": "Allow dragging the window by its title bar.",
               "fieldName": "movable"
             },
+            {
+              "name": "outline-drag",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Drag by the title bar as an outline: a press draws a dotted one-pixel\nrectangle around the window on the desktop's drag surface, with the\nicon drag outline's pen; the drag moves it, held where the window can\nland, and the window moves there on the release, in one write. Escape\ncancels and writes nothing, as does a release that never moved it.\nUnset, the window moves live under the pointer; with no `vf-desktop` on\nits path it moves live either way. Only matters with `movable`.",
+              "fieldName": "outlineDrag"
+            },
             {
               "name": "resizable",
               "type": {

package/dist/components/vf-desktop.d.ts

@@ -65,7 +65,10 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  * icon reaches it without an import, the menu-handshake idiom: on a drag's
  * first step it dispatches `vf-drag-surface-request` (bubbles, non-composed,
  * `detail.surface` null), and the nearest desktop on its light-DOM path
- * fills the detail with the layer. Not the top layer: stable Safari cannot
+ * fills the detail with the layer. A window asks the same way and draws
+ * there with the same pen: its zoom rects when it opens from a rect
+ * (`vf-window.show({ from })`), its outline under an `outline-drag`. Not the
+ * top layer: stable Safari cannot
  * blend an element there against the page (src/cursor.ts), and a second
  * kit entry in the top layer would need a re-promotion handshake.
  *
@@ -307,10 +310,11 @@ export declare class VfDesktop extends VfDesktop_base {
      */
     private _onGestureEnd;
     /**
-     * A dragged icon asking for the screen's drag surface (see the class
-     * doc). Non-composed, so it reaches here only through the light-DOM path
-     * the icon is slotted on — a window body included. The nearest desktop
-     * answers; an outer one leaves a filled detail alone.
+     * A dragged icon, or a window opening from a rect, asking for the screen's
+     * drag surface (see the class doc). Non-composed, so it reaches here only
+     * through the light-DOM path the asker is slotted on — a window body
+     * included. The nearest desktop answers; an outer one leaves a filled
+     * detail alone.
      */
     private _onDragSurfaceRequest;
     /**

package/dist/components/vf-icon-field.js

@@ -7,13 +7,13 @@ import { vfBase as o } from "../styles/recipes/host.js";
 import { DocumentListenersController as s } from "../document-listeners.js";
 import { VfSized as c } from "../size.js";
 import "../motion.js";
-import { paintSelectionRect as l, penPhase as u } from "../open-art.js";
-import { LitElement as d, css as f, html as p } from "lit";
-import { property as m } from "lit/decorators.js";
+import { paintSelectionRect as l, penPhase as u, xorPenCanvas as d } from "../open-art.js";
+import { LitElement as f, css as p, html as m } from "lit";
+import { property as h } from "lit/decorators.js";
 //#region src/components/vf-icon-field.ts
-var h = (e, t, n) => Math.min(Math.max(e, t), n), g = class extends c(a(d)) {
+var g = (e, t, n) => Math.min(Math.max(e, t), n), _ = class extends c(a(f)) {
 	static {
-		this.styles = [o, f`
+		this.styles = [o, p`
       :host {
         /* A block that shrink-wraps: the field is exactly as big as what it
            holds in flow — nothing, for a field of placed icons — so it can
@@ -137,8 +137,8 @@ var h = (e, t, n) => Math.min(Math.max(e, t), n), g = class extends c(a(d)) {
 	}
 	#h(e, t, n, r) {
 		return {
-			x: h(Math.round((e.clientX - t.left) / n), r.minX, r.maxX),
-			y: h(Math.round((e.clientY - t.top) / n), r.minY, r.maxY)
+			x: g(Math.round((e.clientX - t.left) / n), r.minX, r.maxX),
+			y: g(Math.round((e.clientY - t.top) / n), r.minY, r.maxY)
 		};
 	}
 	#g(e, t) {
@@ -172,10 +172,8 @@ var h = (e, t, n) => Math.min(Math.max(e, t), n), g = class extends c(a(d)) {
 		};
 	}
 	#v() {
-		let e = document.createElement("canvas");
-		e.className = "selection-rect";
-		let t = e.style;
-		return t.position = "fixed", t.display = "block", t.pointerEvents = "none", t.filter = "invert(1)", t.mixBlendMode = "difference", t.imageRendering = "pixelated", e;
+		let e = d("selection-rect");
+		return e.style.position = "fixed", e;
 	}
 	#y(e, t) {
 		let { rect: n, canvas: r } = e;
@@ -238,9 +236,9 @@ var h = (e, t, n) => Math.min(Math.max(e, t), n), g = class extends c(a(d)) {
 		e.finished || (e.finished = !0, this.#r === e && (this.#r = null, this.#i.detach()), e.settle());
 	}
 	render() {
-		return p`<slot @slotchange=${this.#s}></slot>`;
+		return m`<slot @slotchange=${this.#s}></slot>`;
 	}
 };
-i([m()], g.prototype, "label", void 0), i([m({ reflect: !0 })], g.prototype, "size", void 0), g = i([t("vf-icon-field")], g);
+i([h()], _.prototype, "label", void 0), i([h({ reflect: !0 })], _.prototype, "size", void 0), _ = i([t("vf-icon-field")], _);
 //#endregion
-export { g as VfIconField };
+export { _ as VfIconField };

package/dist/components/vf-icon.d.ts

@@ -626,6 +626,17 @@ export declare class VfIcon extends VfIcon_base {
         right: number;
         bottom: number;
     }): boolean;
+    /**
+     * The reserved art cell's box in the viewport, CSS px: 32×32 system px, or
+     * 16×16 under `size="small"`, centered at the top of the frame — the same
+     * box whatever the art, the name, `width`, `open` or `selected`. The
+     * slotted art is no stand-in for it: `open` hides the slot, so the art
+     * measures nothing. The box to hand anything that opens from the icon or
+     * closes to it. Null while the icon is not rendered — out of the
+     * document, or under `display: none`, inside a hidden window say. Before
+     * the first render, the host's box.
+     */
+    cellRect(): DOMRect | null;
     /**
      * Place the icon as a drop would: the stated pair — the origin point
      * under an `origin`, the corner without one — clamped whole in the