@stll/folio-cli 0.1.1 → 0.3.0

package/dist/output-file.js

@@ -1,10 +1,10 @@
-import { NO_FOLLOW, errnoCode, sameFile } from "./document.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { NO_FOLLOW, errnoCode, sameFile } from "./file-system.js";
 import { Result } from "better-result";
-import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { open, realpath, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 //#region src/output-file.ts
 /**
 * Write a rendered file (PDF, PNG, HTML) next to where the caller asked: to a

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.1.1";
+var version = "0.3.0";
 //#endregion
 export { version };

package/dist/save.d.ts

@@ -0,0 +1,48 @@
+import { FolioCliIo } from "./cli.js";
+import { FolioCliError } from "./errors.js";
+import { WriteDestination } from "./transaction.js";
+import "./execute-write.js";
+import { Result } from "better-result";
+//#region src/save.d.ts
+/** How the editor produced the bytes, as it reports it. */
+declare const EDITOR_SAVE_STRATEGIES: readonly ["selective", "full-repack", "unspecified"];
+type EditorSaveStrategy = (typeof EDITOR_SAVE_STRATEGIES)[number];
+type SaveDocumentOptions = {
+  /** The document the editor opened. */
+  path: string;
+  /** The whole package the editor serialized. */
+  bytes: Uint8Array;
+  /** The fileVersion the editor loaded (or last saved). */
+  expectedVersion: string;
+  author: string;
+  /** The lease owner a transient lease records (default `folio-cli`). */
+  owner?: string;
+  /** Which editor saved, for the journal (`vscode`, `herdr`; default `cli`). */
+  surface?: string;
+  saveStrategy?: EditorSaveStrategy;
+  /** Idempotency key; generated when absent. */
+  txId?: string;
+  /** After waiting for another editor to flush, take the lease over. */
+  force?: boolean;
+  /** Default in place. */
+  destination?: WriteDestination;
+  /** Save under a lease the caller holds (an editor's long-lived lease) instead of taking one. */
+  leaseToken?: string;
+  /** How long to wait for another editor holding the lease to save and release. */
+  flushWaitMs?: number;
+  /** The transaction's UTC timestamp (default now). */
+  date?: string;
+};
+/**
+ * Commit an editor's serialized package as one transaction and return its
+ * receipt (`fileVersion`, `backup`, `changedParts`, ...). Refuses a stale
+ * `expectedVersion`, a lease another live holder keeps, bytes that do not
+ * open as a document, and anything over 64 MiB, writing nothing.
+ */
+declare const saveDocumentBytes: (options: SaveDocumentOptions) => Promise<Result<Readonly<Record<string, unknown>>, FolioCliError>>;
+declare const SAVE_HELP: string;
+/** `--flush-wait <ms>`: a whole number of milliseconds from 0. */
+declare const parseFlushWait: (value: string | undefined) => Result<number | undefined, FolioCliError>;
+declare const runSave: (rest: readonly string[], io: FolioCliIo) => Promise<number>;
+//#endregion
+export { EDITOR_SAVE_STRATEGIES, EditorSaveStrategy, SAVE_HELP, SaveDocumentOptions, parseFlushWait, runSave, saveDocumentBytes };

package/dist/save.js

@@ -0,0 +1,354 @@
+import { MAX_DOCUMENT_BYTES, checkExpectedVersion, isFileVersion, readDocumentFile } from "./document.js";
+import { acquireLeaseForWrite } from "./editor-lease.js";
+import { EXIT_CODES, FOLIO_CLI_ERROR_CODES, cliError, exitCodeForError } from "./errors.js";
+import { EDITOR_SAVE_TOOL, TX_ID_PATTERN, canonicalJson, resolveTarget } from "./execute-write.js";
+import { fileVersionOf, sameFile } from "./file-system.js";
+import { findCommit, journalPathFor, recoverStages } from "./journal.js";
+import { adoptLease, isLeaseOwner } from "./lock.js";
+import { OUTPUT_FORMATS, failureEnvelope, isOutputFormat, renderEnvelope, successEnvelope } from "./output.js";
+import { diffPackages } from "./package-parts.js";
+import { resolveAuthor, resolveTransactionDate } from "./provenance.js";
+import { unsafePath } from "./sidecar.js";
+import { commitTransaction } from "./transaction.js";
+import { Result } from "better-result";
+import { parseArgs } from "node:util";
+import { FolioDocxReviewer } from "@stll/folio-core/server";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/save.ts
+/**
+* `folio save`: commit a whole package an editor serialized (a selective
+* patch where the editor could, a full repack otherwise) with the same
+* transaction as a tool call: under the lease, after crash recovery, against
+* the version the editor loaded, staged, checked, backed up, journaled
+* (`tool: "editor_save"`), and renamed into place.
+*
+* Unlike a tool call, a save may replace every part: the editor has to be
+* able to save any edit, and the backup and journal line keep the previous
+* version recoverable; the host warns the user. It is not an MCP tool, so
+* an agent never replaces a whole package.
+*/
+/** How the editor produced the bytes, as it reports it. */
+const EDITOR_SAVE_STRATEGIES = [
+	"selective",
+	"full-repack",
+	"unspecified"
+];
+const isEditorSaveStrategy = (value) => EDITOR_SAVE_STRATEGIES.some((strategy) => strategy === value);
+const invalidInput = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message,
+	hint
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const NAME_PATTERN = /^[\w.-]{1,64}$/u;
+const checkOptions = (options) => {
+	if (options.txId !== void 0 && !TX_ID_PATTERN.test(options.txId)) return Result.err(invalidInput("txId must be 1 to 128 letters, digits, '.', '_' or '-'."));
+	if (options.owner !== void 0 && !isLeaseOwner(options.owner)) return Result.err(invalidInput("owner must be 1 to 64 letters, digits, '.', '_' or '-'."));
+	if (options.surface !== void 0 && !NAME_PATTERN.test(options.surface)) return Result.err(invalidInput("surface must be 1 to 64 letters, digits, '.', '_' or '-'."));
+	if (!isFileVersion(options.expectedVersion)) return Result.err(invalidInput("expectedVersion must be a 64-character hex fileVersion."));
+	if (options.bytes.byteLength > 67108864) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.tooLarge,
+		message: `The saved package is over the ${MAX_DOCUMENT_BYTES}-byte limit.`
+	}));
+	return Result.ok();
+};
+/** The bytes must open as a document before anything is staged. */
+const checkParses = async (bytes) => {
+	const parsed = await Result.tryPromise({
+		try: () => FolioDocxReviewer.fromBuffer(bytes.slice().buffer),
+		catch: (error) => cliError({
+			code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+			message: `The saved bytes are not a readable .docx package: ${error instanceof Error ? error.message : String(error)}`,
+			hint: "Nothing was written; the editor's serializer produced a broken package."
+		})
+	});
+	return parsed.isErr() ? Result.err(parsed.error) : Result.ok();
+};
+const leaseForSave = async (documentPath, txId, options) => {
+	if (options.leaseToken !== void 0) {
+		const adopted = await adoptLease(documentPath, options.leaseToken);
+		return adopted.isOk() ? Result.ok({
+			lease: adopted.value,
+			flush: { type: "notAsked" }
+		}) : Result.err(adopted.error);
+	}
+	return await acquireLeaseForWrite({
+		documentPath,
+		txId,
+		force: options.force === true,
+		owner: options.owner ?? "folio-cli",
+		...options.flushWaitMs !== void 0 && { flushWaitMs: options.flushWaitMs }
+	});
+};
+/**
+* Commit an editor's serialized package as one transaction and return its
+* receipt (`fileVersion`, `backup`, `changedParts`, ...). Refuses a stale
+* `expectedVersion`, a lease another live holder keeps, bytes that do not
+* open as a document, and anything over 64 MiB, writing nothing.
+*/
+const saveDocumentBytes = async (options) => {
+	const checked = checkOptions(options);
+	if (checked.isErr()) return Result.err(checked.error);
+	const date = resolveTransactionDate(options.date);
+	if (date.isErr()) return Result.err(date.error);
+	const destination = options.destination ?? { type: "inPlace" };
+	const txId = options.txId ?? randomUUID();
+	const surface = options.surface ?? "cli";
+	const saveStrategy = options.saveStrategy ?? "unspecified";
+	const owner = options.owner ?? "folio-cli";
+	const bytes = new Uint8Array(options.bytes);
+	const parses = await checkParses(bytes);
+	if (parses.isErr()) return Result.err(parses.error);
+	const target = await resolveTarget({
+		sourcePath: options.path,
+		destination
+	});
+	if (target.isErr()) return Result.err(target.error);
+	const { sourcePath, sourceIdentity, destinationPath } = target.value;
+	const inPlace = destinationPath === sourcePath;
+	const journalPath = journalPathFor(destinationPath, void 0);
+	const acquired = await leaseForSave(destinationPath, txId, options);
+	if (acquired.isErr()) return Result.err(acquired.error);
+	const { lease, flush } = acquired.value;
+	try {
+		const recovered = await recoverStages({
+			documentPath: destinationPath,
+			journalPath,
+			now: date.value
+		});
+		if (recovered.isErr()) return Result.err(recovered.error);
+		const toVersion = fileVersionOf(bytes);
+		const requestHash = createHash("sha256").update(canonicalJson({
+			tool: EDITOR_SAVE_TOOL,
+			toVersion,
+			source: sourcePath,
+			destination: destinationPath
+		})).digest("hex");
+		if (options.txId !== void 0) {
+			const found = await findCommit(journalPath, txId);
+			if (found.isErr()) return Result.err(found.error);
+			const prior = found.value;
+			if (prior !== void 0) return prior.requestHash === requestHash ? Result.ok({
+				...prior.receipt,
+				status: "replayed"
+			}) : Result.err(cliError({
+				code: FOLIO_CLI_ERROR_CODES.transactionConflict,
+				message: `Transaction ${txId} already committed a different save.`,
+				hint: "Use a new txId for a new save."
+			}));
+		}
+		const source = await readDocumentFile(sourcePath);
+		if (source.isErr()) return Result.err(source.error);
+		const expectedIdentity = inPlace && (flush.type !== "notAsked" || recovered.value.some(({ action }) => action === "rolledForward")) ? source.value.identity : sourceIdentity;
+		if (!sameFile(source.value.identity, expectedIdentity)) return Result.err(unsafePath(`${sourcePath} was replaced while the save started.`));
+		if (inPlace && source.value.links > 1) return Result.err(unsafePath(`${sourcePath} has other hard links; an in-place save would detach them.`, "Save to a new file with -o instead."));
+		const version = checkExpectedVersion(source.value, options.expectedVersion);
+		if (version.isErr()) return Result.err(cliError({
+			code: version.error.code,
+			message: version.error.message,
+			hint: "Reload the document (it changed on disk) and save again.",
+			details: {
+				...isRecord(version.error.details) ? version.error.details : {},
+				...recovered.value.length > 0 && { recovered: recovered.value }
+			}
+		}));
+		const base = {
+			txId,
+			tool: EDITOR_SAVE_TOOL,
+			path: destinationPath,
+			fromVersion: source.value.fileVersion,
+			...!inPlace && { source: {
+				path: sourcePath,
+				fileVersion: source.value.fileVersion
+			} },
+			author: options.author,
+			time: date.value,
+			owner,
+			surface,
+			saveStrategy
+		};
+		if (inPlace && toVersion === source.value.fileVersion) return Result.ok({
+			...base,
+			status: "unchanged",
+			fileVersion: toVersion,
+			changedParts: []
+		});
+		const changedParts = await diffPackages(source.value.bytes, bytes);
+		if (changedParts.isErr()) return Result.err(changedParts.error);
+		const receipt = {
+			...base,
+			status: "committed",
+			changedParts: changedParts.value,
+			...recovered.value.length > 0 && { recovered: recovered.value }
+		};
+		const committed = await commitTransaction({
+			txId,
+			destinationPath,
+			destination,
+			sourcePath,
+			sourceIdentity: expectedIdentity,
+			fromVersion: source.value.fileVersion,
+			bytes,
+			verifyLease: lease.verify,
+			changedParts: changedParts.value,
+			journalPath,
+			entry: {
+				txId,
+				requestHash,
+				tool: EDITOR_SAVE_TOOL,
+				fromVersion: source.value.fileVersion,
+				author: options.author,
+				time: date.value,
+				ops: {
+					surface,
+					saveStrategy,
+					owner
+				},
+				receipts: []
+			},
+			receipt
+		});
+		return committed.isErr() ? Result.err(committed.error) : Result.ok(committed.value.receipt);
+	} finally {
+		await lease.release();
+	}
+};
+const usageError = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.usage,
+	message,
+	hint
+});
+const SAVE_HELP = [
+	"Usage: folio save <file> --from <saved.docx> --expect-version <sha> [flags]",
+	"",
+	"Commit a whole package an editor serialized as a folio transaction: under the write",
+	"lease, against the version the editor loaded, checked, backed up to .folio/backups,",
+	"journaled (tool \"editor_save\"), and renamed into place atomically. Unlike the tool",
+	"commands it may replace every part. It is not offered over MCP.",
+	"",
+	"An editor holding the lease long-lived saves under it with --lease-token. Any other",
+	"save that finds such an editor asks it to save and release first, waiting up to",
+	"--flush-wait ms; its own --expect-version then no longer matches and it is refused.",
+	"",
+	"Flags:",
+	"  --from <path>                       The package to commit (required)",
+	"  --expect-version <sha>              The fileVersion the editor loaded (required)",
+	"  -o, --out <path>                    Save to this path instead of in place",
+	"  --overwrite                         Let -o replace an existing file",
+	"  --expect-destination-version <sha>  The fileVersion of the file -o --overwrite replaces",
+	"  --author <name>                     Author (default: FOLIO_AUTHOR, then git user.name)",
+	"  --owner <name>                      Lease owner to record (default: folio-cli)",
+	"  --surface <name>                    Which editor saved, for the journal (default: cli)",
+	`  --save-strategy <kind>              ${EDITOR_SAVE_STRATEGIES.join(", ")}`,
+	"  --lease-token <token>               Save under this held lease instead of taking one",
+	"  --flush-wait <ms>                   Wait for another editor to flush (default 5000)",
+	"  --tx-id <key>                       Idempotency key",
+	"  --force                             After the wait, take the lease over",
+	"  --date <iso>                        Transaction timestamp (default: now)",
+	"  --output <json|text>                Envelope format",
+	""
+].join("\n");
+const saveOptions = {
+	from: { type: "string" },
+	"expect-version": { type: "string" },
+	out: {
+		type: "string",
+		short: "o"
+	},
+	overwrite: { type: "boolean" },
+	"expect-destination-version": { type: "string" },
+	author: { type: "string" },
+	owner: { type: "string" },
+	surface: { type: "string" },
+	"save-strategy": { type: "string" },
+	"lease-token": { type: "string" },
+	"flush-wait": { type: "string" },
+	"tx-id": { type: "string" },
+	force: { type: "boolean" },
+	date: { type: "string" },
+	output: { type: "string" },
+	help: {
+		type: "boolean",
+		short: "h"
+	}
+};
+/** `--flush-wait <ms>`: a whole number of milliseconds from 0. */
+const parseFlushWait = (value) => {
+	if (value === void 0) return Result.ok(void 0);
+	const parsed = Number(value);
+	return Number.isInteger(parsed) && parsed >= 0 ? Result.ok(parsed) : Result.err(usageError("--flush-wait expects a whole number of milliseconds."));
+};
+const parseSaveArgs = (rest) => parseArgs({
+	args: [...rest],
+	options: saveOptions,
+	allowPositionals: true,
+	strict: true
+});
+const runSaveValues = async (values, positionals, io) => {
+	const [file, ...extra] = positionals;
+	if (file === void 0 || extra.length > 0) return Result.err(usageError("Usage: folio save <file> --from <saved.docx> --expect-version <sha>."));
+	if (values.from === void 0) return Result.err(usageError("folio save needs --from <saved.docx>."));
+	if (values["expect-version"] === void 0) return Result.err(usageError("folio save needs --expect-version <fileVersion> of the file the editor loaded."));
+	const saveStrategy = values["save-strategy"];
+	if (saveStrategy !== void 0 && !isEditorSaveStrategy(saveStrategy)) return Result.err(usageError(`--save-strategy must be ${EDITOR_SAVE_STRATEGIES.join(", ")}.`));
+	const expectedDestination = values["expect-destination-version"];
+	if ((values.overwrite === true || expectedDestination !== void 0) && values.out === void 0) return Result.err(usageError("--overwrite and --expect-destination-version only apply to -o <path>."));
+	const flushWaitMs = parseFlushWait(values["flush-wait"]);
+	if (flushWaitMs.isErr()) return Result.err(flushWaitMs.error);
+	const author = resolveAuthor({
+		explicit: values.author,
+		env: io.env,
+		cwd: io.cwd
+	});
+	if (author.isErr()) return Result.err(author.error);
+	const saved = await readDocumentFile(values.from);
+	if (saved.isErr()) return Result.err(saved.error);
+	return await saveDocumentBytes({
+		path: file,
+		bytes: saved.value.bytes,
+		expectedVersion: values["expect-version"],
+		author: author.value,
+		...values.owner !== void 0 && { owner: values.owner },
+		...values.surface !== void 0 && { surface: values.surface },
+		...saveStrategy !== void 0 && { saveStrategy },
+		...values["tx-id"] !== void 0 && { txId: values["tx-id"] },
+		...values["lease-token"] !== void 0 && { leaseToken: values["lease-token"] },
+		...flushWaitMs.value !== void 0 && { flushWaitMs: flushWaitMs.value },
+		...values.date !== void 0 && { date: values.date },
+		force: values.force === true,
+		destination: values.out === void 0 ? { type: "inPlace" } : {
+			type: "file",
+			path: values.out,
+			overwrite: values.overwrite === true,
+			expectedVersion: expectedDestination
+		}
+	});
+};
+const emit = (io, format, result) => {
+	const rendered = renderEnvelope({
+		envelope: result.isOk() ? successEnvelope(result.value) : failureEnvelope(result.error),
+		format,
+		tool: EDITOR_SAVE_TOOL
+	});
+	if (rendered.stdout !== "") io.stdout(rendered.stdout);
+	if (rendered.stderr !== "") io.stderr(rendered.stderr);
+	return result.isOk() ? EXIT_CODES.ok : exitCodeForError(result.error.code);
+};
+const runSave = async (rest, io) => {
+	const fallback = io.isTTY ? "text" : "json";
+	const parsed = Result.try({
+		try: () => parseSaveArgs(rest),
+		catch: (error) => usageError(error instanceof Error ? error.message : String(error), "Run folio save --help.")
+	});
+	if (parsed.isErr()) return emit(io, fallback, parsed);
+	const { values, positionals } = parsed.value;
+	if (values.help === true) {
+		io.stdout(SAVE_HELP);
+		return EXIT_CODES.ok;
+	}
+	const output = values.output;
+	if (output !== void 0 && !isOutputFormat(output)) return emit(io, fallback, Result.err(usageError(`--output must be ${OUTPUT_FORMATS.join(" or ")}.`)));
+	return emit(io, output ?? fallback, await runSaveValues(values, positionals, io));
+};
+//#endregion
+export { EDITOR_SAVE_STRATEGIES, SAVE_HELP, parseFlushWait, runSave, saveDocumentBytes };

