@mrkt_frwd/leaf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Asare
+
+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/README.md

@@ -0,0 +1,16 @@
+# @mrkt_frwd/leaf
+
+Take a self-contained HTML page apart into editable CSS and JS, put it back, and
+prove it is the same file.
+
+```bash
+npx leaf unpack page.html --output-dir ./out
+npx leaf pack ./out --out page.html
+npx leaf check page.html
+```
+
+Leaf never rebuilds the document from a parse tree — it cuts block bodies out by
+byte offset and puts them back. Unchanged in, unchanged out, verified against
+every page in the studio. `docs/getting-started.md` has the rest.
+
+MIT.

package/docs/getting-started.md

@@ -0,0 +1,50 @@
+# Getting started
+
+A **Leaf** is a self-contained HTML page taken apart into editable files, and put
+back without losing a byte.
+
+```bash
+npx leaf                                        # prints this guide
+npx leaf unpack page.html --output-dir ./out    # take it apart
+npx leaf pack ./out --out page.html             # put it back
+npx leaf check page.html                        # is it actually self-contained?
+```
+
+## What you get
+
+```
+out/
+  shell.html          the original document, with /*leaf:N*/ where each block was
+  parts/00-style.css
+  parts/01-script.js
+  leaf.json           order, types, byte counts, digests
+```
+
+Edit the parts. `pack` puts them back in the order `leaf.json` records and tells
+you whether the result is byte-identical to what you unpacked — unchanged in,
+unchanged out.
+
+## Why the shell keeps the original
+
+Most tools that do this rebuild the document from a parse tree, which is how a
+page comes back with its attribute quoting normalised, its shader indentation
+re-flowed and a newline missing from inside a template literal. It still loads.
+It still looks right. That is the problem.
+
+Leaf never rebuilds. It records byte offsets, cuts the block bodies out, and puts
+them back where they were. The round trip is the guarantee, and it is tested
+against every page in the studio rather than a fixture chosen to pass.
+
+## check
+
+`check` answers one question: does this page fetch anything from another origin?
+A single-file page claims it opens from `file://` on a machine with no network
+and looks the same. A Google Fonts stylesheet or a CDN import map breaks that
+claim quietly — the page renders in a fallback typeface and reports nothing.
+
+Hyperlinks, canonical URLs and `og:image` are not failures. Only what the browser
+fetches to render the page counts.
+
+## Licence
+
+MIT — `LICENSE` in this package. Copyright (c) 2026 Joe Asare.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@mrkt_frwd/leaf",
+  "version": "0.1.0",
+  "description": "Leaf — take a self-contained HTML page apart into editable CSS and JS, put it back, and prove it is the same file.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "bin": {
+    "leaf": "./src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/src/check.mjs

