@marimo-team/marimo-export 0.0.0 → 0.0.1

package/dist/marimo-snapshot--nNjqcq_.mjs

@@ -0,0 +1,280 @@
+import { _ as portableJsonValue, d as isJsonNumber, f as isJsonString, g as portableJsonObject, m as isRecordValue } from "./loader-CDfnJ5Yb.mjs";
+import { a as parseStrictJson, t as canonicalJson } from "./schema-SJ_aIgcO.mjs";
+//#region src/marimo-snapshot.ts
+const decoder = new TextDecoder("utf-8", {
+	fatal: true,
+	ignoreBOM: true
+});
+const encoder = new TextEncoder();
+const SHA256 = /^[0-9a-f]{64}$/u;
+const MAX_SNAPSHOT_VALUES = 2e6;
+const CELL_CHANNELS = /* @__PURE__ */ new Set([
+	"stdout",
+	"stderr",
+	"stdin",
+	"pdb",
+	"output",
+	"marimo-error",
+	"media"
+]);
+function parseMarimoOutputSnapshot(bytes) {
+	const root = snapshotRoot(bytes, "marimo.output.v1", [
+		"output",
+		"ownerCellId",
+		"projectionSha256",
+		"resources",
+		"schema"
+	]);
+	const ownerCellId = nonEmptyString(root.ownerCellId, "ownerCellId");
+	const projectionSha256 = digest(root.projectionSha256, "projectionSha256");
+	return Object.freeze({
+		schema: "marimo.output.v1",
+		projectionSha256,
+		ownerCellId,
+		output: parseCellOutput(root.output, "output"),
+		resources: parseResources(root.resources, ownerCellId, projectionSha256)
+	});
+}
+function parseMarimoCellSnapshot(bytes) {
+	const root = snapshotRoot(bytes, "marimo.cell.v1", [
+		"cell",
+		"console",
+		"outcome",
+		"output",
+		"projectionSha256",
+		"resources",
+		"schema"
+	]);
+	if (root.outcome !== "completed") throw new TypeError("Marimo cell snapshot outcome must be \"completed\".");
+	if (!Array.isArray(root.console)) throw new TypeError("Marimo cell snapshot console must be an array.");
+	const cell = parseCellIdentity(root.cell);
+	const projectionSha256 = digest(root.projectionSha256, "projectionSha256");
+	return Object.freeze({
+		schema: "marimo.cell.v1",
+		projectionSha256,
+		cell,
+		outcome: "completed",
+		output: parseCellOutput(root.output, "output"),
+		console: Object.freeze(root.console.map((output, index) => {
+			const parsed = parseCellOutput(output, `console[${index}]`);
+			if (parsed === null) throw new TypeError(`console[${index}] must contain an output.`);
+			return parsed;
+		})),
+		resources: parseResources(root.resources, cell.id, projectionSha256)
+	});
+}
+function snapshotRoot(bytes, schema, fields) {
+	const text = decoder.decode(bytes);
+	const parsed = parseStrictJson(text, MAX_SNAPSHOT_VALUES);
+	const root = strictRecord(parsed, `${schema} snapshot`, fields);
+	if (root.schema !== schema) throw new TypeError(`Snapshot schema must be ${JSON.stringify(schema)}.`);
+	if (!equalBytes(bytes, encoder.encode(canonicalJson(parsed)))) throw new TypeError(`${schema} snapshot must be canonical JSON.`);
+	return root;
+}
+function parseCellIdentity(value) {
+	const cell = strictRecord(value, "cell", [
+		"codeSha256",
+		"config",
+		"id",
+		"name"
+	]);
+	const id = nonEmptyString(cell.id, "cell.id");
+	const name = cell.name === null ? null : nonEmptyString(cell.name, "cell.name");
+	if (!isJsonString(cell.codeSha256) || !SHA256.test(cell.codeSha256)) throw new TypeError("cell.codeSha256 must be a lowercase SHA-256 digest.");
+	return Object.freeze({
+		id,
+		name,
+		codeSha256: cell.codeSha256,
+		config: portableJsonObject(cell.config, "cell.config")
+	});
+}
+function parseCellOutput(value, path) {
+	if (value === null) return null;
+	const output = strictRecord(value, path, [
+		"channel",
+		"data",
+		"mimetype"
+	]);
+	return Object.freeze({
+		channel: cellChannel(output.channel, `${path}.channel`),
+		mimetype: nonEmptyString(output.mimetype, `${path}.mimetype`),
+		data: portableJsonValue(output.data, `${path}.data`)
+	});
+}
+function parseResources(value, ownerCellId, projectionSha256) {
+	const resources = strictRecord(value, "resources", [
+		"files",
+		"functions",
+		"modelNotifications",
+		"uiValues"
+	]);
+	const files = record(resources.files, "resources.files");
+	const parsedFiles = Object.freeze(Object.fromEntries(Object.entries(files).map(([path, dataUrl]) => [nonEmptyString(path, "resources.files key"), dataUrlString(dataUrl, `resources.files[${JSON.stringify(path)}]`)])));
+	if (!Array.isArray(resources.modelNotifications)) throw new TypeError("resources.modelNotifications must be an array.");
+	const modelNotifications = Object.freeze(resources.modelNotifications.map((notification, index) => parseModelLifecycle(notification, index, parsedFiles, projectionSha256)));
+	const functions = record(resources.functions, "resources.functions");
+	const parsedFunctions = Object.freeze(Object.fromEntries(Object.entries(functions).map(([namespace, names]) => {
+		if (!Array.isArray(names) || names.some((name) => !isJsonString(name) || !name)) throw new TypeError(`resources.functions[${JSON.stringify(namespace)}] must be an array of names.`);
+		if (names.length > 0) throw new TypeError(`resources.functions[${JSON.stringify(namespace)}] must be empty for static replay.`);
+		return [projectionUiObjectId(namespace, "resources.functions key", ownerCellId, projectionSha256), Object.freeze([...names])];
+	})));
+	const uiValues = record(resources.uiValues, "resources.uiValues");
+	const parsedUiValues = Object.freeze(Object.fromEntries(Object.entries(uiValues).map(([objectId, item]) => [projectionUiObjectId(objectId, "resources.uiValues key", ownerCellId, projectionSha256), portableJsonValue(item, `resources.uiValues[${JSON.stringify(objectId)}]`)])));
+	for (const objectId of Object.keys(parsedUiValues)) if (!Object.hasOwn(parsedFunctions, objectId)) throw new TypeError(`resources.uiValues key ${JSON.stringify(objectId)} has no function namespace.`);
+	for (const objectId of Object.keys(parsedFunctions)) if (!Object.hasOwn(parsedUiValues, objectId)) throw new TypeError(`resources.functions key ${JSON.stringify(objectId)} has no replay UI value.`);
+	return Object.freeze({
+		files: parsedFiles,
+		modelNotifications,
+		functions: parsedFunctions,
+		uiValues: parsedUiValues
+	});
+}
+function projectionUiObjectId(value, path, ownerCellId, projectionSha256) {
+	const objectId = nonEmptyString(value, path);
+	const ownerPrefix = `${ownerCellId}-projection-${projectionSha256}-ui-`;
+	if (!objectId.startsWith(ownerPrefix) || objectId.length === ownerPrefix.length) throw new TypeError(`${path} must be a projection-scoped UI object owned by ${JSON.stringify(ownerCellId)}.`);
+	return objectId;
+}
+function parseModelLifecycle(value, index, files, projectionSha256) {
+	const path = `resources.modelNotifications[${index}]`;
+	const notification = strictRecord(value, path, [
+		"message",
+		"model_id",
+		"op"
+	]);
+	if (notification.op !== "model-lifecycle") throw new TypeError(`${path}.op must be "model-lifecycle".`);
+	const modelId = nonEmptyString(notification.model_id, `${path}.model_id`);
+	const modelPrefix = `projection-${projectionSha256}-model-`;
+	const modelIndex = modelId.slice(modelPrefix.length);
+	if (!modelId.startsWith(modelPrefix) || !/^(?:0|[1-9][0-9]*)$/u.test(modelIndex)) throw new TypeError(`${path}.model_id must belong to the snapshot projection.`);
+	const message = record(notification.message, `${path}.message`);
+	const method = message.method;
+	if (method === "open" || method === "update") {
+		exactFields(message, [
+			"buffer_paths",
+			"buffers",
+			"esm_spec",
+			"method",
+			"state"
+		], `${path}.message`);
+		const state = portableJsonObject(message.state, `${path}.message.state`);
+		const paths = bufferPaths(message.buffer_paths, `${path}.message.buffer_paths`);
+		const buffers = stringArray(message.buffers, `${path}.message.buffers`);
+		if (paths.length !== buffers.length) throw new TypeError(`${path}.message buffer paths and buffers must have equal length.`);
+		const esmSpec = parseEsmSpec(message.esm_spec, `${path}.message.esm_spec`, files);
+		return Object.freeze({
+			op: "model-lifecycle",
+			model_id: modelId,
+			message: Object.freeze({
+				method,
+				state,
+				buffer_paths: paths,
+				buffers,
+				esm_spec: esmSpec
+			})
+		});
+	} else if (method === "custom") {
+		exactFields(message, [
+			"buffers",
+			"content",
+			"method"
+		], `${path}.message`);
+		return Object.freeze({
+			op: "model-lifecycle",
+			model_id: modelId,
+			message: Object.freeze({
+				method: "custom",
+				content: portableJsonValue(message.content, `${path}.message.content`),
+				buffers: stringArray(message.buffers, `${path}.message.buffers`)
+			})
+		});
+	} else if (method === "close") {
+		exactFields(message, ["method"], `${path}.message`);
+		return Object.freeze({
+			op: "model-lifecycle",
+			model_id: modelId,
+			message: Object.freeze({ method: "close" })
+		});
+	} else throw new TypeError(`${path}.message.method is invalid.`);
+}
+function bufferPaths(value, path) {
+	if (!Array.isArray(value)) throw new TypeError(`${path} must be an array.`);
+	return Object.freeze(value.map((item, index) => {
+		if (!Array.isArray(item) || item.length === 0) throw new TypeError(`${path}[${index}] must be a non-empty array.`);
+		const parsed = item.map((token) => {
+			if (isJsonString(token)) return token;
+			if (isJsonNumber(token) && Number.isSafeInteger(token) && token >= 0) return token;
+			throw new TypeError(`${path}[${index}] contains an invalid token.`);
+		});
+		return Object.freeze(parsed);
+	}));
+}
+function parseEsmSpec(value, path, files) {
+	if (value === null) return null;
+	const spec = strictRecord(value, path, ["hash", "url"]);
+	const hash = nonEmptyString(spec.hash, `${path}.hash`);
+	const url = nonEmptyString(spec.url, `${path}.url`);
+	const embeddedKey = url.startsWith("./@file/") ? url.slice(1) : url;
+	if (Object.hasOwn(files, embeddedKey) || url.startsWith("data:")) return Object.freeze({
+		hash,
+		url
+	});
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch (error) {
+		throw new TypeError(`${path}.url references an unavailable resource.`, { cause: error });
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError(`${path}.url uses an incompatible protocol.`);
+	return Object.freeze({
+		hash,
+		url
+	});
+}
+function stringArray(value, path) {
+	if (!Array.isArray(value) || value.some((item) => !isJsonString(item))) throw new TypeError(`${path} must be an array of strings.`);
+	return Object.freeze([...value]);
+}
+function strictRecord(value, path, fields) {
+	const parsed = record(value, path);
+	exactFields(parsed, fields, path);
+	return parsed;
+}
+function exactFields(value, fields, path) {
+	const expected = new Set(fields);
+	const missing = fields.filter((field) => !Object.hasOwn(value, field));
+	const extra = Object.keys(value).filter((field) => !expected.has(field));
+	if (missing.length > 0) throw new TypeError(`${path} is missing fields: ${missing.join(", ")}.`);
+	if (extra.length > 0) throw new TypeError(`${path} has unknown fields: ${extra.join(", ")}.`);
+}
+function record(value, path) {
+	if (!isJsonObject(value)) throw new TypeError(`${path} must be an object.`);
+	return value;
+}
+function isJsonObject(value) {
+	return isRecordValue(value);
+}
+function nonEmptyString(value, path) {
+	if (!isJsonString(value) || value.length === 0) throw new TypeError(`${path} must be a non-empty string.`);
+	return value;
+}
+function digest(value, path) {
+	const parsed = nonEmptyString(value, path);
+	if (!SHA256.test(parsed)) throw new TypeError(`${path} must be a lowercase SHA-256 digest.`);
+	return parsed;
+}
+function dataUrlString(value, path) {
+	const dataUrl = nonEmptyString(value, path);
+	if (!dataUrl.startsWith("data:")) throw new TypeError(`${path} must contain a data URL.`);
+	return dataUrl;
+}
+function cellChannel(value, path) {
+	const channel = nonEmptyString(value, path);
+	if (!CELL_CHANNELS.has(channel)) throw new TypeError(`${path} is not a Marimo cell channel.`);
+	return channel;
+}
+function equalBytes(left, right) {
+	return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+//#endregion
+export { parseMarimoOutputSnapshot as n, parseMarimoCellSnapshot as t };

package/dist/marimo-snapshot-Df66Xan0.d.mts

@@ -0,0 +1,74 @@
+import { B as JsonObject, H as JsonValue } from "./types-D52GHn1Q.mjs";
+//#region src/marimo-snapshot.d.ts
+type MarimoCellChannel = "stdout" | "stderr" | "stdin" | "pdb" | "output" | "marimo-error" | "media";
+type MarimoBufferPathToken = string | number;
+type MarimoBufferPath = readonly [MarimoBufferPathToken, ...MarimoBufferPathToken[]];
+interface MarimoEsmSpec {
+  readonly hash: string;
+  readonly url: string;
+}
+interface MarimoModelOpenMessage {
+  readonly method: "open";
+  readonly state: JsonObject;
+  readonly buffer_paths: readonly MarimoBufferPath[];
+  readonly buffers: readonly string[];
+  readonly esm_spec: MarimoEsmSpec | null;
+}
+interface MarimoModelUpdateMessage {
+  readonly method: "update";
+  readonly state: JsonObject;
+  readonly buffer_paths: readonly MarimoBufferPath[];
+  readonly buffers: readonly string[];
+  readonly esm_spec: MarimoEsmSpec | null;
+}
+interface MarimoModelCustomMessage {
+  readonly method: "custom";
+  readonly content: JsonValue;
+  readonly buffers: readonly string[];
+}
+interface MarimoModelCloseMessage {
+  readonly method: "close";
+}
+type MarimoModelLifecycleMessage = MarimoModelOpenMessage | MarimoModelUpdateMessage | MarimoModelCustomMessage | MarimoModelCloseMessage;
+interface MarimoModelLifecycleNotification {
+  readonly op: "model-lifecycle";
+  readonly model_id: string;
+  readonly message: MarimoModelLifecycleMessage;
+}
+interface MarimoCellOutput {
+  readonly channel: MarimoCellChannel;
+  readonly mimetype: string;
+  readonly data: JsonValue;
+}
+interface MarimoReplayResources {
+  readonly files: Readonly<Record<string, string>>;
+  readonly modelNotifications: readonly MarimoModelLifecycleNotification[];
+  readonly functions: Readonly<Record<string, readonly string[]>>;
+  readonly uiValues: Readonly<Record<string, JsonValue>>;
+}
+interface MarimoOutputSnapshot {
+  readonly schema: "marimo.output.v1";
+  readonly projectionSha256: string;
+  readonly ownerCellId: string;
+  readonly output: MarimoCellOutput | null;
+  readonly resources: MarimoReplayResources;
+}
+interface MarimoCellIdentity {
+  readonly id: string;
+  readonly name: string | null;
+  readonly codeSha256: string;
+  readonly config: JsonObject;
+}
+interface MarimoCellSnapshot {
+  readonly schema: "marimo.cell.v1";
+  readonly projectionSha256: string;
+  readonly cell: MarimoCellIdentity;
+  readonly outcome: "completed";
+  readonly output: MarimoCellOutput | null;
+  readonly console: readonly MarimoCellOutput[];
+  readonly resources: MarimoReplayResources;
+}
+declare function parseMarimoOutputSnapshot(bytes: Uint8Array): MarimoOutputSnapshot;
+declare function parseMarimoCellSnapshot(bytes: Uint8Array): MarimoCellSnapshot;
+//#endregion
+export { parseMarimoOutputSnapshot as _, MarimoCellOutput as a, MarimoModelCloseMessage as c, MarimoModelLifecycleNotification as d, MarimoModelOpenMessage as f, parseMarimoCellSnapshot as g, MarimoReplayResources as h, MarimoCellIdentity as i, MarimoModelCustomMessage as l, MarimoOutputSnapshot as m, MarimoBufferPathToken as n, MarimoCellSnapshot as o, MarimoModelUpdateMessage as p, MarimoCellChannel as r, MarimoEsmSpec as s, MarimoBufferPath as t, MarimoModelLifecycleMessage as u };

package/dist/prepared/index.d.mts

@@ -0,0 +1,116 @@
+import { B as JsonObject, C as NotebookExport, H as JsonValue, O as OpenExportOptions, c as ControlBinding, h as ExportState } from "../types-D52GHn1Q.mjs";
+//#region src/prepared/manifest.d.ts
+interface PreparedExportManifest {
+  readonly schema: "marimo-export.prepared.v1";
+  readonly instance: string;
+  readonly exportUrl: string;
+  readonly inputs: JsonObject;
+  readonly stateFingerprint: string;
+  readonly refreshIntervalMs?: number;
+}
+interface PreparedPublication {
+  readonly manifest: PreparedExportManifest;
+  readonly notebookExport: NotebookExport;
+  readonly state: ExportState;
+}
+interface OpenPreparedPublicationOptions extends OpenExportOptions {
+  readonly openExport?: (base: string | URL, options?: OpenExportOptions) => Promise<NotebookExport>;
+}
+declare const parsePreparedExportManifest: <Input>(input: Input) => PreparedExportManifest;
+declare const resolvePreparedPublication: (manifest: PreparedExportManifest, manifestUrl: URL, notebookExport: NotebookExport) => PreparedPublication;
+declare const openPreparedPublication: (manifest: PreparedExportManifest, manifestUrl: URL, options?: OpenPreparedPublicationOptions) => Promise<PreparedPublication>;
+//#endregion
+//#region src/prepared/manifest-fetch.d.ts
+interface PreparedManifestFetchOptions {
+  readonly fetch?: typeof globalThis.fetch;
+  readonly signal?: AbortSignal;
+}
+declare const fetchPreparedExportManifest: (url: URL, options?: PreparedManifestFetchOptions) => Promise<PreparedExportManifest>;
+//#endregion
+//#region src/prepared/state-port.d.ts
+type PreparedStateChangeReason = "start" | "state" | "publication";
+interface PreparedStateChange {
+  readonly previous: PreparedPublication | undefined;
+  readonly next: PreparedPublication;
+  readonly reason: PreparedStateChangeReason;
+}
+interface PreparedStatePort {
+  /** Load every required output, then publish the complete state atomically. */
+  apply(change: PreparedStateChange, signal: AbortSignal): Promise<void>;
+  /** Restore the last committed state after a rejected application request. */
+  restore?(publication: PreparedPublication): void | Promise<void>;
+  dispose?(): void | Promise<void>;
+}
+interface PreparedStateSnapshot {
+  readonly current: PreparedPublication | undefined;
+  readonly pendingInputs: JsonObject | undefined;
+  readonly transition: {
+    readonly generation: number;
+    readonly target: PreparedPublication | undefined;
+    readonly active: boolean;
+  };
+  readonly disposed: boolean;
+}
+//#endregion
+//#region src/prepared/controller.d.ts
+declare class PreparedStateController {
+  #private;
+  constructor(port: PreparedStatePort, signal?: AbortSignal);
+  snapshot(): PreparedStateSnapshot;
+  start(publication: PreparedPublication, signal?: AbortSignal): Promise<void>;
+  updateInputs(patch: JsonObject, signal?: AbortSignal): Promise<void>;
+  updateControl(objectId: string, value: JsonValue, signal?: AbortSignal): Promise<boolean>;
+  updateQuery(query: string, signal?: AbortSignal): Promise<boolean>;
+  replacePublication(publication: PreparedPublication, signal?: AbortSignal): Promise<void>;
+  cancel<Reason>(reason?: Reason): void;
+  settle(): Promise<readonly PromiseSettledResult<void>[]>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/prepared/refresh.d.ts
+interface PreparedPublicationRefreshDependencies {
+  fetchManifest(url: URL, options?: PreparedManifestFetchOptions): Promise<PreparedExportManifest>;
+  openPublication(manifest: PreparedExportManifest, manifestUrl: URL, options?: OpenPreparedPublicationOptions): Promise<PreparedPublication>;
+}
+interface PreparedPublicationRefreshOptions {
+  readonly dependencies?: Partial<PreparedPublicationRefreshDependencies>;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly openExport?: OpenPreparedPublicationOptions["openExport"];
+  readonly signal?: AbortSignal;
+  readonly onError?: (cause: unknown) => void;
+}
+declare class PreparedPublicationRefresh {
+  #private;
+  constructor(manifestUrl: URL, state: PreparedStateController, options?: PreparedPublicationRefreshOptions);
+  start(signal?: AbortSignal): Promise<void>;
+  refresh(signal?: AbortSignal): Promise<void>;
+  settle(): Promise<readonly PromiseSettledResult<void>[]>;
+  syncPolling(): void;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/prepared/control.d.ts
+declare const samePreparedInputs: (left: JsonObject, right: JsonObject) => boolean;
+declare const preparedControlInputPatch: (inputs: JsonObject, binding: ControlBinding, value: JsonValue) => JsonObject | undefined;
+//#endregion
+//#region src/prepared/query.d.ts
+declare const resolvePreparedQuerySelection: (notebookExport: NotebookExport, current: ExportState, query: string) => ExportState | undefined;
+declare const resolvePreparedQueryState: (notebookExport: NotebookExport, current: ExportState, query: string) => ExportState;
+//#endregion
+//#region src/prepared/cancellation.d.ts
+declare const isPreparedAbort: <Value>(value: Value) => boolean;
+//#endregion
+//#region src/prepared/errors.d.ts
+declare const PREPARED_EXPORT_ERROR_CODES: readonly ["manifest_invalid", "manifest_read_failed", "query_ambiguous", "query_miss"];
+type PreparedExportErrorCode = (typeof PREPARED_EXPORT_ERROR_CODES)[number];
+interface PreparedExportErrorOptions {
+  readonly cause?: unknown;
+}
+declare class PreparedExportError extends Error {
+  readonly code: PreparedExportErrorCode;
+  readonly cause: unknown;
+  constructor(code: PreparedExportErrorCode, message: string, options?: PreparedExportErrorOptions);
+}
+declare const isPreparedExportError: <Value>(value: Value) => value is Value & PreparedExportError;
+//#endregion
+export { type OpenPreparedPublicationOptions, PreparedExportError, type PreparedExportErrorCode, type PreparedExportManifest, type PreparedManifestFetchOptions, type PreparedPublication, PreparedPublicationRefresh, type PreparedPublicationRefreshDependencies, type PreparedPublicationRefreshOptions, type PreparedStateChange, type PreparedStateChangeReason, PreparedStateController, type PreparedStatePort, type PreparedStateSnapshot, fetchPreparedExportManifest, isPreparedAbort, isPreparedExportError, openPreparedPublication, parsePreparedExportManifest, preparedControlInputPatch, resolvePreparedPublication, resolvePreparedQuerySelection, resolvePreparedQueryState, samePreparedInputs };