@marimo-team/marimo-export 0.0.0 → 0.0.1

package/dist/prepared/index.mjs

@@ -0,0 +1,703 @@
+import { _ as portableJsonValue, c as isNotebookExportError, d as isJsonNumber, f as isJsonString, g as portableJsonObject, h as isStringValue, m as isRecordValue, p as isPropertyOwner } from "../loader-CDfnJ5Yb.mjs";
+import { i as parsePortableJson } from "../schema-SJ_aIgcO.mjs";
+import { n as normalizeBase, t as openExport } from "../export-6118xT3K.mjs";
+//#region src/prepared/cancellation.ts
+const preparedAbortReason = (reason, message = "Prepared export operation aborted") => {
+	if (reason instanceof Error || reason instanceof DOMException) return reason;
+	return new DOMException(message, "AbortError");
+};
+const isPreparedAbort = (value) => value instanceof DOMException && value.name === "AbortError" || value instanceof Error && value.name === "AbortError" || isNotebookExportError(value) && value.code === "abort";
+const throwIfPreparedAborted = (signal, message) => {
+	if (signal?.aborted) throw preparedAbortReason(signal.reason, message);
+};
+const linkPreparedAbort = (controller, signal) => {
+	const abort = () => controller.abort(preparedAbortReason(signal.reason));
+	signal.addEventListener("abort", abort, { once: true });
+	if (signal.aborted) abort();
+	return () => signal.removeEventListener("abort", abort);
+};
+const disposePreparedOnAbort = (signal, lifecycle, dispose) => {
+	const disposeAfterAbort = () => {
+		dispose().catch(() => {});
+	};
+	const abort = () => {
+		lifecycle.abort(preparedAbortReason(signal.reason));
+		disposeAfterAbort();
+	};
+	signal.addEventListener("abort", abort, { once: true });
+	if (signal.aborted) {
+		lifecycle.abort(preparedAbortReason(signal.reason));
+		queueMicrotask(disposeAfterAbort);
+	}
+	return () => signal.removeEventListener("abort", abort);
+};
+//#endregion
+//#region src/prepared/errors.ts
+const PREPARED_EXPORT_ERROR_BRAND = Symbol.for("@marimo-team/marimo-export.PreparedExportError.v1");
+const PREPARED_EXPORT_ERROR_CODE_SET = /* @__PURE__ */ new Set([
+	"manifest_invalid",
+	"manifest_read_failed",
+	"query_ambiguous",
+	"query_miss"
+]);
+var PreparedExportError = class extends Error {
+	code;
+	cause;
+	constructor(code, message, options = {}) {
+		if (!PREPARED_EXPORT_ERROR_CODE_SET.has(code)) throw new TypeError("PreparedExportError code must be a known code.");
+		if (!isStringValue(message)) throw new TypeError("PreparedExportError message must be a string.");
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		Object.defineProperty(this, PREPARED_EXPORT_ERROR_BRAND, { value: true });
+		this.name = "PreparedExportError";
+		this.code = code;
+		this.cause = options.cause;
+		Object.freeze(this);
+	}
+};
+const isPreparedExportError = (value) => {
+	if (!isPropertyOwner(value) || !Object.isFrozen(value)) return false;
+	try {
+		return Object.getOwnPropertyDescriptor(value, PREPARED_EXPORT_ERROR_BRAND)?.value === true && Object.getOwnPropertyDescriptor(value, "name")?.value === "PreparedExportError" && isStringValue(Object.getOwnPropertyDescriptor(value, "message")?.value) && PREPARED_EXPORT_ERROR_CODE_SET.has(String(Object.getOwnPropertyDescriptor(value, "code")?.value));
+	} catch {
+		return false;
+	}
+};
+//#endregion
+//#region src/prepared/manifest.ts
+const MANIFEST_MAX_URL_BYTES = 8192;
+const SHA256 = /^[\da-f]{64}$/u;
+const encoder = new TextEncoder();
+const parsePreparedExportManifest = (input) => {
+	try {
+		const root = portableJsonObject(input, "prepared manifest");
+		requireFields(root, [
+			"export_url",
+			"inputs",
+			"instance",
+			"schema",
+			"state_fingerprint"
+		], ["refresh_interval_ms"]);
+		if (root.schema !== "marimo-export.prepared.v1") invalid("prepared manifest.schema must be marimo-export.prepared.v1");
+		const instance = digest(root.instance, "prepared manifest.instance");
+		const exportUrl = boundedUrl(root.export_url);
+		const inputs = portableJsonObject(root.inputs, "prepared manifest.inputs");
+		if (Object.keys(inputs).some((name) => name.length === 0)) invalid("prepared manifest.inputs must use nonempty input names");
+		const stateFingerprint = digest(root.state_fingerprint, "prepared manifest.state_fingerprint");
+		const refreshIntervalMs = parseRefreshInterval(root.refresh_interval_ms);
+		const manifest = {
+			schema: "marimo-export.prepared.v1",
+			instance,
+			exportUrl,
+			inputs,
+			stateFingerprint
+		};
+		if (refreshIntervalMs === void 0) return Object.freeze(manifest);
+		return Object.freeze({
+			...manifest,
+			refreshIntervalMs
+		});
+	} catch (error) {
+		if (error instanceof PreparedExportError) throw error;
+		throw new PreparedExportError("manifest_invalid", "The prepared export manifest is invalid.", { cause: error });
+	}
+};
+const resolvePreparedPublication = (manifest, manifestUrl, notebookExport) => {
+	if (manifest.instance !== notebookExport.identity) invalid("The prepared manifest does not match the immutable export identity.");
+	const expected = preparedExportBase(manifest, manifestUrl);
+	if (notebookExport.base.href !== expected.href) invalid("The prepared manifest export URL does not match the opened immutable export.");
+	let state;
+	try {
+		state = notebookExport.resolve(manifest.inputs);
+	} catch (error) {
+		throw new PreparedExportError("manifest_invalid", "The prepared manifest selects a state absent from the immutable export.", { cause: error });
+	}
+	if (state.fingerprint !== manifest.stateFingerprint) invalid("The prepared manifest state fingerprint does not match its selected inputs.");
+	return Object.freeze({
+		manifest,
+		notebookExport,
+		state
+	});
+};
+const preparedExportBase = (manifest, manifestUrl) => normalizeBase(new URL(manifest.exportUrl, manifestUrl));
+const openPreparedPublication = async (manifest, manifestUrl, options = {}) => {
+	throwIfPreparedAborted(options.signal);
+	const base = preparedExportBase(manifest, manifestUrl);
+	const opener = options.openExport ?? openExport;
+	const openOptions = {};
+	if (options.fetch !== void 0) openOptions.fetch = options.fetch;
+	if (options.signal !== void 0) openOptions.signal = options.signal;
+	const notebookExport = await opener(base, openOptions);
+	throwIfPreparedAborted(options.signal);
+	return resolvePreparedPublication(manifest, manifestUrl, notebookExport);
+};
+const requireFields = (value, required, optional) => {
+	const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+	if (required.some((key) => !Object.hasOwn(value, key))) invalid("The prepared export manifest is missing a required field.");
+	if (Object.keys(value).some((key) => !allowed.has(key))) invalid("The prepared export manifest contains an unknown field.");
+};
+const digest = (value, path) => {
+	if (!isJsonString(value)) invalid(`${path} must be a lowercase SHA-256 digest.`);
+	if (!SHA256.test(value)) invalid(`${path} must be a lowercase SHA-256 digest.`);
+	return value;
+};
+const boundedUrl = (value) => {
+	if (!isJsonString(value)) invalid(`prepared manifest.export_url must be at most ${MANIFEST_MAX_URL_BYTES} UTF-8 bytes.`);
+	if (value.length === 0 || encoder.encode(value).byteLength > MANIFEST_MAX_URL_BYTES) invalid(`prepared manifest.export_url must be at most ${MANIFEST_MAX_URL_BYTES} UTF-8 bytes.`);
+	return value;
+};
+const parseRefreshInterval = (value) => {
+	if (value === void 0) return;
+	if (!isJsonNumber(value)) invalid("prepared manifest.refresh_interval_ms must be 0 or between 250 and 60000.");
+	if (!Number.isSafeInteger(value) || value !== 0 && (value < 250 || value > 6e4)) invalid("prepared manifest.refresh_interval_ms must be 0 or between 250 and 60000.");
+	return value;
+};
+function invalid(message) {
+	throw new PreparedExportError("manifest_invalid", message);
+}
+//#endregion
+//#region src/prepared/manifest-fetch.ts
+const MANIFEST_MAX_BYTES = 262144;
+const fetchPreparedExportManifest = async (url, options = {}) => {
+	throwIfPreparedAborted(options.signal);
+	let response;
+	try {
+		const request = {
+			cache: "no-store",
+			headers: { Accept: "application/json" }
+		};
+		if (options.signal !== void 0) request.signal = options.signal;
+		response = await (options.fetch ?? globalThis.fetch)(url, request);
+	} catch (error) {
+		if (options.signal?.aborted) throw preparedAbortReason(options.signal.reason);
+		throw new PreparedExportError("manifest_read_failed", "The prepared export manifest could not be read.", { cause: error });
+	}
+	if (options.signal?.aborted) {
+		await cancelBody(response);
+		throwIfPreparedAborted(options.signal);
+	}
+	if (!response.ok) {
+		await cancelBody(response);
+		throw new PreparedExportError("manifest_read_failed", `The prepared export manifest request failed with ${response.status}.`);
+	}
+	const bytes = await readManifestBytes(response, options.signal);
+	try {
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		return parsePreparedExportManifest(parsePortableJson(text));
+	} catch (error) {
+		if (error instanceof PreparedExportError) throw error;
+		throw new PreparedExportError("manifest_invalid", "The prepared export manifest is not valid portable JSON.", { cause: error });
+	}
+};
+const readManifestBytes = async (response, signal) => {
+	if (signal?.aborted) {
+		await cancelBody(response);
+		throwIfPreparedAborted(signal);
+	}
+	const length = response.headers.get("Content-Length");
+	if (length !== null && /^\d+$/u.test(length) && Number(length) > MANIFEST_MAX_BYTES) {
+		await cancelBody(response);
+		throw manifestTooLarge();
+	}
+	const reader = response.body?.getReader();
+	if (reader === void 0) return /* @__PURE__ */ new Uint8Array();
+	const chunks = [];
+	let size = 0;
+	const abort = () => {
+		reader.cancel(signal?.reason).catch(() => {});
+	};
+	signal?.addEventListener("abort", abort, { once: true });
+	try {
+		if (signal?.aborted) {
+			await reader.cancel(signal.reason);
+			throwIfPreparedAborted(signal);
+		}
+		while (true) {
+			throwIfPreparedAborted(signal);
+			const chunk = await reader.read();
+			throwIfPreparedAborted(signal);
+			if (chunk.done) break;
+			size += chunk.value.byteLength;
+			if (size > MANIFEST_MAX_BYTES) {
+				await reader.cancel();
+				throw manifestTooLarge();
+			}
+			chunks.push(chunk.value);
+		}
+	} catch (error) {
+		if (signal?.aborted) throw preparedAbortReason(signal.reason);
+		if (error instanceof PreparedExportError) throw error;
+		throw new PreparedExportError("manifest_read_failed", "The prepared export manifest body could not be read.", { cause: error });
+	} finally {
+		signal?.removeEventListener("abort", abort);
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+};
+const cancelBody = async (response) => {
+	try {
+		await response.body?.cancel();
+	} catch {}
+};
+const manifestTooLarge = () => new PreparedExportError("manifest_read_failed", `The prepared export manifest exceeds ${MANIFEST_MAX_BYTES} bytes.`);
+//#endregion
+//#region src/prepared/control.ts
+const sameJsonValue = (left, right) => {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => sameJsonValue(value, right[index]));
+	if (!isJsonObject(left) || !isJsonObject(right)) return false;
+	const leftKeys = Object.keys(left);
+	return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => Object.hasOwn(right, key) && sameJsonValue(left[key], right[key]));
+};
+const samePreparedInputs = (left, right) => sameJsonValue(left, right);
+const invalidBinding = (binding) => new PreparedExportError("manifest_invalid", `Control binding for input ${JSON.stringify(binding.input)} does not match the current state.`);
+const replaceControlValue = (current, binding, offset, next) => {
+	const step = binding.path[offset];
+	if (step === void 0) return next;
+	if (step.kind === "element") throw invalidBinding(binding);
+	if (step.kind === "index" && Array.isArray(current)) {
+		if (step.value >= current.length) throw invalidBinding(binding);
+		const replaced = [...current];
+		replaced[step.value] = replaceControlValue(current[step.value], binding, offset + 1, next);
+		return Object.freeze(replaced);
+	}
+	if (!isJsonObject(current)) throw invalidBinding(binding);
+	const key = step.kind === "index" ? String(step.value) : step.value;
+	if (!Object.hasOwn(current, key)) throw invalidBinding(binding);
+	return portableJsonObject({
+		...current,
+		[key]: replaceControlValue(current[key], binding, offset + 1, next)
+	});
+};
+const isJsonObject = (value) => isRecordValue(value);
+const preparedControlInputPatch = (inputs, binding, value) => {
+	if (binding.path.some((step) => step.kind === "element")) return;
+	if (!Object.hasOwn(inputs, binding.input)) throw invalidBinding(binding);
+	return portableJsonObject({ [binding.input]: replaceControlValue(inputs[binding.input], binding, 0, portableJsonValue(value, "control value")) });
+};
+//#endregion
+//#region src/prepared/state-selection.ts
+const mergePreparedInputs = (base, patch) => portableJsonObject({
+	...base,
+	...patch
+}, "prepared state patch");
+const withPreparedState = (publication, state) => Object.freeze({
+	...publication,
+	state
+});
+const selectPendingPublication = (publication, pendingInputs) => {
+	if (pendingInputs === void 0) return publication;
+	try {
+		return withPreparedState(publication, publication.notebookExport.resolve(pendingInputs));
+	} catch (error) {
+		if (!isPreparedStateUnavailable(error)) throw error;
+		return publication;
+	}
+};
+const samePreparedInputContract = (left, right) => {
+	const leftNames = left.notebookExport.inputNames;
+	const rightNames = new Set(right.notebookExport.inputNames);
+	return leftNames.length === rightNames.size && leftNames.every((name) => rightNames.has(name));
+};
+const pendingInputsForPublication = (current, next, pending) => pending !== void 0 && current !== void 0 && !samePreparedInputContract(current, next) ? void 0 : pending;
+const isPreparedStateUnavailable = (value) => isNotebookExportError(value) && value.code === "state_unavailable";
+const isPreparedStatePendingFailure = (value) => {
+	if (!isNotebookExportError(value)) return false;
+	if (value.code === "state_unavailable") return true;
+	return value.code === "read_failed" && value.details !== void 0 && Object.hasOwn(value.details, "status") && value.details.status === 404;
+};
+const pendingInputsAfterFailure = (pending, requested, error, callerAborted) => {
+	if (pending === void 0 || !samePreparedInputs(pending, requested)) return pending;
+	if (isPreparedAbort(error)) return callerAborted ? void 0 : pending;
+	return isPreparedStatePendingFailure(error) ? pending : void 0;
+};
+const preservePreparedSelection = (current, next) => {
+	if (current === void 0 || current.state.fingerprint === current.manifest.stateFingerprint || !samePreparedInputContract(current, next)) return next;
+	try {
+		return withPreparedState(next, next.notebookExport.resolve(current.state.inputs));
+	} catch (error) {
+		if (isNotebookExportError(error) && (error.code === "state_input_invalid" || error.code === "state_unavailable")) return next;
+		throw error;
+	}
+};
+//#endregion
+//#region src/prepared/state-port.ts
+var PreparedStateTransitions = class {
+	port;
+	lifecycle;
+	#current;
+	#target;
+	#controller;
+	#generation = 0;
+	#operation = Promise.resolve();
+	#closed = false;
+	constructor(port, lifecycle) {
+		this.port = port;
+		this.lifecycle = lifecycle;
+	}
+	get current() {
+		return this.#current;
+	}
+	get target() {
+		return this.#target;
+	}
+	snapshot(pendingInputs, disposed) {
+		return Object.freeze({
+			current: this.#current,
+			pendingInputs,
+			transition: Object.freeze({
+				generation: this.#generation,
+				target: this.#target,
+				active: this.#controller !== void 0
+			}),
+			disposed
+		});
+	}
+	setMetadata(publication) {
+		if (this.#target !== void 0) throw new Error("Prepared state transition is active.");
+		this.#current = publication;
+	}
+	apply(next, reason, parentSignal) {
+		if (this.#closed) throw new Error("Prepared state transitions are closed.");
+		throwIfPreparedAborted(parentSignal);
+		this.cancel(new DOMException("Prepared state transition superseded", "AbortError"));
+		const generation = this.#generation;
+		const controller = new AbortController();
+		const unlinkLifecycle = linkPreparedAbort(controller, this.lifecycle);
+		const unlinkParent = linkPreparedAbort(controller, parentSignal);
+		this.#controller = controller;
+		this.#target = next;
+		const operation = this.#operation.catch(() => {}).then(async () => {
+			throwIfPreparedAborted(controller.signal);
+			const previous = this.#current;
+			try {
+				await this.port.apply({
+					previous,
+					next,
+					reason
+				}, controller.signal);
+				throwIfPreparedAborted(controller.signal);
+			} catch (error) {
+				if (generation === this.#generation && !this.#closed && !isPreparedAbort(error)) await this.restoreAfter(error);
+				throw error;
+			}
+			if (generation === this.#generation && !this.#closed) this.#current = next;
+		});
+		this.#operation = operation.finally(() => {
+			unlinkLifecycle();
+			unlinkParent();
+			if (this.#controller === controller) this.#controller = void 0;
+			if (generation === this.#generation) this.#target = void 0;
+		});
+		return this.#operation;
+	}
+	async restoreAfter(primary) {
+		try {
+			await this.restore();
+		} catch (cleanup) {
+			throw new AggregateError([primary, cleanup], "Prepared state transition and restoration failed.");
+		}
+	}
+	async restore() {
+		if (this.#current !== void 0) await this.port.restore?.(this.#current);
+	}
+	cancel(reason) {
+		this.#generation += 1;
+		this.#target = void 0;
+		this.#controller?.abort(reason);
+		this.#controller = void 0;
+	}
+	settle() {
+		return Promise.allSettled([this.#operation]);
+	}
+	wait() {
+		return this.#operation;
+	}
+	async close(reason) {
+		this.#closed = true;
+		this.cancel(reason);
+		await this.#operation.catch(() => {});
+		this.#current = void 0;
+		this.#target = void 0;
+		this.#controller = void 0;
+		this.#operation = Promise.resolve();
+	}
+};
+//#endregion
+//#region src/prepared/query.ts
+const jsonKey = (value) => JSON.stringify(value);
+const queryText = (value) => isStringValue(value) ? value : JSON.stringify(value);
+const inputDomain = (notebookExport, name) => {
+	const values = /* @__PURE__ */ new Map();
+	for (const state of notebookExport.states()) if (Object.hasOwn(state.inputs, name)) {
+		const value = state.inputs[name];
+		values.set(jsonKey(value), value);
+	}
+	return Array.from(values.values());
+};
+const queryInput = (notebookExport, name, values) => {
+	if (values.length !== 1) throw new PreparedExportError("query_miss", `Query input ${JSON.stringify(name)} must have exactly one value.`);
+	const matches = inputDomain(notebookExport, name).filter((candidate) => queryText(candidate) === values[0]);
+	if (matches.length === 0) throw new PreparedExportError("query_miss", `Query input ${JSON.stringify(name)} has no exported value matching ${JSON.stringify(values[0])}.`);
+	if (matches.length > 1) throw new PreparedExportError("query_ambiguous", `Query input ${JSON.stringify(name)} matches more than one exported value.`);
+	return matches[0];
+};
+const resolvePreparedQuerySelection = (notebookExport, current, query) => {
+	const search = new URLSearchParams(query.startsWith("?") ? query.slice(1) : query);
+	const patch = [];
+	for (const name of notebookExport.inputNames) if (search.has(name)) patch.push([name, queryInput(notebookExport, name, search.getAll(name))]);
+	return patch.length === 0 ? void 0 : current.resolve(Object.fromEntries(patch));
+};
+const resolvePreparedQueryState = (notebookExport, current, query) => resolvePreparedQuerySelection(notebookExport, current, query) ?? current;
+//#endregion
+//#region src/prepared/state-update.ts
+const preparedControlPatch = (publication, inputs, objectId, value) => {
+	const bindings = publication.notebookExport.controlBindings;
+	if (!Object.hasOwn(bindings, objectId)) return;
+	return preparedControlInputPatch(inputs, bindings[objectId], value);
+};
+const preparedQueryPatch = (publication, query) => resolvePreparedQuerySelection(publication.notebookExport, publication.state, query)?.inputs;
+//#endregion
+//#region src/prepared/controller.ts
+var PreparedStateController = class {
+	#lifecycle = new AbortController();
+	#port;
+	#transitions;
+	#pendingInputs;
+	#disposed = false;
+	#disposal;
+	#unlinkLifecycle = () => {};
+	constructor(port, signal) {
+		this.#port = port;
+		this.#transitions = new PreparedStateTransitions(port, this.#lifecycle.signal);
+		if (signal !== void 0) this.#unlinkLifecycle = disposePreparedOnAbort(signal, this.#lifecycle, () => this.dispose());
+	}
+	snapshot() {
+		return this.#transitions.snapshot(this.#pendingInputs, this.#disposed);
+	}
+	start(publication, signal = this.#lifecycle.signal) {
+		this.#requireActive();
+		throwIfPreparedAborted(signal);
+		if (this.#transitions.current !== void 0 || this.#transitions.target !== void 0) throw new Error("Prepared state controller has already started.");
+		return this.#apply(publication, "start", signal);
+	}
+	async updateInputs(patch, signal = this.#lifecycle.signal) {
+		this.#requireActive();
+		throwIfPreparedAborted(signal);
+		const source = this.#transitions.target ?? this.#requireCurrent();
+		const base = this.#pendingInputs ?? source.state.inputs;
+		const requested = mergePreparedInputs(base, patch);
+		this.#pendingInputs = requested;
+		if (samePreparedInputs(requested, source.state.inputs)) {
+			if (this.#transitions.target !== void 0) await this.#transitions.wait();
+			else {
+				this.#pendingInputs = void 0;
+				await this.#transitions.restore();
+			}
+			return;
+		}
+		let next;
+		try {
+			next = withPreparedState(source, source.notebookExport.resolve(requested));
+		} catch (error) {
+			if (!isPreparedStateUnavailable(error)) this.#pendingInputs = void 0;
+			await this.#transitions.restoreAfter(error);
+			throw error;
+		}
+		try {
+			await this.#apply(next, "state", signal);
+		} catch (error) {
+			this.#pendingInputs = pendingInputsAfterFailure(this.#pendingInputs, requested, error, signal.aborted);
+			throw error;
+		}
+	}
+	async updateControl(objectId, value, signal = this.#lifecycle.signal) {
+		this.#requireActive();
+		throwIfPreparedAborted(signal);
+		const source = this.#transitions.target ?? this.#requireCurrent();
+		const patch = preparedControlPatch(source, this.#pendingInputs ?? source.state.inputs, objectId, value);
+		if (patch === void 0) return false;
+		await this.updateInputs(patch, signal);
+		return true;
+	}
+	async updateQuery(query, signal = this.#lifecycle.signal) {
+		this.#requireActive();
+		throwIfPreparedAborted(signal);
+		const source = this.#transitions.target ?? this.#requireCurrent();
+		const patch = preparedQueryPatch(source, query);
+		if (patch === void 0) return false;
+		await this.updateInputs(patch, signal);
+		return true;
+	}
+	async replacePublication(publication, signal = this.#lifecycle.signal) {
+		this.#requireActive();
+		throwIfPreparedAborted(signal);
+		const current = this.#transitions.current;
+		this.#pendingInputs = pendingInputsForPublication(current, publication, this.#pendingInputs);
+		const selected = selectPendingPublication(publication, this.#pendingInputs);
+		if (this.#transitions.target === void 0 && current !== void 0 && current.notebookExport.identity === selected.notebookExport.identity && current.state.fingerprint === selected.state.fingerprint) {
+			this.#transitions.setMetadata(selected);
+			this.#clearSatisfiedPending(selected);
+			return;
+		}
+		await this.#apply(selected, "publication", signal);
+	}
+	cancel(reason) {
+		this.#transitions.cancel(preparedAbortReason(reason, "Prepared state transition superseded"));
+	}
+	settle() {
+		return this.#transitions.settle();
+	}
+	dispose() {
+		this.#disposal ??= this.#dispose();
+		return this.#disposal;
+	}
+	async #apply(next, reason, signal) {
+		await this.#transitions.apply(next, reason, signal);
+		this.#clearSatisfiedPending(next);
+	}
+	#clearSatisfiedPending(publication) {
+		if (this.#pendingInputs !== void 0 && samePreparedInputs(this.#pendingInputs, publication.state.inputs)) this.#pendingInputs = void 0;
+	}
+	#requireCurrent() {
+		const current = this.#transitions.current;
+		if (current === void 0) throw new Error("Prepared state controller has not started.");
+		return current;
+	}
+	#requireActive() {
+		if (this.#disposed) throw new Error("Prepared state controller is disposed.");
+	}
+	async #dispose() {
+		this.#disposed = true;
+		this.#lifecycle.abort(new DOMException("Prepared state controller disposed", "AbortError"));
+		this.#unlinkLifecycle();
+		this.#unlinkLifecycle = () => {};
+		try {
+			await this.#transitions.close(this.#lifecycle.signal.reason);
+			await this.#port.dispose?.();
+		} finally {
+			this.#pendingInputs = void 0;
+		}
+	}
+};
+//#endregion
+//#region src/prepared/refresh.ts
+var PreparedPublicationRefresh = class {
+	#lifecycle = new AbortController();
+	#manifestUrl;
+	#state;
+	#dependencies;
+	#openOptions;
+	#onError;
+	#operation;
+	#controller;
+	#timer;
+	#disposed = false;
+	#unlinkLifecycle = () => {};
+	constructor(manifestUrl, state, options = {}) {
+		this.#manifestUrl = new URL(manifestUrl.href);
+		this.#state = state;
+		this.#dependencies = {
+			fetchManifest: options.dependencies?.fetchManifest ?? fetchPreparedExportManifest,
+			openPublication: options.dependencies?.openPublication ?? openPreparedPublication
+		};
+		const openOptions = {};
+		if (options.fetch !== void 0) openOptions.fetch = options.fetch;
+		if (options.openExport !== void 0) openOptions.openExport = options.openExport;
+		this.#openOptions = openOptions;
+		this.#onError = options.onError ?? (() => {});
+		if (options.signal !== void 0) this.#unlinkLifecycle = disposePreparedOnAbort(options.signal, this.#lifecycle, () => this.dispose());
+	}
+	start(signal = this.#lifecycle.signal) {
+		throwIfPreparedAborted(signal);
+		const snapshot = this.#state.snapshot();
+		if (snapshot.current !== void 0 || snapshot.transition.target !== void 0) throw new Error("Prepared publication refresh has already started.");
+		return this.#operation ?? this.#begin("start", signal);
+	}
+	refresh(signal = this.#lifecycle.signal) {
+		if (this.#disposed) return Promise.resolve();
+		throwIfPreparedAborted(signal);
+		return this.#operation ?? this.#begin("refresh", signal);
+	}
+	settle() {
+		return Promise.allSettled(this.#operation === void 0 ? [] : [this.#operation]);
+	}
+	syncPolling() {
+		this.#clearPolling();
+		if (this.#disposed) return;
+		const interval = this.#state.snapshot().current?.manifest.refreshIntervalMs ?? 0;
+		if (interval === 0) return;
+		this.#timer = setInterval(() => {
+			if (this.#disposed) return;
+			this.refresh().catch((error) => {
+				if (!this.#lifecycle.signal.aborted) this.#onError(error);
+			});
+		}, interval);
+	}
+	async dispose() {
+		if (this.#disposed) {
+			await this.settle();
+			return;
+		}
+		this.#disposed = true;
+		this.#clearPolling();
+		this.#lifecycle.abort(new DOMException("Prepared publication refresh disposed", "AbortError"));
+		this.#controller?.abort(this.#lifecycle.signal.reason);
+		this.#unlinkLifecycle();
+		this.#unlinkLifecycle = () => {};
+		await this.settle();
+	}
+	#begin(kind, parentSignal) {
+		throwIfPreparedAborted(parentSignal);
+		const controller = new AbortController();
+		const unlinkLifecycle = linkPreparedAbort(controller, this.#lifecycle.signal);
+		const unlinkParent = linkPreparedAbort(controller, parentSignal);
+		this.#controller = controller;
+		let tracked;
+		tracked = this.#perform(kind, controller.signal).finally(() => {
+			unlinkLifecycle();
+			unlinkParent();
+			if (this.#controller === controller) this.#controller = void 0;
+			if (this.#operation === tracked) this.#operation = void 0;
+		});
+		this.#operation = tracked;
+		return tracked;
+	}
+	async #perform(kind, signal) {
+		throwIfPreparedAborted(signal);
+		const manifestOptions = { signal };
+		if (this.#openOptions.fetch !== void 0) manifestOptions.fetch = this.#openOptions.fetch;
+		const manifest = await this.#dependencies.fetchManifest(this.#manifestUrl, manifestOptions);
+		throwIfPreparedAborted(signal);
+		if (this.#state.snapshot().transition.active) {
+			await this.#state.settle();
+			throwIfPreparedAborted(signal);
+		}
+		const current = this.#state.snapshot().current;
+		let publication;
+		if (current !== void 0 && current.notebookExport.identity === manifest.instance && current.notebookExport.base.href === preparedExportBase(manifest, this.#manifestUrl).href) publication = resolvePreparedPublication(manifest, this.#manifestUrl, current.notebookExport);
+		else publication = await this.#dependencies.openPublication(manifest, this.#manifestUrl, {
+			...this.#openOptions,
+			signal
+		});
+		publication = preservePreparedSelection(current, publication);
+		throwIfPreparedAborted(signal);
+		if (kind === "start" && current === void 0) await this.#state.start(publication, signal);
+		else await this.#state.replacePublication(publication, signal);
+		throwIfPreparedAborted(signal);
+		this.syncPolling();
+	}
+	#clearPolling() {
+		if (this.#timer !== void 0) {
+			clearInterval(this.#timer);
+			this.#timer = void 0;
+		}
+	}
+};
+//#endregion
+export { PreparedExportError, PreparedPublicationRefresh, PreparedStateController, fetchPreparedExportManifest, isPreparedAbort, isPreparedExportError, openPreparedPublication, parsePreparedExportManifest, preparedControlInputPatch, resolvePreparedPublication, resolvePreparedQuerySelection, resolvePreparedQueryState, samePreparedInputs };