@jolly-pixel/asset-server 1.0.0

package/dist/sync/foldProjection.d.ts

@@ -0,0 +1,12 @@
+import { type AssetEvent, type AssetInlineContent } from "../events/AssetEvents.ts";
+/**
+ * Physical state one asset stream asks for. `null` means "absent".
+ */
+export interface AssetProjection {
+    readonly path: string;
+    readonly kind: string;
+    readonly hash: string;
+    readonly content: AssetInlineContent;
+}
+export declare function applyProjection(projection: AssetProjection | null, event: AssetEvent): AssetProjection | null;
+//# sourceMappingURL=foldProjection.d.ts.map

package/dist/sync/foldProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldProjection.d.ts","sourceRoot":"","sources":["../../src/sync/foldProjection.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,eAAe,GAAG,IAAI,EAClC,KAAK,EAAE,UAAU,GAChB,eAAe,GAAG,IAAI,CA4BxB"}

package/dist/sync/foldProjection.js

@@ -0,0 +1,32 @@
+// Import Internal Dependencies
+import { ASSET_CREATED, ASSET_DELETED, ASSET_RENAMED, ASSET_UPDATED } from "../events/AssetEvents.js";
+export function applyProjection(projection, event) {
+    switch (event.eventType) {
+        case ASSET_CREATED:
+        case ASSET_UPDATED: {
+            const { eventData } = event;
+            return {
+                path: eventData.path,
+                kind: eventData.kind,
+                hash: eventData.hash,
+                content: eventData.content
+            };
+        }
+        case ASSET_RENAMED: {
+            if (projection === null) {
+                return null;
+            }
+            return {
+                ...projection,
+                path: event.eventData.to
+            };
+        }
+        case ASSET_DELETED:
+            return null;
+        default:
+            return unhandled(event);
+    }
+}
+function unhandled(event) {
+    throw new TypeError(`Unhandled asset event type: ${JSON.stringify(event)}`);
+}

package/dist/sync/index.d.ts

@@ -0,0 +1,19 @@
+export { AssetProjector } from "./AssetProjector.ts";
+export type { AssetProjectorOptions } from "./AssetProjector.ts";
+export { AssetStateStore } from "./AssetStateStore.ts";
+export type { AssetStateEntry, AssetStateStoreOptions } from "./AssetStateStore.ts";
+export { applyProjection } from "./foldProjection.ts";
+export type { AssetProjection } from "./foldProjection.ts";
+export { ProjectionState } from "./ProjectionState.ts";
+export type { ProjectionFailure, ProjectionStateData } from "./ProjectionState.ts";
+export { SnapshotScheduler } from "./SnapshotScheduler.ts";
+export type { SnapshotSchedulerOptions } from "./SnapshotScheduler.ts";
+export { AssetWriter } from "./AssetWriter.ts";
+export type { AssetWriterOptions, CreateAssetInput, DeleteAssetInput, RenameAssetInput, UpdateAssetInput } from "./AssetWriter.ts";
+export { matchRenames } from "./matchRenames.ts";
+export type { CreatedAsset, DeletedAsset, ObservedEntry, ProjectedEntry, RenameMatch, RenamedAsset, UpdatedAsset } from "./matchRenames.ts";
+export { Reconciler } from "./Reconciler.ts";
+export type { ReconcileReport, ReconcilerOptions } from "./Reconciler.ts";
+export { ReconciliationWatcher } from "./ReconciliationWatcher.ts";
+export type { ReconciliationWatcherOptions } from "./ReconciliationWatcher.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,eAAe,EACf,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,YAAY,EACV,4BAA4B,EAC7B,MAAM,4BAA4B,CAAC"}

package/dist/sync/index.js

@@ -0,0 +1,9 @@
+export { AssetProjector } from "./AssetProjector.js";
+export { AssetStateStore } from "./AssetStateStore.js";
+export { applyProjection } from "./foldProjection.js";
+export { ProjectionState } from "./ProjectionState.js";
+export { SnapshotScheduler } from "./SnapshotScheduler.js";
+export { AssetWriter } from "./AssetWriter.js";
+export { matchRenames } from "./matchRenames.js";
+export { Reconciler } from "./Reconciler.js";
+export { ReconciliationWatcher } from "./ReconciliationWatcher.js";

