vintage-frames 0.17.0 → 0.18.0

package/custom-elements.json

@@ -3908,6 +3908,20 @@
                 "module": "src/modal-dialog.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "#opened",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the modal has opened since its last close was funneled: true from\nan open until `#funnelClose` runs for the close that ends it, which can be\nafter the native `<dialog>` has closed, while its `close` event is queued.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "show",
@@ -4095,7 +4109,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reconcile the native `<dialog>` with `open`. Opening states the origin —\nthe author's, or the centered one — onto the top-layer box; the UA's own\n`margin: auto` centering lands on a half pixel whenever viewport minus\ndialog is odd, which fringes all the 1-bit chrome inside. Closing just\ncalls `dialog.close()`, routing teardown through the native `close` event\nso _onNativeClose is the one place placement is cleared and\n`vf-close` is fired.",
+              "description": "Reconcile the native `<dialog>` with `open`. Opening states the origin —\nthe author's, or the centered one — onto the top-layer box; the UA's own\n`margin: auto` centering lands on a half pixel whenever viewport minus\ndialog is odd, which fringes all the 1-bit chrome inside. Closing just\ncalls `dialog.close()`, and the native `close` event runs the close funnel,\n`#funnelClose`, the one place placement is cleared and `vf-close` is\nfired.",
               "inheritedFrom": {
                 "name": "VfModalDialog",
                 "module": "src/modal-dialog.ts"
@@ -4152,7 +4166,7 @@
                   }
                 }
               ],
-              "description": "While open, watch everything that invalidates the placement: the dialog's\nown box changing (content upgrade/growth, and `--vf-scale` moving under a\nzoom or density change, since every metric resizes with it), the viewport\nresizing, and the scale itself — which the box alone would miss on a page\nthat pins `--vf-scale`, where a zoom moves the lattice without resizing\nanything. Undone in _onNativeClose / `disconnectedCallback`.",
+              "description": "While open, watch everything that invalidates the placement: the dialog's\nown box changing (content upgrade/growth, and `--vf-scale` moving under a\nzoom or density change, since every metric resizes with it), the viewport\nresizing, and the scale itself — which the box alone would miss on a page\nthat pins `--vf-scale`, where a zoom moves the lattice without resizing\nanything. Undone by the close funnel and `disconnectedCallback`.",
               "inheritedFrom": {
                 "name": "VfModalDialog",
                 "module": "src/modal-dialog.ts"
@@ -4196,7 +4210,22 @@
                   "text": "void"
                 }
               },
-              "description": "Native `close` — the single teardown funnel for every close path. Drops\nthe written origin so the next open re-derives it from the box it will\nactually have (a stated `top`/`left` is the author's or the user's and\nsurvives, and is re-applied by that open), syncs `open`, and fires\n`vf-close` with the reason and the value the close carried.",
+              "description": "Native `close`, which every close path ends in: syncs `open` and runs the\nclose funnel. An open that came before the event has run the funnel for\nthis close already, and the event passes.",
+              "inheritedFrom": {
+                "name": "VfModalDialog",
+                "module": "src/modal-dialog.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#funnelClose",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "The close funnel, the single teardown for every close path. Drops the\nwritten origin so the next open re-derives it from the box it will\nactually have (a stated `top`/`left` is the author's or the user's and\nsurvives, and is re-applied by that open), and fires `vf-close` with the\nreason and the value the close carried.",
               "inheritedFrom": {
                 "name": "VfModalDialog",
                 "module": "src/modal-dialog.ts"
@@ -24316,7 +24345,7 @@
         },
         {
           "kind": "class",
-          "description": "Base class for the modal shell `vf-dialog` — and for a consumer's own\nmodal (an alert box, say) authored against the kit.\n\nOwns the native `<dialog>` lifecycle every modal shares: `open` sync, `show()` /\n`close()`, the top/left placement (stated or centered) and the\nsingle `close` funnel that drops the written origin and fires `vf-close` with\nthe reason. Because every close path — Escape, `close()`, the opt-in\nlightDismiss click outside — routes through the native `close`\nevent, an Escape-close no longer leaves a stale origin behind, so the next\nopen re-derives it.\n\nIt also owns the two keyboard rules every classic dialog followed (see\ndefaultButton and initialFocusTarget): Return or Enter\nactivates the default button from anywhere in the dialog, and the box opens\nwith the insertion point in its first text field — or, with none, focus on\nthe default button. A field marked `autoselect` takes the focus with its\ntext selected, on every open.\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\nA `<form method=\"dialog\">` inside the modal closes it with the submitting\nbutton's `value` as returnValue, as a form inside a native\n`<dialog>` does. The platform's own rule looks for a `<dialog>` around the\nform, and this one is in the shadow root, so the modal listens for the\nsubmit itself.\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. That event is queued: a modal opened again before it\ncomes (`close()` then `show()` in one turn) runs the funnel at the open,\ninside `show()`, so the close's `vf-close` still comes before the open's\n`vf-show`, and the late event changes nothing.\n\nIt also owns the two keyboard rules every classic dialog followed (see\ndefaultButton and initialFocusTarget): Return or Enter\nactivates the default button from anywhere in the dialog, and the box opens\nwith the insertion point in its first text field — or, with none, focus on\nthe default button. A field marked `autoselect` takes the focus with its\ntext selected, on every open.\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\nA `<form method=\"dialog\">` inside the modal closes it with the submitting\nbutton's `value` as returnValue, as a form inside a native\n`<dialog>` does. The platform's own rule looks for a `<dialog>` around the\nform, and this one is in the shadow root, so the modal listens for the\nsubmit itself.\n\nSubclasses supply only the frame chrome: a `render()` returning\n`<dialog",
           "name": "VfModalDialog",
           "members": [
             {
@@ -24551,6 +24580,16 @@
               "default": "null",
               "description": "The element that was focused when the modal opened. The normal close path\nrestores focus natively, but the removal path (see the class doc) skips\nthe close algorithm, and by the time `disconnectedCallback` runs, focus\nhas already fallen to `<body>` — so we keep our own record."
             },
+            {
+              "kind": "field",
+              "name": "#opened",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the modal has opened since its last close was funneled: true from\nan open until `#funnelClose` runs for the close that ends it, which can be\nafter the native `<dialog>` has closed, while its `close` event is queued."
+            },
             {
               "kind": "method",
               "name": "show",
@@ -24702,7 +24741,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reconcile the native `<dialog>` with `open`. Opening states the origin —\nthe author's, or the centered one — onto the top-layer box; the UA's own\n`margin: auto` centering lands on a half pixel whenever viewport minus\ndialog is odd, which fringes all the 1-bit chrome inside. Closing just\ncalls `dialog.close()`, routing teardown through the native `close` event\nso _onNativeClose is the one place placement is cleared and\n`vf-close` is fired."
+              "description": "Reconcile the native `<dialog>` with `open`. Opening states the origin —\nthe author's, or the centered one — onto the top-layer box; the UA's own\n`margin: auto` centering lands on a half pixel whenever viewport minus\ndialog is odd, which fringes all the 1-bit chrome inside. Closing just\ncalls `dialog.close()`, and the native `close` event runs the close funnel,\n`#funnelClose`, the one place placement is cleared and `vf-close` is\nfired."
             },
             {
               "kind": "field",
@@ -24743,7 +24782,7 @@
                   }
                 }
               ],
-              "description": "While open, watch everything that invalidates the placement: the dialog's\nown box changing (content upgrade/growth, and `--vf-scale` moving under a\nzoom or density change, since every metric resizes with it), the viewport\nresizing, and the scale itself — which the box alone would miss on a page\nthat pins `--vf-scale`, where a zoom moves the lattice without resizing\nanything. Undone in _onNativeClose / `disconnectedCallback`."
+              "description": "While open, watch everything that invalidates the placement: the dialog's\nown box changing (content upgrade/growth, and `--vf-scale` moving under a\nzoom or density change, since every metric resizes with it), the viewport\nresizing, and the scale itself — which the box alone would miss on a page\nthat pins `--vf-scale`, where a zoom moves the lattice without resizing\nanything. Undone by the close funnel and `disconnectedCallback`."
             },
             {
               "kind": "method",
@@ -24775,7 +24814,18 @@
                   "text": "void"
                 }
               },
