Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions scripts/optimize-opening-assets.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { copyFile, mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { WRENS_LIGHT_SCENES } from "../web/src/opening/wrens-light/wrens-light-scenes";

// Delivery derivatives only; generation and documented normalization happen before this script.
const project = resolve(import.meta.dir, "..");
const source = join(project, "web/assets/source/opening");
const target = join(project, "web/public/assets/opening");
const delivery = {
portrait: { width: 780, height: 1688, maxBytes: 1_250_000, firstMaxBytes: 200_000 },
landscape: { width: 1728, height: 1080, maxBytes: 1_800_000, firstMaxBytes: 300_000 },
landscapeRetina: { width: 2880, height: 1800, maxBytes: 3_200_000, firstMaxBytes: 500_000 },
} as const;
const quality = 87;
const placeholderTarget = "web/src/opening/wrens-light/opening-placeholder.ts";
const names = WRENS_LIGHT_SCENES.flatMap(scene => [scene.id, `${scene.id}-landscape`]).sort();
const actual = (await readdir(source)).filter(name => name.endsWith(".png")).map(name => name.slice(0, -4)).sort();
assert.deepEqual(actual, names, "Each of the seven scenes needs a portrait and a landscape master");

type Size = { width: number; height: number };
type ArtRecord = {
prompt: string; sourceSha256: string; styleReferences: (string | { path: string; use: string })[];
native?: Size & { path: string; sha256: string };
generatedSource?: string; generatedSize?: Size; generatedSha256?: string;
};
type ArtRecords = { created: string; generator: { tool: string; requestedModel: string; model?: string }; files: Record<string, ArtRecord> };
const record = await Bun.file(join(source, "provenance.json")).json() as ArtRecords;
assert(/^\d{4}-\d{2}-\d{2}$/.test(record.created), "Art record needs its actual creation date");
assert(record.generator?.tool, "Art record needs its actual generator tool");
assert.equal(record.generator.requestedModel, "gpt-6-astra", "Record the requested model without claiming the unexposed backend");
assert.deepEqual(Object.keys(record.files).sort(), names.map(name => `${name}.png`).sort(), "Every scene needs exactly one generation record");

const hash = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
function run(command: string[]) {
const result = Bun.spawnSync(command);
assert.equal(result.exitCode, 0, `${command[0]} failed: ${result.stderr.toString()}`);
return result.stdout.toString().trim();
}
function pixelSize(path: string) {
const [width, height] = run(["magick", "identify", "-format", "%w %h", path]).split(" ").map(Number);
assert(Number.isInteger(width) && width > 0 && Number.isInteger(height) && height > 0, `Invalid image dimensions: ${path}`);
return { width, height };
}
const publicValue = (key: string, value: unknown) => key === "originalGeneratedPath"
|| typeof value === "string" && /^\/(Users|private|tmp)\//.test(value) ? undefined : value;
assert.equal(JSON.stringify({ nested: { originalGeneratedPath: "/Users/local.png", path: "web/assets/source/opening/storm.png" }, local: "/tmp/local.png" }, publicValue),
'{"nested":{"path":"web/assets/source/opening/storm.png"}}', "Public metadata removes private paths recursively");

const work = await mkdtemp(join(tmpdir(), "opening-art-"));
const files = [], provenance: Record<string, unknown> = {};
const placeholders: { orientation: "portrait" | "landscape"; source: string; sourceSha256: string; sha256: string; bytes: number; dataUriBytes: number; width: number; height: number }[] = [];
const inline: Record<string, string> = {}, finalInline: Record<string, string> = {};
try {
for (const name of names) {
const master = join(source, `${name}.png`), stripped = join(work, `${name}.png`);
const before = await Bun.file(master).bytes();
const art = record.files[`${name}.png`];
assert.equal(hash(before), art.sourceSha256, `Source differs from its verified generation record: ${name}`);
const landscape = name.endsWith("-landscape"), orientation = landscape ? "landscape" : "portrait";
const expectedSize = landscape ? { width: 2304, height: 1440 } : { width: 1170, height: 2532 };
const native = art.native ?? { path: art.generatedSource, sha256: art.generatedSha256, ...art.generatedSize };
assert(typeof native.path === "string" && native.path.startsWith("web/assets/source/opening/generated/") && !native.path.split("/").includes(".."), `Missing preserved native image: ${name}`);
const nativePath = join(project, native.path), nativeBytes = await Bun.file(nativePath).bytes();
assert.equal(hash(nativeBytes), native.sha256, `Native generation differs from its provenance: ${name}`);
assert.deepEqual(pixelSize(nativePath), { width: native.width, height: native.height }, `Native dimensions differ from provenance: ${name}`);
try {
const sourceSize = pixelSize(master);
assert.deepEqual(sourceSize, expectedSize, `Master needs the authored ${orientation} delivery canvas: ${name}`);
assert.equal(run(["magick", nativePath, "-format", "%[opaque]", "info:"]).toLowerCase(), "true", `Native scene must be opaque: ${name}`);
assert.equal(run(["magick", master, "-format", "%[opaque]", "info:"]).toLowerCase(), "true", `Opening scene must be opaque: ${name}`);
assert(typeof art.prompt === "string" && art.prompt.length > 0, `Missing prompt: ${name}`);
assert(Array.isArray(art.styleReferences) && art.styleReferences.every(ref => {
const path = typeof ref === "string" ? ref : ref.path;
return typeof path === "string" && path.startsWith("web/assets/source/") && !path.split("/").includes("..");
}), `References must use repository-relative master paths: ${name}`);
for (const tier of landscape ? ["landscape", "landscapeRetina"] as const : ["portrait"] as const) {
const size = delivery[tier], outputName = `${name}${tier === "landscapeRetina" ? "-2880" : ""}.webp`;
const output = join(work, outputName);
run(["magick", master, "-filter", "Lanczos", "-resize", `${size.width}x${size.height}`, "-strip", stripped]);
run(["cwebp", "-quiet", "-q", String(quality), "-m", "6", "-sharp_yuv", stripped, "-o", output]);
const after = await Bun.file(output).bytes(), outputSize = pixelSize(output);
assert.deepEqual(outputSize, { width: size.width, height: size.height }, `Runtime must preserve the authored aspect ratio: ${name}`);
assert.equal(run(["magick", output, "-format", "%[opaque]", "info:"]).toLowerCase(), "true", `Output must stay opaque: ${name}`);
files.push({ source: `web/assets/source/opening/${name}.png`, output: `web/public/assets/opening/${outputName}`,
orientation, tier, sourceSha256: hash(before), sha256: hash(after), sourceBytes: before.length, bytes: after.length, sourceSize, outputSize,
native: { path: native.path, sha256: native.sha256, width: native.width, height: native.height, bytes: nativeBytes.length } });
provenance[outputName] = { master: `web/assets/source/opening/${name}.png`, created: record.created,
generator: record.generator, ...art, delivery: { operation: `Proportional Lanczos ${tier === "landscapeRetina" ? "upsample from approved master; no new native detail" : "downsample"}; no crop or repaint`, quality, outputSize, sha256: hash(after), bytes: after.length } };
if (name === "storm" || name === "storm-landscape") {
assert(after.length <= size.firstMaxBytes, `First ${tier} scene exceeds its cold-load budget`);
}
}
if (["storm", "storm-landscape", "mochi-quay", "mochi-quay-landscape"].includes(name)) {
const poster = join(work, `${name}-poster.png`), encoded = join(work, `${name}-poster.webp`);
run(["magick", master, "-filter", "Lanczos", "-resize", landscape ? "96x60" : "60x130", "-strip", poster]);
run(["cwebp", "-quiet", "-q", "55", "-m", "6", poster, "-o", encoded]);
const bytes = await Bun.file(encoded).bytes();
const posters = name.startsWith("storm") ? inline : finalInline;
posters[orientation] = `data:image/webp;base64,${Buffer.from(bytes).toString("base64")}`;
assert(posters[orientation].length <= 2500, `Inline ${name} poster must stay tiny`);
placeholders.push({ orientation, source: `web/assets/source/opening/${name}.png`, sourceSha256: hash(before),
sha256: hash(bytes), bytes: bytes.length, dataUriBytes: posters[orientation].length, ...pixelSize(encoded) });
}
} finally {
assert.equal(hash(await Bun.file(master).bytes()), hash(before), `Master must stay byte-identical: ${name}.png`);
}
}
const totalBytes = files.reduce((total, file) => total + file.bytes, 0);
const bytesByOrientation: Record<string, number> = { portrait: 0, landscape: 0 };
const bytesByDelivery = { portrait: 0, landscape: 0, landscapeRetina: 0 };
for (const file of files) {
bytesByOrientation[file.orientation] += file.bytes;
bytesByDelivery[file.tier] += file.bytes;
}
for (const tier of ["portrait", "landscape", "landscapeRetina"] as const) assert(bytesByDelivery[tier] <= delivery[tier].maxBytes, `${tier} film exceeds its delivery budget`);
assert.deepEqual(Object.keys(inline).sort(), ["landscape", "portrait"], "Both first-scene orientations need an inline poster");
assert.deepEqual(Object.keys(finalInline).sort(), ["landscape", "portrait"], "Both final-scene orientations need an inline poster");
const placeholderModule = `// Generated by scripts/optimize-opening-assets.ts from the approved first and final plates.\nexport const OPENING_PLACEHOLDER = ${JSON.stringify(inline, null, 2)} as const;\nexport const FINAL_OPENING_PLACEHOLDER = ${JSON.stringify(finalInline, null, 2)} as const;\n`;
const manifest = { purpose: "Keep Wren’s Light opening; seven authored portrait and landscape pairs with responsive desktop delivery", encoder: `ImageMagick Lanczos proportional resize + metadata strip; cwebp quality${quality} method6 sharp_yuv`,
budget: { ...delivery, inlinePostersMaxBytes: 10000, note: "Portrait is unchanged at 2x the 390x844 phone. Landscape candidates are 1728 and 2880 pixels wide; the latter is resampled from the approved 2304px master, not newly generated detail. Each delivery tier has its own budget; rotating or resizing may fetch more than one tier. Native outputs and source masters remain unchanged." },
totalBytes, bytesByOrientation, bytesByDelivery, inlinePosters: { module: placeholderTarget, moduleBytes: Buffer.byteLength(placeholderModule), files: placeholders }, files };
const publicProvenance = { purpose: "Authored opening scenes for Familiar", delivery: "Native generator outputs and full-resolution masters remain separately preserved and hashed. Delivery WebPs use proportional Lanczos resizing to portrait780x1688 and landscape1728x1080 or landscape2880x1800, encoded at quality87, method6, sharp_yuv. The 2880px candidate resamples the approved 2304px master and adds no native detail; preserved landscape generator outputs are approximately 1586px wide. No crops or repaints. Tiny first- and final-scene WebP posters (quality55) are inlined in code for immediate paint. All text is rendered in code.", inlinePosters: placeholders, files: provenance };
const metadata = JSON.stringify(publicProvenance, publicValue, 2) + "\n";
assert(!metadata.includes("/Users/") && !metadata.includes("/private/") && !metadata.includes("/tmp/"), "Public provenance must not contain private local paths");
await mkdir(target, { recursive: true });
for (const file of files) await copyFile(join(work, file.output.split("/").at(-1)!), join(project, file.output));
await Bun.write(join(target, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
await Bun.write(join(target, "provenance.json"), metadata);
await Bun.write(join(project, placeholderTarget), placeholderModule);
console.log(JSON.stringify(manifest, null, 2));
} finally {
await rm(work, { recursive: true, force: true });
}
80 changes: 80 additions & 0 deletions web/assets/source/opening/art-arrival-prompts.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
{
"created": "2026-11-14",
"generator": {
"tool": "image_gen.imagegen",
"requestedModel": "gpt-6-astra",
"actualModel": "not exposed by the built-in tool"
},
"files": {
"mochi-quay.png": {
"prompt": "Use case: identity-preserve / illustration-story. Recompose reference image 1, the canonical Familiar Mochi arrival scene, into a true tall 390:844 portrait composition, intended output1170x2532. Reference image2 is the house harbor materials and geography. Preserve ONE Mochi exactly: orange felt tabby, three forehead stripes, cream muzzle and paws, two dark whiskers per cheek, brown eyes, red scarf and stitched brown satchel. Same curious capable three-quarter head tilt and standing pose, unchanged character proportions. At logical390x844, place her complete silhouette including tail within x95-264/y290-540, feet at y540 and eyeline around y365. She is a nearby companion; leave clear low-detail open space to her left for a later Bram entrance. Lighthouse is behind her on the right: entire red cap, dark glass lantern room and wooden balcony must stay within x262-344/y155-285 with ≥24px right clearance; tower and base within x250-358/y260-425. Unlit beacon, no beam. Soft peach dawn, lilac cloud undersides, blue-green harbor, tactile sandstone, miniature trees, cottage terracotta and brass. Keep x20-190/y14-75 quiet subdued dawn sky or dark low-detail foliage behind future native wordmark. All quay posts and ropes above y555. Reserve x26-364/y600-744 and y760-824 for quiet low-contrast gently shaded stone, with no flowers, strong bright joints, posts or rope crossing this region. No baked caption gradients. Full tall authored painting, no letterbox, no stretched or cropped inset. No new accessories, no redesign, no second cat or enlarged background face, no Wren, no added Bram, no new plot evidence, text, logos, interface or borders. This is a provisional FILM staging target, not a claim to match an unavailable live prologue.",
"styleReferences": [
"web/assets/source/opening/generated/mochi-quay-reference.png",
"web/assets/source/first-light-motion/harbor.png"
],
"sourceSha256": "00e75b1464b4bbbecc40b6e1064121a8df3df74f8a1ddbce8a8cd237e883f760",
"attempts": 1,
"native": {
"path": "web/assets/source/opening/generated/mochi-quay.png",
"width": 852,
"height": 1846,
"sha256": "50279475395149dd3838cc9f92da387c1e1cece19912347a8fdd4e5f2364efde"
},
"delivery": {
"width": 1170,
"height": 2532,
"method": "ImageMagick proportional resize to cover, centered extent; less than 4 delivery pixels removed vertically; no stretching or subject crop."
},
"registration": "Film target only. No captured live Slice B prologue exists in accessible worktrees; cross-scene match remains unverified.",
"styleReferenceHashes": {
"web/assets/source/first-light-motion/harbor.png": "2325df200d988554c83d93c37f65219cd5b8ffe8cd1c09089ad03fea783e0920",
"web/assets/source/opening/generated/mochi-quay-reference.png": "17f4f3694f84b9d915b410901ac4018bcacad557e0229f1024db87e93cbf0e66"
},
"referenceHashes": [
{
"path": "web/assets/source/opening/generated/mochi-quay-reference.png",
"sha256": "17f4f3694f84b9d915b410901ac4018bcacad557e0229f1024db87e93cbf0e66"
},
{
"path": "web/assets/source/first-light-motion/harbor.png",
"sha256": "2325df200d988554c83d93c37f65219cd5b8ffe8cd1c09089ad03fea783e0920"
}
]
},
"mochi-quay-landscape.png": {
"prompt": "Use case: identity-preserve / illustration-story. Create one beautiful premium handcrafted Familiar landscape film plate, exactly 16:10 composition, intended 2304x1440. Image 1 is the canonical Mochi arrival character and dawn scene: preserve Mochi's orange felt tabby identity, three forehead stripes, cream muzzle and paws, two dark whiskers per cheek, brown eyes, red scarf, and stitched brown satchel, her curious capable expression and current standing pose. Image 2 is the house harbor material and geography reference. Compose a single spatially coherent landscape view of this harbor at warm peach and lilac dawn. Place ONE complete Mochi in the right half, full silhouette at logical x875-1140/y330-665 on a 1440x900 canvas; feet around y665, eyeline around y425, nearby companion scale. Place the complete dark beacon including red cap, lantern room, wooden balcony, tower and base behind her toward logical x1170-1340/y145-510, at least 70 pixels from right edge. The beacon remains unlit. Naturally extend actual water, sky and wet sandstone toward the left with continuous miniature perspective; left x50-570/y540-850 is quiet softly shaded low-detail stone for future native captions and buttons. Top-left x30-260/y20-95 quiet dark foliage or subdued dawn sky for a future wordmark. Keep posts and rope out of the reading column. Preserve Familiar rounded cream sandstone, terracotta roof, imperfect clay masonry, felt textures, brass, wood, subtle miniature greenery. Warm luminous morning everywhere except naturally shaded left stone. No gradients painted for captions. No second Mochi, no enlarged background face, no portrait panel, no seam, no mirroring, no blurred filler, no Wren, no Bram added, no new accessories or narrative elements, no text or interface anywhere.",
"styleReferences": [
"web/assets/source/opening/generated/mochi-quay-reference.png",
"web/assets/source/first-light-motion/harbor.png"
],
"sourceSha256": "356ae00ca91d9147ce02bd294879939a2744ec615069079bd70200e300ed97c5",
"attempts": 1,
"native": {
"path": "web/assets/source/opening/generated/mochi-quay-landscape.png",
"width": 1586,
"height": 992,
"sha256": "9cb9de8e64629b9972568b52c278fe835574f7dac5909ff09bf6f9afbdf0b265"
},
"delivery": {
"width": 2304,
"height": 1440,
"method": "ImageMagick proportional resize to cover, centered extent; less than 2 delivery pixels removed vertically; no stretching or subject crop."
},
"registration": "Film target only, no live prologue registration reference available.",
"styleReferenceHashes": {
"web/assets/source/first-light-motion/harbor.png": "2325df200d988554c83d93c37f65219cd5b8ffe8cd1c09089ad03fea783e0920",
"web/assets/source/opening/generated/mochi-quay-reference.png": "17f4f3694f84b9d915b410901ac4018bcacad557e0229f1024db87e93cbf0e66"
},
"referenceHashes": [
{
"path": "web/assets/source/opening/generated/mochi-quay-reference.png",
"sha256": "17f4f3694f84b9d915b410901ac4018bcacad557e0229f1024db87e93cbf0e66"
},
{
"path": "web/assets/source/first-light-motion/harbor.png",
"sha256": "2325df200d988554c83d93c37f65219cd5b8ffe8cd1c09089ad03fea783e0920"
}
]
}
}
}
Loading