vintage-frames 0.16.2 → 0.17.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/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,55 @@
+/**
+ * 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;
+    /** 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, 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,90 @@
+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 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);
+	} 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,42 @@
+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,
+	ink: "#000000",
+	align: "center"
+}, i = {
+	picture: n,
+	artwork: {
+		left: 48,
+		top: 48,
+		width: 384,
+		height: 384,
+		stamp: 8
+	},
+	text: [
+		{
+			...r,
+			top: 456,
+			strike: t,
+			text: "{name}"
+		},
+		{
+			...r,
+			top: 510,
+			strike: e,
+			text: "Version {version}"
+		},
+		{
+			...r,
+			top: 546,
+			strike: e,
+			text: "by {author}"
+		}
+	]
+};
+//#endregion
+export { i 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,40 @@
+/**
+ * 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: its `app.ts`. */
+    app: {
+        id: string;
+        name: string;
+        version: string;
+        author: 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. */
+    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,129 @@
+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";
+//#region src/build/plugins.ts
+var u = [
+	"vintage-frames",
+	"vintage-frames/shell",
+	"vintage-frames/shell/pure"
+], d = "app-code";
+function f(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;
+}
+function m(e) {
+	let { app: c, entry: d, icon: m, artwork: h, copyTo: g } = 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;
+	return {
+		name: "vintage-frames:app-file",
+		apply: "build",
+		config: () => ({ build: {
+			lib: {
+				entry: d,
+				formats: ["es"],
+				fileName: "app"
+			},
+			copyPublicDir: !1,
+			rolldownOptions: {
+				external: /^vintage-frames(?:\/|$)/,
+				output: { codeSplitting: !1 }
+			}
+		} }),
+		configResolved(e) {
+			v = e.root;
+		},
+		buildStart() {
+			for (let e of [
+				m,
+				h,
+				"package.json"
+			]) e && this.addWatchFile(l(v, 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.`);
+				}
+				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.`);
+				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({
+						manifest: {
+							id: c.id,
+							name: c.name,
+							version: c.version,
+							requires: e,
+							author: c.author
+						},
+						icon: new Uint8Array(await a(l(v, m))),
+						code: g.code,
+						artwork: h ? new Uint8Array(await a(l(v, h))) : void 0
+					});
+				} catch (e) {
+					this.error(`${c.name}: ${e.message}`);
+				}
+				delete i[g.fileName], this.emitFile({
+					type: "asset",
+					fileName: _,
+					source: y
+				});
+			}
+		},
+		async writeBundle() {
+			if (!g || !y) return;
+			let e = l(v, g);
+			await i(e, { recursive: !0 }), await o(s(e, _), y);
+		}
+	};
+}
+function h() {
+	let r = "";
+	return {
+		name: "vintage-frames:app-files",
+		enforce: "pre",
+		configResolved(e) {
+			r = 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;
+			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}`)}`,
+				`export const manifest = ${JSON.stringify(p)}`,
+				"export default (...args) => ({ ...factory(...args), icon: manifest.icon })",
+				""
+			].join("\n"));
+		}
+	};
+}
+//#endregion
+export { m as appFile, h as appFiles };

