@deckjsx/node 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import { AssetLoader, DeckPlugin, RenderPatchPlanPart } from "deckjsx/integration";
+import { RenderResult } from "deckjsx";
+
+//#region src/package-patch.d.ts
+type WriteDiagnostic = {
+  readonly code: string;
+  readonly message: string;
+  readonly path?: string;
+};
+//#endregion
+//#region src/index.d.ts
+type WriteStrategy = "atomic-replace" | "in-place" | "write-file";
+type WriteResult = {
+  readonly path: string;
+  readonly status: "created" | "failed" | "patched" | "replaced";
+  readonly strategy: WriteStrategy;
+  readonly bytesWritten: number;
+  readonly patchedParts: readonly string[];
+  readonly diagnostics: readonly WriteDiagnostic[];
+};
+type PatchablePptxPartInspectionStatus = "missing" | "stale" | "unsupported" | "verified";
+type PatchablePptxPartInspection = Omit<RenderPatchPlanPart, "buildReason" | "buildStatus"> & {
+  readonly status: PatchablePptxPartInspectionStatus;
+  readonly currentFingerprint?: string;
+  readonly zipMethod?: number;
+};
+type PatchablePptxInspectionResult = {
+  readonly path: string;
+  readonly ok: boolean;
+  readonly patchable: boolean;
+  readonly manifestPath: string;
+  readonly partCount: number;
+  readonly parts: readonly PatchablePptxPartInspection[];
+  readonly diagnostics: readonly WriteDiagnostic[];
+};
+type NodeFileAssetLoaderOptions = {
+  readonly root?: string;
+  readonly resolverIdentity?: string;
+};
+declare function createNodeFileAssetLoader(options?: NodeFileAssetLoaderOptions): AssetLoader;
+declare function nodeAssets(options?: NodeFileAssetLoaderOptions): DeckPlugin;
+declare function inspectPatchablePptx(outputPath: string): Promise<PatchablePptxInspectionResult>;
+declare function write(render: RenderResult, outputPath: string): Promise<WriteResult>;
+//#endregion
+export { NodeFileAssetLoaderOptions, PatchablePptxInspectionResult, PatchablePptxPartInspection, PatchablePptxPartInspectionStatus, type WriteDiagnostic, WriteResult, WriteStrategy, createNodeFileAssetLoader, inspectPatchablePptx, nodeAssets, write };

package/dist/index.mjs

