vintage-frames 0.5.2 → 0.5.3

package/custom-elements.json

@@ -2845,7 +2845,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 +3129,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 +3213,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 +3547,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 +3651,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 +19785,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 +19843,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 +19903,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 +20149,7 @@
           ],
           "events": [
             {
-              "description": "The modal closed. `detail: { reason: 'escape' | 'close' }`.",
+              "description": "The modal closed. `detail: { reason: 'escape' | 'close' | 'outside' }`.",
               "name": "vf-close"
             }
           ],
@@ -20065,6 +20194,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-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

@@ -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

@@ -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.3",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -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.3",
   "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",