vintage-frames 0.16.2 → 0.18.0

package/README.md

@@ -39,6 +39,8 @@ createShell(document.querySelector('vf-desktop'), {
 
 See [docs/SHELL.md](https://github.com/aportilla/vintage-frames/blob/main/docs/SHELL.md). Its API may change in any minor release while it is experimental.
 
+An application on the shell can ship as one PNG, its app file. `vintage-frames/build` holds the Vite plugins that write app files and build them into a site; it runs in the build only. See [docs/APP-FILES.md](https://github.com/aportilla/vintage-frames/blob/main/docs/APP-FILES.md).
+
 
 ## Sizing
 

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/app-file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Writing app files. The box's own chunks are copied as they are, so the
+ * picture is never re-encoded; any app chunks already there are dropped,
+ * and the manifest's and the code's go in before IEND.
+ */
+import type { AppManifest } from '../shell/app-file.js';
+/** What {@link packApp} packs. */
+export interface PackAppInput {
+    /** The manifest's fields but its format and icon, which the packer fills in. */
+    manifest: Omit<AppManifest, 'format' | 'icon'>;
+    /** The icon's PNG, 32 × 32. */
+    icon: Uint8Array;
+    /** The application's code: one ES module whose default export is its factory. */
+    code: string;
+    /** The artwork's PNG, for the box. Without it the icon is stamped there. */
+    artwork?: Uint8Array;
+}
+/** `box` with `manifest` and `code` in its chunks. */
+export declare function writeAppFile(box: Uint8Array, manifest: AppManifest, code: string): Promise<Uint8Array>;
+/** The whole app file: the box in the kit's frame, then the manifest and the code. */
+export declare function packApp({ manifest, icon, code, artwork }: PackAppInput): Promise<Uint8Array>;

package/dist/build/app-file.js

@@ -0,0 +1,41 @@
+import { CODE_KEYWORD as e, MANIFEST_KEYWORD as t, PNG_SIGNATURE as n, deflate as r, itxtKeyword as i, manifestOf as a, pngChunks as o } from "../shell/app-file.js";
+import { concat as s, pngChunk as c } from "./png.js";
+import { composeBox as l } from "./box.js";
+//#region src/build/app-file.ts
+var u = new TextEncoder();
+function d(e, t, n) {
+	let r = Uint8Array.from([...e].map((e) => e.charCodeAt(0)));
+	return c("iTXt", s([
+		r,
+		Uint8Array.of(0, +!!n, 0, 0, 0),
+		t
+	]));
+}
+async function f(c, l, f) {
+	let p = o(c);
+	if (!p) throw Error("vintage-frames/build: the box is not a whole PNG");
+	let m = a(l);
+	if (typeof m == "string") throw Error(`vintage-frames/build: the manifest won't read back: ${m}`);
+	let h = [d(t, u.encode(JSON.stringify(m)), !1), d(e, await r(u.encode(f)), !0)], g = [n];
+	for (let e of p) e.type === "iTXt" && ["vintage-frames.app", "vintage-frames.code"].includes(i(e.data)) || (e.type === "IEND" && g.push(...h), g.push(c.subarray(e.start, e.end)));
+	return s(g);
+}
+async function p({ manifest: e, icon: t, code: n, artwork: r }) {
+	let i = {
+		...e,
+		format: 1,
+		icon: `data:image/png;base64,${m(t)}`
+	};
+	return f(await l({
+		manifest: i,
+		icon: t,
+		artwork: r
+	}), i, n);
+}
+function m(e) {
+	let t = "";
+	for (let n = 0; n < e.length; n += 32768) t += String.fromCharCode(...e.subarray(n, n + 32768));
+	return btoa(t);
+}
+//#endregion
+export { p as packApp, f as writeAppFile };

package/dist/build/box.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The box: the picture an app file shows. The kit's frame, with the
+ * application's artwork in the artwork slot, or its icon stamped large on
+ * the slot's backdrop when there is none, and lines of text set from the
+ * kit's strikes with the manifest's fields in them. Artwork and the stamp
+ * are pasted by their alpha. Nothing is drawn outside the slots.
+ */
+import type { AppManifest } from '../shell/app-file.js';
+import type { Strike } from '../styles/strike.js';
+import type { Pixels } from './png.js';
+/** A box in a frame's picture, in its px. */
+export interface Slot {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** A frame: a picture with everything fixed drawn in, and its slots. */
+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;
+    };
+    /** The lines of text. */
+    text: readonly TextSlot[];
+}
+/** A line of text on the box. */
+export interface TextSlot {
+    /** The top-left of its em box, and the width it fits in. */
+    left: number;
+    top: number;
+    width: number;
+    strike: Strike;
+    /** Picture px per design px. */
+    scale: number;
+    /** `#rrggbb`. */
+    ink: string;
+    align?: 'left' | 'center' | 'right';
+    /** The line, with manifest fields in braces: `{name}`, `Version {version}`, `by {author}`, or fixed text. */
+    text: string;
+}
+/** What a box is composed from. */
+export interface BoxInput {
+    manifest: AppManifest;
+    /** The icon's PNG, 32 × 32. */
+    icon: Uint8Array;
+    /** 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. */
+export declare function composeBox(input: BoxInput): Promise<Uint8Array>;
+/** The box in `frame`, as pixels. */
+export declare function drawBox(frame: BoxFrame, { manifest, icon, artwork }: BoxInput): Promise<Pixels>;

package/dist/build/box.js

@@ -0,0 +1,93 @@
+import { FRAME as e } from "./frame.js";
+import { decodePng as t, encodePng as n } from "./png.js";
+//#region src/build/box.ts
+var r = [
+	"id",
+	"name",
+	"version",
+	"requires",
+	"author"
+];
+async function i(t) {
+	return n(await a(e, t));
+}
+async function a(e, { manifest: n, icon: r, artwork: i }) {
+	let a = await t(e.picture, "the frame"), c = await t(r, "the icon");
+	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 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);
+	}
+	for (let t of e.text) p(a, t, l(t.text, n));
+	return a;
+}
+function o({ width: e, height: t }) {
+	let n = [];
+	for (let r = 2; r <= e && n.length < 3; r++) e % r === 0 && t % r === 0 && n.push(`${e / r} × ${t / r}`);
+	return [...n, "…"].join(", ");
+}
+function s(e, t, n, r, i, a) {
+	let o = Math.max(n, a.left, 0), s = Math.max(r, a.top, 0), l = Math.min(n + t.width * i, a.left + a.width, e.width), u = Math.min(r + t.height * i, a.top + a.height, e.height);
+	for (let a = s; a < u; a++) for (let s = o; s < l; s++) {
+		let o = (Math.floor((a - r) / i) * t.width + Math.floor((s - n) / i)) * 4;
+		c(e, s, a, t.data.subarray(o, o + 4));
+	}
+}
+function c(e, t, n, [r, i, a, o]) {
+	if (!o) return;
+	let s = e.data, c = (n * e.width + t) * 4;
+	if (o === 255) {
+		s[c] = r, s[c + 1] = i, s[c + 2] = a, s[c + 3] = 255;
+		return;
+	}
+	let l = s[c + 3] * (255 - o) / 255, u = o + l;
+	s[c] = Math.round((r * o + s[c] * l) / u), s[c + 1] = Math.round((i * o + s[c + 1] * l) / u), s[c + 2] = Math.round((a * o + s[c + 2] * l) / u), s[c + 3] = Math.round(u);
+}
+function l(e, t) {
+	return e.replace(/\{(\w+)\}/g, (n, i) => {
+		let a = r.find((e) => e === i);
+		if (!a) throw Error(`the frame's line "${e}" names {${i}}, which a manifest doesn't have`);
+		return t[a];
+	});
+}
+var u = (e) => `"${e}" (U+${e.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")})`, d = (e, t) => [...t].reduce((t, n) => t + e.glyphs[n].advance, 0);
+function f(e, t, n) {
+	if (d(e, t) <= n) return t;
+	if (!e.glyphs["…"]) throw Error(`${e.family} has no ${u("…")} to shorten "${t}" with`);
+	let r = [...t];
+	for (; r.length && d(e, r.join("").trimEnd() + "…") > n;) r.pop();
+	return r.join("").trimEnd() + "…";
+}
+function p(e, t, n) {
+	let { strike: r, scale: i } = t;
+	for (let e of n) if (!r.glyphs[e]) throw Error(`${r.family} has no ${u(e)}, in "${n}"`);
+	let a = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(t.ink);
+	if (!a) throw Error(`the frame's ink "${t.ink}" is not #rrggbb`);
+	let o = Uint8Array.of(parseInt(a[1], 16), parseInt(a[2], 16), parseInt(a[3], 16), 255), s = f(r, n, t.width / i), l = d(r, s) * i, p = t.align === "center" ? Math.floor((t.width - l) / 2 / i) * i : t.align === "right" ? t.width - l : 0, m = {
+		left: t.left,
+		top: t.top,
+		width: t.width,
+		height: (r.ascent + r.descent) * i
+	}, h = t.top + r.ascent * i, g = t.left + p;
+	for (let t of s) {
+		let n = r.glyphs[t];
+		n.rows.forEach((t, r) => {
+			let a = h - (n.y0 + n.height - r) * i;
+			for (let r = 0; r < t.length; r++) {
+				if (t[r] !== "#") continue;
+				let s = g + (n.x0 + r) * i;
+				for (let t = Math.max(a, m.top, 0); t < Math.min(a + i, m.top + m.height, e.height); t++) for (let n = Math.max(s, m.left, 0); n < Math.min(s + i, m.left + m.width, e.width); n++) c(e, n, t, o);
+			}
+		}), g += n.advance * i;
+	}
+}
+//#endregion
+export { i as composeBox, a as drawBox };

package/dist/build/client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `vintage-frames/build/client`: the types of a `*.png?app` import, which
+ * `appFiles()` serves. A site adds it to tsconfig's `types` beside
+ * `vite/client`.
+ */
+declare module '*.png?app' {
+    /** The application's factory: its definition, given the manifest's icon. */
+    const app: (...args: any[]) => import('../shell/index.js').AppDefinition<any>;
+    export default app;
+    /** The app file's manifest. */
+    export const manifest: import('../shell/pure.js').AppManifest;
+}

package/dist/build/frame-picture.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The kit's frame's picture: box/frame.png, 480 × 615, 3095 bytes.
+ * GENERATED by `npm run embed:frame`: redraw box/frame.png and re-run rather
+ * than editing this file. Its slots are src/build/frame.ts's.
+ */
+export declare const FRAME_PNG: Uint8Array;

package/dist/build/frame-picture.js

@@ -0,0 +1,4 @@
+//#region src/build/frame-picture.ts
+var e = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAeAAAAJnCAYAAABPiYBoAAAL3klEQVR42u3VwQkAIAwEwfRfW3rSBnwJBuFmYQpQAldVtQCAcT4BAAwwAKQNsCRJepcBliTJAEuSZIAlSZIBliTJAEuSJAMsSZIBliRJBliSJAMsSZIMsCRJBliSJAMsSZIMsCRJBliSJBlgSZIMsCRJMsCSJBlgSZJkgCVJMsCSJBlgAyxJkgGWJMkAS5IkAyxJkgGWJEkGWJIkAyxJkgywJEkGWJIkA2yAJUkywJIkGWBJkmSAJUkywJIkyQBLkmSAJUmSAZYkyQBLkmSADbAkSQZYkiQDLEmSDPDxAQCEM8AGGAADbIABMMAG+NEDuhuAQAbYAANggA0wAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADTAABtgAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMAAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA0wAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADTAABtgAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMAAG2AADYIANsCMEMMAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wgAE2wAYYAANsgAEwwAbYAANggA0wAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAAQywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAG2AADLABBsAAG2ADDGCADbABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2AADYIANMAAG2AAbYAADbIANMAAG2AADYIANsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYAANsgAEwwAbYAANggA0wAAbYAANggA2wAQbAABtgAAywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAA2CADbABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2AADYIANMAAG2AADYIANsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYAANsgAEwwAbYAANggA0wAAbYAANggA2wAQbAABtgAAywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAO0IAA2yADTAABtgAA2CADbABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2BECGGADbIABMMAGGAADbIANMAAG2AADYIANsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA2wAQbAABtgAAywATbAAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADbABBjDABtgAA2CADTAABtgAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMAAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA0wAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADTAABtgAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMAAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA0wAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADbAjBDDABtgAA2CADTAABtgAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMIABNsAGGAADbIABMMAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEMsAE2wAAYYAMMgAE2wAYYAANsgAEwwAbYAANggA0wAAbYABtgAAywAQbAABtgAwxggA2wAQbAABtgAAywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAG2AADLABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYAANsgAEwwAbYAANggA0wAAbYABtgAAywAQbAABtgAAywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAG2AADLABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2AADYIANMAAG2AAbYAAMsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYAANsgAEwwAbYAANggA0wAAbYABtgAAywAQbAABtgRwhggA2wAQbAABtgAAywATbAABhgAwyAATbABhgAA2yAATDABtgAA2CADTAABtgAG2AAA2yADTAABtgAA2CADbABBsAAG2AADLABNsAAGGADDIABNsAGGAADbIABMMAG2AADGGADbIABMMAGGAADbIANMAAG2AADYIANsAEGwAAbYAAMsAE2wAAYYAMMgAE2wAYYwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA2wAQbAABtgAAywATbAAAbYABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADbABBsAAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbIANMAAG2AADYIANsAEGwAAbYAAMsAEGwAAbYAMMgAE2wAAYYANsgAEwwAYYAANsgA0wAAbYAANggA2wAQbAABtgAAywAQbAABtgAwyAATbAABhgA2yAATDABhgAA2yADTAABtgAA2CADbABBsAAG2AADLABBsAAG2ADDIABNsAAGGADbIABMMAGGAADbICvHwBAOANsgAEwwAYYAANsgCVJCs8AS5JkgCVJMsCSJMkAS5JkgCVJkgGWJMkAS5IkAyxJkgGWJEkGWJIkAyxJkgGWJEkGWJIkAyxJkgywJEkGWJIkGWBJkgywJEkywJIkGWBJkgywAZYkyQBLkmSAJUmSAZYkyQBLkiQDLEmSAZYkSQZYkiQDLEmSATbAkiQZYEmSDLAkSTLAkiQZYEmSZIAlSTLAkiTJAEuSZIAlSTLABliSJAMsSZIBliRJBliSJAMsSZIMsCRJBliSJBlgSZIMsCRJBtgAS5JkgCVJMsCSJMkAS5JkgCVJkgGWJMkAS5IkAyxJkgGWJMkAG2BJkgywJEkGWJIkGWBJkgywJEkywJIkGWBJkmSAJUkywJIkGWADLEmSAZYkyQBLkiQDLEmSAZYkSQZYkiQDLEmSDLAkSQZYkiQDbIAlSTLAkiQZYEmSZIAlSTLAkiTJAEuSZIAlSZIBliTJAEuSZIANsCRJBliSJAMsSZIMsCRJBliSJBlgSZIMsCRJMsCSJBlgSZJkgCVJMsCSJBlgSZJkgCVJMsCSJMkAS5JkgCVJkgGWJMkAS5IkAyxJkgGWJMkAG2BJkgywJEkGWJIkGWBJkgywJEkywJIkGWBJkmSAJUkywJIkGWADLEmSAZYkyQBLkiQDLEmSAZYkSQZYkiQDLEmSDLAkSQZYkiQDbIAlSTLAkiQZYEmSZIAlSTLAkiTJAEuSZIAlSZIBliTJAEuSZIANsCRJBliSJAMsSZIMsCRJBliSJBlgSZIMsCRJMsCSJBlgSZIMsAGWJMkAS5JkgCVJkgGWJMkAS5IkAyxJkgGWJEkGWJIkAyxJkgE2wJIkGWBJkgywJEkywJIkGWBJkmSAJUkywJIkyQBLkmSAJUkywAZYkiQDLEmSAZYkSQZYkiQDLEmSDLAkSQZYkiQZYEmSDLAkSQbYAEuSZIAlSTLAkiTJAEuSZIAlSZIBliTJAEuSJAMsSZIBliRJBliSpK8GGAAY4xMAwAADQIANOM+x56UXUawAAAAASUVORK5CYII="), (e) => e.charCodeAt(0));
+//#endregion
+export { e as FRAME_PNG };

package/dist/build/frame.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The kit's frame: the picture every app file's box is drawn on, and its
+ * slots, in the picture's px. A placeholder: a white card on 160 × 205
+ * system px drawn at 3×, the artwork's slot on a gray backdrop inside a
+ * black rule, then the name, the version and the author, centered.
+ *
+ * The picture is box/frame.png (`npm run embed:frame`). A redrawn picture
+ * moves its slots here.
+ */
+import type { BoxFrame } from './box.js';
+export declare const FRAME: BoxFrame;

package/dist/build/frame.js

@@ -0,0 +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 = 3, i = {
+	left: 16 * r,
+	width: 128 * r,
+	scale: r,
+	ink: "#000000",
+	align: "center"
+}, a = {
+	picture: n,
+	scale: r,
+	artwork: {
+		left: 16 * r,
+		top: 16 * r,
+		width: 128 * r,
+		height: 128 * r,
+		stamp: 3 * r
+	},
+	text: [
+		{
+			...i,
+			top: 152 * r,
+			strike: t,
+			text: "{name}"
+		},
+		{
+			...i,
+			top: 170 * r,
+			strike: e,
+			text: "Version {version}"
+		},
+		{
+			...i,
+			top: 182 * r,
+			strike: e,
+			text: "by {author}"
+		}
+	]
+};
+//#endregion
+export { a as FRAME };

package/dist/build/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `vintage-frames/build` — app files, written: the Vite plugin that makes an
+ * application's build write its app file, the one that builds app files
+ * into a site, and the pieces under them: the packer, the writer and the box
+ * in the kit's frame. Build-only: it runs under Node, and no page imports
+ * it. Reading an app file is `vintage-frames/shell/pure`'s.
+ * docs/APP-FILES.md is the guide.
+ */
+export { appFile, appFiles } from './plugins.js';
+export type { AppFileOptions } from './plugins.js';
+export { packApp, writeAppFile } from './app-file.js';
+export type { PackAppInput } from './app-file.js';
+export { composeBox } from './box.js';
+export type { BoxInput } from './box.js';

package/dist/build/index.js

@@ -0,0 +1,4 @@
+import { composeBox as e } from "./box.js";
+import { packApp as t, writeAppFile as n } from "./app-file.js";
+import { appFile as r, appFiles as i } from "./plugins.js";
+export { r as appFile, i as appFiles, e as composeBox, t as packApp, n as writeAppFile };

package/dist/build/plugins.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Vite plugins. `appFile()` makes an application's build write its app
+ * file; `appFiles()` builds app files into a site.
+ */
+import type { Plugin } from 'vite';
+export interface AppFileOptions {
+    /** 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 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;
+}
+/**
+ * Makes an application's build write its app file, `dist/<name>.png`. It
+ * builds the entry as a library, one ES module with the kit's entries left
+ * as imports, and fails the build when the bundle breaks a rule: CSS or any
+ * other file beside the code, more than one module, Lit or the kit bundled
+ * in, or an import of anything but the kit's three entries. `npm run dev`
+ * is untouched.
+ */
+export declare function appFile(options: AppFileOptions): Plugin;
+/**
+ * Builds app files into a site. An import of `*.png?app` reads the file and
+ * refuses one that isn't an app file, or whose `requires` this kit's
+ * version doesn't meet. Its default export is the application's factory,
+ * its definition given the manifest's icon, and `manifest` is the manifest.
+ * The code imports the kit by name, so the page keeps one copy of it. A new
+ * file reloads the dev server's page.
+ */
+export declare function appFiles(): Plugin;

package/dist/build/plugins.js

@@ -0,0 +1,131 @@
+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 d = [
+	"vintage-frames",
+	"vintage-frames/shell",
+	"vintage-frames/shell/pure"
+], 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 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 h(e) {
+	let { app: l, entry: f, icon: h, artwork: g, copyTo: _ } = e;
+	for (let e of [
+		"id",
+		"name",
+		"version",
+		"author"
+	]) 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: f,
+				formats: ["es"],
+				fileName: "app"
+			},
+			copyPublicDir: !1,
+			rolldownOptions: {
+				external: /^vintage-frames(?:\/|$)/,
+				output: { codeSplitting: !1 }
+			}
+		} }),
+		configResolved(e) {
+			y = e.root;
+		},
+		buildStart() {
+			for (let e of [
+				h,
+				g,
+				"package.json"
+			]) e && this.addWatchFile(u(y, e));
+		},
+		generateBundle: {
+			order: "post",
+			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 _ = [...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 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: l.id,
+							name: l.name,
+							version: l.version,
+							requires: e,
+							author: l.author,
+							description: l.description
+						},
+						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(`${l.name}: ${e.message}`);
+				}
+				delete t[f.fileName], this.emitFile({
+					type: "asset",
+					fileName: v,
+					source: b
+				});
+			}
+		},
+		async writeBundle() {
+			if (!_ || !b) return;
+			let e = u(y, _);
+			await a(e, { recursive: !0 }), await s(c(e, v), b);
+		}
+	};
+}
+function g() {
+	let t = "";
+	return {
+		name: "vintage-frames:app-files",
+		enforce: "pre",
+		configResolved(e) {
+			t = e.root;
+		},
+		async load(i) {
+			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 = 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 })",
+				""
+			].join("\n"));
+		}
+	};
+}
+//#endregion
+export { h as appFile, g as appFiles };