vintage-frames 0.5.2 → 0.5.4

package/custom-elements.json

@@ -2237,7 +2237,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, at pointer-gesture\nends), so tabbing walks the stack the way the eye does and Shift+Tab is\nits 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\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": [
             {
@@ -2460,6 +2460,16 @@
               "default": "false",
               "description": "Whether _syncDomOrder is putting focus back after a node move."
             },
+            {
+              "kind": "field",
+              "name": "_domSyncTimer",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "The pending DOM-order sync task, or 0 (see _requestDomSync)."
+            },
             {
               "kind": "field",
               "name": "_gestureEnd",
@@ -2503,7 +2513,7 @@
                   }
                 }
               ],
-              "description": "Bring a slotted window to the front of its tier. A document-tier window\nalso becomes the single active window (clearing `active` on the other\ndocument windows); a utility window restacks within the floating tier\nand leaves every `active` state alone.\n\nThe light-DOM order of the slotted windows follows (_syncDomOrder):\nvisual stacking and sequential focus order come from independent channels\n(z-index vs DOM position), and letting them drift apart is how a desktop\ntabs front-to-back one way and back-to-front the other, with widgets\nreachable only travelling backwards. Deferred to the end of any in-flight\npointer gesture — moving a node clears the pointer capture a title-bar\ndrag or grow-box resize holds on it, and a background window must stay\ndraggable in the same gesture that raises it."
+              "description": "Bring a slotted window to the front of its tier. A document-tier window\nalso becomes the single active window (clearing `active` on the other\ndocument windows); a utility window restacks within the floating tier\nand leaves every `active` state alone.\n\nThe light-DOM order of the slotted windows follows (_syncDomOrder):\nvisual stacking and sequential focus order come from independent channels\n(z-index vs DOM position), and letting them drift apart is how a desktop\ntabs front-to-back one way and back-to-front the other, with widgets\nreachable only travelling backwards. The sync runs in a task, and not\nbefore any in-flight pointer gesture has ended — moving a node clears the\npointer capture a title-bar drag or grow-box resize holds on it (a\nbackground window must stay draggable in the same gesture that raises\nit), and a node moved between a press's release and its `click` costs a\ncontrol in the raised window that click (see _requestDomSync)."
             },
             {
               "kind": "field",
@@ -2552,7 +2562,7 @@
                   "text": "void"
                 }
               },
-              "description": "Sync the DOM order now, or at gesture end if a pointer is down."
+              "description": "Schedule the DOM-order sync: one task from now, coalesced, and never\nwhile a pointer is down — the gesture's end schedules it instead.\n\nA task rather than the synchronous move this used to be, because the\nbrowser dispatches a release's pointerup, mouseup and click in ONE task,\nand Chromium drops a click whose mousedown node left the tree before the\nclick was dispatched — and re-inserting a window is a removal. Synced at\npointerup, a raise moved the window between the press and its click, so\na control in a background window (a checkbox in a palette under another\npalette) got its press and release but never its click: it looked\npressed and never acted. Not a microtask either — that runs between the\nlisteners of the same dispatch, still ahead of the click. A task runs\nafter the whole chain, the shape `deferActivation` (src/events.ts) falls\nback on for the same reason."
             },
             {
               "kind": "method",
@@ -2571,7 +2581,7 @@
                   }
                 }
               ],
-              "description": "Raise the window an event originated in, skipping the restack/activation\nchurn when it is already on top of its own tier (and, for a document\nwindow, already active): otherwise every click inside the front window\nwould bump _zCounter and re-run the whole-fleet activation loop for\nnothing.\n\nRestacks z/active only — deliberately no DOM sync. A focus-driven raise\nMUST NOT move nodes: moving the window focus just entered re-orders the\nsequence mid-traversal, and a Shift+Tab that raises each window it\nenters (pushing it forward in the DOM, back the way the traversal came)\nwould revisit it forever. The pointer path syncs at gesture end instead,\nwhich is also the next safe point after any keyboard-session staleness."
+              "description": "Raise the window an event originated in, skipping the restack/activation\nchurn when it is already on top of its own tier (and, for a document\nwindow, already active): otherwise every click inside the front window\nwould bump _zCounter and re-run the whole-fleet activation loop for\nnothing.\n\nRestacks z/active only — deliberately no DOM sync. A focus-driven raise\nMUST NOT move nodes: moving the window focus just entered re-orders the\nsequence mid-traversal, and a Shift+Tab that raises each window it\nenters (pushing it forward in the DOM, back the way the traversal came)\nwould revisit it forever. The pointer path schedules the sync at gesture\nend instead, which is also the next safe point after any keyboard-session\nstaleness."
             },
             {
               "kind": "field",
@@ -2583,7 +2593,7 @@
               "kind": "field",
               "name": "_onGestureEnd",
               "privacy": "private",
-              "description": "The press ended (or was cancelled) — sync the DOM order. Unconditional\nrather than only-if-raised: the sync no-ops when order already agrees,\nand running it at every gesture end is what heals the staleness a\nkeyboard-only stretch leaves behind (focus-driven raises change z but\nnever move nodes — see _raise)."
+              "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",
@@ -2715,7 +2725,7 @@
                   "text": "void"
                 }
               },
