vintage-frames 0.17.0 → 0.19.0

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

@@ -4,13 +4,27 @@
  * 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
- * 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.
+ * This is the reading half: the reader, checking a version against a range,
+ * putting versions in order, the app API levels and whether this kit runs an
+ * application, 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;
+/**
+ * The app API this kit provides: the level of what a built application can
+ * use of it. It goes up when something in it changes or goes away, and never
+ * for an addition. app-api.json lists what it covers.
+ */
+export declare const APP_API = 2;
+/** The oldest app API this kit still runs. */
+export declare const APP_API_OLDEST = 2;
+/**
+ * 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";
@@ -23,7 +37,11 @@ export interface AppManifest {
     version: string;
     /** The kit range the code was built and checked against: `^0.17.0`. */
     requires: string;
+    /** The app API the code was built against, {@link APP_API}. A file from before levels has none. */
+    api?: number;
     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 +80,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
@@ -75,3 +107,9 @@ export declare function readAppFile(bytes: Uint8Array): Promise<AppFile | null>;
  * false.
  */
 export declare function satisfies(version: string, range: string): boolean;
+/**
+ * Whether this kit runs the application a manifest describes: one built at
+ * an app API from {@link APP_API_OLDEST} to {@link APP_API}, or, for a file
+ * from before levels, one whose `requires` this kit's version meets.
+ */
+export declare function appRuns(manifest: Pick<AppManifest, 'requires' | 'api'>): boolean;

package/dist/shell/app-file.js

@@ -1,27 +1,30 @@
+import { VERSION as e } from "./version.js";
 //#region src/shell/app-file.ts
