@hraness/design-kit 0.31.1

package/scripts/check-lantern-material-snapshot.d.mts

@@ -0,0 +1,26 @@
+/** Finite, asset-free portable presentation contract. */
+export const lanternSnapshotPaths: Readonly<{
+  "lantern-material.css": "src/lantern-material.css";
+  "check.mjs": "scripts/check-lantern-material-snapshot.mjs";
+  "check.d.mts": "scripts/check-lantern-material-snapshot.d.mts";
+  LICENSE: "LICENSE";
+}>;
+export type LanternSnapshotArtifact = keyof typeof lanternSnapshotPaths;
+export const lanternSnapshotFileLimits: Readonly<Record<LanternSnapshotArtifact, number>>;
+export interface LanternMaterialSnapshot {
+  readonly schemaVersion: 1;
+  readonly contractVersion: 1;
+  readonly source: {
+    readonly repository: "https://github.com/hraness/design-kit";
+    readonly commit: string;
+    readonly export: "@hraness/design-kit/lantern-material.css";
+  };
+  readonly files: Readonly<Record<LanternSnapshotArtifact, {
+    readonly path: string;
+    readonly sha256: string;
+  }>>;
+}
+export function createLanternMaterialSnapshot(commit: string, files: Readonly<Record<LanternSnapshotArtifact, Uint8Array>>): LanternMaterialSnapshot;
+export function parseLanternMaterialSnapshot(value: unknown): LanternMaterialSnapshot;
+/** Offline byte/provenance consistency check. This does not authenticate a GitHub release. */
+export function checkLanternMaterialSnapshot(directory?: string): Promise<LanternMaterialSnapshot>;

package/scripts/check-lantern-material-snapshot.mjs