package/dist/sync/matchRenames.d.ts

@@ -0,0 +1,45 @@
+export interface ProjectedEntry {
+    readonly id: string;
+    readonly path: string;
+    readonly kind: string;
+    readonly hash: string;
+}
+export interface ObservedEntry {
+    readonly path: string;
+    readonly hash: string;
+}
+export interface RenamedAsset {
+    readonly id: string;
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+    readonly hash: string;
+}
+export interface UpdatedAsset {
+    readonly id: string;
+    readonly kind: string;
+    readonly path: string;
+    readonly hash: string;
+}
+export interface CreatedAsset {
+    readonly path: string;
+    readonly hash: string;
+}
+export interface DeletedAsset {
+    readonly id: string;
+    readonly kind: string;
+    readonly path: string;
+}
+export interface RenameMatch {
+    readonly renamed: RenamedAsset[];
+    readonly updated: UpdatedAsset[];
+    readonly created: CreatedAsset[];
+    readonly deleted: DeletedAsset[];
+}
+/**
+ * Matches a rename only when one removed and one added path share a hash.
+ *
+ * Ambiguous hashes remain deletes and creates.
+ */
+export declare function matchRenames(projected: Iterable<ProjectedEntry>, observed: Iterable<ObservedEntry>): RenameMatch;
+//# sourceMappingURL=matchRenames.d.ts.map

package/dist/sync/matchRenames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchRenames.d.ts","sourceRoot":"","sources":["../../src/sync/matchRenames.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC,EACnC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAChC,WAAW,CAmFb"}

package/dist/sync/matchRenames.js

@@ -0,0 +1,85 @@
+/**
+ * Matches a rename only when one removed and one added path share a hash.
+ *
+ * Ambiguous hashes remain deletes and creates.
+ */
+export function matchRenames(projected, observed) {
+    const previous = new Map();
+    for (const entry of projected) {
+        previous.set(entry.path, entry);
+    }
+    const current = new Map();
+    for (const entry of observed) {
+        current.set(entry.path, entry);
+    }
+    const updated = [];
+    const appeared = [];
+    const disappeared = [];
+    for (const [path, entry] of current) {
+        const before = previous.get(path);
+        if (before === undefined) {
+            appeared.push(entry);
+        }
+        else if (before.hash !== entry.hash) {
+            updated.push({
+                id: before.id,
+                kind: before.kind,
+                path,
+                hash: entry.hash
+            });
+        }
+    }
+    for (const [path, entry] of previous) {
+        if (!current.has(path)) {
+            disappeared.push(entry);
+        }
+    }
+    const appearedByHash = Map.groupBy(appeared, (entry) => entry.hash);
+    const disappearedByHash = Map.groupBy(disappeared, (entry) => entry.hash);
+    const renamed = [];
+    const created = [];
+    const deleted = [];
+    for (const [hash, candidates] of appearedByHash) {
+        const sources = disappearedByHash.get(hash) ?? [];
+        const source = singleton(sources);
+        const target = singleton(candidates);
+        if (source !== undefined && target !== undefined) {
+            renamed.push({
+                id: source.id,
+                kind: source.kind,
+                from: source.path,
+                to: target.path,
+                hash
+            });
+            disappearedByHash.delete(hash);
+            continue;
+        }
+        for (const candidate of candidates) {
+            created.push({
+                path: candidate.path,
+                hash: candidate.hash
+            });
+        }
+    }
+    for (const sources of disappearedByHash.values()) {
+        for (const source of sources) {
+            deleted.push({
+                id: source.id,
+                kind: source.kind,
+                path: source.path
+            });
+        }
+    }
+    return {
+        renamed: sortBy(renamed, (entry) => entry.to),
+        updated: sortBy(updated, (entry) => entry.path),
+        created: sortBy(created, (entry) => entry.path),
+        deleted: sortBy(deleted, (entry) => entry.path)
+    };
+}
+function singleton(values) {
+    return values.length === 1 ? values.at(0) : undefined;
+}
+function sortBy(values, key) {
+    return values.sort((a, b) => key(a).localeCompare(key(b)));
+}

