@drift-beacon/plugin 0.1.0

package/dist/internal/compatibility.js

@@ -0,0 +1,52 @@
+import { API_VERSION } from "../version.js";
+/**
+ * API versions this build of Drift Beacon runs: the newest minor of each supported major.
+ * Before 1.0 only the current version is listed, because every 0.x minor may break plugins.
+ * From 1.0, the previous major stays listed for at least six months after its successor ships.
+ */
+export const SUPPORTED_API_VERSIONS = [API_VERSION];
+const API_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** Parse a `major.minor` API version; null when malformed. */
+export function parseApiVersion(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = API_VERSION_PATTERN.exec(value);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]) };
+}
+/**
+ * Whether a plugin built for `pluginVersion` runs on a build supporting `supported`.
+ * Before 1.0 the minor must match exactly; from 1.0 the major must match and the plugin's
+ * minor must not be newer than the host's.
+ */
+export function checkApiCompatibility(pluginVersion, supported = SUPPORTED_API_VERSIONS) {
+    const plugin = parseApiVersion(pluginVersion);
+    if (!plugin) {
+        return {
+            compatible: false,
+            reason: "invalid",
+            message: `The plugin's apiVersion must be "major.minor", for example "${API_VERSION}".`,
+        };
+    }
+    const hosts = supported.map(parseApiVersion).filter((version) => version !== null);
+    const runs = hosts.some((host) => host.major === 0
+        ? plugin.major === 0 && plugin.minor === host.minor
+        : plugin.major === host.major && plugin.minor <= host.minor);
+    if (runs)
+        return { compatible: true };
+    const newest = hosts.reduce((best, host) => !best || host.major > best.major || (host.major === best.major && host.minor > best.minor) ? host : best, null);
+    const tooNew = !newest || plugin.major > newest.major || (plugin.major === newest.major && plugin.minor > newest.minor);
+    const list = supported.join(", ");
+    return tooNew
+        ? {
+            compatible: false,
+            reason: "needs-newer-app",
+            message: `Built for plugin API ${pluginVersion}. Update Drift Beacon to run it (this version supports ${list}).`,
+        }
+        : {
+            compatible: false,
+            reason: "needs-plugin-update",
+            message: `Built for plugin API ${pluginVersion}, which this version of Drift Beacon no longer runs (it supports ${list}). The plugin needs an update.`,
+        };
+}

package/dist/internal/json-equal.d.ts

@@ -0,0 +1,3 @@
+/** Structural equality for JSON-shaped values such as data rows and storage items. */
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=json-equal.d.ts.map

package/dist/internal/json-equal.js

@@ -0,0 +1,20 @@
+/** Structural equality for JSON-shaped values such as data rows and storage items. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => jsonEqual(item, b[index]));
+    }
+    if (Array.isArray(b))
+        return false;
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length)
+        return false;
+    return keys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]));
+}

package/dist/internal/manifest.d.ts

@@ -0,0 +1,51 @@
+interface ConfigurationItemBase {
+    name: string;
+    title: string;
+    description?: string;
+    required?: boolean;
+}
+export interface StringConfigurationItem extends ConfigurationItemBase {
+    type: "string";
+    default?: string;
+    placeholder?: string;
+}
+export interface NumberConfigurationItem extends ConfigurationItemBase {
+    type: "number";
+    default?: number;
+    minimum?: number;
+    maximum?: number;
+}
+export interface BooleanConfigurationItem extends ConfigurationItemBase {
+    type: "boolean";
+    default?: boolean;
+}
+export interface DropdownConfigurationItem extends ConfigurationItemBase {
+    type: "dropdown";
+    default?: string;
+    data: ReadonlyArray<{
+        readonly title: string;
+        readonly value: string;
+    }>;
+}
+/** One setting declared in `manifest.json`; drives the settings form and config validation. */
+export type ConfigurationItem = StringConfigurationItem | NumberConfigurationItem | BooleanConfigurationItem | DropdownConfigurationItem;
+export interface PluginManifest {
+    id: string;
+    name: string;
+    version: string;
+    /** Plugin API version (`major.minor`) the plugin was built for. */
+    apiVersion: string;
+    description: string;
+    author: {
+        name: string;
+        email?: string;
+    };
+    category: "plugin" | "utility" | "ui";
+    icon: string;
+    configuration: readonly ConfigurationItem[];
+}
+export declare const isStableVersion: (value: unknown) => value is string;
+/** Throws a readable error when `manifest` is not a valid plugin manifest. Shared by the server and the pack tool. */
+export declare function validateManifest(manifest: unknown): asserts manifest is PluginManifest;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/internal/manifest.js