-              "description": "Re-order the slotted windows in the light DOM to match their z-order\n(bottom-most first), so sequential focus navigation walks the stack the\nway the eye does — and Shift+Tab is its exact mirror. The utility band\nsorts the floating tier after every document window by construction.\n\nMinimal-move: windows already in relative order are never touched (the\ncommon case — after one raise, one window moves). Non-window siblings\n(a menu bar, page content) keep their positions; only a window that must\ncross the stack moves past them. Moving a node containing the focused\nelement drops focus to `<body>`, so it is restored afterwards — behind\n`_restoringFocus`, because the restore re-fires focusin (see\n_onFocusIn) on an element that may sit in a background window.\nOnly runs between pointer gestures or programmatically, never from a\nfocus-driven raise (see _raise for why)."
+              "description": "Re-order the slotted windows in the light DOM to match their z-order\n(bottom-most first), so sequential focus navigation walks the stack the\nway the eye does — and Shift+Tab is its exact mirror. The utility band\nsorts the floating tier after every document window by construction.\n\nMinimal-move: windows already in relative order are never touched (the\ncommon case — after one raise, one window moves). Non-window siblings\n(a menu bar, page content) keep their positions; only a window that must\ncross the stack moves past them. Moving a node containing the focused\nelement drops focus to `<body>`, so it is restored afterwards — behind\n`_restoringFocus`, because the restore re-fires focusin (see\n_onFocusIn) on an element that may sit in a background window.\nReached only through _requestDomSync's task — after a pointer\ngesture or a programmatic raise, never from a focus-driven one (see\n_raise for why)."
             },
             {
               "kind": "field",
@@ -2845,7 +2855,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' }`.",
+          "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.",
           "name": "VfDialog",
           "cssProperties": [
             {
@@ -3129,6 +3139,21 @@
                 "module": "src/modal-dialog.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "lightDismiss",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+              "attribute": "light-dismiss",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "_dialog",
@@ -3198,6 +3223,61 @@
                 "module": "src/modal-dialog.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "#outsidePress",
+              "privacy": "private",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "The `pointerId` of a press that landed on the backdrop, held until its\nrelease decides whether the click was outside; null while nothing is\npending. See lightDismiss.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#dismissListeners",
+              "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.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerDown",
+              "privacy": "private",
+              "description": "A press on the backdrop arms the dismissal. A press anywhere else — the\nframe, a control, the title bar — disarms it, so a stale arm (a press the\nplatform never released to us, a right-click's on macOS) can't survive to\nthe next release.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerUp",
+              "privacy": "private",
+              "description": "The release completes it — the same press *and* release on the backdrop.\nDeliberately not the `click` event: UI Events dispatches a\npress-drag-release click at the common ancestor of the two targets, which\nfor a press on the frame released outside is the dialog itself, and that\nwould dismiss on exactly the gesture the two-step rule exists to ignore.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerCancel",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "#invoker",
@@ -3477,7 +3557,7 @@
           ],
           "events": [
             {
-              "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' }`.",
+              "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`.",
               "name": "vf-close",
               "inheritedFrom": {
                 "name": "VfModalDialog",
@@ -3581,6 +3661,19 @@
                 "name": "VfModalDialog",
                 "module": "src/modal-dialog.ts"
               }
+            },
+            {
+              "name": "light-dismiss",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+              "fieldName": "lightDismiss",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
             }
           ],
           "superclass": {
@@ -19702,7 +19795,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()`, backdrop — routes\nthrough the native `close` event, an Escape-close no longer leaves a stale\norigin behind, so the next open 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\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": [
             {
@@ -19760,6 +19853,17 @@
               "description": "Offset from the left of the viewport, in whole system px. See top.",
               "attribute": "left"
             },
+            {
+              "kind": "field",
+              "name": "lightDismiss",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+              "attribute": "light-dismiss",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "_dialog",
@@ -19809,6 +19913,41 @@
               "default": "null",
               "description": "Close reason pending for the next native `close` event."
             },
+            {
+              "kind": "field",
+              "name": "#outsidePress",
+              "privacy": "private",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "The `pointerId` of a press that landed on the backdrop, held until its\nrelease decides whether the click was outside; null while nothing is\npending. See lightDismiss."
+            },
+            {
+              "kind": "field",
+              "name": "#dismissListeners",
+              "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."
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerDown",
+              "privacy": "private",
+              "description": "A press on the backdrop arms the dismissal. A press anywhere else — the\nframe, a control, the title bar — disarms it, so a stale arm (a press the\nplatform never released to us, a right-click's on macOS) can't survive to\nthe next release."
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerUp",
+              "privacy": "private",
+              "description": "The release completes it — the same press *and* release on the backdrop.\nDeliberately not the `click` event: UI Events dispatches a\npress-drag-release click at the common ancestor of the two targets, which\nfor a press on the frame released outside is the dialog itself, and that\nwould dismiss on exactly the gesture the two-step rule exists to ignore."
+            },
+            {
+              "kind": "field",
+              "name": "#onDialogPointerCancel",
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "#invoker",
@@ -20020,7 +20159,7 @@
           ],
           "events": [
             {
-              "description": "The modal closed. `detail: { reason: 'escape' | 'close' }`.",
+              "description": "The modal closed. `detail: { reason: 'escape' | 'close' | 'outside' }`.",
               "name": "vf-close"
             }
           ],
@@ -20065,6 +20204,15 @@
               },
               "description": "Offset from the left of the viewport, in whole system px. See top.",
               "fieldName": "left"
+            },
+            {
+              "name": "light-dismiss",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+              "fieldName": "lightDismiss"
             }
           ],
           "superclass": {

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

@@ -9,9 +9,9 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  * `vf-window` children: a `pointerdown` or
  * `focusin` (keyboard focus) anywhere inside a window brings it to the front
  * and makes it the single active window. The windows' light-DOM order is kept
- * in step with the stacking order (bottom-most first, at pointer-gesture
- * ends), so tabbing walks the stack the way the eye does and Shift+Tab is
- * its exact mirror.
+ * in step with the stacking order (bottom-most first, synced in a task once
+ * any pointer gesture has ended), so tabbing walks the stack the way the eye
+ * does and Shift+Tab is its exact mirror.
  *
  * Utility windows (`vf-window[variant="utility"]`) stack in a floating tier
  * above every document-tier window, restack only among themselves, and stand
@@ -183,6 +183,8 @@ export declare class VfDesktop extends VfDesktop_base {
     private _pointerGesture;
     /** Whether {@link _syncDomOrder} is putting focus back after a node move. */
     private _restoringFocus;
+    /** The pending DOM-order sync task, or 0 (see {@link _requestDomSync}). */
+    private _domSyncTimer;
     /**
      * Ends the pointer-gesture window that defers DOM reordering. Capture-phase
      * on the document so a component's `stopPropagation` can't strand the flag,
@@ -206,10 +208,12 @@ export declare class VfDesktop extends VfDesktop_base {
      * visual stacking and sequential focus order come from independent channels
      * (z-index vs DOM position), and letting them drift apart is how a desktop
      * tabs front-to-back one way and back-to-front the other, with widgets
-     * reachable only travelling backwards. Deferred to the end of any in-flight
-     * pointer gesture — moving a node clears the pointer capture a title-bar
-     * drag or grow-box resize holds on it, and a background window must stay
-     * draggable in the same gesture that raises it.
+     * reachable only travelling backwards. The sync runs in a task, and not
+     * before any in-flight pointer gesture has ended — moving a node clears the
+     * pointer capture a title-bar drag or grow-box resize holds on it (a
+     * background window must stay draggable in the same gesture that raises
+     * it), and a node moved between a press's release and its `click` costs a
+     * control in the raised window that click (see {@link _requestDomSync}).
      */
     bringToFront(win: HTMLElement): void;
     /** The active document-tier window, or null while the tier is deactivated
@@ -226,7 +230,22 @@ export declare class VfDesktop extends VfDesktop_base {
     clearActive(): void;
     /** The z/active half of a raise, shared by every path. */
     private _restack;
-    /** Sync the DOM order now, or at gesture end if a pointer is down. */
+    /**
+     * Schedule the DOM-order sync: one task from now, coalesced, and never
+     * while a pointer is down — the gesture's end schedules it instead.
+     *
+     * A task rather than the synchronous move this used to be, because the
+     * browser dispatches a release's pointerup, mouseup and click in ONE task,
+     * and Chromium drops a click whose mousedown node left the tree before the
+     * click was dispatched — and re-inserting a window is a removal. Synced at
+     * pointerup, a raise moved the window between the press and its click, so
+     * a control in a background window (a checkbox in a palette under another
+     * palette) got its press and release but never its click: it looked
+     * pressed and never acted. Not a microtask either — that runs between the
+     * listeners of the same dispatch, still ahead of the click. A task runs
+     * after the whole chain, the shape `deferActivation` (src/events.ts) falls
+     * back on for the same reason.
+     */
     private _requestDomSync;
     /**
      * Raise the window an event originated in, skipping the restack/activation
@@ -239,8 +258,9 @@ export declare class VfDesktop extends VfDesktop_base {
      * MUST NOT move nodes: moving the window focus just entered re-orders the
      * sequence mid-traversal, and a Shift+Tab that raises each window it
      * enters (pushing it forward in the DOM, back the way the traversal came)
-     * would revisit it forever. The pointer path syncs at gesture end instead,
-     * which is also the next safe point after any keyboard-session staleness.
+     * would revisit it forever. The pointer path schedules the sync at gesture
+     * end instead, which is also the next safe point after any keyboard-session
+     * staleness.
      */
     private _raise;
     /**
@@ -251,11 +271,11 @@ export declare class VfDesktop extends VfDesktop_base {
      */
     private _onPointerDown;
     /**
-     * The press ended (or was cancelled) — sync the DOM order. Unconditional
-     * rather than only-if-raised: the sync no-ops when order already agrees,
-     * and running it at every gesture end is what heals the staleness a
-     * keyboard-only stretch leaves behind (focus-driven raises change z but
-     * never move nodes — see {@link _raise}).
+     * The press ended (or was cancelled) — schedule the DOM-order sync.
+     * Unconditional rather than only-if-raised: the sync no-ops when order
+     * already agrees, and running it after every gesture is what heals the
+     * staleness a keyboard-only stretch leaves behind (focus-driven raises
+     * change z but never move nodes — see {@link _raise}).
      */
     private _onGestureEnd;
     /**
@@ -311,8 +331,9 @@ export declare class VfDesktop extends VfDesktop_base {
      * element drops focus to `<body>`, so it is restored afterwards — behind
      * `_restoringFocus`, because the restore re-fires focusin (see
      * {@link _onFocusIn}) on an element that may sit in a background window.
-     * Only runs between pointer gestures or programmatically, never from a
-     * focus-driven raise (see {@link _raise} for why).
+     * Reached only through {@link _requestDomSync}'s task — after a pointer
+     * gesture or a programmatic raise, never from a focus-driven one (see
+     * {@link _raise} for why).
      */
     private _syncDomOrder;
     protected willUpdate(changed: PropertyValues<this>): void;

package/dist/components/vf-desktop.js

@@ -23,7 +23,7 @@ var A = 1e6, j = 2 * A, M = 512, N = 342, P = "gray-50", F = p(d[P], "#000000",
 				width: this.width ?? M,
 				height: this.height ?? N
 			})
-		}), this._zCounter = 0, this._activeWindow = null, this._deactivated = !1, this._awaitingUpgrade = !1, this._pointerGesture = !1, this._restoringFocus = !1, this._gestureEnd = new b(this, () => [[
+		}), this._zCounter = 0, this._activeWindow = null, this._deactivated = !1, this._awaitingUpgrade = !1, this._pointerGesture = !1, this._restoringFocus = !1, this._domSyncTimer = 0, this._gestureEnd = new b(this, () => [[
 			document,
 			"pointerup",
 			this._onGestureEnd,
@@ -38,7 +38,7 @@ var A = 1e6, j = 2 * A, M = 512, N = 342, P = "gray-50", F = p(d[P], "#000000",
 			let t = this._windowFromEvent(e);
 			t && this._raise(t);
 		}, this._onGestureEnd = () => {
-			this._gestureEnd.detach(), this._pointerGesture = !1, this._syncDomOrder();
+			this._gestureEnd.detach(), this._pointerGesture = !1, this._requestDomSync();
 		}, this._onFocusIn = (e) => {
 			if (this._restoringFocus) return;
 			let t = this._windowFromEvent(e);
@@ -185,7 +185,7 @@ var A = 1e6, j = 2 * A, M = 512, N = 342, P = "gray-50", F = p(d[P], "#000000",
 		super.connectedCallback(), this.addEventListener("pointerdown", this._onPointerDown), this.addEventListener("focusin", this._onFocusIn);
 	}
 	disconnectedCallback() {
-		this.removeEventListener("pointerdown", this._onPointerDown), this.removeEventListener("focusin", this._onFocusIn), this._pointerGesture = !1, super.disconnectedCallback();
+		this.removeEventListener("pointerdown", this._onPointerDown), this.removeEventListener("focusin", this._onFocusIn), this._pointerGesture = !1, this._domSyncTimer &&= (clearTimeout(this._domSyncTimer), 0), super.disconnectedCallback();
 	}
 	_isUtility(e) {
 		return e.getAttribute("variant") === "utility";
@@ -204,7 +204,9 @@ var A = 1e6, j = 2 * A, M = 512, N = 342, P = "gray-50", F = p(d[P], "#000000",
 		e.style.zIndex = String(++this._zCounter + (t ? A : 0)), t || this._setActive(e);
 	}
 	_requestDomSync() {
-		this._pointerGesture || this._syncDomOrder();
+		this._pointerGesture || this._domSyncTimer || (this._domSyncTimer = window.setTimeout(() => {
+			this._domSyncTimer = 0, this._pointerGesture || this._syncDomOrder();
+		}, 0));
 	}
 	_raise(e) {
 		let t = this._isUtility(e), n = this._windows.filter((e) => this._isUtility(e) === t);

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

@@ -23,7 +23,9 @@ import './vf-button-group.js';
  * Open it with `show()` (or set the `open` attribute/property); close with
  * `close()`. Escape closes it and fires `vf-close` with
  * `{ reason: 'escape' }`; the close box and programmatic closing fire
- * `{ reason: 'close' }`.
+ * `{ reason: 'close' }`. With `light-dismiss`, a click outside the frame
+ * closes it too, with `{ reason: 'outside' }` — for the About box; off by
+ * default, since the classic modal ignored an outside click.
  *
  * @slot - Default slot: dialog body content.
  * @slot buttons - Optional action buttons. Rendered as a bottom-right
@@ -40,7 +42,8 @@ import './vf-button-group.js';
  *   scrolls under a System 7 rail and becomes a keyboard stop.
  * @csspart footer - The action row wrapping the buttons.
  * @csspart buttons - The button group inside the footer.
- * @fires vf-close - Dialog closed. Detail `{ reason: 'escape' | 'close' }`.
+ * @fires vf-close - Dialog closed. Detail `{ reason: 'escape' | 'close' |
+ *   'outside' }` — `'outside'` only under `light-dismiss`.
  * @cssprop --vf-dots-pattern - the windoid bar's dot-grid dither — a 2×2 tile,
  *   one black pixel at the origin (`vfDots`; override the whole pattern like
  *   `--vf-desktop-pattern`)

package/dist/modal-dialog.d.ts

@@ -1,8 +1,12 @@
 import { LitElement } from 'lit';
 import type { PropertyValues } from 'lit';
 import { ScaleController } from './scale.js';
-/** Reason a modal closed, carried by the `vf-close` event's detail. */
-export type VfCloseReason = 'escape' | 'close';
+/**
+ * Reason a modal closed, carried by the `vf-close` event's detail: the Escape
+ * key, the close box or `close()`, or — with {@link VfModalDialog.lightDismiss}
+ * — a click outside the frame.
+ */
+export type VfCloseReason = 'escape' | 'close' | 'outside';
 /**
  * The width an undeclared modal falls back to, in system px — a classic
  * dialog's own measure, wide enough for a line of chrome text and a button row.
@@ -23,9 +27,10 @@ export declare const modalDialogStyles: import("lit").CSSResult;
  * Owns the native `<dialog>` lifecycle every modal shares: `open` sync, `show()` /
  * `close()`, the {@link top}/{@link left} placement (stated or centered) and the
  * single `close` funnel that drops the written origin and fires `vf-close` with
- * the reason. Because every close path — Escape, `close()`, backdrop — routes
- * through the native `close` event, an Escape-close no longer leaves a stale
- * origin behind, so the next open re-derives it.
+ * the reason. Because every close path — Escape, `close()`, the opt-in
+ * {@link lightDismiss} click outside — routes through the native `close`
+ * event, an Escape-close no longer leaves a stale origin behind, so the next
+ * open re-derives it.
  *
  * Removing an open modal from the DOM is a close path too. HTML's dialog
  * *removing steps* take the element out of the top layer **without** running
@@ -42,7 +47,8 @@ export declare const modalDialogStyles: import("lit").CSSResult;
  * `<dialog @cancel=${this._onNativeCancel} @close=${this._onNativeClose}>` with
  * their role/ARIA and body, and {@link modalDialogStyles} in `static styles`.
  *
- * @fires vf-close - The modal closed. `detail: { reason: 'escape' | 'close' }`.
+ * @fires vf-close - The modal closed. `detail: { reason: 'escape' | 'close' |
+ *   'outside' }`.
  */
 export declare class VfModalDialog extends LitElement {
     #private;
@@ -94,6 +100,22 @@ export declare class VfModalDialog extends LitElement {
     top?: number | null;
     /** Offset from the left of the viewport, in whole system px. See {@link top}. */
     left?: number | null;
+    /**
+     * Close on a click outside the frame — a press on the backdrop — and fire
+     * `vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal
+     * ignored an outside click (and beeped), and a dialog that asks a question
+     * should keep ignoring it. Opt in for the About box and the splash, the
+     * dialogs the classic Mac did dismiss on a click.
+     *
+     * Both halves of the click have to land outside — the two-step the
+     * platform's own `closedby="any"` light dismiss uses — so a press that
+     * starts on a control and slides off the frame, or a title-bar drag
+     * released past it, leaves the dialog open. The press is consumed either
+     * way: a modal's backdrop lets nothing beneath it see the click, so
+     * dismissing the About box does not also select whatever was under the
+     * pointer. Escape closes the dialog regardless, as it always has.
+     */
+    lightDismiss: boolean;
     protected _dialog: HTMLDialogElement;
     /**
      * The declared box as inline styles for the subclass's `<dialog>`:

package/dist/modal-dialog.js

@@ -1,9 +1,10 @@
 import { emit as e } from "./events.js";
 import { ScaleController as t, onScaleChange as n, snapSys as r, sysLength as i, toSysExact as a } from "./scale.js";
 import o from "./_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
-import { LitElement as s, css as c } from "lit";
-import { property as l, query as u } from "lit/decorators.js";
-var d = 24, f = c`
+import { DocumentListenersController as s } from "./document-listeners.js";
+import { LitElement as c, css as l } from "lit";
+import { property as u, query as d } from "lit/decorators.js";
+var f = 24, p = l`
   dialog {
     padding: 0;
     margin: auto;
@@ -42,9 +43,32 @@ var d = 24, f = c`
        the fallback is the arrow it always showed. */
     cursor: var(--vf-cursor, default);
   }
-`, p = class extends s {
+`, m = class extends c {
 	constructor(...e) {
-		super(...e), this.scale = new t(this), this.open = !1, this.#e = !1, this.#n = null, this.#r = null, this.#l = () => this.settle();
+		super(...e), this.scale = new t(this), this.open = !1, this.lightDismiss = !1, this.#e = !1, this.#n = null, this.#r = null, this.#i = new s(this, () => [
+			[
+				this._dialog,
+				"pointerdown",
+				this.#a
+			],
+			[
+				this._dialog,
+				"pointerup",
+				this.#o
+			],
+			[
+				this._dialog,
+				"pointercancel",
+				this.#s
+			]
+		]), this.#a = (e) => {
+			this.#r = e.target === this._dialog ? e.pointerId : null;
+		}, this.#o = (e) => {
+			let t = this.#r === e.pointerId;
+			this.#r = null, !(!t || e.target !== this._dialog || !this.lightDismiss) && (this.#n = "outside", this.close());
+		}, this.#s = () => {
+			this.#r = null;
+		}, this.#c = null, this.#m = () => this.settle();
 	}
 	get dialogSize() {
 		return {
@@ -63,38 +87,43 @@ var d = 24, f = c`
 	}
 	#n;
 	#r;
+	#i;
+	#a;
+	#o;
+	#s;
+	#c;
 	show() {
-		this.open = !0, this.hasUpdated && this.#c();
+		this.open = !0, this.hasUpdated && this.#p();
 	}
 	close() {
-		this.open = !1, this.hasUpdated && this.#c();
+		this.open = !1, this.hasUpdated && this.#p();
 	}
 	updated(e) {
-		e.has("open") && this.#c(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
+		e.has("open") && this.#p(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
 	}
-	#i() {
+	#l() {
 		let e = document.documentElement;
 		return {
 			width: a(e.clientWidth || window.innerWidth, this),
 			height: a(e.clientHeight || window.innerHeight, this)
 		};
 	}
-	#a(e, t) {
-		let n = this.#i(), r = a(this._dialog?.offsetWidth ?? 0, this);
+	#u(e, t) {
+		let n = this.#l(), r = a(this._dialog?.offsetWidth ?? 0, this);
 		return {
-			x: Math.min(Math.max(e, d - r), n.width - d),
-			y: Math.min(Math.max(t, 0), Math.max(0, n.height - d))
+			x: Math.min(Math.max(e, f - r), n.width - f),
+			y: Math.min(Math.max(t, 0), Math.max(0, n.height - f))
 		};
 	}
-	#o() {
-		let e = this.#i(), t = this._dialog?.getBoundingClientRect();
+	#d() {
+		let e = this.#l(), t = this._dialog?.getBoundingClientRect();
 		return {
 			x: (e.width - a(t?.width ?? 0, this)) / 2,
 			y: (e.height - a(t?.height ?? 0, this)) / 2
 		};
 	}
 	placeAt(e, t) {
-		let n = this.#a(e, t);
+		let n = this.#u(e, t);
 		this.left = r(n.x, this), this.top = r(n.y, this);
 	}
 	settle() {
@@ -103,10 +132,10 @@ var d = 24, f = c`
 		let t = this.left != null || this.top != null ? {
 			x: this.left ?? 0,
 			y: this.top ?? 0
-		} : this.#o(), n = this.#a(t.x, t.y);
+		} : this.#d(), n = this.#u(t.x, t.y);
 		e.style.left = i(r(n.x, this)), e.style.top = i(r(n.y, this)), e.style.right = "auto", e.style.bottom = "auto", e.style.margin = "0";
 	}