package/dist/utils/TaskChain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Serializes async work without letting a rejection break the chain.
+ */
+export declare class TaskChain {
+    #private;
+    run<TResult>(task: () => Promise<TResult>): Promise<TResult>;
+    settled(): Promise<void>;
+}
+//# sourceMappingURL=TaskChain.d.ts.map

package/dist/utils/TaskChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskChain.d.ts","sourceRoot":"","sources":["../../src/utils/TaskChain.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAS;;IAGpB,GAAG,CAAC,OAAO,EACT,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAC3B,OAAO,CAAC,OAAO,CAAC;IAYb,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/utils/TaskChain.js

@@ -0,0 +1,14 @@
+/**
+ * Serializes async work without letting a rejection break the chain.
+ */
+export class TaskChain {
+    #tail = Promise.resolve();
+    run(task) {
+        const next = this.#tail.then(task, task);
+        this.#tail = next.catch(() => void 0);
+        return next;
+    }
+    async settled() {
+        await this.#tail;
+    }
+}

package/dist/utils/contentHash.d.ts

@@ -0,0 +1,2 @@
+export declare function contentHash(data: Uint8Array): string;
+//# sourceMappingURL=contentHash.d.ts.map

package/dist/utils/contentHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentHash.d.ts","sourceRoot":"","sources":["../../src/utils/contentHash.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,GACf,MAAM,CAIR"}

package/dist/utils/contentHash.js