package/dist/build/png.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PNG pixels, with no canvas and no dependency: a decoder for the forms art
+ * comes in, and an encoder for the box.
+ *
+ * - Decoding takes 8-bit gray, RGB, gray with alpha and RGBA, and indexed
+ *   or gray at 1, 2, 4 or 8 bits, non-interlaced, with their transparency.
+ *   16-bit and interlaced files are refused, naming what to save them as.
+ * - Encoding writes 8-bit RGBA, each row filtered the way that compresses
+ *   it best.
+ */
+/** Straight RGBA, 8 bits a channel, rows top first. */
+export interface Pixels {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** `parts`, end to end. */
+export declare function concat(parts: readonly Uint8Array[]): Uint8Array;
+/** One chunk, with its length and CRC. */
+export declare function pngChunk(type: string, data: Uint8Array): Uint8Array;
+/** A PNG's pixels. `what` names it in an error: "the artwork". */
+export declare function decodePng(bytes: Uint8Array, what?: string): Promise<Pixels>;
+/** Pixels as an 8-bit RGBA PNG. */
+export declare function encodePng({ width, height, data }: Pixels): Promise<Uint8Array>;

package/dist/build/png.js

@@ -0,0 +1,116 @@
+import { PNG_SIGNATURE as e, crc32 as t, deflate as n, inflate as r, pngChunks as i } from "../shell/app-file.js";
+//#region src/build/png.ts
+var a = {
+	0: 1,
+	2: 3,
+	3: 1,
+	4: 2,
+	6: 4
+};
+function o(e) {
+	let t = new Uint8Array(e.reduce((e, t) => e + t.length, 0)), n = 0;
+	for (let r of e) t.set(r, n), n += r.length;
+	return t;
+}
+function s(e, n) {
+	let r = new Uint8Array(12 + n.length), i = new DataView(r.buffer);
+	i.setUint32(0, n.length);
+	for (let t = 0; t < 4; t++) r[4 + t] = e.charCodeAt(t);
+	return r.set(n, 8), i.setUint32(8 + n.length, t(r.subarray(4, 8 + n.length))), r;
+}
+async function c(e, t = "the PNG") {
+	let n = i(e), s = n?.[0];
+	if (!n || s?.type !== "IHDR" || s.data.length !== 13) throw Error(`${t} is not a whole PNG`);
+	let c = new DataView(s.data.buffer, s.data.byteOffset, 13), l = c.getUint32(0), u = c.getUint32(4), [f, p, m, h, g] = s.data.subarray(8);
+	if (f === 16) throw Error(`${t} is a 16-bit PNG: save it as an 8-bit PNG`);
+	if (g) throw Error(`${t} is interlaced: save it as a non-interlaced PNG`);
+	let _ = a[p], v = p === 0 || p === 3 ? [
+		1,
+		2,
+		4,
+		8
+	].includes(f) : f === 8;
+	if (!_ || !v || m || h) throw Error(`${t} is a kind of PNG this kit doesn't read (color type ${p}, ${f} bits): save it as an 8-bit PNG`);
+	let y = null, b = null, x = [];
+	for (let { type: e, data: t } of n) e === "PLTE" ? y = t : e === "tRNS" ? b = t : e === "IDAT" && x.push(t);
+	if (p === 3 && !y) throw Error(`${t} is indexed and has no palette`);
+	let S = _ * f, C = Math.ceil(l * S / 8), w = await r(o(x)).catch(() => {
+		throw Error(`${t} is not a whole PNG`);
+	});
+	if (w.length < u * (C + 1)) throw Error(`${t} is not a whole PNG`);
+	let T = d(w, u, C, Math.max(1, S >> 3), t), E = (1 << f) - 1, D = (e, t) => {
+		let n = t * f;
+		return T[e + (n >> 3)] >> 8 - f - (n & 7) & E;
+	}, O = (e) => b && b.length >= e * 2 + 2 ? b[e * 2] << 8 | b[e * 2 + 1] : -1, k = new Uint8Array(l * u * 4);
+	for (let e = 0; e < u; e++) {
+		let n = e * C;
+		for (let r = 0; r < l; r++) {
+			let i = (e * l + r) * 4;
+			if (p === 0) {
+				let e = f === 8 ? T[n + r] : D(n, r);
+				k[i] = k[i + 1] = k[i + 2] = Math.round(e * 255 / E), k[i + 3] = e === O(0) ? 0 : 255;
+			} else if (p === 3) {
+				let e = f === 8 ? T[n + r] : D(n, r);
+				if (e * 3 + 2 >= y.length) throw Error(`${t} uses a color its palette lacks`);
+				k[i] = y[e * 3], k[i + 1] = y[e * 3 + 1], k[i + 2] = y[e * 3 + 2], k[i + 3] = b?.[e] ?? 255;
+			} else if (p === 2) {
+				let e = n + r * 3;
+				k.set(T.subarray(e, e + 3), i);
+				let t = T[e] !== O(0) || T[e + 1] !== O(1) || T[e + 2] !== O(2);
+				k[i + 3] = t ? 255 : 0;
+			} else if (p === 4) {
+				let e = n + r * 2;
+				k[i] = k[i + 1] = k[i + 2] = T[e], k[i + 3] = T[e + 1];
+			} else k.set(T.subarray(n + r * 4, n + r * 4 + 4), i);
+		}
+	}
+	return {
+		width: l,
+		height: u,
+		data: k
+	};
+}
+function l(e, t, n) {
+	let r = e + t - n, i = Math.abs(r - e), a = Math.abs(r - t), o = Math.abs(r - n);
+	return i <= a && i <= o ? e : a <= o ? t : n;
+}
+function u(e, t, n, r) {
+	return e === 1 ? t : e === 2 ? n : e === 3 ? t + n >> 1 : e === 4 ? l(t, n, r) : 0;
+}
+function d(e, t, n, r, i) {
+	let a = new Uint8Array(t * n);
+	for (let o = 0; o < t; o++) {
+		let t = e[o * (n + 1)];
+		if (t > 4) throw Error(`${i} is not a whole PNG`);
+		let s = o * (n + 1) + 1, c = o * n;
+		for (let i = 0; i < n; i++) {
+			let l = i >= r ? a[c + i - r] : 0, d = o ? a[c - n + i] : 0, f = i >= r && o ? a[c - n + i - r] : 0;
+			a[c + i] = e[s + i] + u(t, l, d, f) & 255;
+		}
+	}
+	return a;
+}
+async function f({ width: t, height: r, data: i }) {
+	let a = t * 4, c = new Uint8Array(r * (a + 1)), l = Array.from({ length: 5 }, () => new Uint8Array(a));
+	for (let e = 0; e < r; e++) {
+		let t = e * a, n = 0, r = Infinity;
+		for (let o = 0; o < 5; o++) {
+			let s = l[o], c = 0;
+			for (let n = 0; n < a; n++) {
+				let r = n >= 4 ? i[t + n - 4] : 0, l = e ? i[t - a + n] : 0, d = n >= 4 && e ? i[t - a + n - 4] : 0, f = i[t + n] - u(o, r, l, d) & 255;
+				s[n] = f, c += f < 128 ? f : 256 - f;
+			}
+			c < r && (r = c, n = o);
+		}
+		c[e * (a + 1)] = n, c.set(l[n], e * (a + 1) + 1);
+	}
+	let d = /* @__PURE__ */ new Uint8Array(13), f = new DataView(d.buffer);
+	return f.setUint32(0, t), f.setUint32(4, r), d[8] = 8, d[9] = 6, o([
+		e,
+		s("IHDR", d),
+		s("IDAT", await n(c)),
+		s("IEND", /* @__PURE__ */ new Uint8Array())
+	]);
+}
+//#endregion
+export { o as concat, c as decodePng, f as encodePng, s as pngChunk };