-var e = 1, t = "vintage-frames.app", n = "vintage-frames.code", r = [
+var t = 1, n = 2, r = 2, i = 3, a = "vintage-frames.app", o = "vintage-frames.code", s = [
 	"id",
 	"name",
 	"version",
 	"requires",
+	"api",
 	"author",
+	"description",
 	"icon"
-], i = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10), a = Uint32Array.from({ length: 256 }, (e, t) => {
+], c = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10), l = 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 u(e) {
 	let t = 4294967295;
-	for (let n of e) t = a[(t ^ n) & 255] ^ t >>> 8;
+	for (let n of e) t = l[(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 d(e) {
+	if (e.length < 8 || c.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 || u(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 +36,91 @@ function s(e) {
 	}
 	return null;
 }
-function c(e) {
+function f(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 p = new TextDecoder("utf-8", { fatal: !0 });
+async function m(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 p.decode(n ? await h(o) : o);
 }
-async function d(e) {
+async function h(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 g(e) {
 	let t = new Blob([e.slice()]).stream().pipeThrough(new CompressionStream("deflate"));
 	return new Uint8Array(await new Response(t).arrayBuffer());
 }
-function p(e) {
+function _(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 s) {
 		let r = t[e];
+		if (e === "api") {
+			if (r === void 0) continue;
+			if (!Number.isInteger(r) || r < 1) return `its api, ${JSON.stringify(r)}, is not a level`;
+			n.api = r;
+			continue;
+		}
+		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" && !S(r)) return `its version, ${r}, is not a version`;
+		if (e === "requires" && !C(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";
-	let i = /* @__PURE__ */ new Map();
-	for (let { type: e, data: t } of r) {
+async function v(e) {
+	let t = d(e);
+	if (!t) return "it is not a whole PNG";
+	let n = /* @__PURE__ */ new Map();
+	for (let { type: e, data: r } 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 = f(r);
+		if (t === "vintage-frames.app" || t === "vintage-frames.code") {
+			if (n.has(t)) return `it has two ${t} chunks`;
+			n.set(t, r);
 		}
 	}
-	let a = i.get(t), o = i.get(n);
-	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 r = n.get(a), i = n.get(o);
+	if (!r && !i) return "it carries no application";
+	if (!r) return "its manifest is missing";
+	if (!i) return "its code is missing";
+	let s;
 	try {
-		l = JSON.parse(await u(a));
+		s = JSON.parse(await m(r));
 	} catch {
 		return "its manifest does not read";
 	}
-	let d = p(l);
-	if (typeof d == "string") return d;
+	let c = _(s);
+	if (typeof c == "string") return c;
 	try {
 		return {
-			manifest: d,
-			code: await u(o)
+			manifest: c,
+			code: await m(i)
 		};
 	} catch {
 		return "its code does not inflate";
 	}
 }
-async function h(e) {
-	let t = await m(e);
+async function y(e) {
+	let t = await v(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 b = /^(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 x(e) {
+	if (typeof e != "string") return null;
+	let t = b.exec(e.trim().replace(/^v/, ""));
 	return t ? {
 		core: [
 			Number(t[1]),
@@ -121,7 +130,18 @@ function _(e) {
 		pre: t[4] ? t[4].split(".") : []
 	} : null;
 }
-function v(e, t) {
+function S(e) {
+	return b.test(e);
+}
+function C(e) {
+	return S(e.startsWith("^") ? e.slice(1) : e);
+}
+function w(e) {
+	if (typeof e != "string") return null;
+	let t = e.trim();
+	return x(t.startsWith("^") ? t.slice(1) : t);
+}
+function T(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 +154,36 @@ 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 E(e, t) {
+	let n = x(e), r = x(t);
+	return n && r ? T(n, r) : !!n - +!!r;
+}
+function D(e, t) {
+	let n = x(e), r = w(t);
+	if (!n || !r) return !1;
+	if (!t.trim().startsWith("^")) return T(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 T(n, r) >= 0 && T(n, s) < 0;
+}
+function O(t) {
+	let { api: n } = t;
+	return n === void 0 ? D(e, t.requires) : Number.isInteger(n) && n >= 2 && n <= 2;
 }
 //#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 { n as APP_API, r as APP_API_OLDEST, t as APP_FILE_FORMAT, i as BOX_SCALE, o as CODE_KEYWORD, a as MANIFEST_KEYWORD, c as PNG_SIGNATURE, O as appRuns, E as compareVersions, u as crc32, g as deflate, h as inflate, v as inspectAppFile, S as isVersion, f as itxtKeyword, _ as manifestOf, d as pngChunks, y as readAppFile, D as satisfies };

package/dist/shell/catalog.d.ts

@@ -13,6 +13,12 @@
  *   never renamed, moved, copied or removed; nothing is made in the Trash.
  *   Deleting is a move into the Trash, and only Empty Trash removes. A
  *   volume's position is stored on a record of its own id.
+ * - The System Folder is kept the same way when the site names it: a folder
+ *   on the startup disk (the desktop without one) holding Apple Menu Items
+ *   and Startup Items, listed after the volumes. What they hold is anyone's,
+ *   and the shell reads it: the Apple menu, and what opens at startup.
+ * - An alias stands for another item: its data names the original's id, and
+ *   `resolve` finds the original wherever it moved, until it is removed.
  * - A folder never goes into itself or a folder inside it. A parent with no
  *   record reads as the desktop.
  * - An item whose kind no application registers is left out of the listing
@@ -30,17 +36,25 @@ import type { Point } from './geometry.js';
 export declare const TRASH = "trash";
 /** The startup disk's id. */
 export declare const DISK = "disk";
+/** The System Folder's id: kept on the startup disk when the site names it. */
+export declare const SYSTEM_FOLDER = "system-folder";
+/** Apple Menu Items' id, in the System Folder: what it holds is the Apple menu. */
+export declare const APPLE_MENU_ITEMS = "apple-menu-items";
+/** Startup Items' id, in the System Folder: what it holds opens at startup. */
+export declare const STARTUP_ITEMS = "startup-items";
 /** A folder's kind. */
 export declare const FOLDER = "folder";
 /** An application's icon: the kind the shell registers, whose data names the application it opens. */
 export declare const APP_KIND = "app";
+/** An alias: the kind the shell registers, whose data names the item it stands for. */
+export declare const ALIAS_KIND = "alias";
 /** The name a new folder takes, counted up where it is taken. */
 export declare const UNTITLED_FOLDER = "untitled folder";
 /** One item of the catalog. */
 export interface Item {
     id: string;
     name: string;
-    /** `folder`, a volume's (`trash`, `disk`), the shell's `app`, or a kind an application registers. */
+    /** `folder`, a volume's (`trash`, `disk`), the shell's `app` or `alias`, or a kind an application registers. */
     kind: string;
     /** A folder's id, a volume's, or null for the desktop. */
     parent: string | null;
@@ -78,9 +92,17 @@ export interface Volumes {
     trash?: string | false;
     disk?: string | false;
 }
+/** The System Folder and its two folders, by name. A site that names them has them. */
+export interface SystemFolders {
+    folder: string;
+    appleMenu: string;
+    startup: string;
+}
 export interface CatalogOptions {
     storage: CatalogStorage | null;
     volumes?: Volumes;
+    /** The System Folder, on the startup disk. Unset, none. */
+    system?: SystemFolders;
     /** Whether an application registers `kind`. Folders are always listed. Default: every kind. */
     listed?(kind: string): boolean;
     /** A kind's payload hooks. */
@@ -109,10 +131,22 @@ export interface CatalogArchive {
 export declare const isContainerKind: (kind: string) => boolean;
 /** Whether `id` names a volume. */
 export declare const isVolume: (id: string | null | undefined) => boolean;
+/**
+ * Whether `id` names a container the catalog keeps, never renamed, moved,
+ * copied or removed: a volume, the System Folder or a folder in it.
+ */
+export declare const isKept: (id: string | null | undefined) => boolean;
 /** The application an `app` item stands for: its `data.app`, or null. */
 export declare function appIdOf(item: Item): string | null;
+/** The id of the item an alias stands for: its `data.original`, or null for anything but an alias. */
+export declare function originalOf(item: Item): string | null;
 /** The item with `id`, or null. */
 export declare function itemOf(state: CatalogState, id: string | null | undefined): Item | null;
+/**
+ * The item `id` names, or the original an alias stands for, through an alias
+ * of an alias too. Null once the original is gone, and for a chain that loops.
+ */
+export declare function resolve(state: CatalogState, id: string | null | undefined): Item | null;
 /** The container `parent` resolves to: that container while it is listed, else the desktop (null). */
 export declare function containerOf(state: CatalogState, parent: string | null | undefined): string | null;
 /** The items directly in a container (null: the desktop), in listing order. */
@@ -142,6 +176,12 @@ export declare function nextFolderName(state: CatalogState, parent: string | nul
  * then " copy 2", " copy 3", …
  */
 export declare function copyName(state: CatalogState, parent: string | null, name: string, kind: string): string;
+/** The name for an alias of `name` in a container: "name alias", then "name alias 2", … while an alias there has it. */
+export declare function aliasName(state: CatalogState, parent: string | null, name: string): string;
+/** What Apple Menu Items holds, by name: the Apple menu's entries. None without the System Folder. */
+export declare const appleMenuItemsOf: (state: CatalogState) => Item[];
+/** What Startup Items holds, by name: what opens at startup. None without the System Folder. */
+export declare const startupItemsOf: (state: CatalogState) => Item[];
 /** The catalog's operations, over its listing. */
 export interface Catalog {
     get(): CatalogState;