@@ -0,0 +1,698 @@
+import { constants } from "node:fs";
+import { access, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PATCH_MANIFEST_KIND, PATCH_MANIFEST_PATH, PATCH_MANIFEST_VERSION, integrationContextId, patchManifestFromParts } from "deckjsx/integration";
+const PATCH_RESERVE_MARKER = "deckjsx-patch-reserve:";
+const textDecoder = new TextDecoder();
+const textEncoder$1 = new TextEncoder();
+const CRC32_TABLE = createCrc32Table();
+function tryCreateInPlacePatch(currentBytes, nextBytes, patchPlan) {
+	const currentArchive = parseZipArchive(currentBytes);
+	const nextArchive = parseZipArchive(nextBytes);
+	if (!currentArchive || !nextArchive) return inPlacePatchFailure("deckjsx.node.write.unreadableZip", "Existing or rendered PPTX bytes could not be read as a ZIP archive.");
+	const manifestEntry = currentArchive.entries.get(PATCH_MANIFEST_PATH);
+	const currentManifest = manifestEntry ? parsePatchManifest(manifestEntry.bytes) : void 0;
+	if (!manifestEntry || !currentManifest) return inPlacePatchFailure("deckjsx.node.write.missingPatchManifest", "Existing PPTX does not contain a deckjsx patch manifest.", PATCH_MANIFEST_PATH);
+	const currentParts = new Map(currentManifest.parts.map((part) => [part.packagePartId, part]));
+	const nextParts = new Map(patchPlan.parts.filter((part) => part.patchableKind !== "manifest").map((part) => [part.packagePartId, part]));
+	for (const currentPart of currentParts.values()) if (!nextParts.has(currentPart.packagePartId)) return inPlacePatchFailure("deckjsx.node.write.patchManifestRemovedPart", "Existing PPTX patch manifest contains a package part that is not present in the current render patch plan.", currentPart.path);
+	const segments = [];
+	const patchedParts = [];
+	for (const nextPart of patchPlan.parts) {
+		if (nextPart.patchableKind === "manifest") continue;
+		const currentPart = currentParts.get(nextPart.packagePartId);
+		if (!currentPart || currentPart.path !== nextPart.path) return inPlacePatchFailure("deckjsx.node.write.patchManifestMismatch", "Existing PPTX patch manifest does not match the current render patch plan.", nextPart.path);
+		const currentEntry = currentArchive.entries.get(currentPart.path);
+		const nextEntry = nextArchive.entries.get(nextPart.path);
+		if (!currentEntry || !nextEntry || currentEntry.method !== 0 || nextEntry.method !== 0) return inPlacePatchFailure("deckjsx.node.write.unsupportedZipEntry", "Changed package part cannot be updated in place because its ZIP entry is missing or unsupported.", nextPart.path);
+		if (fingerprintPatchableEntry(currentPart, currentEntry.bytes) !== currentPart.fingerprint) return inPlacePatchFailure("deckjsx.node.write.patchManifestStale", "Existing PPTX package part bytes do not match the deckjsx patch manifest.", currentPart.path);
+		if (currentPart.fingerprint === nextPart.fingerprint) continue;
+		let patchedBytes;
+		if (nextPart.patchableKind === "xml") patchedBytes = paddedXmlBytes(nextEntry.bytes, currentEntry.compressedSize);
+		else if (nextPart.patchableKind === "media") patchedBytes = nextEntry.bytes.byteLength === currentEntry.compressedSize ? nextEntry.bytes : void 0;
+		else return inPlacePatchFailure("deckjsx.node.write.unsupportedPatchableKind", "Changed package part cannot be updated in place by the current node writer.", nextPart.path);
+		if (!patchedBytes) return inPlacePatchFailure("deckjsx.node.write.inPlacePatchExceededCapacity", "Changed package part exceeded its reserved in-place patch capacity.", nextPart.path);
+		segments.push(...zipEntryPatchSegments(currentEntry, patchedBytes));
+		patchedParts.push(nextPart.path);
+	}
+	const manifestBytes = paddedManifestBytes(patchManifestLogicalBytes(patchPlan), manifestEntry.compressedSize);
+	if (!manifestBytes) return inPlacePatchFailure("deckjsx.node.write.inPlacePatchExceededCapacity", "Patch manifest exceeded its reserved in-place patch capacity.", PATCH_MANIFEST_PATH);
+	segments.push(...zipEntryPatchSegments(manifestEntry, manifestBytes));
+	patchedParts.push(PATCH_MANIFEST_PATH);
+	return {
+		ok: true,
+		segments,
+		patchedParts
+	};
+}
+function fingerprintPatchableEntry(part, bytes) {
+	if (part.patchableKind === "xml") return fingerprintBytes(stripXmlReserve(bytes));
+	return fingerprintBytes(bytes);
+}
+function parsePatchManifest(bytes) {
+	try {
+		const value = JSON.parse(textDecoder.decode(bytes).trim());
+		return isPatchManifest(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+function isPatchManifest(value) {
+	if (!isRecord(value) || value.kind !== PATCH_MANIFEST_KIND || value.version !== PATCH_MANIFEST_VERSION) return false;
+	return Array.isArray(value.parts) && value.parts.every(isPatchManifestPart);
+}
+function isPatchManifestPart(value) {
+	if (!isRecord(value)) return false;
+	return typeof value.packagePartId === "string" && typeof value.path === "string" && isPatchableKind(value.patchableKind) && typeof value.reservedCapacity === "number" && Number.isSafeInteger(value.reservedCapacity) && value.reservedCapacity >= 0 && typeof value.logicalByteLength === "number" && Number.isSafeInteger(value.logicalByteLength) && value.logicalByteLength >= 0 && typeof value.storedByteLength === "number" && Number.isSafeInteger(value.storedByteLength) && value.storedByteLength >= 0 && typeof value.fingerprint === "string";
+}
+function isPatchableKind(value) {
+	return value === "manifest" || value === "media" || value === "xml";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseZipArchive(bytes) {
+	const eocdOffset = findEndOfCentralDirectory(bytes);
+	if (eocdOffset < 0) return;
+	const entryCount = readUint16(bytes, eocdOffset + 10);
+	const centralDirectorySize = readUint32(bytes, eocdOffset + 12);
+	const centralDirectoryOffset = readUint32(bytes, eocdOffset + 16);
+	if (entryCount === void 0 || centralDirectorySize === void 0 || centralDirectoryOffset === void 0) return;
+	if (centralDirectoryOffset + centralDirectorySize > bytes.byteLength) return;
+	const entries = /* @__PURE__ */ new Map();
+	let cursor = centralDirectoryOffset;
+	for (let index = 0; index < entryCount; index += 1) {
+		const centralSignature = readUint32(bytes, cursor);
+		const method = readUint16(bytes, cursor + 10);
+		const compressedSize = readUint32(bytes, cursor + 20);
+		const uncompressedSize = readUint32(bytes, cursor + 24);
+		const pathByteLength = readUint16(bytes, cursor + 28);
+		const extraByteLength = readUint16(bytes, cursor + 30);
+		const commentByteLength = readUint16(bytes, cursor + 32);
+		const localHeaderOffset = readUint32(bytes, cursor + 42);
+		if (centralSignature !== 33639248 || method === void 0 || compressedSize === void 0 || uncompressedSize === void 0 || pathByteLength === void 0 || extraByteLength === void 0 || commentByteLength === void 0 || localHeaderOffset === void 0) return;
+		const pathStart = cursor + 46;
+		const pathEnd = pathStart + pathByteLength;
+		if (pathEnd > bytes.byteLength) return;
+		const entryPath = textDecoder.decode(bytes.subarray(pathStart, pathEnd));
+		const localEntry = localZipEntry(bytes, {
+			compressedSize,
+			localHeaderOffset,
+			path: entryPath
+		});
+		if (!localEntry) return;
+		entries.set(entryPath, {
+			path: entryPath,
+			method,
+			compressedSize,
+			uncompressedSize,
+			localHeaderOffset,
+			centralHeaderOffset: cursor,
+			dataOffset: localEntry.dataOffset,
+			bytes: bytes.subarray(localEntry.dataOffset, localEntry.dataOffset + compressedSize)
+		});
+		cursor = pathEnd + extraByteLength + commentByteLength;
+	}
+	return { entries };
+}
+function fingerprintBytes(bytes) {
+	let hash = 2166136261;
+	for (const byte of bytes) {
+		hash ^= byte;
+		hash = Math.imul(hash, 16777619);
+	}
+	return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function inPlacePatchFailure(code, message, path) {
+	return {
+		ok: false,
+		diagnostics: [{
+			code,
+			message,
+			...path ? { path } : {}
+		}]
+	};
+}
+function patchManifestLogicalBytes(patchPlan) {
+	const manifest = patchManifestFromParts(patchPlan.parts);
+	return textEncoder$1.encode(`${JSON.stringify(manifest, null, 2)}\n`);
+}
+function paddedManifestBytes(logical, targetSize) {
+	if (logical.byteLength > targetSize) return;
+	const bytes = new Uint8Array(targetSize);
+	bytes.set(logical, 0);
+	bytes.fill(32, logical.byteLength);
+	return bytes;
+}
+function paddedXmlBytes(bytes, targetSize) {
+	const logical = stripXmlReserve(bytes);
+	if (logical.byteLength === targetSize) return logical;
+	const prefix = textEncoder$1.encode(`\n<!--${PATCH_RESERVE_MARKER}`);
+	const suffix = textEncoder$1.encode("-->");
+	if (targetSize - logical.byteLength - prefix.byteLength - suffix.byteLength < 0) return;
+	const result = new Uint8Array(targetSize);
+	result.set(logical, 0);
+	result.set(prefix, logical.byteLength);
+	result.fill(46, logical.byteLength + prefix.byteLength, targetSize - suffix.byteLength);
+	result.set(suffix, targetSize - suffix.byteLength);
+	return result;
+}
+function stripXmlReserve(bytes) {
+	const text = textDecoder.decode(bytes);
+	const markerIndex = text.lastIndexOf(`<!--${PATCH_RESERVE_MARKER}`);
+	if (markerIndex < 0) return bytes;
+	return textEncoder$1.encode(text.slice(0, markerIndex));
+}
+function zipEntryPatchSegments(entry, bytes) {
+	const crc = uint32Bytes(crc32(bytes));
+	return [
+		{
+			position: entry.localHeaderOffset + 14,
+			bytes: crc
+		},
+		{
+			position: entry.centralHeaderOffset + 16,
+			bytes: crc
+		},
+		{
+			position: entry.dataOffset,
+			bytes
+		}
+	];
+}
+function localZipEntry(bytes, input) {
+	if (readUint32(bytes, input.localHeaderOffset) !== 67324752) return;
+	const pathByteLength = readUint16(bytes, input.localHeaderOffset + 26);
+	const extraByteLength = readUint16(bytes, input.localHeaderOffset + 28);
+	if (pathByteLength === void 0 || extraByteLength === void 0) return;
+	const dataOffset = input.localHeaderOffset + 30 + pathByteLength + extraByteLength;
+	return dataOffset + input.compressedSize <= bytes.byteLength ? { dataOffset } : void 0;
+}
+function findEndOfCentralDirectory(bytes) {
+	const minimumOffset = Math.max(0, bytes.byteLength - 65535 - 22);
+	for (let offset = bytes.byteLength - 22; offset >= minimumOffset; offset -= 1) if (readUint32(bytes, offset) === 101010256) return offset;
+	return -1;
+}
+function readUint16(bytes, offset) {
+	if (offset < 0 || offset + 2 > bytes.byteLength) return;
+	return bytes[offset] | bytes[offset + 1] << 8;
+}
+function readUint32(bytes, offset) {
+	if (offset < 0 || offset + 4 > bytes.byteLength) return;
+	return (bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24) >>> 0;
+}
+function uint32Bytes(value) {
+	return new Uint8Array([
+		value & 255,
+		value >>> 8 & 255,
+		value >>> 16 & 255,
+		value >>> 24 & 255
+	]);
+}
+function createCrc32Table() {
+	const table = new Uint32Array(256);
+	for (let index = 0; index < table.length; index += 1) {
+		let value = index;
+		for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 3988292384 ^ value >>> 1 : value >>> 1;
+		table[index] = value >>> 0;
+	}
+	return table;
+}
+function crc32(bytes) {
+	let crc = 4294967295;
+	for (const byte of bytes) crc = CRC32_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+	return (crc ^ 4294967295) >>> 0;
+}
+//#endregion
+//#region src/index.ts
+const textEncoder = new TextEncoder();
+function createNodeFileAssetLoader(options = {}) {
+	const normalizedOptions = {
+		...options,
+		root: options.root ? path.resolve(options.root) : void 0
+	};
+	return {
+		resolverIdentity: options.resolverIdentity ?? nodeFileAssetResolverIdentity(normalizedOptions),
+		async probe(context) {
+			const filePath = resolveNodeFileAssetPath({
+				options: normalizedOptions,
+				source: context.source,
+				importer: context.origin?.importer
+			});
+			if (!filePath.ok) return nodeFileAssetOriginMissing({
+				phase: "probe",
+				source: context.source
+			});
+			if (!filePath.path) return;
+			try {
+				return {
+					ok: true,
+					value: await probeFileAsset(filePath.path)
+				};
+			} catch (error) {
+				return nodeFileAssetReadFailure({
+					phase: "probe",
+					filePath: filePath.path,
+					source: context.source,
+					error
+				});
+			}
+		},
+		async load(context) {
+			const filePath = resolveNodeFileAssetPath({
+				options: normalizedOptions,
+				source: context.source,
+				importer: context.origin?.importer
+			});
+			if (!filePath.ok) return nodeFileAssetOriginMissing({
+				phase: "load",
+				source: context.source
+			});
+			if (!filePath.path) return;
+			try {
+				return {
+					ok: true,
+					value: await loadFileAsset(filePath.path)
+				};
+			} catch (error) {
+				return nodeFileAssetReadFailure({
+					phase: "load",
+					filePath: filePath.path,
+					source: context.source,
+					error
+				});
+			}
+		}
+	};
+}
+function nodeAssets(options = {}) {
+	return {
+		kind: "deckjsx.plugin",
+		id: "@deckjsx/node/assets",
+		name: "@deckjsx/node/assets",
+		integration: {
+			id: integrationContextId("@deckjsx/node/assets"),
+			assetLoaders: [createNodeFileAssetLoader(options)]
+		}
+	};
+}
+async function inspectPatchablePptx(outputPath) {
+	try {
+		return inspectPatchablePptxBytes(new Uint8Array(await readFile(outputPath)), outputPath);
+	} catch (error) {
+		return {
+			path: outputPath,
+			ok: false,
+			patchable: false,
+			manifestPath: PATCH_MANIFEST_PATH,
+			partCount: 0,
+			parts: [],
+			diagnostics: [{
+				code: "deckjsx.node.inspect.readFailed",
+				message: error instanceof Error ? error.message : String(error),
+				path: outputPath
+			}]
+		};
+	}
+}
+async function write(render, outputPath) {
+	if (!render.ok) {
+		const renderDiagnosticCodes = render.diagnostics.items.map((item) => item.code);
+		return {
+			path: outputPath,
+			status: "failed",
+			strategy: "write-file",
+			bytesWritten: 0,
+			patchedParts: [],
+			diagnostics: [{
+				code: "deckjsx.node.write.renderFailed",
+				message: renderDiagnosticCodes.length ? `@deckjsx/node write() requires a successful render result. Render diagnostics: ${renderDiagnosticCodes.join(", ")}.` : "@deckjsx/node write() requires a successful render result.",
+				path: outputPath
+			}]
+		};
+	}
+	const artifact = render.artifact;
+	if (!artifact) return {
+		path: outputPath,
+		status: "failed",
+		strategy: "write-file",
+		bytesWritten: 0,
+		patchedParts: [],
+		diagnostics: [{
+			code: "deckjsx.node.write.missingArtifact",
+			message: "@deckjsx/node write() requires a render result with an artifact.",
+			path: outputPath
+		}]
+	};
+	if (artifact.format !== "pptx") return {
+		path: outputPath,
+		status: "failed",
+		strategy: "write-file",
+		bytesWritten: 0,
+		patchedParts: [],
+		diagnostics: [{
+			code: "deckjsx.node.write.unsupportedFormat",
+			message: `@deckjsx/node write() can only write pptx artifacts, got ${artifact.format}.`,
+			path: outputPath
+		}]
+	};
+	const lock = await acquireWriteLock(outputPath);
+	if (!lock.ok) return {
+		path: outputPath,
+		status: "failed",
+		strategy: "write-file",
+		bytesWritten: 0,
+		patchedParts: [],
+		diagnostics: lock.diagnostics
+	};
+	try {
+		if (!await pathExists(outputPath)) {
+			await writeFile(outputPath, artifact.bytes);
+			return {
+				path: outputPath,
+				status: "created",
+				strategy: "write-file",
+				bytesWritten: artifact.bytes.byteLength,
+				patchedParts: [],
+				diagnostics: []
+			};
+		}
+		const patch = render.patchPlan ? tryCreateInPlacePatch(await readFile(outputPath), artifact.bytes, render.patchPlan) : void 0;
+		if (patch?.ok) {
+			await writePatchSegments(outputPath, patch.segments);
+			return {
+				path: outputPath,
+				status: "patched",
+				strategy: "in-place",
+				bytesWritten: patch.segments.reduce((total, segment) => total + segment.bytes.byteLength, 0),
+				patchedParts: patch.patchedParts,
+				diagnostics: []
+			};
+		}
+		await replaceFile(outputPath, artifact.bytes);
+		return {
+			path: outputPath,
+			status: "replaced",
+			strategy: "atomic-replace",
+			bytesWritten: artifact.bytes.byteLength,
+			patchedParts: [],
+			diagnostics: patch?.diagnostics ?? []
+		};
+	} catch (error) {
+		return {
+			path: outputPath,
+			status: "failed",
+			strategy: "write-file",
+			bytesWritten: 0,
+			patchedParts: [],
+			diagnostics: [{
+				code: "deckjsx.node.write.failed",
+				message: error instanceof Error ? error.message : String(error),
+				path: outputPath
+			}]
+		};
+	} finally {
+		await releaseWriteLock(lock.lock);
+	}
+}
+function inspectPatchablePptxBytes(bytes, outputPath) {
+	const archive = parseZipArchive(bytes);
+	if (!archive) return {
+		path: outputPath,
+		ok: false,
+		patchable: false,
+		manifestPath: PATCH_MANIFEST_PATH,
+		partCount: 0,
+		parts: [],
+		diagnostics: [{
+			code: "deckjsx.node.inspect.unreadableZip",
+			message: "Existing PPTX bytes could not be read as a ZIP archive.",
+			path: outputPath
+		}]
+	};
+	const manifestEntry = archive.entries.get(PATCH_MANIFEST_PATH);
+	if (!manifestEntry) return {
+		path: outputPath,
+		ok: false,
+		patchable: false,
+		manifestPath: PATCH_MANIFEST_PATH,
+		partCount: 0,
+		parts: [],
+		diagnostics: [{
+			code: "deckjsx.node.inspect.missingPatchManifest",
+			message: "Existing PPTX does not contain a deckjsx patch manifest.",
+			path: PATCH_MANIFEST_PATH
+		}]
+	};
+	const manifest = parsePatchManifest(manifestEntry.bytes);
+	if (!manifest) return {
+		path: outputPath,
+		ok: false,
+		patchable: false,
+		manifestPath: PATCH_MANIFEST_PATH,
+		partCount: 0,
+		parts: [],
+		diagnostics: [{
+			code: "deckjsx.node.inspect.invalidPatchManifest",
+			message: "Existing PPTX deckjsx patch manifest could not be parsed.",
+			path: PATCH_MANIFEST_PATH
+		}]
+	};
+	const diagnostics = [];
+	const parts = manifest.parts.map((part) => {
+		const entry = archive.entries.get(part.path);
+		if (!entry) {
+			diagnostics.push({
+				code: "deckjsx.node.inspect.missingPatchPart",
+				message: "Patch manifest references a package part that is missing from the PPTX archive.",
+				path: part.path
+			});
+			return {
+				...part,
+				status: "missing"
+			};
+		}
+		if (entry.method !== 0) {
+			diagnostics.push({
+				code: "deckjsx.node.inspect.unsupportedZipEntry",
+				message: "Patch manifest references a ZIP entry that cannot be updated in place.",
+				path: part.path
+			});
+			return {
+				...part,
+				status: "unsupported",
+				zipMethod: entry.method
+			};
+		}
+		const currentFingerprint = fingerprintPatchableEntry(part, entry.bytes);
+		if (currentFingerprint !== part.fingerprint) {
+			diagnostics.push({
+				code: "deckjsx.node.inspect.patchManifestStale",
+				message: "Existing PPTX package part bytes do not match the deckjsx patch manifest.",
+				path: part.path
+			});
+			return {
+				...part,
+				status: "stale",
+				currentFingerprint,
+				zipMethod: entry.method
+			};
+		}
+		return {
+			...part,
+			status: "verified",
+			currentFingerprint,
+			zipMethod: entry.method
+		};
+	});
+	return {
+		path: outputPath,
+		ok: diagnostics.length === 0,
+		patchable: diagnostics.length === 0,
+		manifestPath: PATCH_MANIFEST_PATH,
+		partCount: parts.length,
+		parts,
+		diagnostics
+	};
+}
+function lockPathFor(outputPath) {
+	return path.join(path.dirname(outputPath), `.${path.basename(outputPath)}.deckjsx-lock`);
+}
+async function acquireWriteLock(outputPath) {
+	const lockPath = lockPathFor(outputPath);
+	let handle;
+	try {
+		handle = await open(lockPath, "wx");
+	} catch (error) {
+		const code = typeof error === "object" && error !== null && "code" in error ? error.code : "";
+		return {
+			ok: false,
+			diagnostics: [{
+				code: code === "EEXIST" ? "deckjsx.node.write.lockUnavailable" : "deckjsx.node.write.lockFailed",
+				message: code === "EEXIST" ? "Another deckjsx write appears to hold the output lock." : error instanceof Error ? error.message : String(error),
+				path: lockPath
+			}]
+		};
+	}
+	try {
+		await handle.writeFile(`${process.pid}\n`);
+	} catch {
+		await handle.close();
+		await unlink(lockPath).catch(() => void 0);
+		return {
+			ok: false,
+			diagnostics: [{
+				code: "deckjsx.node.write.lockFailed",
+				message: "Deckjsx could not initialize the output lock file.",
+				path: lockPath
+			}]
+		};
+	}
+	return {
+		ok: true,
+		lock: {
+			path: lockPath,
+			handle
+		}
+	};
+}
+async function releaseWriteLock(lock) {
+	await lock.handle.close().catch(() => void 0);
+	await unlink(lock.path).catch(() => void 0);
+}
+async function pathExists(outputPath) {
+	try {
+		await access(outputPath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function replaceFile(outputPath, bytes) {
+	const temporaryPath = path.join(path.dirname(outputPath), `.${path.basename(outputPath)}.${process.pid}.${Date.now()}.deckjsx-tmp`);
+	await writeFile(temporaryPath, bytes);
+	await rename(temporaryPath, outputPath);
+}
+function extensionFromPath(filePath) {
+	return path.extname(filePath).slice(1).toLowerCase() || void 0;
+}
+function mediaTypeFromExtension(extension) {
+	switch (extension) {
+		case "gif": return "image/gif";
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "png": return "image/png";
+		case "svg": return "image/svg+xml";
+		case "webp": return "image/webp";
+		default: return;
+	}
+}
+function pngDimensions(bytes) {
+	if (bytes.byteLength < 24 || bytes[0] !== 137 || bytes[1] !== 80 || bytes[2] !== 78 || bytes[3] !== 71) return {};
+	return {
+		width: (bytes[16] << 24 | bytes[17] << 16 | bytes[18] << 8 | bytes[19]) >>> 0,
+		height: (bytes[20] << 24 | bytes[21] << 16 | bytes[22] << 8 | bytes[23]) >>> 0
+	};
+}
+function nodeFileAssetResolverIdentity(options) {
+	const config = JSON.stringify({
+		package: "@deckjsx/node",
+		root: options.root ?? process.cwd()
+	});
+	return `@deckjsx/node:file:${fingerprintBytes(textEncoder.encode(config))}`;
+}
+function resolveNodeFileAssetPath(input) {
+	if (input.source.kind !== "path") return { ok: true };
+	if (path.isAbsolute(input.source.path)) return {
+		ok: true,
+		path: input.source.path
+	};
+	if (input.importer) return {
+		ok: true,
+		path: path.resolve(path.dirname(input.importer), input.source.path)
+	};
+	if (input.options.root) return {
+		ok: true,
+		path: path.resolve(input.options.root, input.source.path)
+	};
+	return { ok: false };
+}
+async function probeFileAsset(filePath) {
+	const [metadata, bytes] = await Promise.all([stat(filePath), readFile(filePath)]);
+	const extension = extensionFromPath(filePath);
+	const mediaType = mediaTypeFromExtension(extension);
+	const dimensions = mediaType === "image/png" ? pngDimensions(bytes) : {};
+	return {
+		...mediaType ? { mediaType } : {},
+		...extension ? { extension } : {},
+		...dimensions.width ? { width: dimensions.width } : {},
+		...dimensions.height ? { height: dimensions.height } : {},
+		byteLength: metadata.size,
+		hash: fingerprintBytes(bytes),
+		provenance: {
+			kind: "file",
+			resolvedId: fingerprintBytes(bytes),
+			hashSource: "bytes"
+		}
+	};
+}
+async function loadFileAsset(filePath) {
+	const buffer = await readFile(filePath);
+	const bytes = new Uint8Array(buffer);
+	return {
+		...await probeFileAsset(filePath),
+		bytes
+	};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function authoredAssetSource(source) {
+	return source.kind === "path" ? source.path : JSON.stringify(source);
+}
+function nodeFileAssetReadFailure(input) {
+	return {
+		ok: false,
+		diagnostics: [{
+			severity: "error",
+			code: "E_NODE_FILE_ASSET_READ_FAILED",
+			title: "node file asset could not be read",
+			message: "@deckjsx/node resolved this media source to a local file, but could not read its bytes.",
+			labels: [{
+				path: input.filePath,
+				message: errorMessage(input.error)
+			}],
+			notes: [`phase=${input.phase}`, `source=${authoredAssetSource(input.source)}`],
+			help: ["Check that the media path exists relative to the importing slide/component module or configured node asset root."]
+		}]
+	};
+}
+function nodeFileAssetOriginMissing(input) {
+	const source = authoredAssetSource(input.source);
+	return {
+		ok: false,
+		diagnostics: [{
+			severity: "error",
+			code: "E_NODE_FILE_ASSET_ORIGIN_MISSING",
+			title: "node file asset importer origin is missing",
+			message: "@deckjsx/node received a relative media path but no importing module path or asset root was available.",
+			labels: [{
+				path: source,
+				message: "relative node asset paths require an importer origin or createNodeFileAssetLoader root"
+			}],
+			notes: [`phase=${input.phase}`, `source=${source}`],
+			help: ["Pass mediaSourceOrigins metadata from JSX transforms or configure createNodeFileAssetLoader({ root })."]
+		}]
+	};
+}
+async function writePatchSegments(outputPath, segments) {
+	const file = await open(outputPath, "r+");
+	try {
+		for (const segment of segments) await file.write(segment.bytes, 0, segment.bytes.byteLength, segment.position);
+		await file.sync();
+	} finally {
+		await file.close();
+	}
+}
+//#endregion
+export { createNodeFileAssetLoader, inspectPatchablePptx, nodeAssets, write };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@deckjsx/node",
+  "version": "0.1.0",
+  "description": "Node.js runtime helpers for deckjsx render artifacts.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "vite-plus": "^0.1.24"
+  },
+  "peerDependencies": {
+    "deckjsx": "^0.9.0"
+  },
+  "packageManager": "bun@1.3.14"
+}