package/dist/serve.js

@@ -1,12 +1,12 @@
 import { readDocumentFile } from "./document.js";
-import { journalPathFor } from "./journal.js";
+import { latestCommitFor } from "./journal.js";
 import { buildDisplayList, displayListHtml } from "./render.js";
-import { SIDECAR_DIRECTORY, inspectPath, readSidecarFile } from "./sidecar.js";
+import { SIDECAR_DIRECTORY } from "./sidecar.js";
 import { Result } from "better-result";
-import { randomBytes } from "node:crypto";
 import { watch } from "node:fs";
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { randomBytes } from "node:crypto";
 import { escapeHtmlText } from "@stll/folio-core/display-list/html/renderDisplayListToHtml";
 import { createServer } from "node:http";
 //#region src/serve.ts
@@ -27,35 +27,44 @@ import { createServer } from "node:http";
 const PREVIEW_HOST = "127.0.0.1";
 /** How often the file is re-checked when a watch event may have been missed. */
 const POLL_INTERVAL_MS = 1e3;
-/** The latest `toVersion` the journal committed for this document, if any. */
-const journalToVersion = async (documentPath) => {
-	const journalPath = journalPathFor(documentPath, void 0);
-	const parent = await inspectPath(path.dirname(journalPath));
-	if (parent.isErr() || parent.value.type !== "directory") return null;
-	const bytes = await readSidecarFile(journalPath);
-	if (bytes.isErr()) return null;
-	const lines = new TextDecoder().decode(bytes.value).split("\n");
-	for (let index = lines.length - 1; index >= 0; index--) {
-		const parsed = Result.try(() => JSON.parse(lines[index] ?? ""));
-		if (!parsed.isOk() || typeof parsed.value !== "object" || parsed.value === null) continue;
-		const entry = { ...parsed.value };
-		if (entry["type"] === "commit" && entry["path"] === documentPath) return typeof entry["toVersion"] === "string" ? entry["toVersion"] : null;
-	}
-	return null;
-};
-const SHELL_STYLE = "html, body { margin: 0; height: 100%; background: #e8e8e8; } iframe { border: 0; width: 100%; height: 100%; display: block; }";
-const shellHtml = (title, nonce) => [
+const SHELL_STYLE = "html, body { margin: 0; height: 100%; overflow: hidden; background: #e8e8e8; } iframe { border: 0; width: 100%; height: 100%; display: block; }";
+/**
+* `document.html` lays its pages out at their real pixel size with no zoom,
+* so a pane narrower than the page would otherwise clip the left margin and
+* scroll horizontally. The shell scales the iframe down (never up) to the
+* widest page, keeping it centered and fully visible; `fit` reruns on resize
+* and whenever a live reload reports a new page width.
+*/
+const shellHtml = (title, nonce, pageWidthPx) => [
 	"<!doctype html>",
 	`<html><head><meta charset="utf-8"><title>${escapeHtmlText(title)}</title>`,
 	`<style nonce="${nonce}">${SHELL_STYLE}</style></head><body>`,
 	"<iframe id=\"document\" sandbox src=\"document.html\" title=\"document\"></iframe>",
 	`<script nonce="${nonce}">`,
 	"const frame = document.getElementById('document');",
+	`let pageWidthPx = ${pageWidthPx !== null && pageWidthPx > 0 ? String(pageWidthPx) : "null"};`,
 	"let version = null;",
+	"frame.style.transformOrigin = 'top left';",
+	"const fit = () => {",
+	"  if (!pageWidthPx) return;",
+	"  const scale = Math.min(1, document.documentElement.clientWidth / pageWidthPx);",
+	"  const inverse = (100 / scale) + '%';",
+	"  frame.style.width = inverse;",
+	"  frame.style.height = inverse;",
+	"  frame.style.transform = 'scale(' + scale + ')';",
+	"};",
+	"fit();",
+	"window.addEventListener('resize', fit);",
 	"const events = new EventSource('events');",
 	"events.onmessage = (event) => {",
 	"  const next = JSON.parse(event.data).fileVersion;",
-	"  if (version !== null && next !== version) frame.src = 'document.html?v=' + next;",
+	"  if (version !== null && next !== version) {",
+	"    fetch('version').then((response) => response.json()).then((info) => {",
+	"      pageWidthPx = info.pageWidthPx > 0 ? info.pageWidthPx : null;",
+	"      fit();",
+	"    }).catch(() => {});",
+	"    frame.src = 'document.html?v=' + next;",
+	"  }",
 	"  version = next;",
 	"};",
 	"<\/script></body></html>"
@@ -103,11 +112,14 @@ const startPreviewServer = async ({ documentPath, port }) => {
 				fileVersion: file.value.fileVersion,
 				message: list.error.message
 			};
+			let pageWidthPx = 0;
+			for (const page of list.value.pages) pageWidthPx = Math.max(pageWidthPx, page.widthPx);
 			return {
 				type: "page",
 				fileVersion: file.value.fileVersion,
 				html: displayListHtml(list.value, title),
-				pageCount: list.value.pages.length
+				pageCount: list.value.pages.length,
+				pageWidthPx
 			};
 		})();
 		const result = await rendering;