@@ -0,0 +1,7 @@
+// Import Node.js Dependencies
+import { createHash } from "node:crypto";
+export function contentHash(data) {
+    return createHash("sha256")
+        .update(data)
+        .digest("hex");
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { contentHash } from "./contentHash.ts";
+export { TaskChain } from "./TaskChain.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export { contentHash } from "./contentHash.js";
+export { TaskChain } from "./TaskChain.js";

package/dist/workspace/createAssetWorkspace.d.ts

@@ -0,0 +1,71 @@
+import { type AssetSource } from "@jolly-pixel/asset-source";
+import * as EventStore from "@jolly-pixel/event-store";
+import { Server, type Extension, type RightsMap } from "@jolly-pixel/network";
+import type { AssetKindHandler } from "../kinds/AssetKindHandler.ts";
+import { type AssetEventDataMap } from "../events/AssetEvents.ts";
+import { type AssetBackend, type AssetBackendOptions } from "../createAssetBackend.ts";
+import { type Logger } from "../logger.ts";
+import { type AssetSeedMap } from "./seedAssetSource.ts";
+export type AssetBackendTuning = Omit<AssetBackendOptions, "source" | "eventStore" | "handlers" | "logger">;
+export interface AssetWorkspaceOptions {
+    /**
+     * Filesystem root of the workspace, behind the default source and the
+     * default event log.
+     */
+    root: string;
+    handlers?: AssetKindHandler[];
+    /**
+     * Documents written when the workspace holds no file at their path.
+     */
+    seed?: AssetSeedMap;
+    /**
+     * @default FilesystemAssetSource on `root`
+     */
+    source?: AssetSource;
+    /**
+     * @default sqlite log inside the workspace state directory
+     */
+    eventStore?: EventStore.TypedEventStore<AssetEventDataMap>;
+    /**
+     * Network server hosting the catalog and asset rooms. Pass one already
+     * carrying extensions instead of letting the workspace build it.
+     */
+    server?: Server;
+    /**
+     * Extensions registered before the asset rooms are attached.
+     */
+    extensions?: Extension[];
+    rights?: RightsMap;
+    logger?: Logger;
+    /**
+     * Grace period, in milliseconds, before an empty asset room is evicted.
+     */
+    roomGraceMs?: number;
+    /**
+     * Drops the events superseded by each asset's newest lifecycle
+     * checkpoint before the back-end loads its projections.
+     *
+     * Destructive and irreversible: it trades the editing history nothing
+     * reads for a log that stops growing without bound.
+     * @default true
+     */
+    compactOnOpen?: boolean;
+    backend?: AssetBackendTuning;
+}
+export interface AssetWorkspace extends AsyncDisposable {
+    readonly source: AssetSource;
+    readonly eventStore: EventStore.TypedEventStore<AssetEventDataMap>;
+    readonly backend: AssetBackend;
+    readonly server: Server;
+    close(): Promise<void>;
+}
+/**
+ * Assembles the pieces a host needs to edit an asset workspace live: a
+ * source, an event log, the back-end and the network server its rooms are
+ * attached to.
+ *
+ * Owns only what it creates. A source, event store or server passed in is
+ * left open by `close()`.
+ */
+export declare function createAssetWorkspace(options: AssetWorkspaceOptions): Promise<AssetWorkspace>;
+//# sourceMappingURL=createAssetWorkspace.d.ts.map

package/dist/workspace/createAssetWorkspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAssetWorkspace.d.ts","sourceRoot":"","sources":["../../src/workspace/createAssetWorkspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAC;AACvD,OAAO,EACL,MAAM,EACN,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,mBAAmB,EACnB,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAChD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B;;OAEG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAC3D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;IACnE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAwEzB"}

package/dist/workspace/createAssetWorkspace.js

@@ -0,0 +1,72 @@
+// Import Node.js Dependencies
+import path from "node:path";
+// Import Third-party Dependencies
+import { FilesystemAssetSource } from "@jolly-pixel/asset-source";
+import * as EventStore from "@jolly-pixel/event-store";
+import { Server } from "@jolly-pixel/network";
+// Import Internal Dependencies
+import { EVENTS_DB_PATH } from "../constants.js";
+import { ASSET_CHECKPOINT_EVENT_TYPES } from "../events/AssetEvents.js";
+import { createAssetBackend } from "../createAssetBackend.js";
+import { silentLogger } from "../logger.js";
+import { seedAssetSource } from "./seedAssetSource.js";
+/**
+ * Assembles the pieces a host needs to edit an asset workspace live: a
+ * source, an event log, the back-end and the network server its rooms are
+ * attached to.
+ *
+ * Owns only what it creates. A source, event store or server passed in is
+ * left open by `close()`.
+ */
+export async function createAssetWorkspace(options) {
+    const { root, handlers = [], seed, extensions = [], rights, logger = silentLogger(), roomGraceMs, compactOnOpen = true, backend: tuning = {} } = options;
+    const source = options.source ?? new FilesystemAssetSource(root);
+    if (seed) {
+        await seedAssetSource(source, seed);
+    }
+    const ownsEventStore = options.eventStore === undefined;
+    const eventStore = options.eventStore ??
+        await EventStore.persistence.sqlite(path.join(root, EVENTS_DB_PATH));
+    if (compactOnOpen) {
+        const report = eventStore.compact({
+            checkpointEventTypes: ASSET_CHECKPOINT_EVENT_TYPES
+        });
+        logger
+            .withMetadata(report)
+            .debug("event log compacted");
+    }
+    const backend = await createAssetBackend({
+        ...tuning,
+        source,
+        eventStore,
+        handlers,
+        logger
+    });
+    const server = options.server ?? new Server({
+        eventStore,
+        rights,
+        roomGraceMs,
+        logger: options.logger
+    });
+    for (const extension of extensions) {
+        server.register(extension);
+    }
+    const detach = backend.attach(server);
+    const workspace = {
+        source,
+        eventStore,
+        backend,
+        server,
+        async close() {
+            detach();
+            await backend.close();
+            if (ownsEventStore) {
+                eventStore.close();
+            }
+        },
+        async [Symbol.asyncDispose]() {
+            await workspace.close();
+        }
+    };
+    return workspace;
+}

package/dist/workspace/index.d.ts

@@ -0,0 +1,5 @@
+export { createAssetWorkspace } from "./createAssetWorkspace.ts";
+export type { AssetBackendTuning, AssetWorkspace, AssetWorkspaceOptions } from "./createAssetWorkspace.ts";
+export { seedAssetSource } from "./seedAssetSource.ts";
+export type { AssetSeedFactory, AssetSeedMap } from "./seedAssetSource.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/workspace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workspace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,sBAAsB,CAAC"}

