vintage-frames 0.14.0 → 0.14.1

package/dist/shell/geometry.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The shell's geometry, pure and DOM-free: boxes in whole system px, the
+ * window cascade, the nine-slice pin that carries windows and icons through
+ * a raster resize, and the icon lattices that new items and Clean Up place
+ * on. Every function takes the area it works in — a desktop's work area, a
+ * folder's plane — so nothing here knows a menu bar's height.
+ */
+/** A point in whole system px. */
+export interface Point {
+    left: number;
+    top: number;
+}
+/** A size in whole system px. */
+export interface Size {
+    width: number;
+    height: number;
+}
+/** A box in whole system px. */
+export interface Box extends Point, Size {
+}
+/** How far each cascaded window steps down and right, system px. */
+export declare const CASCADE_STEP = 24;
+/** How many slots a cascade has before it wraps. */
+export declare const CASCADE_SLOTS = 5;
+/** A cascade's step and slot count. */
+export interface CascadeOptions {
+    step?: number;
+    slots?: number;
+}
+/** Where a desktop's first window opens: this far in from its window area's corner. */
+export declare const WINDOW_ORIGIN: Point;
+/** The first cascade slot in a window area: {@link WINDOW_ORIGIN} in from its corner. */
+export declare function windowOrigin(area: Box): Point;
+/** Cascade slot `i` from `base`, wrapping past the slot count. */
+export declare function cascadeSlot(base: Point, i: number, { step, slots }?: CascadeOptions): Point & {
+    slot: number;
+};
+/**
+ * The first cascade slot from `base` that no window in `occupied` (their
+ * top-lefts) holds. A window within half a step of a slot holds it, which
+ * absorbs snapping and clamping. Every slot held wraps rather than walking
+ * off the screen.
+ */
+export declare function cascadeFrom(base: Point, occupied: readonly Point[], options?: CascadeOptions): Point & {
+    slot: number;
+};
+/** A box of `size` centered in `area`, its top-left held at the area's. */
+export declare function centeredBox(area: Box, size: Size): Box;
+/**
+ * A box of `size` on cascade slot `n` from `origin`, pulled in to fit `area`
+ * but never past its top-left.
+ */
+export declare function cascadedBox(area: Box, size: Size, origin: Point, n?: number, options?: CascadeOptions): Box;
+/** {@link nearBox}'s tolerance: more than a lattice snap, less than a real move. */
+export declare const NEAR = 10;
+/** Whether every edge of `box` is within `tol` of `target`'s. */
+export declare function nearBox(box: Box, target: Box, tol?: number): boolean;
+/** The least thickness of an outer slice, system px. The middle is the remainder. */
+export declare const BAND = 100;
+/** Each outer slice's thickness, system px. */
+export interface Bands {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * The frame a pin is read in: `reserve` is the band above the open area — a
+ * desktop's work area top, the pin's y = 0 line — and `bands` each outer
+ * slice's thickness.
+ */
+export interface Frame {
+    reserve: number;
+    bands: Bands;
+}
+/** A frame below `reserve`, its bands at least {@link BAND}, any of them wider. */
+export declare function frameOf(reserve?: number, bands?: Partial<Bands>): Frame;
+/**
+ * A resize policy per axis ({@link pinTo}): `size` fixes an axis at a size,
+ * `min` floors a resizable one.
+ */
+export interface Policy {
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    min?: {
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * One edge's pin. `near`: the offset from the span's start; `far`: from its
+ * end; `spring`: the unrounded fraction of the middle.
+ */
+export interface EdgePin {
+    kind: 'near' | 'far' | 'spring';
+    v: number;
+}
+/** A box's pin: per axis, the near edge (left or top), then the far edge. */
+export interface Pin {
+    x: [EdgePin, EdgePin];
+    y: [EdgePin, EdgePin];
+}
+/** Whether `p` has a pin's shape — a stored or garbled record reads as none, so pinTo never throws. */
+export declare function isPin(p: unknown): p is Pin;
+/** A box's pin on `raster` in `frame`: each edge a strut or a spring. */
+export declare function pinOf(box: Box, raster: Size, frame: Frame): Pin;
+/**
+ * A pin back on `raster` as a box, in the frame it was read in, rounded to
+ * whole system px. The policy applies per axis: `size` fixes it, `min`
+ * floors it. Callers snap to their lattice and cap an oversize box.
+ */
+export declare function pinTo(pin: Pin, raster: Size, frame: Frame, { size, min }?: Policy): Box;
+/** An icon's cell, system px: the 64px plate, name included. Two icons collide where their cells overlap. */
+export declare const ICON_CELL = 64;
+/** The lattice's pitches and its inset from the container, system px. */
+export declare const ICON_ROW = 72;
+export declare const ICON_COLUMN = 80;
+export declare const ICON_INSET = 16;
+/**
+ * A container's icon grid. `left`/`top` locate cell (0,0); `dx` is negative
+ * where columns run left; `cols` or `rows` is `Infinity` when unbounded;
+ * `down` fills a column at a time, otherwise a row at a time.
+ */
+export interface Lattice {
+    left: number;
+    top: number;
+    dx: number;
+    dy: number;
+    cols: number;
+    rows: number;
+    down: boolean;
+}
+/** A lattice's cell, pitches and inset from its container's edges, system px. */
+export interface LatticeOptions {
+    cell?: number;
+    column?: number;
+    row?: number;
+    inset?: Partial<{
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }>;
+}
+/**
+ * The desktop's lattice in its work area: cell (0,0) at the top right, rows
+ * running down to the bottom inset, columns running left. At least one row
+ * and one column. Insets default to 16 on the top, right and bottom.
+ */
+export declare function desktopLattice(area: Box, options?: LatticeOptions): Lattice;
+/**
+ * The Trash's place in a desktop's work area: the bottom-right cell, inset
+ * as the desktop's lattice is, held inside the area's top-left.
+ */
+export declare function trashCell(area: Box, options?: LatticeOptions): Point;
+/**
+ * A folder plane's lattice for a plane `width` wide: rows from the top left,
+ * wrapping at the width, unbounded downward. At least one column. Insets
+ * default to 16 on the top and left.
+ */
+export declare function folderLattice(width: number, options?: LatticeOptions): Lattice;
+/** The top-left of cell (`col`, `row`), whether or not the lattice reaches it. */
+export declare function latticeCell(grid: Lattice, col: number, row: number): Point;
+/** Cell number `slot` in the lattice's fill order. */
+export declare function latticeSlot(grid: Lattice, slot: number): Point;
+/**
+ * Two positions in the lattice's fill order, negative when `a` comes first.
+ * Each rounds to its nearest cell, so a pixel of drift still sorts right.
+ */
+export declare function fillOrder(grid: Lattice, a: Point, b: Point): number;
+/**
+ * Clean Up: each position's cell on the lattice. Each icon takes the free
+ * cell nearest it, searching square rings outward from its own rounded,
+ * clamped cell; icons past the last free cell share their own. One position
+ * per input, in input order.
+ */
+export declare function cleanUp(grid: Lattice, positions: readonly Point[]): Point[];
+/**
+ * The first cell, in fill order, that no icon at `taken` overlaps — an icon
+ * off the lattice blocks every cell its own cell touches. The home cell when
+ * a bounded lattice is full.
+ */
+export declare function nextFreeCell(grid: Lattice, taken: readonly Point[], cell?: number): Point;
+/**
+ * A folder's field: at least its viewport, grown to hold every icon at
+ * `positions` (their top-lefts) plus the inset past it. The field's size is
+ * the window's scroll range.
+ */
+export declare function fieldExtent(positions: readonly Point[], viewport: Size, { cell, inset }?: {
+    cell?: number;
+    inset?: number;
+}): Size;
+/** The pairs of `boxes` that overlap, as `"i,j"` with i < j. Boxes sharing only an edge do not. */
+export declare function collisions(boxes: readonly Box[]): Set<string>;

package/dist/shell/geometry.js

@@ -0,0 +1,241 @@
+//#region src/shell/geometry.ts
+var e = 24, t = 5, n = {
+	left: 40,
+	top: 20
+};
+function r(e) {
+	return {
+		left: e.left + n.left,
+		top: e.top + n.top
+	};
+}
+function i(e, t, { step: n = 24, slots: r = 5 } = {}) {
+	let i = (t % r + r) % r;
+	return {
+		left: e.left + n * i,
+		top: e.top + n * i,
+		slot: i
+	};
+}
+function a(e, t, n = {}) {
+	let { step: r = 24, slots: a = 5 } = n, o = r / 2;
+	for (let r = 0; r < a; r++) {
+		let a = i(e, r, n);
+		if (!t.some((e) => Math.abs(e.left - a.left) < o && Math.abs(e.top - a.top) < o)) return a;
+	}
+	return i(e, t.length % a, n);
+}
+function o(e, t) {
+	return {
+		left: Math.max(e.left, e.left + Math.floor((e.width - t.width) / 2)),
+		top: Math.max(e.top, e.top + Math.floor((e.height - t.height) / 2)),
+		width: t.width,
+		height: t.height
+	};
+}
+function s(e, t, n, r = 0, a = {}) {
+	let o = i(n, r, a);
+	return {
+		left: Math.max(e.left, Math.min(o.left, e.left + e.width - t.width)),
+		top: Math.max(e.top, Math.min(o.top, e.top + e.height - t.height)),
+		width: t.width,
+		height: t.height
+	};
+}
+var c = 10;
+function l(e, t, n = 10) {
+	return Math.abs(e.left - t.left) <= n && Math.abs(e.top - t.top) <= n && Math.abs(e.left + e.width - (t.left + t.width)) <= n && Math.abs(e.top + e.height - (t.top + t.height)) <= n;
+}
+var u = 100;
+function d(e = 0, t = {}) {
+	let n = (e) => Math.max(100, e ?? 100);
+	return {
+		reserve: e,
+		bands: {
+			left: n(t.left),
+			top: n(t.top),
+			right: n(t.right),
+			bottom: n(t.bottom)
+		}
+	};
+}
+function f(e) {
+	let t = (e) => {
+		let t = e;
+		return !!t && (t.kind === "near" || t.kind === "far" || t.kind === "spring") && Number.isFinite(t.v);
+	}, n = (e) => Array.isArray(e) && e.length === 2 && t(e[0]) && t(e[1]), r = e;
+	return !!r && typeof r == "object" && n(r.x) && n(r.y);
+}
+function p(e, t, n, r) {
+	return e < n ? {
+		kind: "near",
+		v: e
+	} : e >= t - r ? {
+		kind: "far",
+		v: t - e
+	} : {
+		kind: "spring",
+		v: (e - n) / Math.max(1, t - n - r)
+	};
+}
+function m(e, t, n, r) {
+	return e.kind === "near" ? e.v : e.kind === "far" ? t - e.v : n + e.v * Math.max(0, t - n - r);
+}
+function h(e, t, n, r, { size: i, min: a = 0 }) {
+	let o = m(e[0], t, n, r), s = m(e[1], t, n, r), c = i;
+	if (c == null) {
+		if (s - o >= a) return {
+			a: o,
+			size: s - o
+		};
+		c = a;
+	}
+	return e[0].kind === "spring" ? e[1].kind === "spring" ? {
+		a: (o + s) / 2 - c / 2,
+		size: c
+	} : {
+		a: s - c,
+		size: c
+	} : {
+		a: o,
+		size: c
+	};
+}
+function g(e, t, n) {
+	let { reserve: r, bands: i } = n, a = t.width, o = t.height - r, s = e.top - r;
+	return {
+		x: [p(e.left, a, i.left, i.right), p(e.left + e.width, a, i.left, i.right)],
+		y: [p(s, o, i.top, i.bottom), p(s + e.height, o, i.top, i.bottom)]
+	};
+}
+function _(e, t, n, { size: r, min: i } = {}) {
+	let { reserve: a, bands: o } = n, s = h(e.x, t.width, o.left, o.right, {
+		size: r?.width,
+		min: i?.width
+	}), c = h(e.y, t.height - a, o.top, o.bottom, {
+		size: r?.height,
+		min: i?.height
+	});
+	return {
+		left: Math.round(s.a),
+		top: Math.round(a + c.a),
+		width: Math.round(s.size),
+		height: Math.round(c.size)
+	};
+}
+var v = 64, y = 72, b = 80, x = 16;
+function S(e, t = {}) {
+	let { cell: n = 64, column: r = 80, row: i = 72 } = t, a = {
+		top: 16,
+		right: 16,
+		bottom: 16,
+		left: 0,
+		...t.inset
+	}, o = e.top + e.height, s = Math.max(e.left + a.left, e.left + e.width - a.right - n), c = e.top + a.top;
+	return {
+		left: s,
+		top: c,
+		dx: -r,
+		dy: i,
+		cols: Math.floor((s - e.left - a.left) / r) + 1,
+		rows: Math.max(1, Math.floor((o - a.bottom - n - c) / i) + 1),
+		down: !0
+	};
+}
+function C(e, t = {}) {
+	let { cell: n = 64 } = t, r = {
+		right: 16,
+		bottom: 16,
+		left: 0,
+		...t.inset
+	};
+	return {
+		left: Math.max(e.left + r.left, e.left + e.width - r.right - n),
+		top: Math.max(e.top, e.top + e.height - r.bottom - n)
+	};
+}
+function w(e, t = {}) {
+	let { cell: n = 64, column: r = 80, row: i = 72 } = t, a = {
+		top: 16,
+		right: 0,
+		bottom: 0,
+		left: 16,
+		...t.inset
+	};
+	return {
+		left: a.left,
+		top: a.top,
+		dx: r,
+		dy: i,
+		cols: Math.max(1, Math.floor((e - a.left - a.right - n) / r) + 1),
+		rows: Infinity,
+		down: !1
+	};
+}
+function T(e, t, n) {
+	return {
+		left: e.left + t * e.dx,
+		top: e.top + n * e.dy
+	};
+}
+function E(e, t) {
+	let n = e.down ? e.rows : e.cols, r = Math.floor(t / n), i = t % n;
+	return e.down ? T(e, r, i) : T(e, i, r);
+}
+function D(e, t, n) {
+	let r = (t) => Math.round((t.left - e.left) / e.dx), i = (t) => Math.round((t.top - e.top) / e.dy);
+	return e.down ? r(t) - r(n) || i(t) - i(n) : i(t) - i(n) || r(t) - r(n);
+}
+var O = (e, t) => Math.min(Math.max(Math.round(e), 0), t - 1);
+function k(e, t) {
+	let { cols: n, rows: r } = e, i = t.map((t) => ({
+		col: O((t.left - e.left) / e.dx, n),
+		row: O((t.top - e.top) / e.dy, r)
+	})), a = (e) => i[e], o = t.map((e, t) => t).sort((e, t) => a(e).row - a(t).row || a(e).col - a(t).col || e - t), s = /* @__PURE__ */ new Set(), c = Math.min(n, t.length + 1) + Math.min(r, t.length + 1), l = [];
+	for (let i of o) {
+		let o = a(i), u = t[i], d = o;
+		for (let t = 0; t <= c; t++) {
+			let i = null, a = Infinity;
+			for (let c = o.col - t; c <= o.col + t; c++) for (let l = o.row - t; l <= o.row + t; l++) {
+				if (Math.max(Math.abs(c - o.col), Math.abs(l - o.row)) !== t || c < 0 || l < 0 || c >= n || l >= r || s.has(`${c},${l}`)) continue;
+				let d = T(e, c, l), f = (d.left - u.left) ** 2 + (d.top - u.top) ** 2;
+				f < a && (a = f, i = {
+					col: c,
+					row: l
+				});
+			}
+			if (i) {
+				d = i;
+				break;
+			}
+		}
+		s.add(`${d.col},${d.row}`), l[i] = T(e, d.col, d.row);
+	}
+	return l;
+}
+function A(e, t, n = 64) {
+	let r = e.cols * e.rows, i = Number.isFinite(r) ? r : 4 * t.length + 1;
+	for (let r = 0; r < i; r++) {
+		let i = E(e, r);
+		if (!t.some((e) => Math.abs(e.left - i.left) < n && Math.abs(e.top - i.top) < n)) return i;
+	}
+	return E(e, 0);
+}
+function j(e, t, { cell: n = 64, inset: r = 16 } = {}) {
+	let i = t.width, a = t.height;
+	for (let t of e) i = Math.max(i, t.left + n + r), a = Math.max(a, t.top + n + r);
+	return {
+		width: i,
+		height: a
+	};
+}
+function M(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n = 0; n < e.length; n++) for (let r = n + 1; r < e.length; r++) {
+		let i = e[n], a = e[r];
+		i.left < a.left + a.width && a.left < i.left + i.width && i.top < a.top + a.height && a.top < i.top + i.height && t.add(`${n},${r}`);
+	}
+	return t;
+}
+//#endregion
+export { u as BAND, t as CASCADE_SLOTS, e as CASCADE_STEP, v as ICON_CELL, b as ICON_COLUMN, x as ICON_INSET, y as ICON_ROW, c as NEAR, n as WINDOW_ORIGIN, a as cascadeFrom, i as cascadeSlot, s as cascadedBox, o as centeredBox, k as cleanUp, M as collisions, S as desktopLattice, j as fieldExtent, D as fillOrder, w as folderLattice, d as frameOf, f as isPin, T as latticeCell, E as latticeSlot, l as nearBox, A as nextFreeCell, g as pinOf, _ as pinTo, C as trashCell, r as windowOrigin };

package/dist/shell/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `vintage-frames/shell` — experimental. Applications over one desktop: a
+ * window manager, a menu bar that shows the front application's menus, a
+ * catalog of what is where, and the stock Finder that shows it. Plain
+ * modules over the kit's elements: it registers no elements, writes no
+ * styles and ships no art, and it reaches the kit only through the
+ * package's own exports, so the page imports `vintage-frames` first.
+ *
+ * Its API may change in any minor release while it is experimental.
+ * docs/SHELL.md is the guide.
+ */
+export { createShell, defineApp, appIdOf, APP_KIND } from './shell.js';
+export type { AppContext, AppDefinition, CatalogSetup, KindDefinition, Shell, ShellOptions } from './shell.js';
+export { createWindowManager, focusInto } from './windows.js';
+export type { AdoptOptions, ArrangeGroup, BoxInput, FocusHome, HomeBox, OpenOptions, PlacePolicy, Placed, WindowManager, WindowManagerOptions, } from './windows.js';
+export { finder, FINDER } from './finder.js';
+export type { FinderApi, FinderArt, FinderCommand, FinderCommandSpec, FinderMenu, FinderOpen, FinderOptions, } from './finder.js';
+export { fileByDrag } from './filing.js';
+export type { FilingOptions } from './filing.js';
+export { createCatalog, memoryStorage, childrenOf, containerOf, copyName, descendantsOf, enclosingFolders, isContainerKind, isInside, isTrashed, isVolume, itemCount, itemOf, nextFolderName, DISK, FOLDER, TRASH, UNTITLED_FOLDER, } from './catalog.js';
+export type { Catalog, CatalogArchive, CatalogOptions, CatalogState, CatalogStorage, Item, KindHooks, NewItem, Volumes, } from './catalog.js';
+export { indexedDbStorage } from './storage.js';
+export { localStorageState, mergeSession, openWindowsOf, readSession } from './state.js';
+export type { LocalStorageStateOptions, SavedSession, SavedWindow, SessionSnapshot, ShellState } from './state.js';
+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 { showAlert } from './alert.js';
+export type { AlertButton, AlertOptions } from './alert.js';

package/dist/shell/index.js

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

package/dist/shell/shell.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The shell: applications over one desktop.
+ *
+ * - The menu bar holds the system menu — the page's own first menu, the
+ *   Apple menu — then the front application's menus, then the clock in the
+ *   bar's `end` slot. Each application's menus are parsed once and the same
+ *   nodes come back each time it is front, so items keep their state. A menu
+ *   off the bar has no key equivalents, so only the front application's fire.
+ *   The bar's label is the front application's name.
+ * - Each application's `init(ctx)` gets the desktop, the window manager, its
+ *   own menus, the system menu, the other applications' actions (read at the
+ *   call), the catalog when a Finder runs, the site's services, `alert()`,
+ *   `gate()`, `onFront()` and `onDispose()`. Everything it sets up comes down
+ *   through `onDispose()`, so a hot reload starts clean.
+ * - A window showing a catalog item follows it: its title follows a rename,
+ *   and it closes when the item is removed.
+ * - The boot reads the catalog, seeds it once, reopens the last session's
+ *   windows deepest first and the active one last, then starts saving.
+ */
+import type { VfDesktop, VfMenu, VfMenuItem, VfViewportBox } from '../index.js';
+import type { Catalog, CatalogStorage, Item, Volumes } from './catalog.js';
+import type { WindowManager } from './windows.js';
+import type { ShellState } from './state.js';
+import type { AlertOptions } from './alert.js';
+/** A kind of catalog item an application registers: how it looks and opens. */
+export interface KindDefinition {
+    /** Its 32×32 art: one URL, or one per item. */
+    art: string | ((item: Item) => string);
+    /** Open the item, its window out of `from` (its icon's box). */
+    open(item: Item, from: VfViewportBox | null): void;
+    /** Renameable in place. Default true. */
+    editable?: boolean;
+    /** Bytes, for Empty Trash's alert. */
+    size?(item: Item): number;
+    /** Copy `from`'s payload to `to` when the Finder copies the item. */
+    copy?(from: Item, to: Item): void | Promise<void>;
+    /** Empty Trash removed the item: drop its payload. */
+    onRemove?(item: Item): void | Promise<void>;
+    /** Make an item of a pasted or dropped file in `parent`; resolves whether it did. */
+    claim?(file: Blob, parent: string | null): Promise<boolean>;
+    /** The item on the system clipboard, as a file. */
+    export?(item: Item): Promise<Blob | null>;
+}
+/** The catalog a Finder brings: where it is stored, its volumes and its seed. */
+export interface CatalogSetup {
+    storage: CatalogStorage | null;
+    volumes?: Volumes;
+    /** Run once per storage, to store the site's defaults. */
+    seed?: (catalog: Catalog) => void | Promise<void>;
+}
+/** One application. */
+export interface AppDefinition<Actions = unknown> {
+    id: string;
+    /** The bar's accessible name while it is front. */
+    name: string;
+    /** Its 32×32 art, for the Finder's icon of it. */
+    icon?: string;
+    /** A fragment of `vf-menu` elements, each with a `data-menu` name. */
+    menus?: string;
+    /** The catalog kinds it opens. */
+    kinds?: Record<string, KindDefinition>;
+    /** The Finder's: the catalog every application shares. */
+    catalog?: CatalogSetup;
+    /**
+     * Set everything up and return what other applications may call. An
+     * application that reopens windows across a reload — or opens from an
+     * icon — provides `open({ item, from })`.
+     */
+    init(ctx: AppContext): Actions | void;
+}
+/** What an application's `init` gets. */
+export interface AppContext {
+    readonly desktop: VfDesktop;
+    readonly windows: WindowManager;
+    /** Its own menus, parsed from `menus`. */
+    readonly menus: VfMenu[];
+    /** The page's system menu, for the items applications install. */
+    readonly systemMenu: VfMenu;
+    /** Every application's actions by id, read at the call. */
+    readonly apps: Record<string, any>;
+    /** The catalog, when a Finder runs; read before the boot has refreshed it, it lists the volumes alone. */
+    readonly catalog: Catalog | null;
+    /** The site's own services. */
+    readonly services: Record<string, any>;
+    /** The saved session, or null. */
+    readonly state: ShellState | null;
+    /** Every kind the applications register, the shell's `app` kind included, in registration order. */
+    readonly kinds: ReadonlyMap<string, KindDefinition>;
+    /** A kind's definition, or undefined. */
+    kind(kind: string): KindDefinition | undefined;
+    /** The application definition with `id`. */
+    app(id: string): AppDefinition | undefined;
+    /** One of its menus by `data-menu`; throws when the markup drifts. */
+    menu(name: string): VfMenu;
+    /** One of its menu items by `value`; throws when the markup drifts. */
+    item(value: string): VfMenuItem;
+    /** Every pick from its menus — never while a modal is open. */
+    onMenu(fn: (value: string, item: VfMenuItem) => void): void;
+    /** Put an item in the system menu, which runs `fn` when picked. */
+    systemItem(value: string, label: string, fn: () => void): VfMenuItem;
+    /** Show an alert with the site's caution art; resolves the button's value. */
+    alert(message: string, options?: AlertOptions): Promise<string | null>;
+    /** Keep `item` disabled while `test` is false: re-run on every press, key, selection change and activation. */
+    gate(item: VfMenuItem, test: () => boolean): void;
+    /** Whether a text field has keyboard focus, read through shadow roots at the call. */
+    typing(): boolean;
+    /** Whether a modal dialog is open. */
+    modalOpen(): boolean;
+    /** Follow whether this application is front; called at once with the current state. */
+    onFront(fn: (front: boolean) => void): void;
+    /** A listener torn down with the application. */
+    on(target: EventTarget, type: string, fn: (e: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Run `fn` when the shell is disposed. */
+    onDispose(fn: () => void): void;
+}
+/** Declare an application, with its actions' type. */
+export declare function defineApp<Actions>(definition: AppDefinition<Actions>): AppDefinition<Actions>;
+export interface ShellOptions {
+    /** The applications; the first with a `catalog` is the Finder. */
+    apps: AppDefinition<any>[];
+    /** The application front while no window is active. Default the Finder, else the first. */
+    defaultApp?: string;
+    /** `'viewport'` sizes the desktop to the viewport on every resize and scale change. */
+    fit?: 'viewport' | false;
+    /** Where the session is saved; null keeps nothing, so a reload resets. */
+    state?: ShellState | null;
+    /** The site's own services, handed to every application. */
+    services?: Record<string, unknown>;
+    /** The clock in the menu bar's `end` slot. Default true. */
+    clock?: boolean;
+    /** The 32×32 caution art the alerts carry. */
+    caution?: string | null;
+}
+/** A running shell. */
+export interface Shell {
+    readonly desktop: VfDesktop;
+    readonly windows: WindowManager;
+    readonly catalog: Catalog | null;
+    readonly apps: Record<string, any>;
+    /** Settles once the boot has read the catalog and reopened the session. */
+    readonly ready: Promise<void>;
+    alert(message: string, options?: AlertOptions): Promise<string | null>;
+    dispose(): void;
+}
+/** The kind the shell registers: an application's icon, which opens it. */
+export declare const APP_KIND = "app";
+/** Start the shell over `desktop`. The page has imported `vintage-frames` first. */
+export declare function createShell(desktop: VfDesktop, options: ShellOptions): Shell;
+/** The application an `app` item stands for. */
+export declare function appIdOf(item: Item): string | null;