@@ -0,0 +1,126 @@
+import { log } from "node:console";
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { TextDecoder } from "node:util";
+
+// This finite, asset-free inventory is owned by the checker, never the manifest.
+export const lanternSnapshotPaths = Object.freeze({
+  "lantern-material.css": "src/lantern-material.css",
+  "check.mjs": "scripts/check-lantern-material-snapshot.mjs",
+  "check.d.mts": "scripts/check-lantern-material-snapshot.d.mts",
+  LICENSE: "LICENSE",
+});
+export const lanternSnapshotFileLimits = Object.freeze({
+  "lantern-material.css": 256 * 1024,
+  "check.mjs": 128 * 1024,
+  "check.d.mts": 64 * 1024,
+  LICENSE: 64 * 1024,
+});
+const names = Object.keys(lanternSnapshotPaths);
+const repository = "https://github.com/hraness/design-kit";
+const exportedCss = "@hraness/design-kit/lantern-material.css";
+const checkerDirectory = dirname(fileURLToPath(import.meta.url));
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const keysEqual = (value, keys) => record(value) && Object.keys(value).sort().join("\n") === [...keys].sort().join("\n");
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const commitPattern = /^[a-f0-9]{40}$/u;
+const hashPattern = /^[a-f0-9]{64}$/u;
+
+export function createLanternMaterialSnapshot(commit, files) {
+  if (typeof commit !== "string" || !commitPattern.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  if (!keysEqual(files, names)) throw new Error("Snapshot has missing or unowned source files.");
+  for (const name of names) {
+    if (!(files[name] instanceof Uint8Array) || files[name].byteLength === 0 || files[name].byteLength > lanternSnapshotFileLimits[name]) {
+      throw new Error(`Invalid ${name} source bytes.`);
+    }
+  }
+  return {
+    schemaVersion: 1,
+    contractVersion: 1,
+    source: { repository, commit, export: exportedCss },
+    files: Object.fromEntries(names.map((name) => [name, { path: lanternSnapshotPaths[name], sha256: sha256(files[name]) }])),
+  };
+}
+
+export function parseLanternMaterialSnapshot(value) {
+  if (!keysEqual(value, ["schemaVersion", "contractVersion", "source", "files"])
+    || value.schemaVersion !== 1 || value.contractVersion !== 1
+    || !keysEqual(value.source, ["repository", "commit", "export"])
+    || value.source.repository !== repository || value.source.export !== exportedCss
+    || typeof value.source.commit !== "string" || !commitPattern.test(value.source.commit)
+    || !keysEqual(value.files, names)) throw new Error("Invalid Lantern material snapshot provenance.");
+  for (const name of names) {
+    const receipt = value.files[name];
+    if (!keysEqual(receipt, ["path", "sha256"]) || receipt.path !== lanternSnapshotPaths[name]
+      || typeof receipt.sha256 !== "string" || !hashPattern.test(receipt.sha256)) throw new Error(`Invalid ${name} provenance.`);
+  }
+  return value;
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function physicalFile(path, maximum) {
+  const before = await lstat(path);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size === 0 || before.size > maximum) {
+    throw new Error("Snapshot files must be bounded physical files with one link.");
+  }
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = await file.stat();
+    if (!sameIdentity(before, opened) || !opened.isFile() || opened.nlink !== 1 || opened.size !== before.size) {
+      throw new Error("Snapshot file changed while opening.");
+    }
+    // Read only the admitted length plus one sentinel byte. A concurrent
+    // append must fail without allocating or reading the growing file to EOF.
+    const bytes = Buffer.alloc(before.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await file.read(bytes, length, bytes.length - length, length);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    const after = await file.stat();
+    const current = await lstat(path);
+    if (length !== before.size || !sameIdentity(before, current) || current.isSymbolicLink()
+      || current.nlink !== 1 || after.nlink !== 1 || after.size !== before.size
+      || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw new Error("Snapshot file changed while reading.");
+    return bytes.subarray(0, length);
+  } finally {
+    await file.close();
+  }
+}
+
+export async function checkLanternMaterialSnapshot(root = checkerDirectory) {
+  root = resolve(root);
+  const directory = await lstat(root);
+  if (!directory.isDirectory() || directory.isSymbolicLink()) throw new Error("Snapshot requires a physical directory.");
+  const entries = await readdir(root, { withFileTypes: true });
+  if (entries.map((entry) => entry.name).sort().join("\n") !== [...names, "provenance.json"].sort().join("\n")) {
+    throw new Error("Snapshot has missing or unowned files.");
+  }
+  if (entries.some((entry) => !entry.isFile() || entry.isSymbolicLink())) throw new Error("Snapshot requires only physical files.");
+  const provenanceBytes = await physicalFile(join(root, "provenance.json"), 16 * 1024);
+  const manifest = parseLanternMaterialSnapshot(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(provenanceBytes)));
+  for (const name of names) {
+    const bytes = await physicalFile(join(root, name), lanternSnapshotFileLimits[name]);
+    if (sha256(bytes) !== manifest.files[name].sha256) throw new Error(`${name} differs from its immutable snapshot.`);
+  }
+  if (!provenanceBytes.equals(await physicalFile(join(root, "provenance.json"), 16 * 1024))) throw new Error("Snapshot provenance changed while checking.");
+  const after = await lstat(root);
+  if (!sameIdentity(directory, after) || !after.isDirectory() || after.isSymbolicLink()
+    || (await readdir(root)).sort().join("\n") !== [...names, "provenance.json"].sort().join("\n")) throw new Error("Snapshot directory changed while checking.");
+  return manifest;
+}
+
+if (process.argv[1] !== undefined && await realpath(process.argv[1]).catch(() => undefined) === fileURLToPath(import.meta.url)) {
+  if (process.argv.length > 3) throw new Error("Usage: node check.mjs [SNAPSHOT_DIRECTORY]");
+  const manifest = await checkLanternMaterialSnapshot(process.argv[2] === undefined ? checkerDirectory : resolve(process.argv[2]));
+  log(`Lantern material snapshot verified at ${manifest.source.commit}.`);
+}

package/scripts/check-marketing-snapshot.d.mts

@@ -0,0 +1,12 @@
+/** Offline validation; throws for altered or unowned files and returns the admitted inventory. */
+export interface MarketingSnapshot {
+  readonly schemaVersion: 1;
+  readonly contractVersion: 1;
+  readonly source: {
+    readonly repository: "https://github.com/hraness/design-kit";
+    readonly commit: string;
+    readonly export: "@hraness/design-kit/product-marketing-preset.css";
+  };
+  readonly files: Readonly<Record<string, { readonly path: string; readonly sha256: string }>>;
+}
+export function checkMarketingSnapshot(directory?: string): Promise<MarketingSnapshot>;

package/scripts/check-marketing-snapshot.mjs

@@ -0,0 +1,58 @@
+import { log } from "node:console";
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import process from "node:process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Finite contract: never accept paths supplied by an untrusted manifest.
+const paths = {
+  "product-marketing-preset.css": "src/product-marketing-preset.css",
+  "fonts/instrument-serif/instrument-serif-latin-400.woff2": "src/fonts/instrument-serif/instrument-serif-latin-400.woff2",
+  "fonts/instrument-serif/OFL.txt": "src/fonts/instrument-serif/OFL.txt",
+  "fonts/instrument-serif/UPSTREAM.md": "src/fonts/instrument-serif/UPSTREAM.md",
+  "marketing-assets/grain.svg": "src/marketing-assets/grain.svg",
+  "marketing-assets/cells.svg": "src/marketing-assets/cells.svg",
+  "marketing-assets/UPSTREAM.md": "src/marketing-assets/UPSTREAM.md",
+  "check.mjs": "scripts/check-marketing-snapshot.mjs",
+  "check.d.mts": "scripts/check-marketing-snapshot.d.mts",
+  LICENSE: "LICENSE",
+};
+const checkerDirectory = dirname(fileURLToPath(import.meta.url));
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+async function inventory(directory, prefix = "") {
+  const details = await lstat(directory);
+  if (!details.isDirectory() || details.isSymbolicLink()) throw new Error("Snapshot requires physical directories.");
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = prefix + entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Snapshot contains a symbolic link: ${path}`);
+    if (entry.isDirectory()) {
+      if (!Object.keys(paths).some((name) => name.startsWith(`${path}/`))) throw new Error(`Snapshot contains an unowned directory: ${path}`);
+      files.push(...await inventory(join(directory, entry.name), `${path}/`));
+    } else if (entry.isFile()) files.push(path);
+    else throw new Error(`Snapshot contains a non-file: ${path}`);
+  }
+  return files.sort();
+}
+export async function checkMarketingSnapshot(root = checkerDirectory) {
+if ((await inventory(root)).join("\n") !== [...Object.keys(paths), "provenance.json"].sort().join("\n")) throw new Error("Snapshot has missing or unowned files.");
+const manifest = JSON.parse(await readFile(join(root, "provenance.json"), "utf8"));
+if (!record(manifest) || manifest.schemaVersion !== 1 || manifest.contractVersion !== 1
+  || !record(manifest.source) || manifest.source.repository !== "https://github.com/hraness/design-kit"
+  || manifest.source.export !== "@hraness/design-kit/product-marketing-preset.css"
+  || typeof manifest.source.commit !== "string" || !/^[a-f0-9]{40}$/u.test(manifest.source.commit)
+  || !record(manifest.files) || Object.keys(manifest.files).sort().join("\n") !== Object.keys(paths).sort().join("\n")) throw new Error("Invalid marketing snapshot provenance.");
+for (const [name, sourcePath] of Object.entries(paths)) {
+  const receipt = manifest.files[name];
+  if (!record(receipt) || receipt.path !== sourcePath || typeof receipt.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.sha256)) throw new Error(`Invalid ${name} provenance.`);
+  if (createHash("sha256").update(await readFile(join(root, name))).digest("hex") !== receipt.sha256) throw new Error(`${name} differs from its immutable snapshot.`);
+}
+return manifest;
+}
+
+if (process.argv[1] !== undefined && await realpath(process.argv[1]).catch(() => undefined) === fileURLToPath(import.meta.url)) {
+  if (process.argv.length > 3) throw new Error("Usage: node check.mjs [SNAPSHOT_DIRECTORY]");
+  const manifest = await checkMarketingSnapshot(process.argv[2] === undefined ? checkerDirectory : resolve(process.argv[2]));
+  log(`Marketing snapshot verified at ${manifest.source.commit}.`);
+}

package/scripts/lantern-material-snapshot.ts

@@ -0,0 +1,101 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+import {
+  checkLanternMaterialSnapshot,
+  createLanternMaterialSnapshot,
+  lanternSnapshotFileLimits,
+  lanternSnapshotPaths,
+} from "./check-lantern-material-snapshot.mjs";
+import type { LanternMaterialSnapshot, LanternSnapshotArtifact } from "./check-lantern-material-snapshot.mjs";
+
+export { checkLanternMaterialSnapshot, createLanternMaterialSnapshot, lanternSnapshotPaths, parseLanternMaterialSnapshot } from "./check-lantern-material-snapshot.mjs";
+export type { LanternMaterialSnapshot } from "./check-lantern-material-snapshot.mjs";
+
+const names = Object.keys(lanternSnapshotPaths) as LanternSnapshotArtifact[];
+const missing = (error: unknown) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+type DirectoryIdentity = { readonly dev: number; readonly ino: number };
+type Previous = { readonly identity: DirectoryIdentity; readonly manifest: LanternMaterialSnapshot | undefined };
+
+async function previousSnapshot(directory: string): Promise<Previous | undefined> {
+  let identity;
+  try { identity = await lstat(directory); } catch (error) { if (missing(error)) return undefined; throw error; }
+  if (!identity.isDirectory() || identity.isSymbolicLink()) throw new Error("Snapshot destination must be a physical directory.");
+  const entries = await readdir(directory);
+  return { identity, manifest: entries.length === 0 ? undefined : await checkLanternMaterialSnapshot(directory) };
+}
+
+async function assertPrevious(directory: string, previous: Previous): Promise<void> {
+  const current = await previousSnapshot(directory);
+  if (current === undefined || current.identity.dev !== previous.identity.dev || current.identity.ino !== previous.identity.ino
+    || JSON.stringify(current.manifest) !== JSON.stringify(previous.manifest)) throw new Error("Snapshot changed during installation.");
+}
+
+export async function writeLanternMaterialSnapshot(directory: string, commit: string, sourceRoot = resolve(import.meta.dir, "..")): Promise<void> {
+  if (!/^[a-f0-9]{40}$/u.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  const git = (args: readonly string[], maximum = 1024) => execFileSync("git", ["--no-pager", "--no-optional-locks", "--no-replace-objects", ...args], {
+    cwd: sourceRoot, maxBuffer: maximum, timeout: 30_000, stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (git(["cat-file", "-t", commit]).toString("utf8").trim() !== "commit") {
+    throw new Error("Snapshot source must name a commit object, not a tree or tag object.");
+  }
+  // Every source mode and byte is read from the exact Git object before any
+  // destination mutation. A dirty checkout cannot change the admitted payload.
+  const files = Object.fromEntries(names.map((name) => {
+    const path = lanternSnapshotPaths[name];
+    const entry = git(["ls-tree", commit, "--", path]).toString("utf8").trim();
+    if (!/^100644 blob [a-f0-9]{40}\t/u.test(entry) || entry.split("\t")[1] !== path) throw new Error(`Snapshot source ${path} must be one regular Git blob.`);
+    return [name, git(["show", "--no-textconv", `${commit}:${path}`], lanternSnapshotFileLimits[name])];
+  })) as Record<LanternSnapshotArtifact, Buffer>;
+  const manifest = createLanternMaterialSnapshot(commit, files);
+  directory = resolve(directory);
+  const previous = await previousSnapshot(directory);
+  await mkdir(dirname(directory), { recursive: true });
+  // Resolve an existing parent once; do not stage through a changing symlink.
+  directory = join(await realpath(dirname(directory)), basename(directory));
+  if (previous !== undefined) await assertPrevious(directory, previous);
+  else if (await previousSnapshot(directory) !== undefined) throw new Error("Snapshot destination appeared during installation.");
+  const stage = `${directory}.stage-${randomUUID()}`;
+  const backup = `${directory}.previous-${randomUUID()}`;
+  let backedUp = false;
+  try {
+    await mkdir(stage, { mode: 0o700 });
+    for (const name of names) await writeFile(join(stage, name), files[name], { flag: "wx", mode: 0o600 });
+    await writeFile(join(stage, "provenance.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await checkLanternMaterialSnapshot(stage);
+    if (previous !== undefined) {
+      await assertPrevious(directory, previous);
+      await rename(directory, backup);
+      backedUp = true;
+      await assertPrevious(backup, previous);
+    } else if (await previousSnapshot(directory) !== undefined) throw new Error("Snapshot destination appeared during installation.");
+    await rename(stage, directory);
+    const installed = await checkLanternMaterialSnapshot(directory);
+    if (JSON.stringify(installed) !== JSON.stringify(manifest)) throw new Error("Installed snapshot differs from its immutable source.");
+    if (backedUp && previous !== undefined) {
+      await assertPrevious(backup, previous);
+      await rm(backup, { recursive: true });
+    }
+  } catch (error) {
+    if (backedUp) {
+      // Never inspect or remove an unexpected destination while recovering the
+      // admitted previous directory. Keep the backup if any path now exists.
+      try { await lstat(directory); } catch (absent) { if (missing(absent)) await rename(backup, directory); }
+    }
+    throw error;
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  const [operation, directory, flag, commit, ...extra] = process.argv.slice(2);
+  if (operation === "--check" && directory !== undefined && flag === undefined) {
+    console.log(`Lantern material snapshot verified at ${(await checkLanternMaterialSnapshot(resolve(directory))).source.commit}.`);
+  } else if (operation === "--write" && directory !== undefined && flag === "--source-commit" && commit !== undefined && extra.length === 0) {
+    await writeLanternMaterialSnapshot(directory, commit);
+    console.log(`Lantern material snapshot installed from ${commit}.`);
+  } else throw new Error("Usage: bun scripts/lantern-material-snapshot.ts --check DIRECTORY | --write DIRECTORY --source-commit FULL_COMMIT");
+}

package/scripts/marketing-textures.ts

@@ -0,0 +1,48 @@
+/** Original deterministic Hraness textures. Grain stays behind content. */
+import assert from "node:assert/strict";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export function marketingTextures(): Readonly<Record<"grain.svg" | "cells.svg", string>> {
+let seed = 4652026;
+function random() {
+  seed ^= seed << 13;
+  seed ^= seed >>> 17;
+  seed ^= seed << 5;
+  return (seed >>> 0) / 4294967296;
+}
+const stipple = ["", ""];
+for (let y = 0; y < 128; y++) {
+  for (let x = 0; x < 128; x++) {
+    const value = random();
+    if (value < .65) stipple[value < .325 ? 0 : 1] += `M${x} ${y}h1v1h-1z`;
+  }
+}
+const grain = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g opacity=".03"><path fill="#000" d="${stipple[0]}"/><path fill="#fff" d="${stipple[1]}"/></g></svg>\n`;
+const gradients: string[] = [];
+const faces: string[] = [];
+// Eight by eight original faces form a seamless repeating field. Each pane
+// has its own light direction and transmission; no visible grid is drawn.
+for (let row = 0; row < 8; row++) {
+  for (let column = 0; column < 8; column++) {
+    const id = `p${row * 8 + column}`;
+    const angle = Math.round(20 + random() * 65);
+    const light = (0.025 + random() * 0.045).toFixed(3);
+    const shade = (0.008 + random() * 0.026).toFixed(3);
+    gradients.push(`<linearGradient id="${id}" x2="${angle}%" y2="100%"><stop stop-color="#fff" stop-opacity="${light}"/><stop offset=".46" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#000" stop-opacity="${shade}"/></linearGradient>`);
+    faces.push(`<path d="M${column * 96} ${row * 96}h96v96h-96z" fill="url(#${id})"/>`);
+  }
+}
+const cells = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 768 768"><defs>${gradients.join("")}</defs>${faces.join("")}</svg>\n`;
+
+return { "grain.svg": grain, "cells.svg": cells };
+}
+
+if (import.meta.main) {
+  const writing = process.argv.slice(2).join(" ") === "--write";
+  for (const [name, contents] of Object.entries(marketingTextures())) {
+    const path = resolve(import.meta.dir, "../src/marketing-assets", name);
+    if (writing) await writeFile(path, contents);
+    else assert.equal(await readFile(path, "utf8"), contents, `${name} differs from its checked source.`);
+  }
+}

package/scripts/paper-theme-snapshot.ts

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const repository = "https://github.com/hraness/design-kit";
+const artifacts = ["paper-theme.css", "LICENSE"] as const;
+const digest = (value: string) => createHash("sha256").update(value).digest("hex");
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export interface PaperThemeSnapshot {
+  readonly schemaVersion: 1;
+  readonly contractVersion: 1;
+  readonly source: {
+    readonly repository: typeof repository;
+    readonly commit: string;
+    readonly export: "@hraness/design-kit/paper-theme.css";
+  };
+  readonly files: Readonly<Record<(typeof artifacts)[number], { readonly path: string; readonly sha256: string }>>;
+}
+
+export function createPaperThemeSnapshot(commit: string, css: string, license: string): PaperThemeSnapshot {
+  if (!/^[a-f0-9]{40}$/u.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  return {
+    schemaVersion: 1, contractVersion: 1,
+    source: { repository, commit, export: "@hraness/design-kit/paper-theme.css" },
+    files: {
+      "paper-theme.css": { path: "src/paper-theme.css", sha256: digest(css) },
+      LICENSE: { path: "LICENSE", sha256: digest(license) },
+    },
+  };
+}
+
+export function parsePaperThemeSnapshot(value: unknown): PaperThemeSnapshot {
+  if (!isRecord(value) || value.schemaVersion !== 1 || value.contractVersion !== 1
+    || !isRecord(value.source) || value.source.repository !== repository
+    || value.source.export !== "@hraness/design-kit/paper-theme.css"
+    || typeof value.source.commit !== "string" || !/^[a-f0-9]{40}$/u.test(value.source.commit)
+    || !isRecord(value.files) || Object.keys(value.files).sort().join(",") !== "LICENSE,paper-theme.css") {
+    throw new Error("Invalid Paper theme provenance manifest.");
+  }
+  for (const name of artifacts) {
+    const artifact = value.files[name];
+    const path = name === "LICENSE" ? "LICENSE" : "src/paper-theme.css";
+    if (!isRecord(artifact) || artifact.path !== path || typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(artifact.sha256)) {
+      throw new Error(`Invalid ${name} provenance.`);
+    }
+  }
+  return value as unknown as PaperThemeSnapshot;
+}
+
+export async function checkPaperThemeSnapshot(directory: string): Promise<PaperThemeSnapshot> {
+  const value: unknown = JSON.parse(await readFile(resolve(directory, "provenance.json"), "utf8"));
+  const manifest = parsePaperThemeSnapshot(value);
+  for (const name of artifacts) {
+    if (digest(await readFile(resolve(directory, name), "utf8")) !== manifest.files[name].sha256) {
+      throw new Error(`${name} differs from its immutable snapshot; keep local adaptations in a separate stylesheet.`);
+    }
+  }
+  return manifest;
+}
+
+export async function writePaperThemeSnapshot(directory: string, commit: string, sourceRoot = resolve(import.meta.dir, "..")): Promise<void> {
+  if (!/^[a-f0-9]{40}$/u.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  const committed = (path: string) => execFileSync("git", ["show", `${commit}:${path}`], { cwd: sourceRoot, encoding: "utf8", maxBuffer: 1024 * 1024 });
+  const css = committed("src/paper-theme.css");
+  const license = committed("LICENSE");
+  const manifest = createPaperThemeSnapshot(commit, css, license);
+  // Existing snapshots must still be intact before an intentional upgrade.
+  try {
+    await readFile(resolve(directory, "provenance.json"));
+    await checkPaperThemeSnapshot(directory);
+  } catch (error) {
+    if (!(isRecord(error) && error.code === "ENOENT")) throw error;
+    for (const name of artifacts) {
+      try { await readFile(resolve(directory, name)); }
+      catch (missing) { if (isRecord(missing) && missing.code === "ENOENT") continue; throw missing; }
+      throw new Error(`Refusing to overwrite ${name} without snapshot provenance.`);
+    }
+  }
+  await mkdir(directory, { recursive: true });
+  await writeFile(resolve(directory, "paper-theme.css"), css);
+  await writeFile(resolve(directory, "LICENSE"), license);
+  await writeFile(resolve(directory, "provenance.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  await checkPaperThemeSnapshot(directory);
+}
+
+if (import.meta.main) {
+  const [operation, directory, flag, commit, ...extra] = process.argv.slice(2);
+  if (operation === "--check" && directory !== undefined && flag === undefined) {
+    const result = await checkPaperThemeSnapshot(resolve(directory));
+    console.log(`Paper theme snapshot verified at ${result.source.commit}.`);
+  } else if (operation === "--write" && directory !== undefined && flag === "--source-commit" && commit !== undefined && extra.length === 0) {
+    await writePaperThemeSnapshot(resolve(directory), commit);
+    console.log(`Paper theme snapshot installed from ${commit}.`);
+  } else throw new Error("Usage: bun scripts/paper-theme-snapshot.ts --check DIRECTORY | --write DIRECTORY --source-commit FULL_COMMIT");
+}

package/scripts/product-marketing-snapshot.ts

@@ -0,0 +1,149 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+const repository = "https://github.com/hraness/design-kit";
+export const marketingSnapshotPaths = {
+  "product-marketing-preset.css": "src/product-marketing-preset.css",
+  "fonts/instrument-serif/instrument-serif-latin-400.woff2": "src/fonts/instrument-serif/instrument-serif-latin-400.woff2",
+  "fonts/instrument-serif/OFL.txt": "src/fonts/instrument-serif/OFL.txt",
+  "fonts/instrument-serif/UPSTREAM.md": "src/fonts/instrument-serif/UPSTREAM.md",
+  "marketing-assets/grain.svg": "src/marketing-assets/grain.svg",
+  "marketing-assets/cells.svg": "src/marketing-assets/cells.svg",
+  "marketing-assets/UPSTREAM.md": "src/marketing-assets/UPSTREAM.md",
+  "check.mjs": "scripts/check-marketing-snapshot.mjs",
+  "check.d.mts": "scripts/check-marketing-snapshot.d.mts",
+  LICENSE: "LICENSE",
+} as const;
+type Artifact = keyof typeof marketingSnapshotPaths;
+const artifacts = Object.keys(marketingSnapshotPaths) as Artifact[];
+const digest = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const missing = (error: unknown) => isRecord(error) && error.code === "ENOENT";
+
+export interface MarketingSnapshot {
+  readonly schemaVersion: 1;
+  readonly contractVersion: 1;
+  readonly source: { readonly repository: typeof repository; readonly commit: string; readonly export: "@hraness/design-kit/product-marketing-preset.css" };
+  readonly files: Readonly<Record<Exclude<Artifact, "check.mjs" | "check.d.mts">, { readonly path: string; readonly sha256: string }> & Partial<Record<"check.mjs" | "check.d.mts", { readonly path: string; readonly sha256: string }>>>;
+}
+
+export function createMarketingSnapshot(commit: string, files: Readonly<Record<Artifact, Uint8Array>>): MarketingSnapshot {
+  if (!/^[a-f0-9]{40}$/u.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  return {
+    schemaVersion: 1, contractVersion: 1,
+    source: { repository, commit, export: "@hraness/design-kit/product-marketing-preset.css" },
+    files: Object.fromEntries(artifacts.map((name) => [name, { path: marketingSnapshotPaths[name], sha256: digest(files[name]) }])) as MarketingSnapshot["files"],
+  };
+}
+
+export function parseMarketingSnapshot(value: unknown, allowPreviousInventory = false): MarketingSnapshot {
+  const expected = allowPreviousInventory && isRecord(value) && isRecord(value.files) && !("check.mjs" in value.files) ? artifacts.filter((name) => name !== "check.mjs" && name !== "check.d.mts") : artifacts;
+  if (!isRecord(value) || value.schemaVersion !== 1 || value.contractVersion !== 1
+    || !isRecord(value.source) || value.source.repository !== repository
+    || value.source.export !== "@hraness/design-kit/product-marketing-preset.css"
+    || typeof value.source.commit !== "string" || !/^[a-f0-9]{40}$/u.test(value.source.commit)
+    || !isRecord(value.files) || Object.keys(value.files).sort().join("\n") !== [...expected].sort().join("\n")) {
+    throw new Error("Invalid marketing snapshot provenance.");
+  }
+  for (const name of expected) {
+    const file = value.files[name];
+    if (!isRecord(file) || file.path !== marketingSnapshotPaths[name] || typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(file.sha256)) {
+      throw new Error(`Invalid ${name} provenance.`);
+    }
+  }
+  return value as unknown as MarketingSnapshot;
+}
+
+async function inventory(directory: string, prefix = ""): Promise<string[]> {
+  const details = await lstat(directory);
+  if (!details.isDirectory() || details.isSymbolicLink()) throw new Error("Snapshot directories must be physical directories.");
+  const files: string[] = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = prefix + entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Snapshot contains a symbolic link: ${path}`);
+    if (entry.isDirectory()) {
+      if (!artifacts.some((name) => name.startsWith(`${path}/`))) throw new Error(`Snapshot contains an unowned directory: ${path}`);
+      files.push(...await inventory(join(directory, entry.name), `${path}/`));
+    }
+    else if (entry.isFile()) files.push(path);
+    else throw new Error(`Snapshot contains a non-file: ${path}`);
+  }
+  return files.sort();
+}
+
+export async function checkMarketingSnapshot(directory: string, allowPreviousInventory = false): Promise<MarketingSnapshot> {
+  const actual = await inventory(directory);
+  const value: unknown = JSON.parse(await readFile(join(directory, "provenance.json"), "utf8"));
+  const manifest = parseMarketingSnapshot(value, allowPreviousInventory);
+  if (actual.join("\n") !== [...Object.keys(manifest.files), "provenance.json"].sort().join("\n")) throw new Error("Snapshot has missing or unowned files.");
+  for (const [name, receipt] of Object.entries(manifest.files)) {
+    if (receipt === undefined) throw new Error(`Missing ${name} provenance.`);
+    if (digest(await readFile(join(directory, name))) !== receipt.sha256) throw new Error(`${name} differs from its immutable snapshot.`);
+  }
+  return manifest;
+}
+
+export async function writeMarketingSnapshot(directory: string, commit: string, sourceRoot = resolve(import.meta.dir, "..")): Promise<void> {
+  if (!/^[a-f0-9]{40}$/u.test(commit)) throw new Error("Snapshot source must be a full lowercase Git commit.");
+  const objectType = execFileSync("git", ["cat-file", "-t", commit], {
+    cwd: sourceRoot, encoding: "utf8", maxBuffer: 1024, timeout: 30_000,
+  }).trim();
+  if (objectType !== "commit") throw new Error("Snapshot source must name a commit object, not a tree or tag object.");
+  directory = resolve(directory);
+  // Read immutable bytes before touching the destination. Never copy a dirty tree.
+  const files = Object.fromEntries(artifacts.map((name) => [name, execFileSync("git", ["show", `${commit}:${marketingSnapshotPaths[name]}`], {
+    cwd: sourceRoot, maxBuffer: 2 * 1024 * 1024, timeout: 30_000,
+  })])) as Record<Artifact, Buffer>;
+  const manifest = createMarketingSnapshot(commit, files);
+  let previous: MarketingSnapshot | undefined;
+  let existed = false;
+  try {
+    const present = await inventory(directory);
+    existed = true;
+    if (present.length > 0) previous = await checkMarketingSnapshot(directory, true);
+  } catch (error) { if (!missing(error)) throw error; }
+  await mkdir(dirname(directory), { recursive: true });
+  const stage = `${directory}.stage-${randomUUID()}`;
+  const backup = `${directory}.previous-${randomUUID()}`;
+  let backedUp = false;
+  try {
+    await mkdir(stage);
+    for (const name of artifacts) {
+      await mkdir(dirname(join(stage, name)), { recursive: true });
+      await writeFile(join(stage, name), files[name]);
+    }
+    await writeFile(join(stage, "provenance.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    await checkMarketingSnapshot(stage);
+    if (existed) {
+      if (previous === undefined) {
+        if ((await inventory(directory)).length !== 0) throw new Error("Unowned files appeared in the snapshot destination.");
+      } else if (JSON.stringify(await checkMarketingSnapshot(directory, true)) !== JSON.stringify(previous)) throw new Error("Snapshot changed during installation.");
+      await rename(directory, backup);
+      backedUp = true;
+      // Check again after moving the exact directory before replacing it.
+      if (previous === undefined ? (await inventory(backup)).length !== 0 : JSON.stringify(await checkMarketingSnapshot(backup, true)) !== JSON.stringify(previous)) throw new Error("Snapshot changed during installation.");
+    }
+    await rename(stage, directory);
+    await checkMarketingSnapshot(directory);
+    if (backedUp) await rm(backup, { recursive: true });
+  } catch (error) {
+    if (backedUp) {
+      try { await lstat(directory); } catch (absent) { if (missing(absent)) await rename(backup, directory); }
+    }
+    throw error;
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  const [operation, directory, flag, commit, ...extra] = process.argv.slice(2);
+  if (operation === "--check" && directory !== undefined && flag === undefined) {
+    console.log(`Marketing snapshot verified at ${(await checkMarketingSnapshot(resolve(directory))).source.commit}.`);
+  } else if (operation === "--write" && directory !== undefined && flag === "--source-commit" && commit !== undefined && extra.length === 0) {
+    await writeMarketingSnapshot(resolve(directory), commit);
+    console.log(`Marketing snapshot installed from ${commit}.`);
+  } else throw new Error("Usage: bun scripts/product-marketing-snapshot.ts --check DIRECTORY | --write DIRECTORY --source-commit FULL_COMMIT");
+}