package/dist/workspace/index.js

@@ -0,0 +1,2 @@
+export { createAssetWorkspace } from "./createAssetWorkspace.js";
+export { seedAssetSource } from "./seedAssetSource.js";

package/dist/workspace/seedAssetSource.d.ts

@@ -0,0 +1,5 @@
+import type { AssetSource } from "@jolly-pixel/asset-source";
+export type AssetSeedFactory = () => Uint8Array | Promise<Uint8Array>;
+export type AssetSeedMap = Record<string, AssetSeedFactory>;
+export declare function seedAssetSource(source: AssetSource, seed: AssetSeedMap): Promise<string[]>;
+//# sourceMappingURL=seedAssetSource.d.ts.map

package/dist/workspace/seedAssetSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedAssetSource.d.ts","sourceRoot":"","sources":["../../src/workspace/seedAssetSource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE5D,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB"}

package/dist/workspace/seedAssetSource.js

@@ -0,0 +1,20 @@
+export async function seedAssetSource(source, seed) {
+    const written = [];
+    for (const [assetPath, build] of Object.entries(seed)) {
+        if (await exists(source, assetPath)) {
+            continue;
+        }
+        await source.write(assetPath, await build());
+        written.push(assetPath);
+    }
+    return written;
+}
+async function exists(source, assetPath) {
+    try {
+        await source.read(assetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/docs/AssetBackend.md

@@ -0,0 +1,73 @@
+# AssetBackend
+
+`createAssetBackend` connects an `AssetSource` to an event store and starts
+catalog projection, filesystem reconciliation and snapshot scheduling.
+
+```ts
+createAssetBackend(options: AssetBackendOptions): Promise<AssetBackend>
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `source` | required | Physical asset storage. |
+| `eventStore` | required | Event store used for asset and domain events. |
+| `handlers` | `[]` | Asset kind handlers. Unmatched paths use `binary`. |
+| `snapshot` | `2_000` / `30_000` ms | Default quiet and maximum snapshot delays. |
+| `reconcileOnStart` | `true` | Scan the source when the backend starts. |
+| `watch` | `true` | Watch sources that implement `watch()`. |
+| `reconcileDebounce` | `200` ms | Quiet period before external changes are scanned. |
+| `logger` | silent | A `loglayer` logger. |
+
+A handler may override either default snapshot delay. See
+[Asset kinds](./AssetKinds.md#snapshot-policy).
+
+## Returned backend
+
+```ts
+interface AssetBackend extends AsyncDisposable {
+  readonly source: AssetSource;
+  readonly eventStore: EventStore;
+  readonly kinds: AssetKindRegistry;
+  readonly writer: AssetWriter;
+  readonly catalog: CatalogProjection;
+
+  flush(assetId?: string): Promise<void>;
+  attach(server: Server, options?: { graceMs?: number }): () => void;
+  close(): Promise<void>;
+}
+```
+
+Use [`writer`](./AssetWriter.md) for asset mutations. `flush(assetId?)` waits
+for pending snapshots and source writes for one asset, or for every pending
+asset when the ID is omitted.
+
+`attach(server)` registers the `asset-catalog` room and installs the dynamic
+asset-room resolver. Its callback clears the resolver. Existing rooms and the
+catalog room remain owned by the `Server` until `server.close()`.
+
+Close the server before the backend so active asset rooms can flush while the
+backend is still running. `close()` stops watching, flushes pending work and
+releases backend subscriptions. It does not close the injected server or event
+store. `[Symbol.asyncDispose]` calls `close()`.
+
+The returned object also exposes `internals` for tests and hosts that need to
+drive an individual stage. Normal application code should use `writer`,
+`catalog`, `flush()` and `attach()`.
+
+## Workspace files
+
+`createAssetBackend` manages these files under the source root:
+
+```text
+.jollypixel/
+  assets.json
+  state.json
+  .gitignore
+```
+
+Commit `assets.json` so paths keep the same asset IDs when a checkout has no
+local event log. `state.json` stores machine-local projection positions and is
+ignored by the generated `.gitignore`. The host chooses where the event store
+is persisted.