-              "description": "Native `close` — the single teardown funnel for every close path. Drops\nthe written origin so the next open re-derives it from the box it will\nactually have (a stated `top`/`left` is the author's or the user's and\nsurvives, and is re-applied by that open), syncs `open`, and fires\n`vf-close` with the reason and the value the close carried."
+              "description": "Native `close`, which every close path ends in: syncs `open` and runs the\nclose funnel. An open that came before the event has run the funnel for\nthis close already, and the event passes."
+            },
+            {
+              "kind": "method",
+              "name": "#funnelClose",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "The close funnel, the single teardown for every close path. Drops the\nwritten origin so the next open re-derives it from the box it will\nactually have (a stated `top`/`left` is the author's or the user's and\nsurvives, and is re-applied by that open), and fires `vf-close` with the\nreason and the value the close carried."
             }
           ],
           "events": [

package/dist/build/box.d.ts

@@ -19,6 +19,8 @@ export interface Slot {
 export interface BoxFrame {
     /** The picture, a PNG. */
     picture: Uint8Array;
+    /** One system px, in the picture's px. Each of the artwork's px is a whole number of them. */
+    scale: number;
     /** Where the artwork goes. Without artwork the icon goes there, `stamp` times its size and centered. */
     artwork: Slot & {
         stamp: number;
@@ -46,7 +48,7 @@ export interface BoxInput {
     manifest: AppManifest;
     /** The icon's PNG, 32 × 32. */
     icon: Uint8Array;
-    /** The artwork's PNG: the artwork slot's size, or that divided by a whole number. */
+    /** The artwork's PNG: the artwork slot's size in system px, or that divided by a whole number. */
     artwork?: Uint8Array;
 }
 /** The box in the kit's frame, as a PNG. */

package/dist/build/box.js

@@ -16,9 +16,12 @@ async function a(e, { manifest: n, icon: r, artwork: i }) {
 	if (c.width !== 32 || c.height !== 32) throw Error(`the icon is ${c.width} × ${c.height}, and an icon is 32 × 32`);
 	let u = e.artwork;
 	if (i) {
-		let e = await t(i, "the artwork"), n = u.width / e.width;
-		if (!Number.isInteger(n) || e.height * n !== u.height) throw Error(`the artwork is ${e.width} × ${e.height}: draw it at ${u.width} × ${u.height}, or that divided by a whole number (${o(u)})`);
-		s(a, e, u.left, u.top, n, u);
+		let n = await t(i, "the artwork"), r = {
+			width: u.width / e.scale,
+			height: u.height / e.scale
+		}, c = r.width / n.width;
+		if (!Number.isInteger(c) || n.height * c !== r.height) throw Error(`the artwork is ${n.width} × ${n.height}: draw it at ${r.width} × ${r.height}, or that divided by a whole number (${o(r)})`);
+		s(a, n, u.left, u.top, c * e.scale, u);
 	} else {
 		let e = 32 * u.stamp;
 		s(a, c, u.left + Math.floor((u.width - e) / 2), u.top + Math.floor((u.height - e) / 2), u.stamp, u);

package/dist/build/frame.js

@@ -1,42 +1,44 @@
+import "../shell/app-file.js";
 import { VF_BODY_STRIKE as e } from "../styles/body-strike.js";
 import { VF_DISPLAY_STRIKE as t } from "../styles/display-strike.js";
 import { FRAME_PNG as n } from "./frame-picture.js";
 //#region src/build/frame.ts
-var r = {
-	left: 48,
-	width: 384,
-	scale: 3,
+var r = 3, i = {
+	left: 16 * r,
+	width: 128 * r,
+	scale: r,
 	ink: "#000000",
 	align: "center"
-}, i = {
+}, a = {
 	picture: n,
+	scale: r,
 	artwork: {
-		left: 48,
-		top: 48,
-		width: 384,
-		height: 384,
-		stamp: 8
+		left: 16 * r,
+		top: 16 * r,
+		width: 128 * r,
+		height: 128 * r,
+		stamp: 3 * r
 	},
 	text: [
 		{
-			...r,
-			top: 456,
+			...i,
+			top: 152 * r,
 			strike: t,
 			text: "{name}"
 		},
 		{
-			...r,
-			top: 510,
+			...i,
+			top: 170 * r,
 			strike: e,
 			text: "Version {version}"
 		},
 		{
-			...r,
-			top: 546,
+			...i,
+			top: 182 * r,
 			strike: e,
 			text: "by {author}"
 		}
 	]
 };
 //#endregion
-export { i as FRAME };
+export { a as FRAME };

package/dist/build/plugins.d.ts

@@ -4,18 +4,19 @@
  */
 import type { Plugin } from 'vite';
 export interface AppFileOptions {
-    /** The application's id, name, version and author: its `app.ts`. */
+    /** The application's id, name, version and author, and its description if it has one: its `app.ts`. */
     app: {
         id: string;
         name: string;
         version: string;
         author: string;
+        description?: string;
     };
     /** The module whose default export is the application's factory. */
     entry: string;
     /** Its 32 × 32 icon, a PNG. */
     icon: string;
-    /** Its artwork for the box: a PNG at the artwork slot's size, or that divided by a whole number. */
+    /** Its artwork for the box: a 128 × 128 PNG, or that divided by a whole number. */
     artwork?: string;
     /** A directory to write the app file to as well, such as a site's `apps/`. */
     copyTo?: string;

package/dist/build/plugins.js

@@ -1,40 +1,41 @@
-import { inspectAppFile as e, satisfies as t } from "../shell/app-file.js";
-import { VERSION as n } from "../shell/version.js";
-import { packApp as r } from "./app-file.js";
-import { mkdir as i, readFile as a, writeFile as o } from "node:fs/promises";
-import { join as s, relative as c, resolve as l } from "node:path";
+import { inspectAppFile as e, isVersion as t, satisfies as n } from "../shell/app-file.js";
+import { VERSION as r } from "../shell/version.js";
+import { packApp as i } from "./app-file.js";
+import { mkdir as a, readFile as o, writeFile as s } from "node:fs/promises";
+import { join as c, relative as l, resolve as u } from "node:path";
 //#region src/build/plugins.ts
-var u = [
+var d = [
 	"vintage-frames",
 	"vintage-frames/shell",
 	"vintage-frames/shell/pure"
-], d = "app-code";
-function f(e) {
+], f = "app-code";
+function p(e) {
 	let t = e.match(/(?<=[\\/]node_modules[\\/])(?:@[^\\/]+[\\/])?[^\\/]+/g)?.at(-1)?.replace("\\", "/");
 	return t === "vintage-frames" ? "a copy of vintage-frames" : t && /^(?:lit|lit-html|lit-element|@lit\/.+|@lit-labs\/.+)$/.test(t) ? `Lit (${t})` : null;
 }
-async function p(e) {
-	let t = JSON.parse(await a(s(e, "package.json"), "utf8")), r = t.devDependencies?.["vintage-frames"] ?? t.dependencies?.["vintage-frames"];
-	if (typeof r != "string") throw Error("package.json has no vintage-frames dev dependency");
-	if (!/^\^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(r)) throw Error(`package.json's vintage-frames range is "${r}", and an app file requires a caret range: ^${n}`);
-	return r;
+async function m(e) {
+	let n = JSON.parse(await o(c(e, "package.json"), "utf8")), i = n.devDependencies?.["vintage-frames"] ?? n.dependencies?.["vintage-frames"];
+	if (typeof i != "string") throw Error("package.json has no vintage-frames dev dependency");
+	if (!i.startsWith("^") || !t(i.slice(1))) throw Error(`package.json's vintage-frames range is "${i}", and an app file requires a caret range: ^${r}`);
+	return i;
 }
-function m(e) {
-	let { app: c, entry: d, icon: m, artwork: h, copyTo: g } = e;
+function h(e) {
+	let { app: l, entry: f, icon: h, artwork: g, copyTo: _ } = e;
 	for (let e of [
 		"id",
 		"name",
 		"version",
 		"author"
-	]) if (typeof c?.[e] != "string" || !c[e]) throw Error(`vintage-frames appFile(): app.${e} is missing`);
-	if (!d || !m) throw Error(`vintage-frames appFile(): ${d ? "icon" : "entry"} is missing`);
-	let _ = `${c.name.replace(/[\\/:*?"<>|]/g, "-")}.png`, v = "", y = null;
+	]) if (typeof l?.[e] != "string" || !l[e]) throw Error(`vintage-frames appFile(): app.${e} is missing`);
+	if (!t(l.version)) throw Error(`vintage-frames appFile(): app.version, ${l.version}, is not a version`);
+	if (!f || !h) throw Error(`vintage-frames appFile(): ${f ? "icon" : "entry"} is missing`);
+	let v = `${l.name.replace(/[\\/:*?"<>|]/g, "-")}.png`, y = "", b = null;
 	return {
 		name: "vintage-frames:app-file",
 		apply: "build",
 		config: () => ({ build: {
 			lib: {
-				entry: d,
+				entry: f,
 				formats: ["es"],
 				fileName: "app"
 			},
@@ -45,79 +46,80 @@ function m(e) {
 			}
 		} }),
 		configResolved(e) {
-			v = e.root;
+			y = e.root;
 		},
 		buildStart() {
 			for (let e of [
-				m,
 				h,
+				g,
 				"package.json"
-			]) e && this.addWatchFile(l(v, e));
+			]) e && this.addWatchFile(u(y, e));
 		},
 		generateBundle: {
 			order: "post",
-			async handler(e, i) {
-				let o = Object.values(i), s = o.filter((e) => e.type === "chunk"), d = o.filter((e) => e.type === "asset").map((e) => e.fileName);
-				d.length && this.error(`${c.name} emits ${d.join(", ")} beside its code, and an app file holds one module: no CSS import, no source map file, its art inlined.`);
-				let [g] = s;
-				(!g || s.length > 1) && this.error(`${c.name} builds to ${s.length} modules, and an app file holds one.`);
-				for (let e of Object.keys(g.modules)) {
-					let t = f(e);
-					t && this.error(`${c.name} bundles ${t}. It composes the page's kit and brings none of its own.`);
+			async handler(e, t) {
+				let a = Object.values(t), s = a.filter((e) => e.type === "chunk"), c = a.filter((e) => e.type === "asset").map((e) => e.fileName);
+				c.length && this.error(`${l.name} emits ${c.join(", ")} beside its code, and an app file holds one module: no CSS import, no source map file, its art inlined.`);
+				let [f] = s;
+				(!f || s.length > 1) && this.error(`${l.name} builds to ${s.length} modules, and an app file holds one.`);
+				for (let e of Object.keys(f.modules)) {
+					let t = p(e);
+					t && this.error(`${l.name} bundles ${t}. It composes the page's kit and brings none of its own.`);
 				}
-				let b = [...g.imports, ...g.dynamicImports].filter((e) => !u.includes(e));
-				b.length && this.error(`${c.name} imports ${b.join(", ")}. An application imports ${u.join(", ")} and its own files.`);
+				let _ = [...f.imports, ...f.dynamicImports].filter((e) => !d.includes(e));
+				_.length && this.error(`${l.name} imports ${_.join(", ")}. An application imports ${d.join(", ")} and its own files.`);
 				try {
-					let e = await p(v);
-					if (!t("0.17.0", e)) throw Error(`package.json requires vintage-frames ${e}, and the build is on ${n}: move the range`);
-					y = await r({
+					let e = await m(y);
+					if (!n("0.18.0", e)) throw Error(`package.json requires vintage-frames ${e}, and the build is on ${r}: move the range`);
+					b = await i({
 						manifest: {
-							id: c.id,
-							name: c.name,
-							version: c.version,
+							id: l.id,
+							name: l.name,
+							version: l.version,
 							requires: e,
-							author: c.author
+							author: l.author,
+							description: l.description
 						},
-						icon: new Uint8Array(await a(l(v, m))),
-						code: g.code,
-						artwork: h ? new Uint8Array(await a(l(v, h))) : void 0
+						icon: new Uint8Array(await o(u(y, h))),
+						code: f.code,
+						artwork: g ? new Uint8Array(await o(u(y, g))) : void 0
 					});
 				} catch (e) {
-					this.error(`${c.name}: ${e.message}`);
+					this.error(`${l.name}: ${e.message}`);
 				}
-				delete i[g.fileName], this.emitFile({
+				delete t[f.fileName], this.emitFile({
 					type: "asset",
-					fileName: _,
-					source: y
+					fileName: v,
+					source: b
 				});
 			}
 		},
 		async writeBundle() {
-			if (!g || !y) return;
-			let e = l(v, g);
-			await i(e, { recursive: !0 }), await o(s(e, _), y);
+			if (!_ || !b) return;
+			let e = u(y, _);
+			await a(e, { recursive: !0 }), await s(c(e, v), b);
 		}
 	};
 }
-function h() {
-	let r = "";
+function g() {
+	let t = "";
 	return {
 		name: "vintage-frames:app-files",
 		enforce: "pre",
 		configResolved(e) {
-			r = e.root;
+			t = e.root;
 		},
 		async load(i) {
-			let o = i.indexOf("?");
-			if (o < 0) return null;
-			let s = i.slice(0, o), l = new URLSearchParams(i.slice(o + 1));
-			if (!s.endsWith(".png") || !(l.has("app") || l.has(d))) return null;
+			let a = i.indexOf("?");
+			if (a < 0) return null;
+			let s = i.slice(0, a), c = new URLSearchParams(i.slice(a + 1));
+			if (!s.endsWith(".png") || !(c.has("app") || c.has(f))) return null;
 			this.addWatchFile(s);
-			let u = c(r, s), f = await e(new Uint8Array(await a(s)));
-			typeof f == "string" && this.error(`${u} is not an app file: ${f}.`);
-			let { manifest: p, code: m } = f;
-			return l.has(d) ? m : (t("0.17.0", p.requires) || this.error(`${u}: ${p.name} ${p.version} requires vintage-frames ${p.requires}, and this site has ${n}. Build ${p.name} on ${n} and copy its app file in.`), [
-				`import factory from ${JSON.stringify(`${s}?${d}`)}`,
+			let u = l(t, s), d = await e(new Uint8Array(await o(s)));
+			typeof d == "string" && this.error(`${u} is not an app file: ${d}.`);
+			let { manifest: p, code: m } = d;
+			return c.has(f) ? m : (n("0.18.0", p.requires) || this.error(`${u}: ${p.name} ${p.version} requires vintage-frames ${p.requires}, and this site has ${r}. Build ${p.name} on ${r} and copy its app file in.`), [
+				`import factory from ${JSON.stringify(`${s}?${f}`)}`,
 				`export const manifest = ${JSON.stringify(p)}`,
 				"export default (...args) => ({ ...factory(...args), icon: manifest.icon })",
 				""
@@ -126,4 +128,4 @@ function h() {
 	};
 }
 //#endregion
-export { m as appFile, h as appFiles };
+export { h as appFile, g as appFiles };

package/dist/modal-dialog.d.ts

@@ -51,7 +51,10 @@ export declare const modalDialogStyles: import("lit").CSSResult;
  * 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.
+ * open re-derives it. That event is queued: a modal opened again before it
+ * comes (`close()` then `show()` in one turn) runs the funnel at the open,
+ * inside `show()`, so the close's `vf-close` still comes before the open's
+ * `vf-show`, and the late event changes nothing.
  *
  * It also owns the two keyboard rules every classic dialog followed (see
  * {@link defaultButton} and {@link initialFocusTarget}): Return or Enter
@@ -242,11 +245,9 @@ export declare class VfModalDialog extends LitElement {
     /** Native `cancel` (Escape): remember the reason; `close` follows. */
     protected _onNativeCancel(): void;
     /**
-     * Native `close` — the single teardown funnel for every close path. Drops
-     * the written origin so the next open re-derives it from the box it will
-     * actually have (a stated `top`/`left` is the author's or the user's and
-     * survives, and is re-applied by that open), syncs `open`, and fires
-     * `vf-close` with the reason and the value the close carried.
+     * Native `close`, which every close path ends in: syncs `open` and runs the
+     * close funnel. An open that came before the event has run the funnel for
+     * this close already, and the event passes.
      */
     protected _onNativeClose(): void;
 }

package/dist/modal-dialog.js

@@ -112,7 +112,7 @@ var p = 24, m = /* @__PURE__ */ new Set([
 			this.#o = null, !(!t || e.target !== this._dialog || !this.lightDismiss) && (this.#n = "outside", this.close());
 		}, this.#f = () => {
 			this.#o = null;
-		}, this.#p = null, this.#y = () => this.settle(), this.addEventListener("submit", this.#a);
+		}, this.#p = null, this.#m = !1, this.#b = () => this.settle(), this.addEventListener("submit", this.#a);
 	}
 	#a;
 	#o;
@@ -133,41 +133,42 @@ var p = 24, m = /* @__PURE__ */ new Set([
 	#d;
 	#f;
 	#p;
+	#m;
 	show() {
-		this.open = !0, this.hasUpdated && this.#v();
+		this.open = !0, this.hasUpdated && this.#y();
 	}
 	close(e) {
-		this.open && e !== void 0 && (this.#r = e), this.open = !1, this.hasUpdated && this.#v();
+		this.open && e !== void 0 && (this.#r = e), this.open = !1, this.hasUpdated && this.#y();
 	}
 	closeFromBox(e) {
 		this.open && (this.#i = e), this.close();
 	}
 	updated(e) {
-		e.has("open") && this.#v(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
+		e.has("open") && this.#y(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
 	}
-	#m() {
+	#h() {
 		let e = document.documentElement;
 		return {
 			width: o(e.clientWidth || window.innerWidth, this),
 			height: o(e.clientHeight || window.innerHeight, this)
 		};
 	}
-	#h(e, t) {
-		let n = this.#m(), r = o(this._dialog?.offsetWidth ?? 0, this);
+	#g(e, t) {
+		let n = this.#h(), r = o(this._dialog?.offsetWidth ?? 0, this);
 		return {
 			x: Math.min(Math.max(e, p - r), n.width - p),
 			y: Math.min(Math.max(t, 0), Math.max(0, n.height - p))
 		};
 	}
-	#g() {
-		let e = this.#m(), t = this._dialog?.getBoundingClientRect();
+	#_() {
+		let e = this.#h(), t = this._dialog?.getBoundingClientRect();
 		return {
 			x: (e.width - o(t?.width ?? 0, this)) / 2,
 			y: (e.height - o(t?.height ?? 0, this)) / 2
 		};
 	}
 	placeAt(e, t) {
-		let n = this.#h(e, t);
+		let n = this.#g(e, t);
 		this.left = i(n.x, this), this.top = i(n.y, this);
 	}
 	settle() {
@@ -176,10 +177,10 @@ var p = 24, m = /* @__PURE__ */ new Set([
 		let t = this.left != null || this.top != null ? {
 			x: this.left ?? 0,
 			y: this.top ?? 0
-		} : this.#g(), n = this.#h(t.x, t.y);
+		} : this.#_(), n = this.#g(t.x, t.y);
 		e.style.left = a(i(n.x, this)), e.style.top = a(i(n.y, this)), e.style.right = "auto", e.style.bottom = "auto", e.style.margin = "0";
 	}
-	#_() {
+	#v() {
 		let e = this._dialog?.style;
 		if (e) for (let t of [
 			"left",
@@ -189,27 +190,31 @@ var p = 24, m = /* @__PURE__ */ new Set([
 			"margin"
 		]) e.removeProperty(t);
 	}
-	#v() {
+	#y() {
 		let e = this._dialog;
 		if (e) {
 			if (this.open && !e.open) {
-				this.#p = document.activeElement, this.returnValue = "", e.showModal();
+				if (this.#m) {
+					this.#T(), this.#y();
+					return;
+				}
+				this.#p = document.activeElement, this.returnValue = "", this.#n = null, this.#r = null, this.#i = null, e.showModal(), this.#m = !0;
 				let n = this.#c();
-				this.settle(), this.#S(e), this.#s.attach(), t(this, "vf-show", { focus: n }), n && _(n) && n.select?.();
+				this.settle(), this.#C(e), this.#s.attach(), t(this, "vf-show", { focus: n }), n && _(n) && n.select?.();
 			} else !this.open && e.open && e.close();
 		}
 	}
-	#y;
 	#b;
 	#x;
-	#S(e) {
-		typeof ResizeObserver < "u" && !this.#b && (this.#b = new ResizeObserver(this.#y), this.#b.observe(e)), window.addEventListener("resize", this.#y), this.#x ??= r(this.#y);
+	#S;
+	#C(e) {
+		typeof ResizeObserver < "u" && !this.#x && (this.#x = new ResizeObserver(this.#b), this.#x.observe(e)), window.addEventListener("resize", this.#b), this.#S ??= r(this.#b);
 	}
-	#C() {
-		this.#b?.disconnect(), this.#b = void 0, window.removeEventListener("resize", this.#y), this.#x?.(), this.#x = void 0;
+	#w() {
+		this.#x?.disconnect(), this.#x = void 0, window.removeEventListener("resize", this.#b), this.#S?.(), this.#S = void 0;
 	}
 	disconnectedCallback() {
-		super.disconnectedCallback(), this.#C();
+		super.disconnectedCallback(), this.#w();
 		let e = this._dialog;
 		if (e?.open) {
 			e.close();
@@ -222,8 +227,11 @@ var p = 24, m = /* @__PURE__ */ new Set([
 		this.#n = "escape";
 	}
 	_onNativeClose() {
+		!this.#m || this._dialog?.open || (this.open = !1, this.#T());
+	}
+	#T() {
 		let e = this.#n ?? "close", n = this.#r, r = this.#i;
-		this.#n = null, this.#r = null, this.#i = null, n !== null && (this.returnValue = n), this.#p = null, this.#o = null, this.#s.detach(), this.#C(), this.open = !1, this.#_(), t(this, "vf-close", {
+		this.#n = null, this.#r = null, this.#i = null, this.#m = !1, n !== null && (this.returnValue = n), this.#p = null, this.#o = null, this.#s.detach(), this.#w(), this.#v(), t(this, "vf-close", {
 			reason: e,
 			returnValue: n,
 			...r

package/dist/shell/app-file.d.ts

@@ -4,13 +4,19 @@
  * JSON, and its code, one ES module compressed with zlib. Any PNG tool reads
  * the chunks and any decoder skips them.
  *
- * This is the reading half, and checking a version against a range. It is
+ * This is the reading half: the reader, checking a version against a range,
+ * putting versions in order, and the scale every box is drawn at. It is
  * pure and runs the same under Node and in a page, through the platform's
  * compression streams. Writing an app file, and the box, are
  * `vintage-frames/build`'s.
  */
 /** The app file format this kit reads and writes. */
 export declare const APP_FILE_FORMAT = 1;
+/**
+ * One system px of an app file's box, in its picture's px: every box of
+ * this format is drawn at 3×, each system px a 3 × 3 block.
+ */
+export declare const BOX_SCALE = 3;
 /** The iTXt keywords of the manifest's chunk and the code's. */
 export declare const MANIFEST_KEYWORD = "vintage-frames.app";
 export declare const CODE_KEYWORD = "vintage-frames.code";
@@ -24,6 +30,8 @@ export interface AppManifest {
     /** The kit range the code was built and checked against: `^0.17.0`. */
     requires: string;
     author: string;
+    /** What the application is, in a sentence or two of plain text. */
+    description?: string;
     /** Its 32 × 32 icon: its PNG as a `data:` URL. */
     icon: string;
 }
@@ -62,11 +70,25 @@ export declare function manifestOf(json: unknown): AppManifest | string;
 /**
  * The manifest and code an app file carries, or why it isn't one: not a
  * whole PNG, a chunk missing or doubled, a format this kit doesn't read, a
- * field missing, or code that doesn't inflate.
+ * field missing or unreadable, or code that doesn't inflate. The reason ends
+ * a sentence such as "Meteors.png is not an app file: …", and is for people:
+ * its wording can change in any release, so match on nothing in it.
  */
 export declare function inspectAppFile(bytes: Uint8Array): Promise<AppFile | string>;
 /** The manifest and code an app file carries, or null for any other PNG. */
 export declare function readAppFile(bytes: Uint8Array): Promise<AppFile | null>;
+/**
+ * Whether `text` is a version exactly as semver writes one: `0.1.0`,
+ * `1.0.0-rc.1`, but not `v0.1.0`, ` 0.1.0` or `01.2.3`.
+ */
+export declare function isVersion(text: string): boolean;
+/**
+ * Below zero, zero or above as version `a` comes before, with or after `b`,
+ * in semver's order: a release after its prereleases, build metadata
+ * ignored. Anything that isn't a version, a string or not, comes before
+ * every version, so a sort never throws.
+ */
+export declare function compareVersions(a: string, b: string): number;
 /**
  * Whether `version` meets `range`: an exact version, or a caret range as
  * npm reads it. `^1.2.3` takes 1.x from 1.2.3 on, `^0.2.3` takes 0.2.x from

package/dist/shell/app-file.js

@@ -1,27 +1,28 @@
 //#region src/shell/app-file.ts
-var e = 1, t = "vintage-frames.app", n = "vintage-frames.code", r = [
+var e = 1, t = 3, n = "vintage-frames.app", r = "vintage-frames.code", i = [
 	"id",
 	"name",
 	"version",
 	"requires",
 	"author",
+	"description",
 	"icon"
-], i = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10), a = Uint32Array.from({ length: 256 }, (e, t) => {
+], a = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10), o = Uint32Array.from({ length: 256 }, (e, t) => {
 	let n = t;
 	for (let e = 0; e < 8; e++) n = n & 1 ? 3988292384 ^ n >>> 1 : n >>> 1;
 	return n >>> 0;
 });
-function o(e) {
+function s(e) {
 	let t = 4294967295;
-	for (let n of e) t = a[(t ^ n) & 255] ^ t >>> 8;
+	for (let n of e) t = o[(t ^ n) & 255] ^ t >>> 8;
 	return (t ^ 4294967295) >>> 0;
 }
-function s(e) {
-	if (e.length < 8 || i.some((t, n) => e[n] !== t)) return null;
+function c(e) {
+	if (e.length < 8 || a.some((t, n) => e[n] !== t)) return null;
 	let t = new DataView(e.buffer, e.byteOffset, e.byteLength), n = [], r = 8;
 	for (; r + 12 <= e.length;) {
 		let i = r + 12 + t.getUint32(r);
-		if (i > e.length || o(e.subarray(r + 4, i - 4)) !== t.getUint32(i - 4)) return null;
+		if (i > e.length || s(e.subarray(r + 4, i - 4)) !== t.getUint32(i - 4)) return null;
 		let a = String.fromCharCode(...e.subarray(r + 4, r + 8));
 		if (n.push({
 			type: a,
@@ -33,85 +34,85 @@ function s(e) {
 	}
 	return null;
 }
-function c(e) {
+function l(e) {
 	let t = e.indexOf(0);
 	return t > 0 ? String.fromCharCode(...e.subarray(0, t)) : "";
 }
-var l = new TextDecoder("utf-8", { fatal: !0 });
-async function u(e) {
+var u = new TextDecoder("utf-8", { fatal: !0 });
+async function d(e) {
 	let t = e.indexOf(0), n = e[t + 1], r = e[t + 2], i = e.indexOf(0, t + 3), a = i < 0 ? -1 : e.indexOf(0, i + 1);
 	if (t < 1 || a < 0 || n > 1 || r !== 0) throw Error("a broken iTXt chunk");
 	let o = e.subarray(a + 1);
-	return l.decode(n ? await d(o) : o);
+	return u.decode(n ? await f(o) : o);
 }
-async function d(e) {
+async function f(e) {
 	let t = new Blob([e.slice()]).stream().pipeThrough(new DecompressionStream("deflate"));
 	return new Uint8Array(await new Response(t).arrayBuffer());
 }
-async function f(e) {
+async function p(e) {
 	let t = new Blob([e.slice()]).stream().pipeThrough(new CompressionStream("deflate"));
 	return new Uint8Array(await new Response(t).arrayBuffer());
 }
-function p(e) {
+function m(e) {
 	if (!e || typeof e != "object") return "its manifest is not an object";
 	let t = e;
 	if (t.format !== 1) return typeof t.format == "number" ? `it is format ${t.format}, and this kit reads format 1` : "its manifest has no format";
-	let n = {
-		format: 1,
-		id: "",
-		name: "",
-		version: "",
-		requires: "",
-		author: "",
-		icon: ""
-	};
-	for (let e of r) {
+	let n = { format: 1 };
+	for (let e of i) {
 		let r = t[e];
+		if (e === "description") {
+			if (r !== void 0 && typeof r != "string") return "its description is not text";
+			typeof r == "string" && r.trim() && (n.description = r);
+			continue;
+		}
 		if (typeof r != "string" || !r) return `its manifest has no ${e}`;
+		if (e === "version" && !y(r)) return `its version, ${r}, is not a version`;
+		if (e === "requires" && !b(r)) return `its requires, ${r}, is not a range`;
 		n[e] = r;
 	}
 	return n;
 }
-async function m(e) {
-	let r = s(e);
-	if (!r) return "it is not a whole PNG";
+async function h(e) {
+	let t = c(e);
+	if (!t) return "it is not a whole PNG";
 	let i = /* @__PURE__ */ new Map();
-	for (let { type: e, data: t } of r) {
+	for (let { type: e, data: n } of t) {
 		if (e !== "iTXt") continue;
-		let n = c(t);
-		if (n === "vintage-frames.app" || n === "vintage-frames.code") {
-			if (i.has(n)) return `it has two ${n} chunks`;
-			i.set(n, t);
+		let t = l(n);
+		if (t === "vintage-frames.app" || t === "vintage-frames.code") {
+			if (i.has(t)) return `it has two ${t} chunks`;
+			i.set(t, n);
 		}
 	}
-	let a = i.get(t), o = i.get(n);
+	let a = i.get(n), o = i.get(r);
 	if (!a && !o) return "it carries no application";
 	if (!a) return "its manifest is missing";
 	if (!o) return "its code is missing";
-	let l;
+	let s;
 	try {
-		l = JSON.parse(await u(a));
+		s = JSON.parse(await d(a));
 	} catch {
 		return "its manifest does not read";
 	}
-	let d = p(l);
-	if (typeof d == "string") return d;
+	let u = m(s);
+	if (typeof u == "string") return u;
 	try {
 		return {
-			manifest: d,
-			code: await u(o)
+			manifest: u,
+			code: await d(o)
 		};
 	} catch {
 		return "its code does not inflate";
 	}
 }
-async function h(e) {
-	let t = await m(e);
+async function g(e) {
+	let t = await h(e);
 	return typeof t == "string" ? null : t;
 }
-var g = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/;
-function _(e) {
-	let t = g.exec(e.trim());
+var _ = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+function v(e) {
+	if (typeof e != "string") return null;
+	let t = _.exec(e.trim().replace(/^v/, ""));
 	return t ? {
 		core: [
 			Number(t[1]),
@@ -121,7 +122,18 @@ function _(e) {
 		pre: t[4] ? t[4].split(".") : []
 	} : null;
 }
-function v(e, t) {
+function y(e) {
+	return _.test(e);
+}
+function b(e) {
+	return y(e.startsWith("^") ? e.slice(1) : e);
+}
+function x(e) {
+	if (typeof e != "string") return null;
+	let t = e.trim();
+	return v(t.startsWith("^") ? t.slice(1) : t);
+}
+function S(e, t) {
 	for (let n = 0; n < 3; n++) if (e.core[n] !== t.core[n]) return e.core[n] - t.core[n];
 	if (!e.pre.length || !t.pre.length) return t.pre.length - e.pre.length;
 	for (let n = 0; n < Math.max(e.pre.length, t.pre.length); n++) {
@@ -134,28 +146,32 @@ function v(e, t) {
 	}
 	return 0;
 }
-function y(e, t) {
-	let n = t.trim().startsWith("^"), r = _(e), i = _(n ? t.trim().slice(1) : t);
-	if (!r || !i) return !1;
-	if (!n) return v(r, i) === 0;
-	if (r.pre.length && !(i.pre.length && r.core.every((e, t) => e === i.core[t]))) return !1;
-	let [a, o, s] = i.core, c = {
-		core: a ? [
-			a + 1,
+function C(e, t) {
+	let n = v(e), r = v(t);
+	return n && r ? S(n, r) : !!n - +!!r;
+}
+function w(e, t) {
+	let n = v(e), r = x(t);
+	if (!n || !r) return !1;
+	if (!t.trim().startsWith("^")) return S(n, r) === 0;
+	if (n.pre.length && !(r.pre.length && n.core.every((e, t) => e === r.core[t]))) return !1;
+	let [i, a, o] = r.core, s = {
+		core: i ? [
+			i + 1,
 			0,
 			0
-		] : o ? [
+		] : a ? [
 			0,
-			o + 1,
+			a + 1,
 			0
 		] : [
 			0,
 			0,
-			s + 1
+			o + 1
 		],
 		pre: []
 	};
-	return v(r, i) >= 0 && v(r, c) < 0;
+	return S(n, r) >= 0 && S(n, s) < 0;
 }
 //#endregion
-export { e as APP_FILE_FORMAT, n as CODE_KEYWORD, t as MANIFEST_KEYWORD, i as PNG_SIGNATURE, o as crc32, f as deflate, d as inflate, m as inspectAppFile, c as itxtKeyword, p as manifestOf, s as pngChunks, h as readAppFile, y as satisfies };
+export { e as APP_FILE_FORMAT, t as BOX_SCALE, r as CODE_KEYWORD, n as MANIFEST_KEYWORD, a as PNG_SIGNATURE, C as compareVersions, s as crc32, p as deflate, f as inflate, h as inspectAppFile, y as isVersion, l as itxtKeyword, m as manifestOf, c as pngChunks, g as readAppFile, w as satisfies };

package/dist/shell/index.d.ts

@@ -25,6 +25,6 @@ export type { LocalStorageStateOptions, SavedSession, SavedWindow, SessionSnapsh
 export { BAND, CASCADE_SLOTS, CASCADE_STEP, ICON_CELL, ICON_COLUMN, ICON_INSET, ICON_ROW, NEAR, WINDOW_ORIGIN, cascadedBox, cascadeFrom, cascadeSlot, centeredBox, cleanUp, collisions, desktopLattice, fieldExtent, fillOrder, folderLattice, frameOf, isPin, latticeCell, latticeSlot, nearBox, nextFreeCell, pinOf, pinTo, trashCell, windowOrigin, } from './geometry.js';
 export type { Bands, Box, CascadeOptions, EdgePin, Frame, Lattice, LatticeOptions, Pin, Point, Policy, Size, } from './geometry.js';
 export { startClock, formatDate, formatTime, DATE_HOLD_MS } from './clock.js';
-export { APP_FILE_FORMAT, readAppFile, satisfies } from './app-file.js';
+export { APP_FILE_FORMAT, BOX_SCALE, compareVersions, inspectAppFile, readAppFile, satisfies } from './app-file.js';
 export type { AppFile, AppManifest } from './app-file.js';
 export { VERSION } from './version.js';

package/dist/shell/index.js

@@ -7,6 +7,6 @@ import { createShell as ae, defineApp as oe } from "./shell.js";
 import { fileByDrag as se } from "./filing.js";
 import { FINDER as ce, finder as le } from "./finder.js";
 import { indexedDbStorage as ue } from "./storage.js";
-import { APP_FILE_FORMAT as de, readAppFile as fe, satisfies as pe } from "./app-file.js";
-import { VERSION as me } from "./version.js";
-export { de as APP_FILE_FORMAT, e as APP_KIND, b as BAND, x as CASCADE_SLOTS, S as CASCADE_STEP, te as DATE_HOLD_MS, t as DISK, ce as FINDER, n as FOLDER, C as ICON_CELL, w as ICON_COLUMN, T as ICON_INSET, E as ICON_ROW, D as NEAR, r as TRASH, i as UNTITLED_FOLDER, me as VERSION, O as WINDOW_ORIGIN, a as appIdOf, k as cascadeFrom, A as cascadeSlot, j as cascadedBox, M as centeredBox, o as childrenOf, N as cleanUp, P as collisions, s as containerOf, c as copyName, l as createCatalog, ae as createShell, Y as createWindowManager, oe as defineApp, u as descendantsOf, F as desktopLattice, d as enclosingFolders, I as fieldExtent, se as fileByDrag, L as fillOrder, le as finder, X as focusInto, R as folderLattice, ne as formatDate, re as formatTime, z as frameOf, ue as indexedDbStorage, f as isContainerKind, p as isInside, B as isPin, m as isTrashed, h as isVolume, g as itemCount, _ as itemOf, V as latticeCell, H as latticeSlot, Z as localStorageState, v as memoryStorage, Q as mergeSession, U as nearBox, y as nextFolderName, W as nextFreeCell, $ as openWindowsOf, G as pinOf, K as pinTo, fe as readAppFile, ee as readSession, pe as satisfies, ie as startClock, q as trashCell, J as windowOrigin };
+import { APP_FILE_FORMAT as de, BOX_SCALE as fe, compareVersions as pe, inspectAppFile as me, readAppFile as he, satisfies as ge } from "./app-file.js";
+import { VERSION as _e } from "./version.js";
+export { de as APP_FILE_FORMAT, e as APP_KIND, b as BAND, fe as BOX_SCALE, x as CASCADE_SLOTS, S as CASCADE_STEP, te as DATE_HOLD_MS, t as DISK, ce as FINDER, n as FOLDER, C as ICON_CELL, w as ICON_COLUMN, T as ICON_INSET, E as ICON_ROW, D as NEAR, r as TRASH, i as UNTITLED_FOLDER, _e as VERSION, O as WINDOW_ORIGIN, a as appIdOf, k as cascadeFrom, A as cascadeSlot, j as cascadedBox, M as centeredBox, o as childrenOf, N as cleanUp, P as collisions, pe as compareVersions, s as containerOf, c as copyName, l as createCatalog, ae as createShell, Y as createWindowManager, oe as defineApp, u as descendantsOf, F as desktopLattice, d as enclosingFolders, I as fieldExtent, se as fileByDrag, L as fillOrder, le as finder, X as focusInto, R as folderLattice, ne as formatDate, re as formatTime, z as frameOf, ue as indexedDbStorage, me as inspectAppFile, f as isContainerKind, p as isInside, B as isPin, m as isTrashed, h as isVolume, g as itemCount, _ as itemOf, V as latticeCell, H as latticeSlot, Z as localStorageState, v as memoryStorage, Q as mergeSession, U as nearBox, y as nextFolderName, W as nextFreeCell, $ as openWindowsOf, G as pinOf, K as pinTo, he as readAppFile, ee as readSession, ge as satisfies, ie as startClock, q as trashCell, J as windowOrigin };

package/dist/shell/pure.d.ts

@@ -8,6 +8,6 @@
 export * from './catalog.js';
 export * from './geometry.js';
 export * from './state.js';
-export { APP_FILE_FORMAT, readAppFile, satisfies } from './app-file.js';
+export { APP_FILE_FORMAT, BOX_SCALE, compareVersions, inspectAppFile, readAppFile, satisfies } from './app-file.js';
 export type { AppFile, AppManifest } from './app-file.js';
 export { VERSION } from './version.js';

package/dist/shell/pure.js

@@ -1,6 +1,6 @@
 import { APP_KIND as e, DISK as t, FOLDER as n, TRASH as r, UNTITLED_FOLDER as i, appIdOf as a, childrenOf as o, containerOf as s, copyName as c, createCatalog as l, descendantsOf as u, enclosingFolders as d, isContainerKind as f, isInside as p, isTrashed as m, isVolume as h, itemCount as g, itemOf as _, memoryStorage as v, nextFolderName as y } from "./catalog.js";
 import { BAND as b, CASCADE_SLOTS as x, CASCADE_STEP as S, ICON_CELL as C, ICON_COLUMN as w, ICON_INSET as T, ICON_ROW as E, NEAR as D, WINDOW_ORIGIN as O, cascadeFrom as k, cascadeSlot as A, cascadedBox as j, centeredBox as M, cleanUp as N, collisions as P, desktopLattice as F, fieldExtent as I, fillOrder as L, folderLattice as R, frameOf as z, isPin as B, latticeCell as V, latticeSlot as H, nearBox as U, nextFreeCell as W, pinOf as G, pinTo as K, trashCell as q, windowOrigin as J } from "./geometry.js";
 import { localStorageState as Y, mergeSession as X, openWindowsOf as Z, readSession as Q } from "./state.js";
-import { APP_FILE_FORMAT as $, readAppFile as ee, satisfies as te } from "./app-file.js";
-import { VERSION as ne } from "./version.js";
-export { $ as APP_FILE_FORMAT, e as APP_KIND, b as BAND, x as CASCADE_SLOTS, S as CASCADE_STEP, t as DISK, n as FOLDER, C as ICON_CELL, w as ICON_COLUMN, T as ICON_INSET, E as ICON_ROW, D as NEAR, r as TRASH, i as UNTITLED_FOLDER, ne as VERSION, O as WINDOW_ORIGIN, a as appIdOf, k as cascadeFrom, A as cascadeSlot, j as cascadedBox, M as centeredBox, o as childrenOf, N as cleanUp, P as collisions, s as containerOf, c as copyName, l as createCatalog, u as descendantsOf, F as desktopLattice, d as enclosingFolders, I as fieldExtent, L as fillOrder, R as folderLattice, z as frameOf, f as isContainerKind, p as isInside, B as isPin, m as isTrashed, h as isVolume, g as itemCount, _ as itemOf, V as latticeCell, H as latticeSlot, Y as localStorageState, v as memoryStorage, X as mergeSession, U as nearBox, y as nextFolderName, W as nextFreeCell, Z as openWindowsOf, G as pinOf, K as pinTo, ee as readAppFile, Q as readSession, te as satisfies, q as trashCell, J as windowOrigin };
+import { APP_FILE_FORMAT as $, BOX_SCALE as ee, compareVersions as te, inspectAppFile as ne, readAppFile as re, satisfies as ie } from "./app-file.js";
+import { VERSION as ae } from "./version.js";
+export { $ as APP_FILE_FORMAT, e as APP_KIND, b as BAND, ee as BOX_SCALE, x as CASCADE_SLOTS, S as CASCADE_STEP, t as DISK, n as FOLDER, C as ICON_CELL, w as ICON_COLUMN, T as ICON_INSET, E as ICON_ROW, D as NEAR, r as TRASH, i as UNTITLED_FOLDER, ae as VERSION, O as WINDOW_ORIGIN, a as appIdOf, k as cascadeFrom, A as cascadeSlot, j as cascadedBox, M as centeredBox, o as childrenOf, N as cleanUp, P as collisions, te as compareVersions, s as containerOf, c as copyName, l as createCatalog, u as descendantsOf, F as desktopLattice, d as enclosingFolders, I as fieldExtent, L as fillOrder, R as folderLattice, z as frameOf, ne as inspectAppFile, f as isContainerKind, p as isInside, B as isPin, m as isTrashed, h as isVolume, g as itemCount, _ as itemOf, V as latticeCell, H as latticeSlot, Y as localStorageState, v as memoryStorage, X as mergeSession, U as nearBox, y as nextFolderName, W as nextFreeCell, Z as openWindowsOf, G as pinOf, K as pinTo, re as readAppFile, Q as readSession, ie as satisfies, q as trashCell, J as windowOrigin };

package/dist/shell/shell.js

@@ -144,7 +144,7 @@ function d(l, d) {
 					let n = (r) => {
 						r.target === t && (t.removeEventListener("vf-close", n), e(r.detail.returnValue));
 					};
-					t.addEventListener("vf-close", n), t.show();
+					t.show(), t.addEventListener("vf-close", n);
 				});
 			},
 			gate(e, t) {

package/dist/shell/version.d.ts

@@ -1,2 +1,2 @@
 /** The kit's version, as published: package.json's `version`. `npm version` rewrites it (the `version` script). */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.18.0";

package/dist/shell/version.js

@@ -1,4 +1,4 @@
 //#region src/shell/version.ts
-var e = "0.17.0";
+var e = "0.18.0";
 //#endregion
 export { e as VERSION };

package/docs/SPEC.md

@@ -234,7 +234,7 @@ 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), `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'`, `returnValue: string` (property only, as on `<dialog>`: the dialog's answer, cleared on each open).
-- **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' }`. **Answers** (`VfModalDialog`): `close(value)` closes with `value` as `returnValue`, and a `<form method="dialog">` inside the dialog closes it on submit with the submitter's `value`, a submitter's `formmethod="dialog"` too. The platform's own rule looks for a `<dialog>` around the form, and this one is in the shadow root, so the base listens for `submit` on the host and closes at the end of the submit's path (`deferActivation`), not at all if anything cancelled it. `vf-button`'s submit proxy carries its `value` with or without a `name`. `vf-close`'s detail carries `returnValue`: the value that close carried, or null (Escape, a click outside, the close box, `close()` alone, removal). Return in a text field runs the form's implicit submission through the ringed `variant="default"` submit button when the form has one, ahead of the first in tree order, so a Cancel/OK row answers OK (`requestImplicitSubmit`). `npm run verify:dialog`, ANSWERS. 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`. **Keyboard: the Dialog Manager's two rules** (`VfModalDialog`). *Initial focus:* right after `showModal()`'s own focusing steps, focus is handed to `initialFocusTarget` — the first slotted control carrying `autofocus` or `autoselect`, else the first enabled text-entry control (`vf-text-field`, `vf-number-field`, `vf-text-area`, or a native text input/textarea), else the default button (`defaultButton`: the first enabled `vf-button[variant="default"]`, looked for among the slotted content and then the shadow tree), else nothing, leaving the browser's pick. A field marked `autoselect` has its whole text selected on every open, right after `vf-show` and once the field has rendered, so a value set before `show()` or in a `vf-show` handler is the text selected. Otherwise the modal selects no text: whether a field opens selected is the page's call. The classic dialog put the insertion point in its first text item and gave nothing else focus; the web needs a focused control, and the default button is the one that makes Return and Space work without a Tab. Left alone, `showModal()` focuses the first focusable thing in flat-tree order — Cancel in a Cancel/OK row, or a link in the body — so Return pressed the wrong thing. Both getters are `protected`, for a consumer's own modal to override. *Return/Enter:* a `keydown` listener on the `<dialog>`, bubble phase, attached while open with the light-dismiss trio. An uncancelled, unmodified Enter activates `defaultButton` (its `click()`, so a `type="submit"` default runs its proxy path) and cancels the keydown, which is what keeps a focused Cancel from firing itself — Space presses the focused control, as on the classic Mac. Anything that took Enter for itself cancelled the keydown first and is left alone: `vf-select`'s list, `vf-list`, an icon's rename, and a text field whose form ran its implicit submission (`requestImplicitSubmit` now reports whether a form owner took the press, and the fields cancel on true — so the submission runs once, not once per layer). A link keeps its own Enter. A multi-line editor (`<textarea>`, contenteditable) keeps Return for the newline; only `code === 'NumpadEnter'` fires the button there — the split a TextEdit item drew between the two keys. With no enabled default button the press is left native. Escape is unchanged (the `cancel` path above). **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.
+- **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' }`. **Answers** (`VfModalDialog`): `close(value)` closes with `value` as `returnValue`, and a `<form method="dialog">` inside the dialog closes it on submit with the submitter's `value`, a submitter's `formmethod="dialog"` too. The platform's own rule looks for a `<dialog>` around the form, and this one is in the shadow root, so the base listens for `submit` on the host and closes at the end of the submit's path (`deferActivation`), not at all if anything cancelled it. `vf-button`'s submit proxy carries its `value` with or without a `name`. `vf-close`'s detail carries `returnValue`: the value that close carried, or null (Escape, a click outside, the close box, `close()` alone, removal). Return in a text field runs the form's implicit submission through the ringed `variant="default"` submit button when the form has one, ahead of the first in tree order, so a Cancel/OK row answers OK (`requestImplicitSubmit`). `npm run verify:dialog`, ANSWERS. 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`. **Keyboard: the Dialog Manager's two rules** (`VfModalDialog`). *Initial focus:* right after `showModal()`'s own focusing steps, focus is handed to `initialFocusTarget` — the first slotted control carrying `autofocus` or `autoselect`, else the first enabled text-entry control (`vf-text-field`, `vf-number-field`, `vf-text-area`, or a native text input/textarea), else the default button (`defaultButton`: the first enabled `vf-button[variant="default"]`, looked for among the slotted content and then the shadow tree), else nothing, leaving the browser's pick. A field marked `autoselect` has its whole text selected on every open, right after `vf-show` and once the field has rendered, so a value set before `show()` or in a `vf-show` handler is the text selected. Otherwise the modal selects no text: whether a field opens selected is the page's call. The classic dialog put the insertion point in its first text item and gave nothing else focus; the web needs a focused control, and the default button is the one that makes Return and Space work without a Tab. Left alone, `showModal()` focuses the first focusable thing in flat-tree order — Cancel in a Cancel/OK row, or a link in the body — so Return pressed the wrong thing. Both getters are `protected`, for a consumer's own modal to override. *Return/Enter:* a `keydown` listener on the `<dialog>`, bubble phase, attached while open with the light-dismiss trio. An uncancelled, unmodified Enter activates `defaultButton` (its `click()`, so a `type="submit"` default runs its proxy path) and cancels the keydown, which is what keeps a focused Cancel from firing itself — Space presses the focused control, as on the classic Mac. Anything that took Enter for itself cancelled the keydown first and is left alone: `vf-select`'s list, `vf-list`, an icon's rename, and a text field whose form ran its implicit submission (`requestImplicitSubmit` now reports whether a form owner took the press, and the fields cancel on true — so the submission runs once, not once per layer). A link keeps its own Enter. A multi-line editor (`<textarea>`, contenteditable) keeps Return for the newline; only `code === 'NumpadEnter'` fires the button there — the split a TextEdit item drew between the two keys. With no enabled default button the press is left native. Escape is unchanged (the `cancel` path above). **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. **Opened again before a close's `close` event comes** — the native event is queued, so a `close()` and a `show()` in one turn do it — the open runs the funnel for that close first: its `vf-close` comes before the open's `vf-show`, and the late event finds the modal open and changes nothing, where it used to close the dialog that had just opened. That `vf-close` fires inside `show()`, so a one-time listener for the open's own answer goes on after `show()` (the shell's `ask()` does). The open drops any close value, reason or keys still pending, so a close asked for in that `vf-close` leaves nothing for a later one. `npm run verify:dialog`, REOPEN. **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`) and is the content region, with no inset of its own: the positioning anchor, so a child placed with `top`/`left` measures from the frame's inner edge, and flow content starts at the same corner. 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 holds a `.content` scroll region (the default slot; part `content`). Placed children anchor to the body, outside that scroller, so they hold still while it scrolls. While the content fits, nothing matches. Once it overflows (`ScrollStateController`, the always-a-rail machinery), the region reserves the rail's 15px as its own right padding, wears the drawn `vfScrollRail` rail (§4) flush against the frame's inner band, which supplies the cell's outer line, 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 body 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. With no bar, `heading` only names the dialog and `closable` is ignored; a title in the body is the composer's, placed like any other item.

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.17.0",
+  "version": "0.18.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintage-frames",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Lit web components that emulate the look and feel of classic Mac OS System 7",
   "type": "module",
   "license": "MIT",