memory-extract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 semigarden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "memory-extract",
+  "description": "Tools for packing interactive scenes into PNG images.",
+  "license": "MIT",
+  "version": "0.1.0",
+  "author": "semigarden",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/semigarden/memory-extract.git"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "tools",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./node": "./tools/memoryFormat.mjs",
+    "./payload": "./src/payloadFormat.js"
+  },
+  "bin": {
+    "memory-pack": "./tools/pack.mjs",
+    "memory-unpack": "./tools/unpack.mjs"
+  },
+  "scripts": {
+    "pack": "node tools/pack.mjs",
+    "unpack": "node tools/unpack.mjs",
+    "test": "node --test test/memory.test.mjs"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  }
+}

package/src/index.js

@@ -0,0 +1,25 @@
+export {
+    MEMORY_MAGIC,
+    MEMORY_CHUNK_TYPE,
+    MEMORY_VERSION,
+    SUPPORTED_VERSIONS,
+    MAX_PAYLOAD_SIZE,
+    decodeManifest,
+    decodeManifestFile,
+    decodeMemoryPayload,
+    extractMemory,
+    listManifestFiles,
+    readMemoryFile,
+} from "./memoryFormat.js";
+
+export {
+    assertSupportedVersion,
+    buildV2Manifest,
+    decodeV2Archive,
+    encodeV2Archive,
+    guessMimeType,
+    readManifestFile,
+    resolveSafePath,
+} from "./payloadFormat.js";
+
+export { createMemoryBlob } from "./loadMemory.js";

package/src/loadMemory.js