@@ -153,7 +165,8 @@ const startPreviewServer = async ({ documentPath, port }) => {
 		const route = url.pathname.slice(prefix.length);
 		if (route === "") {
 			const nonce = randomBytes(16).toString("base64");
-			respond(response, 200, shellHtml(title, nonce), {
+			const page = await current();
+			respond(response, 200, shellHtml(title, nonce, page.type === "page" ? page.pageWidthPx : null), {
 				"Content-Type": "text/html; charset=utf-8",
 				"Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; frame-src 'self'; connect-src 'self'`
 			});
@@ -172,8 +185,11 @@ const startPreviewServer = async ({ documentPath, port }) => {
 			respond(response, 200, JSON.stringify({
 				path: realPath,
 				fileVersion: page.fileVersion,
-				journalToVersion: await journalToVersion(realPath),
-				...page.type === "page" ? { pageCount: page.pageCount } : { error: page.message }
+				journalToVersion: (await latestCommitFor(realPath))?.toVersion ?? null,
+				...page.type === "page" ? {
+					pageCount: page.pageCount,
+					pageWidthPx: page.pageWidthPx
+				} : { error: page.message }
 			}), { "Content-Type": "application/json" });
 			return;
 		}

package/dist/sidecar.d.ts

@@ -1,5 +1,5 @@
 import { FolioCliError } from "./errors.js";
-import { FileIdentity } from "./document.js";
+import { FileIdentity } from "./file-system.js";
 import { Result } from "better-result";
 import { FileHandle } from "node:fs/promises";
 //#region src/sidecar.d.ts

package/dist/sidecar.js

@@ -1,5 +1,5 @@
-import { NO_FOLLOW, errnoCode } from "./document.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { NO_FOLLOW, errnoCode } from "./file-system.js";
 import { Result } from "better-result";
 import { constants } from "node:fs";
 import { lstat, mkdir, open } from "node:fs/promises";

package/dist/transaction.d.ts

@@ -1,5 +1,6 @@
 import { FolioCliError } from "./errors.js";
-import { FileIdentity } from "./document.js";
+import { FileIdentity } from "./file-system.js";
+import "./document.js";
 import { JournalCommit } from "./journal.js";
 import { ChangedPart } from "./package-parts.js";
 import { Result } from "better-result";

package/dist/transaction.js

@@ -1,5 +1,6 @@
-import { fileVersionOf, readDocumentFile, sameFile } from "./document.js";
+import { readDocumentFile } from "./document.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { fileVersionOf, sameFile } from "./file-system.js";
 import { appendJournal, stagePathFor } from "./journal.js";
 import { checkPackageIntegrity } from "./package-parts.js";
 import { inspectPath, readSidecarFile, sidecarDirectory, syncDirectory, unsafePath, writeNewSidecarFile } from "./sidecar.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Command line and stdio MCP server for reading, reviewing, and redlining .docx files with folio: tracked-change edits, comments, and comparisons written atomically with version preconditions.",
   "keywords": [
     "cli",
@@ -40,6 +40,14 @@
     ".": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./editor-lease": {
+      "types": "./dist/editor-lease.d.ts",
+      "import": "./dist/editor-lease.js"
+    },
+    "./save": {
+      "types": "./dist/save.d.ts",
+      "import": "./dist/save.js"
     }
   },
   "publishConfig": {
@@ -62,8 +70,8 @@
     "@fontsource/source-sans-3": "^5.2.9",
     "@fontsource/tinos": "^5.2.7",
     "@modelcontextprotocol/server": "2.0.0",
-    "@stll/folio-agents": "^0.14.0",
-    "@stll/folio-core": "^0.50.0",
+    "@stll/folio-agents": "^0.14.1",
+    "@stll/folio-core": "^0.51.0",
     "better-result": "3.0.1",
     "fast-xml-parser": "^5.10.1",
     "jszip": "3.10.1"