@@ -0,0 +1,73 @@
+import { parseApiVersion } from "./compatibility.js";
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const isStableVersion = (value) => typeof value === "string" &&
+    STABLE_VERSION.test(value) &&
+    (value.split("+")[0] ?? "").split(".").every((part) => Number.isSafeInteger(Number(part)));
+/** Throws a readable error when `manifest` is not a valid plugin manifest. Shared by the server and the pack tool. */
+export function validateManifest(manifest) {
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Invalid plugin manifest");
+    const value = manifest;
+    for (const field of ["id", "name", "version", "apiVersion", "description", "category"]) {
+        const text = value[field];
+        if (typeof text !== "string" || !text.trim())
+            throw new Error(`Plugin manifest missing required field: ${field}`);
+    }
+    const { id, version, apiVersion, author, category, icon, configuration } = value;
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) {
+        throw new Error("Plugin id must contain only lowercase letters, numbers and hyphens (maximum 64 characters)");
+    }
+    if (!isStableVersion(version)) {
+        throw new Error("Plugin version must be a stable semantic version (for example 1.2.3)");
+    }
+    if (!parseApiVersion(apiVersion))
+        throw new Error('Plugin apiVersion must be "major.minor", for example "0.1"');
+    if (!author || typeof author.name !== "string" || !author.name.trim()) {
+        throw new Error("Plugin manifest author must have a name");
+    }
+    if (!["plugin", "utility", "ui"].includes(category))
+        throw new Error("Invalid plugin category");
+    if (typeof icon !== "string" || /[/\\]|^\./.test(icon)) {
+        throw new Error("Plugin icon must be a file name in ui/public/, or empty");
+    }
+    if (!Array.isArray(configuration))
+        throw new Error("Plugin configuration must be an array");
+    const names = new Set();
+    for (const item of configuration)
+        validateConfigurationItem(item, names);
+}
+function validateConfigurationItem(value, names) {
+    const item = value;
+    if (!item ||
+        typeof item !== "object" ||
+        typeof item.name !== "string" ||
+        !item.name.trim() ||
+        typeof item.title !== "string" ||
+        !["string", "number", "boolean", "dropdown"].includes(item.type) ||
+        (item.required !== undefined && typeof item.required !== "boolean") ||
+        (item.description !== undefined && typeof item.description !== "string"))
+        throw new Error("Invalid plugin configuration item");
+    if (names.has(item.name))
+        throw new Error(`Duplicate plugin configuration name: ${item.name}`);
+    names.add(item.name);
+    const defaultType = item.type === "dropdown" ? "string" : item.type;
+    if (item.default !== undefined && typeof item.default !== defaultType)
+        throw new Error(`Invalid configuration default: ${item.name}`);
+    if (item.type === "string" && item.placeholder !== undefined && typeof item.placeholder !== "string") {
+        throw new Error(`Invalid configuration placeholder: ${item.name}`);
+    }
+    if (item.type === "number") {
+        for (const number of [item.default, item.minimum, item.maximum]) {
+            if (number !== undefined && (typeof number !== "number" || !Number.isFinite(number)))
+                throw new Error(`Invalid numeric configuration: ${item.name}`);
+        }
+        if (item.minimum !== undefined && item.maximum !== undefined && item.minimum > item.maximum) {
+            throw new Error(`Configuration minimum exceeds maximum: ${item.name}`);
+        }
+    }
+    if (item.type === "dropdown" &&
+        (!Array.isArray(item.data) ||
+            item.data.some((option) => !option || typeof option.title !== "string" || typeof option.value !== "string"))) {
+        throw new Error(`Invalid dropdown configuration: ${item.name}`);
+    }
+}

package/dist/internal/models.d.ts