@@ -0,0 +1,67 @@
+/**
+ * Is this page actually self-contained?
+ *
+ * The claim a single-file page makes is that it opens from a file:// URL on a
+ * machine with no network and looks the same. Every reference to another origin
+ * is a way that claim fails quietly — the page still renders, just wrong, and
+ * a screenshot of it looks entirely plausible. That failure mode has already
+ * cost this codebase a set of recordings that rendered in the wrong typeface
+ * and reported nothing.
+ */
+import fs from 'fs';
+import { findBlocks } from './parse.mjs';
+
+/**
+ * Only references the browser actually fetches to render the page. A hyperlink
+ * to GitHub, a canonical URL and an og:image are not self-containment failures
+ * — they are metadata and navigation, and flagging them would make every
+ * correctly built page look broken.
+ */
+const FETCHED = [
+  { what: 'script', re: /<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi },
+  { what: 'stylesheet', re: /<link\b(?=[^>]*\brel\s*=\s*["'](?:stylesheet|preload|modulepreload|icon)["'])[^>]*\bhref\s*=\s*["']([^"']+)["'][^>]*>/gi },
+  { what: 'media', re: /<(?:img|source|video|audio|track|embed|iframe)\b[^>]*\b(?:src|poster)\s*=\s*["']([^"']+)["'][^>]*>/gi },
+  { what: 'poster', re: /<video\b[^>]*\bposter\s*=\s*["']([^"']+)["'][^>]*>/gi },
+];
+const CSS_URL = /url\(\s*["']?([^"')]+)["']?\s*\)/gi;
+
+const isRemote = (ref) => /^(?:https?:)?\/\//i.test(ref);
+
+export function check(htmlPath) {
+  const html = fs.readFileSync(htmlPath, 'utf8');
+  const blocks = findBlocks(html);
+  const remote = new Map();
+
+  const note = (ref, where) => {
+    if (!isRemote(ref)) return;
+    const origin = ref.replace(/^(?:https?:)?\/\//i, '').split('/')[0];
+    if (!remote.has(ref)) remote.set(ref, { ref, origin, where });
+  };
+
+  for (const { what, re } of FETCHED) {
+    re.lastIndex = 0;
+    for (const m of html.matchAll(re)) note(m[1], what);
+  }
+  for (const b of blocks) {
+    if (b.tag !== 'style') continue;
+    for (const m of b.content.matchAll(CSS_URL)) note(m[1], 'css');
+  }
+  // An import map is a promise about where modules come from — a remote entry
+  // there is as disqualifying as a remote <script src>.
+  for (const b of blocks) {
+    if ((b.attrs.type || '').toLowerCase() !== 'importmap') continue;
+    try {
+      const map = JSON.parse(b.content);
+      for (const target of Object.values(map.imports || {})) note(target, 'importmap');
+    } catch { /* a malformed import map is the page's problem, not ours */ }
+  }
+
+  const findings = [...remote.values()];
+  return {
+    file: htmlPath,
+    bytes: Buffer.byteLength(html, 'utf8'),
+    blocks: blocks.filter((b) => !b.empty).length,
+    selfContained: findings.length === 0,
+    remote: findings,
+  };
+}

package/src/cli.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Leaf's CLI prints its own instructions, the way Job's does. An agent should
+ * need one command to become useful here.
+ */
+import fs from 'fs';
+import path from 'path';
+import { unpack } from './unpack.mjs';
+import { pack } from './pack.mjs';
+import { check } from './check.mjs';
+
+const USAGE = `leaf — a single-file page, unfolded and folded back.
+
+  leaf unpack <page.html> --output-dir <dir>   take it apart into editable parts
+  leaf pack <dir> [--out <page.html>]          put it back, and prove it matches
+  leaf check <page.html>                       is it genuinely self-contained?
+
+A leaf directory holds shell.html, parts/ and leaf.json. Edit the parts; the
+shell keeps the original document with a /*leaf:N*/ token where each block was.
+pack refuses quietly to lie: it reports whether the result is byte-identical to
+what was unpacked.
+`;
+
+function arg(argv, name) {
+  const i = argv.indexOf(name);
+  return i === -1 ? null : argv[i + 1] || null;
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  if (cmd === 'unpack') {
+    const file = rest.find((a) => !a.startsWith('-'));
+    const dest = arg(rest, '--output-dir');
+    if (!file || !dest) { process.stderr.write('usage: leaf unpack <page.html> --output-dir <dir>\n'); return 2; }
+    const m = unpack(file, dest);
+    process.stdout.write(`unpacked ${m.source.name} → ${dest}\n`);
+    process.stdout.write(`sha256 ${m.source.sha256.slice(0, 12)}…  ${m.parts.length} part(s)\n`);
+    for (const p of m.parts) process.stdout.write(`  ${p.file.padEnd(28)} ${String(p.bytes).padStart(7)} B\n`);
+    return 0;
+  }
+
+  if (cmd === 'pack') {
+    const dir = rest.find((a) => !a.startsWith('-'));
+    if (!dir) { process.stderr.write('usage: leaf pack <dir> [--out <page.html>]\n'); return 2; }
+    const out = arg(rest, '--out');
+    const r = pack(dir, { outFile: out });
+    if (out) process.stdout.write(`packed → ${out}\n`);
+    process.stdout.write(`sha256 ${r.sha256.slice(0, 12)}…  ${r.bytes} B\n`);
+    process.stdout.write(r.identical
+      ? 'identical to the source it was unpacked from\n'
+      : `changed from source ${r.source.sha256.slice(0, 12)}… — expected if you edited a part\n`);
+    return 0;
+  }
+
+  if (cmd === 'check') {
+    const file = rest.find((a) => !a.startsWith('-'));
+    if (!file) { process.stderr.write('usage: leaf check <page.html>\n'); return 2; }
+    const r = check(file);
+    process.stdout.write(`${path.basename(r.file)}  ${r.blocks} block(s)  ${r.bytes} B\n`);
+    if (r.selfContained) { process.stdout.write('ok  self-contained — nothing is fetched from another origin\n'); return 0; }
+    process.stdout.write(`not self-contained — ${r.remote.length} remote reference(s)\n`);
+    for (const x of r.remote) process.stdout.write(`  ${x.where.padEnd(12)} ${x.ref}\n`);
+    return 1;
+  }
+
+  process.stderr.write(`unknown command: ${cmd}\n\n${USAGE}`);
+  return 2;
+}
+
+process.exit(main(process.argv.slice(2)));

package/src/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * Leaf — a single-file page, unfolded and folded back.
+ *
+ * unpack takes a self-contained HTML experience apart into editable CSS and JS.
+ * pack puts it back and proves it is the same file. check says whether the page
+ * is genuinely self-contained or only looks like it.
+ */
+export { findBlocks, parseAttrs } from './parse.mjs';
+export { unpack, SCHEMA } from './unpack.mjs';
+export { pack } from './pack.mjs';
+export { check } from './check.mjs';

package/src/pack.mjs

@@ -0,0 +1,46 @@
+/**
+ * Editable parts → single file, and it must be the same file.
+ *
+ * pack verifies its own output against the source digest leaf.json recorded at
+ * unpack time. An unchanged round trip that does not reproduce the original
+ * byte for byte is a bug in this package, and it says so rather than shipping
+ * a file that is nearly right.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { SCHEMA } from './unpack.mjs';
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+export function pack(srcDir, { outFile = null } = {}) {
+  const manifestPath = path.join(srcDir, 'leaf.json');
+  if (!fs.existsSync(manifestPath)) {
+    const err = new Error(`no leaf.json in ${srcDir} — is this a leaf directory?`);
+    err.code = 'NOT_A_LEAF';
+    throw err;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (manifest.schema !== SCHEMA) {
+    const err = new Error(`unsupported schema ${manifest.schema} (expected ${SCHEMA})`);
+    err.code = 'SCHEMA';
+    throw err;
+  }
+
+  let html = fs.readFileSync(path.join(srcDir, manifest.shell.file), 'utf8');
+  for (const part of manifest.parts) {
+    const at = html.indexOf(part.token);
+    if (at === -1) {
+      const err = new Error(`shell.html has lost the token for ${part.file} — put ${part.token} back where the block belongs`);
+      err.code = 'TOKEN_MISSING';
+      throw err;
+    }
+    const body = fs.readFileSync(path.join(srcDir, part.file), 'utf8');
+    html = html.slice(0, at) + body + html.slice(at + part.token.length);
+  }
+
+  const digest = sha256(html);
+  const identical = digest === manifest.source.sha256;
+  if (outFile) fs.writeFileSync(outFile, html);
+  return { html, sha256: digest, bytes: Buffer.byteLength(html, 'utf8'), identical, source: manifest.source };
+}

package/src/parse.mjs

@@ -0,0 +1,56 @@
+/**
+ * Find the <script> and <style> blocks in an HTML file, by offset.
+ *
+ * Deliberately not a full HTML parser. It needs to answer one question — where
+ * does each embedded block's content start and end, in bytes — and a real parser
+ * would answer it by rebuilding the document, which is exactly the step that
+ * loses the original formatting. Offsets keep the file authoritative.
+ */
+
+const BLOCKS = [
+  { tag: 'script', re: /<script\b([^>]*)>/gi, close: '</script>' },
+  { tag: 'style', re: /<style\b([^>]*)>/gi, close: '</style>' },
+];
+
+/** Parse the attributes of an open tag into a plain object, order preserved. */
+export function parseAttrs(raw = '') {
+  const attrs = {};
+  const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) {
+    attrs[m[1]] = m[2] ?? m[3] ?? m[4] ?? '';
+  }
+  return attrs;
+}
+
+/**
+ * Every embedded block, in document order.
+ *
+ * A block with no content is reported with `empty: true` and never extracted —
+ * `<script src=…></script>` is a reference, not a payload, and turning it into
+ * an empty file would make the round trip look lossy when it is not.
+ */
+export function findBlocks(html) {
+  const found = [];
+  for (const { tag, re, close } of BLOCKS) {
+    re.lastIndex = 0;
+    let open;
+    while ((open = re.exec(html)) !== null) {
+      const contentStart = open.index + open[0].length;
+      const closeAt = html.toLowerCase().indexOf(close, contentStart);
+      if (closeAt === -1) continue; // unclosed — leave it alone rather than guess
+      const content = html.slice(contentStart, closeAt);
+      found.push({
+        tag,
+        attrs: parseAttrs(open[1] || ''),
+        openTag: open[0],
+        contentStart,
+        contentEnd: closeAt,
+        content,
+        empty: content.trim() === '',
+      });
+      re.lastIndex = closeAt + close.length;
+    }
+  }
+  return found.sort((a, b) => a.contentStart - b.contentStart);
+}

package/src/unpack.mjs

@@ -0,0 +1,87 @@
+/**
+ * Single-file page → editable parts, without losing a byte.
+ *
+ * The shell keeps the original document exactly as written, with each embedded
+ * block's body swapped for a `/*leaf:N*\/` token — valid syntax in both CSS and
+ * JavaScript, so the shell still parses and can still be edited by hand.
+ * Everything needed to put it back lives in leaf.json.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { findBlocks } from './parse.mjs';
+
+export const SCHEMA = 'leaf/1';
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+function extensionFor(block) {
+  if (block.tag === 'style') return 'css';
+  const type = (block.attrs.type || '').toLowerCase();
+  if (type === 'importmap' || type.includes('json')) return 'json';
+  return 'js';
+}
+
+function nameFor(block, i) {
+  const type = (block.attrs.type || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  const stem = type ? `${block.tag}-${type}` : block.tag;
+  return `${String(i).padStart(2, '0')}-${stem}.${extensionFor(block)}`;
+}
+
+/**
+ * A token the document does not already contain. Collisions are vanishingly
+ * unlikely and silently catastrophic, so this checks rather than assumes.
+ */
+function tokenFor(index, html) {
+  let token = `/*leaf:${index}*/`;
+  let guard = 0;
+  while (html.includes(token)) {
+    token = `/*leaf:${index}:${(guard += 1)}*/`;
+    if (guard > 64) throw new Error('could not find a collision-free token');
+  }
+  return token;
+}
+
+export function unpack(htmlPath, destDir) {
+  const original = fs.readFileSync(htmlPath, 'utf8');
+  const blocks = findBlocks(original).filter((b) => !b.empty);
+
+  const parts = [];
+  let shell = '';
+  let cursor = 0;
+
+  blocks.forEach((block, i) => {
+    const file = nameFor(block, i);
+    const token = tokenFor(i, original);
+    shell += original.slice(cursor, block.contentStart) + token;
+    cursor = block.contentEnd;
+    parts.push({
+      index: i,
+      tag: block.tag,
+      type: block.attrs.type || null,
+      file: path.posix.join('parts', file),
+      token,
+      bytes: Buffer.byteLength(block.content, 'utf8'),
+      sha256: sha256(block.content),
+      content: block.content,
+    });
+  });
+  shell += original.slice(cursor);
+
+  fs.mkdirSync(path.join(destDir, 'parts'), { recursive: true });
+  fs.writeFileSync(path.join(destDir, 'shell.html'), shell);
+  for (const p of parts) fs.writeFileSync(path.join(destDir, p.file), p.content);
+
+  const manifest = {
+    schema: SCHEMA,
+    source: {
+      name: path.basename(htmlPath),
+      bytes: Buffer.byteLength(original, 'utf8'),
+      sha256: sha256(original),
+    },
+    shell: { file: 'shell.html', sha256: sha256(shell) },
+    parts: parts.map(({ content, ...rest }) => rest),
+  };
+  fs.writeFileSync(path.join(destDir, 'leaf.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}