-	#s() {
+	#f() {
 		let e = this._dialog?.style;
 		if (e) for (let t of [
 			"left",
@@ -116,40 +145,44 @@ var d = 24, f = c`
 			"margin"
 		]) e.removeProperty(t);
 	}
-	#c() {
+	#p() {
 		let e = this._dialog;
-		e && (this.open && !e.open ? (this.#r = document.activeElement, e.showModal(), this.settle(), this.#f(e)) : !this.open && e.open && e.close());
+		e && (this.open && !e.open ? (this.#c = document.activeElement, e.showModal(), this.settle(), this.#_(e), this.#i.attach()) : !this.open && e.open && e.close());
 	}
-	#l;
-	#u;
-	#d;
-	#f(e) {
-		typeof ResizeObserver < "u" && !this.#u && (this.#u = new ResizeObserver(this.#l), this.#u.observe(e)), window.addEventListener("resize", this.#l), this.#d ??= n(this.#l);
+	#m;
+	#h;
+	#g;
+	#_(e) {
+		typeof ResizeObserver < "u" && !this.#h && (this.#h = new ResizeObserver(this.#m), this.#h.observe(e)), window.addEventListener("resize", this.#m), this.#g ??= n(this.#m);
 	}
-	#p() {
-		this.#u?.disconnect(), this.#u = void 0, window.removeEventListener("resize", this.#l), this.#d?.(), this.#d = void 0;
+	#v() {
+		this.#h?.disconnect(), this.#h = void 0, window.removeEventListener("resize", this.#m), this.#g?.(), this.#g = void 0;
 	}
 	disconnectedCallback() {
-		super.disconnectedCallback(), this.#p();
+		super.disconnectedCallback(), this.#v();
 		let e = this._dialog;
 		if (e?.open) {
 			e.close();
-			let t = this.#r, n = document.activeElement;
+			let t = this.#c, n = document.activeElement;
 			t instanceof HTMLElement && t.isConnected && (n === null || n === document.body) && t.focus();
 		}
-		this.#r = null;
+		this.#c = null;
 	}
 	_onNativeCancel() {
 		this.#n = "escape";
 	}
 	_onNativeClose() {
 		let t = this.#n ?? "close";
-		this.#n = null, this.#r = null, this.#p(), this.open = !1, this.#s(), e(this, "vf-close", { reason: t });
+		this.#n = null, this.#c = null, this.#r = null, this.#i.detach(), this.#v(), this.open = !1, this.#f(), e(this, "vf-close", { reason: t });
 	}
 };
-o([l({
+o([u({
 	type: Boolean,
 	reflect: !0
-})], p.prototype, "open", void 0), o([l({ type: Number })], p.prototype, "width", void 0), o([l({ type: Number })], p.prototype, "height", void 0), o([l({ type: Number })], p.prototype, "top", void 0), o([l({ type: Number })], p.prototype, "left", void 0), o([u("dialog")], p.prototype, "_dialog", void 0);
+})], m.prototype, "open", void 0), o([u({ type: Number })], m.prototype, "width", void 0), o([u({ type: Number })], m.prototype, "height", void 0), o([u({ type: Number })], m.prototype, "top", void 0), o([u({ type: Number })], m.prototype, "left", void 0), o([u({
+	type: Boolean,
+	reflect: !0,
+	attribute: "light-dismiss"
+})], m.prototype, "lightDismiss", void 0), o([d("dialog")], m.prototype, "_dialog", void 0);
 //#endregion
-export { p as VfModalDialog, f as modalDialogStyles };
+export { m as VfModalDialog, p as modalDialogStyles };

package/docs/SPEC.md

@@ -199,7 +199,7 @@ Full-bleed classic desktop container.
 - **Visual:** `display: block; position: relative;` — the paint lives on an inner screen surface (part `desktop`, `overflow: hidden` — the whole-system-px raster, inset by `bezel` when one is set). Screen surface = the `pattern` (the classic 50% dither, `gray-50`, by default), painted as the screen's own background by the pattern fill (*Patterns* under *Tiled fills*): black ink on the fill's opaque `--vf-white` paper, one whole-surface raster — the authentic black-on-white dither. A consumer `--vf-desktop-pattern` renders instead as a placed tile grid on the token's 30-system-px tile with no paper, so `var(--vf-desktop, #808080)` beneath shows only under a custom tile with transparent cells (or `none`). Forced colors: flat Canvas.
 - **Slots:** default (menu bar, windows, anything).
 - **Behavior:** manages stacking of slotted `vf-window` children: `pointerdown` *or `focusin`* on a window brings it to front (incrementing z-index counter) and sets its `active` attribute, clearing `active` on the others — the `focusin` half is the keyboard route to activation: Tab landing anywhere in a background window (its undrawn-but-focusable widgets included) raises it. Listens via delegated pointerdown/focusin listeners + `slotchange`. Windows slotted before `vf-window` is defined are re-normalized once `customElements.whenDefined('vf-window')` settles, since the upgrade reflects each window's `active = true` default back out and upgrading a slotted node doesn't re-fire `slotchange`.
-  - **DOM order follows z-order** (bottom-most first), so sequential focus order matches the visual stack and Shift+Tab mirrors Tab exactly. The sync runs at pointer-gesture end (a mid-gesture node move would clear the pointer capture a title-bar drag or grow-box resize holds) and on programmatic `bringToFront`, never from a focus-driven raise (moving the window focus just entered would re-order the tab sequence mid-traversal); focus surviving its own window's move is restored without re-raising that window. Non-window children (a menu bar, page content) keep their positions. `npm run verify:window-a11y`.
+  - **DOM order follows z-order** (bottom-most first), so sequential focus order matches the visual stack and Shift+Tab mirrors Tab exactly. The sync runs in a task after a pointer gesture ends, or after a programmatic `bringToFront` — never mid-gesture (a node move would clear the pointer capture a title-bar drag or grow-box resize holds), never between a press's release and its `click` (Chromium drops a click whose mousedown node was re-inserted first, which used to cost a control in a background window its click), and never from a focus-driven raise (moving the window focus just entered would re-order the tab sequence mid-traversal); focus surviving its own window's move is restored without re-raising that window. Non-window children (a menu bar, page content) keep their positions. `npm run verify:window-a11y`.
   - **Floating tier:** `vf-window[variant="utility"]` children stack in a z band `1_000_000` above the document tier (one shared monotonic counter, so a palette stays above every document window), restack only among themselves, and stand outside the single-active invariant both ways: clicking a palette doesn't deactivate the active document window, and activating a document window never clears a palette's `active` — System 7 windoid behavior while the app is frontmost. The tier test reads the `variant` *attribute*, so a not-yet-upgraded element still lands right.
   - **Menu tier:** a slotted `vf-menu-bar` — or a free-standing `vf-menu` placed on the desktop — is restated at `z-index: 2_000_000` by the desktop's own `::slotted(vf-menu-bar), ::slotted(vf-menu)` rule (an outer-tree `::slotted` declaration beats the bar's inner `:host { z-index: 1000 }`), a band above the floating tier, so a dropped menu paints over palettes and document windows alike — the Menu Manager drew menus over every window. Only the screen-corner mask is in front. The full stack inside the screen's isolated context: consumer tile grid (−1) < document windows (counter) < utility windows (counter + 1_000_000) < menu tier (2_000_000) < corner mask (max). A popup *inside* a window (`vf-select`'s fixed panel) is a different case: it stacks within its window's context, so a palette can still cover it — KNOWN-BUGS.md. `npm run verify:archetypes` (MENU TIER).
   - **Deactivation:** on a real System 7 machine clicking the desktop clicked the *Finder* — the frontmost application's windows lost their stripes. `clearActive()` is that gesture's handler: it clears `active` from the whole document tier, and **zero active windows is a legal state**, held until a press or `focusin` re-enters a document window or a new one is slotted (opening a window brings its application forward — a newly slotted window ends a deliberate deactivation, where a mere survivor never does: removing a *background* window while deactivated promotes nothing, while removing the holder outside a deactivation promotes the topmost survivor). The desktop never takes the decision itself — a press on its own bare dither changes nothing; desktop furniture is slotted light DOM, so only the page knows which of its children mean "the Finder". Utility windows keep their `active` through a deactivation (their dots stay drawn). Every change of holder — window to window, window to none, none to window — fires `vf-activate`, once per change; re-asserting the current holder is silent. `npm run verify:desktop-activate`.
@@ -227,15 +227,15 @@ The desktop-window shell: the classic document window (see DragThing screenshot)
 
 #### `vf-dialog` (`VfDialog`, vf-dialog.ts)
 The modal-dialog shell: movable modal by default (the dBoxProc double frame with the striped title bar set into it — traced from a 2× System 7 capture of a movable modal), the modal dialog box with `frame="plain"` (the bare double frame; see the Group A recipe table).
-- **Attributes/props:** `open: boolean` (reflect), `heading: string`, `top: number` / `left: number` (whole system px, in **viewport** coordinates — see §1 Explicit placement; unset means centered), `width: number` / `height: number` (**declare them both** — whole system px, the same fixed box `vf-window` is. A native `<dialog>` is `width: fit-content` measured against the space left beside its own offsets, and stating an offset is how the movable modal is positioned, so an undeclared dialog squeezes itself and reflows as it is dragged toward an edge. The two fall back differently — width to 260 system px, height to the content — and it names whichever are missing, once, on the open that first shows it), `label: string` (accessible name for a dialog with no `heading`), `closable: boolean` (default **false** — the bare movable-modal bar; the close box is opt-in because the HIG's Chapter 6 text denies a movable modal one while its Figure 5-1 grants it — the parameter enables either reading), `frame?: 'plain'`.
-- **Implementation:** wraps a native `<dialog>` (for top-layer + focus trap). `show()` → `showModal()`; `close()` closes. Keep `open` attr in sync both directions. Drag the title bar to move it (shared `DragController` with `vf-window`), stating `top`/`left` in system px; drags starting on the close widget are ignored (same composedPath guard as `vf-window`). Escape → close + `vf-close` detail `{ reason: 'escape' }`; close box/programmatic/close() → `{ reason: 'close' }`. No backdrop dimming: `::backdrop { background: transparent; }`. **Removal while open is a close path** (`VfModalDialog.disconnectedCallback`): HTML's dialog removing steps skip the close algorithm entirely, which is exactly what a framework unmount does — the teardown routes through the same native-`close` funnel (`vf-close` fires on the removed element; nothing bubbles, it left the tree), `open` and the written origin reconcile so a re-append mounts closed, and focus returns to the element focused at open time. **The placement re-settles while open** whenever the dialog's own box resizes — slotted content upgrading after `showModal()`, `--vf-scale` moving under zoom — the viewport resizes, or the scale changes. What survives depends on how the modal got where it is: an unplaced one re-centers (it never claimed a spot, and the stranded case is exactly this one), while a dragged or authored origin is kept and only re-clamped on screen.
+- **Attributes/props:** `open: boolean` (reflect), `heading: string`, `top: number` / `left: number` (whole system px, in **viewport** coordinates — see §1 Explicit placement; unset means centered), `width: number` / `height: number` (**declare them both** — whole system px, the same fixed box `vf-window` is. A native `<dialog>` is `width: fit-content` measured against the space left beside its own offsets, and stating an offset is how the movable modal is positioned, so an undeclared dialog squeezes itself and reflows as it is dragged toward an edge. The two fall back differently — width to 260 system px, height to the content — and it names whichever are missing, once, on the open that first shows it), `label: string` (accessible name for a dialog with no `heading`), `closable: boolean` (default **false** — the bare movable-modal bar; the close box is opt-in because the HIG's Chapter 6 text denies a movable modal one while its Figure 5-1 grants it — the parameter enables either reading), `light-dismiss: boolean` (`lightDismiss`; default **false** — a click outside the frame closes the dialog with `vf-close` reason `'outside'`. Off by default because the classic modal ignored an outside click, and a dialog that asks a question should keep ignoring it; opt in for the About box and the splash, which the classic Mac did dismiss on a click. Reflected, and read at the release, so it can be toggled on an open dialog), `frame?: 'plain'`.
+- **Implementation:** wraps a native `<dialog>` (for top-layer + focus trap). `show()` → `showModal()`; `close()` closes. Keep `open` attr in sync both directions. Drag the title bar to move it (shared `DragController` with `vf-window`), stating `top`/`left` in system px; drags starting on the close widget are ignored (same composedPath guard as `vf-window`). Escape → close + `vf-close` detail `{ reason: 'escape' }`; close box/programmatic/close() → `{ reason: 'close' }`; a click outside under `light-dismiss` → `{ reason: 'outside' }`. No backdrop dimming: `::backdrop { background: transparent; }`. **Light dismiss is target identity, not geometry** (`VfModalDialog`): the `::backdrop` hit-tests as its `<dialog>`, and the frame fills the dialog's box, so the dialog is a pointer event's *target* exactly when the pointer was outside the frame — the listeners sit on the `<dialog>` itself, attached while open. It takes both halves of the click: a `pointerdown` on the backdrop arms (any other press disarms, so a right-click macOS never releases can't leave a stale arm), and a `pointerup` on the backdrop with the same `pointerId` closes — the platform's own `closedby="any"` two-step, so a press that starts on a control and slides off, or a title-bar drag released past the frame, leaves the dialog open. Deliberately not the `click` event: UI Events dispatches a press-drag-release click at the common ancestor of the two targets, which for a press on the frame released outside is the dialog itself. The platform's `closedby` attribute is not used because its dismissal arrives as `cancel`, which the base already reads as Escape. The press is consumed either way — a modal's backdrop lets nothing beneath it see the click — which is what lets a page dismiss its About box without also selecting the icon under the pointer. `npm run verify:dialog`. **Removal while open is a close path** (`VfModalDialog.disconnectedCallback`): HTML's dialog removing steps skip the close algorithm entirely, which is exactly what a framework unmount does — the teardown routes through the same native-`close` funnel (`vf-close` fires on the removed element; nothing bubbles, it left the tree), `open` and the written origin reconcile so a re-append mounts closed, and focus returns to the element focused at open time. **The placement re-settles while open** whenever the dialog's own box resizes — slotted content upgrading after `showModal()`, `--vf-scale` moving under zoom — the viewport resizes, or the scale changes. What survives depends on how the modal got where it is: an unplaced one re-centers (it never claimed a spot, and the stranded case is exactly this one), while a dragged or authored origin is kept and only re-clamped on screen.
 - **Visual (default chrome):** `vfModalFrame` with `vfTitleBar` set into it (§4) — the bar is literally the recipe `vf-window` uses, so it is identical by construction (stripes + centered title) rather than by matching copies; the frame is the modal double frame, **not** the window's shadowed `vfChromeFrame`. Outside → in: 1px outer rule; the 18px bar directly under it, 2px in at either end with its stripes starting 2px from the rule; the 2px band as the bar's floor (the bar's rule + the inner box's 1px top border); 2px gap + 2px band down the sides and along the bottom; no shadow. The body begins 20px below the dialog's top and 5px inside its other three edges. The bar takes the default `--vf-title-inset` (16px) — 60px when `closable`, the same clearance as `vf-window`, since the centered title needs symmetric room for the widget — and sets `touch-action: none` unconditionally, having no immovable state. `closable` renders the shared close box (`vfWindowWidgets` + `closeBox()` — byte-identical to `vf-window`'s, per the `moveable modal dialog.png` reference). Body is WHITE (`--vf-surface: #fff`), `padding: 16px`. An optional `buttons` slot renders a bottom-right `vf-button-group` footer that only takes space when populated (equal-width, faces aligned). Both chromes are full-height flex columns and the body takes the slack, for the same reason `vf-window`'s frame is: the declared `height` lands on the `<dialog>` (see `dialogSize`), and the recipes are skin only. The frame is the flex child of the `<dialog>` itself (`dialog[open]` is a flex column in `modalDialogStyles` — `[open]`-scoped, or it would out-cascade the UA's `dialog:not([open]) { display: none }`), not a `height: 100%` block: a percentage can't resolve against the undeclared-height dialog that only the UA's `dialog:modal` max-height caps, and that spill was how a viewport-tall modal stranded its buttons off-screen. **The box never grows, but over-stuffed content scrolls instead of clipping**: the body is a flex column of a `.content` scroll region (heading + default slot; part `content`) over the pinned footer. While the content fits, nothing matches — rendering is pixel-identical to the old block flow. Once it overflows (`ScrollStateController`, the always-a-rail machinery), the region reserves the 16px channel as its own right padding, wears the drawn `vfScrollRail` rail (§4) boxed by a 1px `.scroll-frame` overlay, and becomes a keyboard stop (`tabindex="0"`, `role="group"`, the kit's dotted ring) so the copy is scrollable without a pointer. The rail rides the wrapper as an overlay pinned to its right edge, deliberately out of the layout flow: a rail *column*'s two fixed 15px arrow cells would hand the region a 32px minimum height, and a short dialog would then measure as fitting with the rail shown and overflowing without it — flip-flopping forever. The drop-open exemption is unchanged.
   - **The CSS and the controller state the same thing.** `.content` is `overflow-y: hidden` until the controller flags overflow, then `overflow-y: scroll`. It is deliberately never `auto`: the controller ignores the body face's negative half-leading (`LEADING_SPILL_SYS`, src/scroll-state.ts — `vf-paragraph` sets a 12-system-px line box under a 16-system-px em, so the inline box spills 2 inkless system px past the block box and `scrollHeight` counts it), and `auto` has no way to know that. With `auto` the two disagreed, and a fixed info dialog whose copy ends in a `vf-paragraph` rubber-banded under the wheel with no rail shown — 6 CSS px at scale 3. `hidden` still scrolls programmatically, so `scrollIntoView` on a focused control is unaffected. `npm run verify:contract`, OVERFLOW group.
 - **Visual (`frame="plain"`):** the same `vfModalFrame` (§4 — 1px outer, 2px gap, 2px inner band, no shadow, per `Windows/modal dialog.png`) with no title bar, and immovable like the original dBoxProc dialog (nothing renders a drag handle). The body begins 5px inside every edge. A `heading` renders as a centered display-face heading at the top of the body (`margin-bottom: 16px`) — the way those dialogs drew their title in content — and `closable` is ignored, there being no bar to carry the widget.
 - **A11y:** named by its own title patch — or, on the plain frame, its body-top heading; both carry `id="title"` — via `aria-labelledby` when `heading` is set. With no heading there is nothing to point at — `aria-labelledby` would resolve to an empty node and leave the dialog unnamed — so it falls back to `aria-label`, taking `label` if given and otherwise `'Dialog'`. An explicit `label` wins over `heading`. The close box is labeled `Close ${heading}` like `vf-window`'s.
 - **Slots:** default, `buttons`.
 - **Parts:** `frame`, `title-bar` (default chrome), `title`, `close-box` (when `closable`), `body`, `content`, `footer`, `buttons`.
-- **Events:** `vf-close`.
+- **Events:** `vf-close` (detail `{ reason: 'escape' | 'close' | 'outside' }`).
 
 #### The alert box (composed — no component)
 System 7's fixed modal alert (double frame: 2px outer, 2px gap, 1px inner rule, *with* the hard shadow) is deliberately not shipped as a component. What separates an alert from a modal dialog is a *picture* — the 32×32 icon — and pictures are the consumer's assets, never the library's (see the glyph-sprites note at the top of this spec). An alert box is composed from the shells above: `vf-dialog frame="plain"` with `label` stated (there is no title bar to name it), a row `vf-stack` slotting the consumer's own 32×32 art through `vf-img`, display-face copy (System 7 alerts used chrome type), and the `buttons` slot. The reference page carries the live recipe, composed from `demo/icons/alert.png`.

package/editor/vscode.html-custom-data.json

@@ -191,7 +191,7 @@
     },
     {
       "name": "vf-desktop",
-      "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, at pointer-gesture\nends), so tabbing walks the stack the way the eye does and Shift+Tab is\nits 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`).\n---\n\n\n### **Events:**\n - **vf-activate** - The active document-tier window changed. Detail `{ window: HTMLElement | null }` — the new holder, or `null` when the document tier deactivated (a {@link clearActive} call, or the active window leaving the DOM with none behind it). Fired once per change of holder, never for a re-assertion of the same one.\n\n### **Slots:**\n - _default_ - Default slot: menu bar, windows, anything.\n\n### **CSS Properties:**\n - **--vf-desktop** - base color under the desktop pattern — occluded by the pattern's opaque paper, so it only shows through a custom `--vf-desktop-pattern` _(default: #808080)_\n- **--vf-desktop-pattern** - a consumer's own desktop tile, in place of `pattern` — the kit's default is the 50% checker drawn as opaque black-on-white rects on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom) _(default: undefined)_\n\n### **CSS Parts:**\n - **desktop** - The patterned screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
+      "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`).\n---\n\n\n### **Events:**\n - **vf-activate** - The active document-tier window changed. Detail `{ window: HTMLElement | null }` — the new holder, or `null` when the document tier deactivated (a {@link clearActive} call, or the active window leaving the DOM with none behind it). Fired once per change of holder, never for a re-assertion of the same one.\n\n### **Slots:**\n - _default_ - Default slot: menu bar, windows, anything.\n\n### **CSS Properties:**\n - **--vf-desktop** - base color under the desktop pattern — occluded by the pattern's opaque paper, so it only shows through a custom `--vf-desktop-pattern` _(default: #808080)_\n- **--vf-desktop-pattern** - a consumer's own desktop tile, in place of `pattern` — the kit's default is the 50% checker drawn as opaque black-on-white rects on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom) _(default: undefined)_\n\n### **CSS Parts:**\n - **desktop** - The patterned screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
       "attributes": [
         {
           "name": "width",
@@ -228,7 +228,7 @@
     },
     {
       "name": "vf-dialog",
-      "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' }`.\n---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' }`.\n\n### **Slots:**\n - _default_ - Default slot: dialog body content.\n- **buttons** - Optional action buttons. Rendered as a bottom-right `vf-button-group` (equal-width, faces aligned); the footer only takes space when the slot is populated.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (or the plain-frame heading).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content area.\n- **content** - The scrolling region inside the body (heading + slotted content, not the footer). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.\n- **footer** - The action row wrapping the buttons.\n- **buttons** - The button group inside the footer.",
+      "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---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`.\n\n### **Slots:**\n - _default_ - Default slot: dialog body content.\n- **buttons** - Optional action buttons. Rendered as a bottom-right `vf-button-group` (equal-width, faces aligned); the footer only takes space when the slot is populated.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (or the plain-frame heading).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content area.\n- **content** - The scrolling region inside the body (heading + slotted content, not the footer). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.\n- **footer** - The action row wrapping the buttons.\n- **buttons** - The button group inside the footer.",
       "attributes": [
         {
           "name": "heading",
@@ -274,6 +274,11 @@
           "name": "left",
           "description": "Offset from the left of the viewport, in whole system px. See top.",
           "values": []
+        },
+        {
+          "name": "light-dismiss",
+          "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+          "values": []
         }
       ],
       "references": []

package/editor/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "vintage-frames",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -457,7 +457,7 @@
         },
         {
           "name": "vf-desktop",
-          "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, at pointer-gesture\nends), so tabbing walks the stack the way the eye does and Shift+Tab is\nits 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`).\n---\n\n\n### **Events:**\n - **vf-activate** - The active document-tier window changed. Detail `{ window: HTMLElement | null }` — the new holder, or `null` when the document tier deactivated (a {@link clearActive} call, or the active window leaving the DOM with none behind it). Fired once per change of holder, never for a re-assertion of the same one.\n\n### **Slots:**\n - _default_ - Default slot: menu bar, windows, anything.\n\n### **CSS Properties:**\n - **--vf-desktop** - base color under the desktop pattern — occluded by the pattern's opaque paper, so it only shows through a custom `--vf-desktop-pattern` _(default: #808080)_\n- **--vf-desktop-pattern** - a consumer's own desktop tile, in place of `pattern` — the kit's default is the 50% checker drawn as opaque black-on-white rects on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom) _(default: undefined)_\n\n### **CSS Parts:**\n - **desktop** - The patterned screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
+          "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`).\n---\n\n\n### **Events:**\n - **vf-activate** - The active document-tier window changed. Detail `{ window: HTMLElement | null }` — the new holder, or `null` when the document tier deactivated (a {@link clearActive} call, or the active window leaving the DOM with none behind it). Fired once per change of holder, never for a re-assertion of the same one.\n\n### **Slots:**\n - _default_ - Default slot: menu bar, windows, anything.\n\n### **CSS Properties:**\n - **--vf-desktop** - base color under the desktop pattern — occluded by the pattern's opaque paper, so it only shows through a custom `--vf-desktop-pattern` _(default: #808080)_\n- **--vf-desktop-pattern** - a consumer's own desktop tile, in place of `pattern` — the kit's default is the 50% checker drawn as opaque black-on-white rects on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom) _(default: undefined)_\n\n### **CSS Parts:**\n - **desktop** - The patterned screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
           "doc-url": "",
           "attributes": [
             {
@@ -554,7 +554,7 @@
         },
         {
           "name": "vf-dialog",
-          "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' }`.\n---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' }`.\n\n### **Slots:**\n - _default_ - Default slot: dialog body content.\n- **buttons** - Optional action buttons. Rendered as a bottom-right `vf-button-group` (equal-width, faces aligned); the footer only takes space when the slot is populated.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (or the plain-frame heading).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content area.\n- **content** - The scrolling region inside the body (heading + slotted content, not the footer). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.\n- **footer** - The action row wrapping the buttons.\n- **buttons** - The button group inside the footer.",
+          "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---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`.\n\n### **Slots:**\n - _default_ - Default slot: dialog body content.\n- **buttons** - Optional action buttons. Rendered as a bottom-right `vf-button-group` (equal-width, faces aligned); the footer only takes space when the slot is populated.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (or the plain-frame heading).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content area.\n- **content** - The scrolling region inside the body (heading + slotted content, not the footer). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.\n- **footer** - The action row wrapping the buttons.\n- **buttons** - The button group inside the footer.",
           "doc-url": "",
           "attributes": [
             {
@@ -601,6 +601,11 @@
               "name": "left",
               "description": "Offset from the left of the viewport, in whole system px. See top.",
               "value": { "type": "number | null | undefined" }
+            },
+            {
+              "name": "light-dismiss",
+              "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+              "value": { "type": "boolean", "default": "false" }
             }
           ],
           "slots": [
@@ -613,7 +618,7 @@
           "events": [
             {
               "name": "vf-close",
-              "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' }`."
+              "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`."
             }
           ],
           "js": {
@@ -662,12 +667,17 @@
                 "name": "left",
                 "description": "Offset from the left of the viewport, in whole system px. See top.",
                 "type": "number | null | undefined"
+              },
+              {
+                "name": "lightDismiss",
+                "description": "Close on a click outside the frame — a press on the backdrop — and fire\n`vf-close` with `{ reason: 'outside' }`. Off by default: the classic modal\nignored an outside click (and beeped), and a dialog that asks a question\nshould keep ignoring it. Opt in for the About box and the splash, the\ndialogs the classic Mac did dismiss on a click.\n\nBoth halves of the click have to land outside — the two-step the\nplatform's own `closedby=\"any\"` light dismiss uses — so a press that\nstarts on a control and slides off the frame, or a title-bar drag\nreleased past it, leaves the dialog open. The press is consumed either\nway: a modal's backdrop lets nothing beneath it see the click, so\ndismissing the About box does not also select whatever was under the\npointer. Escape closes the dialog regardless, as it always has.",
+                "type": "boolean"
               }
             ],
             "events": [
               {
                 "name": "vf-close",
-                "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' }`."
+                "description": "Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`."
               }
             ]
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintage-frames",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Lit web components that emulate the look and feel of classic Mac OS System 7",
   "type": "module",
   "license": "MIT",
@@ -73,6 +73,7 @@
     "probe:menus": "node scripts/probe-menu-scale.mjs",
     "verify:desktop": "node scripts/verify-desktop-upgrade.mjs",
     "verify:desktop-activate": "node scripts/verify-desktop-activate.mjs",
+    "verify:dialog": "node scripts/verify-dialog.mjs",
     "verify:list-focus": "node scripts/verify-list-focus.mjs",
     "verify:control-heights": "node scripts/verify-control-heights.mjs",
     "verify:list-typeahead": "node scripts/verify-list-typeahead.mjs",