@@ -0,0 +1,198 @@
+import {
+    listManifestFiles,
+    readMemoryFile,
+    extractMemory,
+} from "./memoryFormat.js";
+
+const textDecoder = new TextDecoder();
+
+const REWRITABLE_ATTRIBUTES = [
+    ["script", "src"],
+    ["link", "href"],
+    ["img", "src"],
+    ["source", "src"],
+    ["video", "src"],
+    ["audio", "src"],
+    ["image", "href"],
+];
+
+const CSS_URL_PATTERN = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+const readInput = async (input) => {
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+
+    if (input instanceof ArrayBuffer) {
+        return new Uint8Array(input);
+    }
+
+    if (input instanceof Blob) {
+        return new Uint8Array(await input.arrayBuffer());
+    }
+
+    throw new Error("Expected a PNG memory image.");
+};
+
+const normalizeAssetPath = (value) => value.replace(/^\.\//, "");
+
+const guessMimeType = (filePath, record) => {
+    if (record?.mime) return record.mime;
+    if (filePath.endsWith(".html")) return "text/html";
+    if (filePath.endsWith(".css")) return "text/css";
+    if (filePath.endsWith(".js")) return "text/javascript";
+    if (filePath.endsWith(".svg")) return "image/svg+xml";
+    if (filePath.endsWith(".png")) return "image/png";
+    if (filePath.endsWith(".json")) return "application/json";
+    if (filePath.endsWith(".woff2")) return "font/woff2";
+    if (filePath.endsWith(".woff")) return "font/woff";
+    return "application/octet-stream";
+};
+
+const resolveAssetUrl = (rawPath, urlByPath) => {
+    if (!rawPath) return null;
+    if (/^(?:[a-z]+:|\/\/|#|data:)/i.test(rawPath)) return null;
+
+    const normalized = normalizeAssetPath(rawPath);
+    return urlByPath.get(normalized) ?? urlByPath.get(rawPath) ?? null;
+};
+
+const resolveManifestPath = (basePath, rawPath, manifestPaths) => {
+    const manifestSet = new Set(manifestPaths);
+    const normalized = normalizeAssetPath(rawPath);
+
+    if (manifestSet.has(normalized)) {
+        return normalized;
+    }
+
+    if (manifestSet.has(rawPath)) {
+        return rawPath;
+    }
+
+    if (!basePath.includes("/")) {
+        return manifestSet.has(normalized) ? normalized : null;
+    }
+
+    const baseDir = basePath.slice(0, basePath.lastIndexOf("/"));
+    const joined = normalizeAssetPath(`${baseDir}/${normalized}`);
+
+    return manifestSet.has(joined) ? joined : null;
+};
+
+const extractCssAssetPaths = (cssText) => {
+    const paths = [];
+    for (const match of cssText.matchAll(CSS_URL_PATTERN)) {
+        paths.push(match[2]);
+    }
+    return paths;
+};
+
+const collectRequiredFiles = (manifest, fileBytes) => {
+    const manifestPaths = listManifestFiles(manifest);
+    const required = new Set([manifest.entry]);
+
+    for (const filePath of manifestPaths) {
+        if (filePath.endsWith(".js") || filePath.endsWith(".css")) {
+            required.add(filePath);
+        }
+    }
+
+    let previousSize = 0;
+    while (required.size !== previousSize) {
+        previousSize = required.size;
+
+        for (const filePath of [...required]) {
+            const bytes = readMemoryFile(manifest, filePath, fileBytes);
+            const text = textDecoder.decode(bytes);
+            const refs = [];
+
+            if (filePath.endsWith(".html")) {
+                const doc = new DOMParser().parseFromString(text, "text/html");
+                REWRITABLE_ATTRIBUTES.forEach(([tag, attribute]) => {
+                    doc.querySelectorAll(`${tag}[${attribute}]`).forEach((element) => {
+                        refs.push(element.getAttribute(attribute));
+                    });
+                });
+            }
+
+            if (filePath.endsWith(".css")) {
+                refs.push(...extractCssAssetPaths(text));
+            }
+
+            refs.forEach((ref) => {
+                const resolved = resolveManifestPath(filePath, ref, manifestPaths);
+                if (resolved) {
+                    required.add(resolved);
+                }
+            });
+        }
+    }
+
+    return required;
+};
+
+const buildLaunchDocument = (html, urlByPath) => {
+    const doc = new DOMParser().parseFromString(html, "text/html");
+
+    REWRITABLE_ATTRIBUTES.forEach(([tag, attribute]) => {
+        doc.querySelectorAll(`${tag}[${attribute}]`).forEach((element) => {
+            const rawPath = element.getAttribute(attribute);
+            const assetUrl = resolveAssetUrl(rawPath, urlByPath);
+
+            if (assetUrl) {
+                element.setAttribute(attribute, assetUrl);
+            }
+
+            element.removeAttribute("crossorigin");
+        });
+    });
+
+    doc.documentElement.querySelectorAll("[crossorigin]").forEach((element) => {
+        element.removeAttribute("crossorigin");
+    });
+
+    return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+};
+
+const getManifestFileMeta = (manifest, filePath) => {
+    if (Array.isArray(manifest.files)) {
+        return manifest.files.find((file) => file.path === filePath) ?? null;
+    }
+
+    return manifest.files?.[filePath] ?? null;
+};
+
+export const createMemoryBlob = async (input) => {
+    const bytes = await readInput(input);
+    const { manifest, fileBytes } = await extractMemory(bytes);
+    const blobUrls = [];
+    const urlByPath = new Map();
+    const requiredFiles = collectRequiredFiles(manifest, fileBytes);
+
+    for (const filePath of requiredFiles) {
+        const fileMeta = getManifestFileMeta(manifest, filePath);
+        const fileContent = readMemoryFile(manifest, filePath, fileBytes);
+        const mime = guessMimeType(filePath, fileMeta);
+        const assetBlob = new Blob([fileContent], { type: mime });
+        const assetUrl = URL.createObjectURL(assetBlob);
+        blobUrls.push(assetUrl);
+        urlByPath.set(filePath, assetUrl);
+        urlByPath.set(normalizeAssetPath(filePath), assetUrl);
+    }
+
+    if (!requiredFiles.has(manifest.entry)) {
+        blobUrls.forEach((url) => URL.revokeObjectURL(url));
+        throw new Error(`Manifest entry not found: ${manifest.entry}`);
+    }
+
+    const htmlBytes = readMemoryFile(manifest, manifest.entry, fileBytes);
+    const html = textDecoder.decode(htmlBytes);
+    const launchDocument = buildLaunchDocument(html, urlByPath);
+    const launchBlob = new Blob([launchDocument], { type: "text/html" });
+
+    launchBlob.dispose = () => {
+        blobUrls.forEach((url) => URL.revokeObjectURL(url));
+    };
+
+    return launchBlob;
+};

package/src/memoryFormat.js

@@ -0,0 +1,213 @@
+import {
+    assertSupportedVersion,
+    decodeV2Archive,
+    listManifestFiles,
+    MAX_PAYLOAD_SIZE,
+    MEMORY_VERSION,
+    readManifestFile,
+    SUPPORTED_VERSIONS,
+} from "./payloadFormat.js";
+
+export {
+    assertSupportedVersion,
+    listManifestFiles,
+    MAX_PAYLOAD_SIZE,
+    MEMORY_VERSION,
+    readManifestFile,
+    SUPPORTED_VERSIONS,
+} from "./payloadFormat.js";
+
+export const MEMORY_MAGIC = new Uint8Array([0x57, 0x4c, 0x46, 0x43]); // WLFC
+export const MEMORY_CHUNK_TYPE = new Uint8Array([0x77, 0x4c, 0x46, 0x43]); // wLFC
+
+const PNG_SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const textDecoder = new TextDecoder();
+
+const bytesMatch = (view, offset, magic) => {
+    if (offset < 0 || offset + magic.length > view.length) return false;
+    for (let index = 0; index < magic.length; index += 1) {
+        if (view[offset + index] !== magic[index]) return false;
+    }
+    return true;
+};
+
+const readUint32BE = (view, offset) =>
+    (view[offset] << 24) |
+    (view[offset + 1] << 16) |
+    (view[offset + 2] << 8) |
+    view[offset + 3];
+
+const parsePngChunks = (view) => {
+    if (view.length < 8 || !bytesMatch(view, 0, PNG_SIGNATURE)) {
+        throw new Error("Invalid PNG signature.");
+    }
+
+    const chunks = [];
+    let offset = 8;
+
+    while (offset + 12 <= view.length) {
+        const length = readUint32BE(view, offset);
+        const type = view.slice(offset + 4, offset + 8);
+        const dataStart = offset + 8;
+        const dataEnd = dataStart + length;
+
+        if (dataEnd + 4 > view.length) {
+            throw new Error("PNG chunk exceeds file size.");
+        }
+
+        chunks.push({
+            type: String.fromCharCode(...type),
+            data: view.slice(dataStart, dataEnd),
+            start: offset,
+            end: dataEnd + 4,
+        });
+
+        offset = dataEnd + 4;
+
+        if (chunks[chunks.length - 1].type === "IEND") {
+            break;
+        }
+    }
+
+    return { view, chunks, trailing: view.slice(offset) };
+};
+
+const readMemoryPayload = (chunkData) => {
+    if (chunkData.length < 8 || !bytesMatch(chunkData, 0, MEMORY_MAGIC)) {
+        throw new Error("Memory chunk magic mismatch.");
+    }
+
+    const version = readUint32BE(chunkData, 4);
+    assertSupportedVersion(version);
+
+    const payload = chunkData.slice(8);
+    if (payload.length > MAX_PAYLOAD_SIZE) {
+        throw new Error(`Memory payload exceeds ${MAX_PAYLOAD_SIZE} bytes.`);
+    }
+
+    return { version, payload };
+};
+
+const gunzip = async (payload) => {
+    const stream = new Blob([payload])
+        .stream()
+        .pipeThrough(new DecompressionStream("gzip"));
+    const buffer = await new Response(stream).arrayBuffer();
+    return new Uint8Array(buffer);
+};
+
+export const decodeManifest = async (payload) => {
+    const decompressed = await gunzip(payload);
+    return JSON.parse(textDecoder.decode(decompressed));
+};
+
+export const decodeMemoryPayload = async (payload, version) => {
+    assertSupportedVersion(version);
+
+    if (version === 1) {
+        return {
+            manifest: await decodeManifest(payload),
+            fileBytes: null,
+        };
+    }
+
+    return decodeV2Archive(await gunzip(payload));
+};
+
+const extractLegacyFooter = async (view) => {
+    let magicIndex = -1;
+    for (let index = view.length - MEMORY_MAGIC.length; index >= 0; index -= 1) {
+        if (bytesMatch(view, index, MEMORY_MAGIC)) {
+            magicIndex = index;
+            break;
+        }
+    }
+
+    if (magicIndex < 0) {
+        throw new Error("Memory footer not found.");
+    }
+
+    const version = readUint32BE(view, magicIndex + 4);
+    const payloadLength = readUint32BE(view, magicIndex + 8);
+    const payloadStart = magicIndex + 12;
+    const payloadEnd = payloadStart + payloadLength;
+
+    if (version !== 1) {
+        throw new Error(`Unsupported legacy memory version: ${version}`);
+    }
+
+    if (payloadEnd > view.length) {
+        throw new Error("Memory payload length exceeds file size.");
+    }
+
+    const payload = view.slice(payloadStart, payloadEnd);
+    const decoded = await decodeMemoryPayload(payload, version);
+
+    return {
+        png: view.slice(0, magicIndex),
+        payload,
+        ...decoded,
+        version,
+    };
+};
+
+const decodeExtractedMemory = async (png, payload, version) => {
+    const decoded = await decodeMemoryPayload(payload, version);
+
+    return {
+        png,
+        payload,
+        ...decoded,
+        version,
+    };
+};
+
+export const extractMemory = async (input) => {
+    const view = input instanceof Uint8Array ? input : new Uint8Array(input);
+
+    if (view.length < 12) {
+        throw new Error("File is too small to be a memory PNG.");
+    }
+
+    try {
+        const { view: pngView, chunks, trailing } = parsePngChunks(view);
+        const memoryChunk = chunks.find((chunk) => chunk.type === "wLFC");
+
+        if (memoryChunk) {
+            const { version, payload } = readMemoryPayload(memoryChunk.data);
+            return decodeExtractedMemory(pngView, payload, version);
+        }
+
+        if (trailing.length > 0) {
+            return extractLegacyFooter(view);
+        }
+    } catch (error) {
+        if (error.message?.includes("Memory footer not found")) {
+            throw error;
+        }
+
+        return extractLegacyFooter(view);
+    }
+
+    throw new Error("Memory chunk not found.");
+};
+
+export const decodeManifestFile = (fileRecord) => {
+    if (!fileRecord?.data) {
+        throw new Error("Invalid manifest file record.");
+    }
+
+    if (typeof Uint8Array.fromBase64 === "function") {
+        return Uint8Array.fromBase64(fileRecord.data, { alphabet: "base64" });
+    }
+
+    const binary = atob(fileRecord.data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+};
+
+export const readMemoryFile = (manifest, filePath, fileBytes = null) =>
+    readManifestFile(manifest, filePath, fileBytes, decodeManifestFile);

package/src/payloadFormat.js

@@ -0,0 +1,171 @@
+export const MEMORY_VERSION = 2;
+export const SUPPORTED_VERSIONS = [1, 2];
+export const MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
+
+export const readUint32BE = (view, offset) =>
+    (view[offset] << 24) |
+    (view[offset + 1] << 16) |
+    (view[offset + 2] << 8) |
+    view[offset + 3];
+
+export const writeUint32BE = (view, offset, value) => {
+    view[offset] = (value >>> 24) & 0xff;
+    view[offset + 1] = (value >>> 16) & 0xff;
+    view[offset + 2] = (value >>> 8) & 0xff;
+    view[offset + 3] = value & 0xff;
+};
+
+export const assertSupportedVersion = (version) => {
+    if (!SUPPORTED_VERSIONS.includes(version)) {
+        throw new Error(`Unsupported memory version: ${version}`);
+    }
+};
+
+export const guessMimeType = (filePath) => {
+    const lower = filePath.toLowerCase();
+
+    if (lower.endsWith(".html")) return "text/html";
+    if (lower.endsWith(".css")) return "text/css";
+    if (lower.endsWith(".js")) return "text/javascript";
+    if (lower.endsWith(".svg")) return "image/svg+xml";
+    if (lower.endsWith(".png")) return "image/png";
+    if (lower.endsWith(".json")) return "application/json";
+    if (lower.endsWith(".woff2")) return "font/woff2";
+    if (lower.endsWith(".woff")) return "font/woff";
+    return "application/octet-stream";
+};
+
+export const listManifestFiles = (manifest) => {
+    if (Array.isArray(manifest.files)) {
+        return manifest.files.map((file) => file.path);
+    }
+
+    return Object.keys(manifest.files ?? {});
+};
+
+export const readManifestFile = (
+    manifest,
+    filePath,
+    fileBytes = null,
+    decodeV1File = null
+) => {
+    if (fileBytes?.[filePath]) {
+        return fileBytes[filePath];
+    }
+
+    const record = manifest.files?.[filePath];
+    if (record && decodeV1File) {
+        return decodeV1File(record);
+    }
+
+    throw new Error(`Manifest file not found: ${filePath}`);
+};
+
+const concatBytes = (parts) => {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const output = new Uint8Array(total);
+    let offset = 0;
+
+    for (const part of parts) {
+        output.set(part, offset);
+        offset += part.length;
+    }
+
+    return output;
+};
+
+const toUint8Array = (value) =>
+    value instanceof Uint8Array ? value : new Uint8Array(value);
+
+export const buildV2Manifest = ({
+    name,
+    entry,
+    files,
+    kind = "web-app",
+    runtime = "iframe-sandbox",
+}) => {
+    const sortedPaths = Object.keys(files).sort();
+
+    return {
+        manifest: {
+            v: 2,
+            kind,
+            name,
+            entry,
+            runtime,
+            files: sortedPaths.map((filePath) => {
+                const bytes = toUint8Array(files[filePath]);
+                return {
+                    path: filePath,
+                    mime: guessMimeType(filePath),
+                    size: bytes.length,
+                };
+            }),
+        },
+        sortedPaths,
+    };
+};
+
+export const encodeV2Archive = ({ name, entry, files, kind, runtime }) => {
+    const { manifest, sortedPaths } = buildV2Manifest({
+        name,
+        entry,
+        files,
+        kind,
+        runtime,
+    });
+    const json = new TextEncoder().encode(JSON.stringify(manifest));
+    const header = new Uint8Array(4);
+    writeUint32BE(header, 0, json.length);
+
+    return concatBytes([
+        header,
+        json,
+        ...sortedPaths.map((filePath) => toUint8Array(files[filePath])),
+    ]);
+};
+
+export const decodeV2Archive = (decompressed) => {
+    const view = toUint8Array(decompressed);
+    const jsonLength = readUint32BE(view, 0);
+    const jsonStart = 4;
+    const jsonEnd = jsonStart + jsonLength;
+
+    if (jsonEnd > view.length) {
+        throw new Error("Memory manifest length exceeds payload size.");
+    }
+
+    const manifest = JSON.parse(new TextDecoder().decode(view.slice(jsonStart, jsonEnd)));
+    const fileBytes = {};
+    let offset = jsonEnd;
+
+    for (const file of manifest.files ?? []) {
+        const end = offset + file.size;
+        if (end > view.length) {
+            throw new Error(`Memory file exceeds payload size: ${file.path}`);
+        }
+
+        fileBytes[file.path] = view.slice(offset, end);
+        offset = end;
+    }
+
+    if (offset !== view.length) {
+        throw new Error("Memory payload trailing bytes remain after decode.");
+    }
+
+    return { manifest, fileBytes };
+};
+
+export const resolveSafePath = (outDir, filePath, pathSep, pathResolve) => {
+    const resolvedOutDir = pathResolve(outDir);
+    const target = pathResolve(resolvedOutDir, filePath);
+    const prefix = resolvedOutDir.endsWith(pathSep)
+        ? resolvedOutDir
+        : `${resolvedOutDir}${pathSep}`;
+
+    if (target !== resolvedOutDir && !target.startsWith(prefix)) {
+        throw new Error(`Unsafe path in manifest: ${filePath}`);
+    }
+
+    return target;
+};

package/tools/blankCover.mjs

@@ -0,0 +1,36 @@
+import { gzipSync } from "node:zlib";
+import { createPngChunk, PNG_SIGNATURE } from "./pngUtils.mjs";
+
+export const createBlankCover = ({
+    width = 64,
+    height = 64,
+    rgb = [0, 8, 2],
+} = {}) => {
+    const rows = Buffer.alloc((width * 3 + 1) * height);
+    for (let y = 0; y < height; y += 1) {
+        const rowStart = y * (width * 3 + 1);
+        rows[rowStart] = 0;
+        for (let x = 0; x < width; x += 1) {
+            const pixelStart = rowStart + 1 + x * 3;
+            rows[pixelStart] = rgb[0];
+            rows[pixelStart + 1] = rgb[1];
+            rows[pixelStart + 2] = rgb[2];
+        }
+    }
+
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 2;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        createPngChunk("IHDR", ihdr),
+        createPngChunk("IDAT", gzipSync(rows, { level: 9 })),
+        createPngChunk("IEND", Buffer.alloc(0)),
+    ]);
+};