@@ -0,0 +1,62 @@
+import type { ActivitiesApi, Activity, ActivityFilter, CategoriesApi, Category, Change, Session, SessionData, SessionFilter, SessionsApi } from "../types.ts";
+import type { Collection } from "./collection.ts";
+import type { ActivityRow, CategoryRow, SessionRow, WorkspaceRowChanges } from "./rows.ts";
+export interface WorkspaceCollections {
+    readonly activities: Collection<ActivityRow>;
+    readonly categories: Collection<CategoryRow>;
+    readonly sessions: Collection<SessionRow>;
+}
+/** Session operations. Each resolves with the session's row once the snapshot containing the result has arrived. */
+export interface SessionActions {
+    start(activityId: string): Promise<unknown>;
+    end(sessionId: string): Promise<unknown>;
+    mark(activityId: string): Promise<unknown>;
+    discard(sessionId: string): Promise<unknown>;
+}
+export interface ModelChanges {
+    readonly activities: readonly Change<Activity>[];
+    readonly categories: readonly Change<Category>[];
+    readonly sessions: readonly Change<Session>[];
+}
+/** The reads and actions of `ctx.activities`, `ctx.categories` and `ctx.sessions`. Contexts add the events. */
+export interface ModelApis {
+    readonly activities: Omit<ActivitiesApi, "onChange">;
+    readonly categories: Omit<CategoriesApi, "onChange">;
+    readonly sessions: Omit<SessionsApi, "onChange">;
+}
+export declare class WorkspaceModels {
+    #private;
+    readonly userId: string;
+    readonly rows: WorkspaceCollections;
+    constructor(options: {
+        readonly userId: string;
+        readonly rows: WorkspaceCollections;
+        readonly actions: SessionActions;
+    });
+    /** The reads and actions for `ctx`. */
+    apis(): ModelApis;
+    activity(id: string): Activity | undefined;
+    category(id: string): Category | undefined;
+    session(id: string): Session | undefined;
+    /** In the app's order: by category (uncategorized last), then `sortOrder`, then name. */
+    activities(filter?: ActivityFilter): readonly Activity[];
+    /** By `sortOrder`, then name. */
+    categories(): readonly Category[];
+    /** Newest first. */
+    sessions(filter?: SessionFilter): readonly Session[];
+    start(activityId: string): Promise<Session>;
+    end(sessionId: string): Promise<Session>;
+    mark(activityId: string): Promise<Session>;
+    discard(sessionId: string): Promise<void>;
+    /** Turn the row changes of a snapshot into model changes. Call it after the collections were replaced. */
+    update(changes: WorkspaceRowChanges): ModelChanges;
+    /**
+     * The model for a session the app sent outside a snapshot (a live event or an action result):
+     * the snapshot's model, or, when the row isn't in the snapshot, a removed model holding these values.
+     */
+    sessionFrom(row: SessionRow): Session;
+    activityRow(id: string): ActivityRow;
+    categoryRow(id: string): CategoryRow;
+    sessionData(id: string): SessionData;
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/internal/models.js

@@ -0,0 +1,387 @@
+/**
+ * The models plugins see: `Activity`, `Category` and `Session` objects over the workspace rows.
+ *
+ * One `WorkspaceModels` per `ctx`. The plugin host builds it for main code; the UI client builds it
+ * inside every UI bundle, so this file is part of the UI wire contract: change it only additively
+ * within an API version.
+ *
+ * Every read goes to the latest snapshot in the collections, synchronously. Nothing is applied ahead
+ * of a snapshot. Lists are computed once per snapshot, so they keep their identity until the data
+ * changes.
+ */
+import { PluginError } from "../errors.js";
+const ACTIVITY_FIELDS = [
+    "id",
+    "name",
+    "description",
+    "trackingType",
+    "icon",
+    "iconPath",
+    "color",
+    "categoryId",
+    "archived",
+    "sortOrder",
+    "unit",
+];
+const CATEGORY_FIELDS = [
+    "id",
+    "name",
+    "description",
+    "color",
+    "icon",
+    "iconPath",
+    "sortOrder",
+];
+const SESSION_FIELDS = [
+    "id",
+    "activityId",
+    "type",
+    "status",
+    "memberIds",
+    "startedAt",
+    "endedAt",
+];
+const gone = (what) => Promise.reject(new PluginError("not-found", `${what} no longer exists`));
+const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Give a model its data fields as enumerable getters, so spreading, `JSON.stringify` and
+ * `postMessage` copy the current values, then freeze it.
+ */
+function seal(model, fields, data) {
+    for (const field of fields) {
+        Object.defineProperty(model, field, { enumerable: true, get: () => data()[field] });
+    }
+    Object.freeze(model);
+}
+class ActivityModel {
+    #models;
+    #id;
+    constructor(models, id) {
+        this.#models = models;
+        this.#id = id;
+        seal(this, ACTIVITY_FIELDS, () => this.data);
+    }
+    get exists() {
+        return this.#models.rows.activities.get(this.#id) !== undefined;
+    }
+    get data() {
+        return this.#models.activityRow(this.#id);
+    }
+    get isSpan() {
+        return this.data.trackingType === "span";
+    }
+    get isPoint() {
+        return this.data.trackingType === "point";
+    }
+    get isLive() {
+        return this.live({ mine: true }).length > 0;
+    }
+    get category() {
+        const categoryId = this.data.categoryId;
+        return categoryId === null ? undefined : this.#models.category(categoryId);
+    }
+    sessions(filter) {
+        return this.#models.sessions({ ...filter, activityId: this.#id });
+    }
+    live(options) {
+        return this.#models.sessions({ status: "live", mine: options?.mine, activityId: this.#id });
+    }
+    start() {
+        return this.exists ? this.#models.start(this.#id) : gone(`Activity ${this.#id}`);
+    }
+    mark() {
+        return this.exists ? this.#models.mark(this.#id) : gone(`Activity ${this.#id}`);
+    }
+    track() {
+        return this.isSpan ? this.start() : this.mark();
+    }
+    end() {
+        const live = this.live({ mine: true })[0];
+        if (live)
+            return live.end();
+        return Promise.reject(new PluginError("not-found", `No live session of "${this.data.name}" for this user`));
+    }
+}
+class CategoryModel {
+    #models;
+    #id;
+    constructor(models, id) {
+        this.#models = models;
+        this.#id = id;
+        seal(this, CATEGORY_FIELDS, () => this.data);
+    }
+    get exists() {
+        return this.#models.rows.categories.get(this.#id) !== undefined;
+    }
+    get data() {
+        return this.#models.categoryRow(this.#id);
+    }
+    activities(filter) {
+        return this.#models.activities({ ...filter, categoryId: this.#id });
+    }
+}
+class SessionModel {
+    #models;
+    #id;
+    constructor(models, id) {
+        this.#models = models;
+        this.#id = id;
+        seal(this, SESSION_FIELDS, () => this.data);
+    }
+    get exists() {
+        return this.#models.rows.sessions.get(this.#id) !== undefined;
+    }
+    get data() {
+        return this.#models.sessionData(this.#id);
+    }
+    get isSpan() {
+        return this.data.type === "span";
+    }
+    get isPoint() {
+        return this.data.type === "point";
+    }
+    get isLive() {
+        return this.data.status === "live";
+    }
+    get isMine() {
+        return this.data.memberIds.includes(this.#models.userId);
+    }
+    get activity() {
+        return this.#models.activity(this.data.activityId);
+    }
+    duration(at = new Date()) {
+        const { type, startedAt, endedAt } = this.data;
+        if (type === "point")
+            return 0;
+        return Math.max(0, (endedAt ?? at).getTime() - startedAt.getTime());
+    }
+    end() {
+        return this.exists ? this.#models.end(this.#id) : gone(`Session ${this.#id}`);
+    }
+    discard() {
+        return this.exists ? this.#models.discard(this.#id) : gone(`Session ${this.#id}`);
+    }
+}
+const isSessionRow = (value) => typeof value === "object" && value !== null && typeof value.id === "string";
+export class WorkspaceModels {
+    userId;
+    rows;
+    #actions;
+    #activities = new Map();
+    #categories = new Map();
+    #sessions = new Map();
+    /** The last row seen for each id, so a model whose row was removed keeps its values. */
+    #lastActivity = new Map();
+    #lastCategory = new Map();
+    #lastSession = new Map();
+    /** Session rows with `Date` fields, one per row version. Built per `ctx`: a `Date` can't be frozen. */
+    #sessionData = new WeakMap();
+    #lists = new Map();
+    #listsSnapshot = [];
+    constructor(options) {
+        this.userId = options.userId;
+        this.rows = options.rows;
+        this.#actions = options.actions;
+    }
+    /** The reads and actions for `ctx`. */
+    apis() {
+        return {
+            activities: {
+                list: (filter) => this.activities(filter),
+                get: (id) => this.activity(id),
+            },
+            categories: {
+                list: () => this.categories(),
+                get: (id) => this.category(id),
+            },
+            sessions: {
+                list: (filter) => this.sessions(filter),
+                get: (id) => this.session(id),
+                live: (options) => this.sessions({ status: "live", mine: options?.mine }),
+                start: (activityId) => this.start(activityId),
+                end: (sessionId) => this.end(sessionId),
+                mark: (activityId) => this.mark(activityId),
+                discard: (sessionId) => this.discard(sessionId),
+            },
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Reads
+    // --------------------------------------------------------------------------
+    activity(id) {
+        return this.rows.activities.get(id) ? this.#activityModel(id) : undefined;
+    }
+    category(id) {
+        return this.rows.categories.get(id) ? this.#categoryModel(id) : undefined;
+    }
+    session(id) {
+        return this.rows.sessions.get(id) ? this.#sessionModel(id) : undefined;
+    }
+    /** In the app's order: by category (uncategorized last), then `sortOrder`, then name. */
+    activities(filter = {}) {
+        const { categoryId, trackingType, includeArchived = false } = filter;
+        const key = {
+            list: "activities",
+            categoryId: categoryId === undefined ? {} : categoryId,
+            trackingType,
+            includeArchived,
+        };
+        return this.#list(key, () => {
+            const rank = new Map(this.categories().map((category, index) => [category.id, index]));
+            const rankOf = (row) => row.categoryId === null ? rank.size : (rank.get(row.categoryId) ?? rank.size);
+            return this.rows.activities
+                .list()
+                .filter((row) => (includeArchived || !row.archived) &&
+                (categoryId === undefined || row.categoryId === categoryId) &&
+                (trackingType === undefined || row.trackingType === trackingType))
+                .sort((a, b) => rankOf(a) - rankOf(b) ||
+                a.sortOrder - b.sortOrder ||
+                compareText(a.name, b.name) ||
+                compareText(a.id, b.id))
+                .map((row) => this.#activityModel(row.id));
+        });
+    }
+    /** By `sortOrder`, then name. */
+    categories() {
+        return this.#list({ list: "categories" }, () => [...this.rows.categories.list()]
+            .sort((a, b) => a.sortOrder - b.sortOrder || compareText(a.name, b.name) || compareText(a.id, b.id))
+            .map((row) => this.#categoryModel(row.id)));
+    }
+    /** Newest first. */
+    sessions(filter = {}) {
+        const { activityId, status, mine = false } = filter;
+        return this.#list({ list: "sessions", activityId, status, mine }, () => this.rows.sessions
+            .list()
+            .filter((row) => (activityId === undefined || row.activityId === activityId) &&
+            (status === undefined || row.status === status) &&
+            (!mine || row.memberIds.includes(this.userId)))
+            .map((row) => ({ row, at: Date.parse(row.startedAt) }))
+            .sort((a, b) => b.at - a.at || compareText(a.row.id, b.row.id))
+            .map(({ row }) => this.#sessionModel(row.id)));
+    }
+    // --------------------------------------------------------------------------
+    // Actions
+    // --------------------------------------------------------------------------
+    async start(activityId) {
+        return this.#result(await this.#actions.start(activityId));
+    }
+    async end(sessionId) {
+        return this.#result(await this.#actions.end(sessionId));
+    }
+    async mark(activityId) {
+        return this.#result(await this.#actions.mark(activityId));
+    }
+    async discard(sessionId) {
+        await this.#actions.discard(sessionId);
+    }
+    // --------------------------------------------------------------------------
+    // Deliveries
+    // --------------------------------------------------------------------------
+    /** Turn the row changes of a snapshot into model changes. Call it after the collections were replaced. */
+    update(changes) {
+        return {
+            activities: changes.activities.map((change) => this.#change(change, this.#lastActivity, (id) => this.#activityModel(id), (row) => row)),
+            categories: changes.categories.map((change) => this.#change(change, this.#lastCategory, (id) => this.#categoryModel(id), (row) => row)),
+            sessions: changes.sessions.map((change) => this.#change(change, this.#lastSession, (id) => this.#sessionModel(id), (row) => this.#toSessionData(row))),
+        };
+    }
+    /**
+     * The model for a session the app sent outside a snapshot (a live event or an action result):
+     * the snapshot's model, or, when the row isn't in the snapshot, a removed model holding these values.
+     */
+    sessionFrom(row) {
+        if (!this.rows.sessions.get(row.id))
+            this.#lastSession.set(row.id, row);
+        return this.#sessionModel(row.id);
+    }
+    // --------------------------------------------------------------------------
+    // Rows, for the models
+    // --------------------------------------------------------------------------
+    activityRow(id) {
+        return latest(this.rows.activities.get(id), this.#lastActivity, id);
+    }
+    categoryRow(id) {
+        return latest(this.rows.categories.get(id), this.#lastCategory, id);
+    }
+    sessionData(id) {
+        return this.#toSessionData(latest(this.rows.sessions.get(id), this.#lastSession, id));
+    }
+    // --------------------------------------------------------------------------
+    // Internals
+    // --------------------------------------------------------------------------
+    #activityModel(id) {
+        let model = this.#activities.get(id);
+        if (!model) {
+            model = new ActivityModel(this, id);
+            this.#activities.set(id, model);
+        }
+        return model;
+    }
+    #categoryModel(id) {
+        let model = this.#categories.get(id);
+        if (!model) {
+            model = new CategoryModel(this, id);
+            this.#categories.set(id, model);
+        }
+        return model;
+    }
+    #sessionModel(id) {
+        let model = this.#sessions.get(id);
+        if (!model) {
+            model = new SessionModel(this, id);
+            this.#sessions.set(id, model);
+        }
+        return model;
+    }
+    #toSessionData(row) {
+        let data = this.#sessionData.get(row);
+        if (!data) {
+            data = Object.freeze({
+                ...row,
+                startedAt: new Date(row.startedAt),
+                endedAt: row.endedAt === null ? null : new Date(row.endedAt),
+            });
+            this.#sessionData.set(row, data);
+        }
+        return data;
+    }
+    #change(change, last, model, data) {
+        last.set(change.item.id, change.item);
+        const item = model(change.item.id);
+        if (change.type === "updated")
+            return { type: "updated", item, previous: data(change.previous) };
+        return { type: change.type, item };
+    }
+    #result(value) {
+        if (!isSessionRow(value))
+            throw new PluginError("failed", "Drift Beacon did not return the session");
+        return this.sessionFrom(value);
+    }
+    /** A list computed once per snapshot: the same frozen array until any collection changes. */
+    #list(key, compute) {
+        const snapshot = [this.rows.activities.list(), this.rows.categories.list(), this.rows.sessions.list()];
+        if (snapshot.some((list, index) => list !== this.#listsSnapshot[index])) {
+            this.#lists = new Map();
+            this.#listsSnapshot = snapshot;
+        }
+        const cacheKey = JSON.stringify(key);
+        let list = this.#lists.get(cacheKey);
+        if (!list) {
+            list = Object.freeze(compute());
+            this.#lists.set(cacheKey, list);
+        }
+        return list;
+    }
+}
+/** The row in the snapshot, remembered as the last one seen; otherwise the last one seen. */
+function latest(row, last, id) {
+    if (row !== undefined) {
+        if (last.get(id) !== row)
+            last.set(id, row);
+        return row;
+    }
+    const remembered = last.get(id);
+    if (remembered === undefined)
+        throw new PluginError("not-found", `No data for ${id}`);
+    return remembered;
+}

package/dist/internal/package-layout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The plugin package: `manifest.json`, `package.json`, `main/index.js` (plus chunks) and `ui/index.html`
+ * (plus assets and the manifest icon). Shared by the pack tool and the server. Pure: the web app bundles
+ * `/internal`, so no `node:` imports.
+ */
+export declare const PACKAGE_LIMITS: {
+    readonly entries: 2000;
+    readonly fileBytes: number;
+    readonly totalBytes: number;
+    readonly archiveBytes: number;
+    readonly manifestBytes: number;
+};
+/** The `package.json` every package gets: main is ESM. */
+export declare const PACKAGE_JSON: {
+    readonly type: "module";
+    readonly private: true;
+};
+export declare const REQUIRED_FILES: readonly ["main/index.js", "ui/index.html"];
+/** manifest.json, package.json, main/** and ui/** (directories: main, ui and below). `name` has no trailing slash. */
+export declare const isPackagePath: (name: string, directory: boolean) => boolean;
+//# sourceMappingURL=package-layout.d.ts.map