mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
One prompt carrier across every harness: embed-prompt.mjs
The prompt behind a generated image was recorded three different ways, a sidecar in the eval harness, nothing in the skill's API tool, nothing for native tools, so intent survived or vanished depending on where you ran. One dependency-free script now embeds the prompt inside the image itself, PNG tEXt or JPEG COM with a sidecar fallback for other formats, idempotent, and reads it back from any impeccable-generated file. The API tool embeds automatically; the prose directs every native-tool generation through it; copies between machines and harnesses keep their intent. Comps meanwhile are declared the build thread's own work, never delegated, and the comp-skeleton guidance now asks for the surface's actual regions instead of prescribing navs onto pages that have none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Fable 5
Claude Fable 5
parent
abe722d105
commit
47b875a7e3
@@ -67,7 +67,7 @@ Codex: the imagegen skill's built-in `image_gen` path is the native tool here; p
|
||||
</codex>
|
||||
7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
|
||||
8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
|
||||
9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: when the generation tool does not write a prompt sidecar itself, write `<asset>.json` with the prompt beside each produced asset, because the build thread composes what you made and needs to know what it is looking at.
|
||||
9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: after every generation, run `node {{scripts_path}}/embed-prompt.mjs <asset> --prompt "<the prompt used>"` so the prompt is embedded in the image itself, because the build thread composes what you made and needs to know what it is looking at, and the embedding survives copies where sidecars get lost.
|
||||
10. Compare each output against its source crop, opening every image by its workspace-relative path; sandboxed viewers reject absolute paths. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
|
||||
|
||||
Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
|
||||
|
||||
@@ -6,9 +6,9 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo
|
||||
|
||||
## Generate three compositional options
|
||||
|
||||
Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Open every image you produce or reference by its workspace-relative path, never an absolute one: sandboxed viewers reject absolute paths, and everything under the project root has a relative path. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
|
||||
Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Comps are the build thread's own work, never delegated: the thread that writes the comp prompts holds the direction's full context, and it has already seen every comp when the build starts. Open every image you produce or reference by its workspace-relative path, never an absolute one: sandboxed viewers reject absolute paths, and everything under the project root has a relative path. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
|
||||
|
||||
- A comp is a designed page, not a picture of the subject. State the page's literal skeleton in the generation prompt, navigation bar and its items, headline block and its scale, each section in order, the footer, because a prompt that leads with the world's atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. Self-check every render: if it could hang as a poster, or reads as a photograph or scene with some text on it, it is not a comp; regenerate with the layout scaffold stated more literally.
|
||||
- A comp is a designed surface, not a picture of the subject. Lead the generation prompt with the surface's own structure, whatever regions this design actually has, named in order with their scale relationships; a page with no navigation states that instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with the world's atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. Self-check every render: if it could hang as a poster, or reads as a photograph or scene with some text on it, it is not a comp; regenerate with the layout scaffold stated more literally.
|
||||
- When the user shortlisted multiple concepts, spread the three across them.
|
||||
- When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing.
|
||||
- Show enough beyond the opening moment to prove the concept can govern the whole requested surface.
|
||||
@@ -34,7 +34,7 @@ Treat the comp as a north star, not something to trace, and know what that allow
|
||||
|
||||
## Produce only the assets the build needs
|
||||
|
||||
Generation context is part of the asset: the thread that wrote a prompt knows what the image contains, why, and how it is meant to sit in the layout, and a build composed by a thread without that knowledge places assets it does not understand. So prefer generating build-critical imagery in the build thread when the budget allows, and when a subagent produces assets instead, every asset must carry its prompt (the generation sidecar or the manifest's prompt_used), and the builder reads those prompts before composing a single one of them.
|
||||
Generation context is part of the asset: the thread that wrote a prompt knows what the image contains, why, and how it is meant to sit in the layout, and a build composed by a thread without that knowledge places assets it does not understand. So prefer generating build-critical imagery in the build thread when the budget allows, and when a subagent produces assets instead, every asset must carry its prompt, and the builder reads those prompts before composing a single one of them. The carrier is uniform across harnesses: after generating any image with any tool, native or `generate-image.mjs` (which does it automatically), run `node {{scripts_path}}/embed-prompt.mjs <image> --prompt "<the prompt used>"` so the intent lives inside the file itself and survives copies between machines and harnesses; `--read` recovers it from any impeccable-generated image.
|
||||
|
||||
When clean raster ingredients are required and the harness runs subagents, use the shipped asset producer, `impeccable-asset-producer` (`impeccable_asset_producer` in codex): give it the approved comp, output paths, required dimensions and formats, transparency needs, crop notes, and what must remain semantic code. Otherwise produce the minimum required assets in the current thread by the book: load [degraded/asset-producer.md](degraded/asset-producer.md) and follow it inline, with whatever generation exists, the native tool or generate-image.mjs.
|
||||
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
#!/usr/bin/env node
|
||||
// Embed a generation prompt into an image so the intent travels with the file,
|
||||
// across harnesses and machines. Read it back with --read.
|
||||
//
|
||||
// node embed-prompt.mjs <image> --prompt "the prompt text"
|
||||
// node embed-prompt.mjs <image> --prompt-file prompt.txt
|
||||
// node embed-prompt.mjs <image> --read
|
||||
//
|
||||
// Formats: PNG (tEXt chunk, keyword "impeccable:prompt"), JPEG (COM segment).
|
||||
// WebP and anything else fall back to a `<image>.json` sidecar; --read checks
|
||||
// the sidecar for every format, so the fallback stays recoverable. Embedding
|
||||
// rewrites a few MB at most: latency is milliseconds, generation is minutes.
|
||||
// Caveat worth knowing: image optimizers in build pipelines often strip
|
||||
// metadata from their OUTPUT files; the intent lives on the source asset,
|
||||
// which is the one a builder reads.
|
||||
|
||||
import fs from 'node:fs';
|
||||
import zlib from 'node:zlib';
|
||||
|
||||
const KEYWORD = 'impeccable:prompt';
|
||||
const args = process.argv.slice(2);
|
||||
const file = args.find(a => !a.startsWith('--'));
|
||||
const readMode = args.includes('--read');
|
||||
const argOf = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : null; };
|
||||
|
||||
if (!file || !fs.existsSync(file)) { console.error('embed-prompt: image file required'); process.exit(1); }
|
||||
|
||||
const buf = fs.readFileSync(file);
|
||||
const isPng = buf.length > 8 && buf.readUInt32BE(0) === 0x89504e47;
|
||||
const isJpeg = buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8;
|
||||
|
||||
const crcTable = (() => {
|
||||
const t = new Uint32Array(256);
|
||||
for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0; }
|
||||
return t;
|
||||
})();
|
||||
const crc32 = (data) => { let c = 0xffffffff; for (const b of data) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
|
||||
|
||||
function pngChunk(type, data) {
|
||||
const out = Buffer.alloc(12 + data.length);
|
||||
out.writeUInt32BE(data.length, 0);
|
||||
out.write(type, 4, 'ascii');
|
||||
data.copy(out, 8);
|
||||
out.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, 'ascii'), data])), 8 + data.length);
|
||||
return out;
|
||||
}
|
||||
|
||||
function readPngText(b) {
|
||||
let off = 8;
|
||||
while (off + 12 <= b.length) {
|
||||
const len = b.readUInt32BE(off);
|
||||
const type = b.toString('ascii', off + 4, off + 8);
|
||||
if (type === 'tEXt' || type === 'zTXt') {
|
||||
const data = b.subarray(off + 8, off + 8 + len);
|
||||
const nul = data.indexOf(0);
|
||||
if (nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD) {
|
||||
if (type === 'tEXt') return data.toString('utf8', nul + 1);
|
||||
return zlib.inflateSync(data.subarray(nul + 2)).toString('utf8');
|
||||
}
|
||||
}
|
||||
off += 12 + len;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function readJpegCom(b) {
|
||||
let off = 2;
|
||||
while (off + 4 <= b.length && b[off] === 0xff) {
|
||||
const marker = b[off + 1];
|
||||
if (marker === 0xda) break; // start of scan: no more segments
|
||||
const len = b.readUInt16BE(off + 2);
|
||||
if (marker === 0xfe) {
|
||||
const text = b.toString('utf8', off + 4, off + 2 + len);
|
||||
if (text.startsWith(KEYWORD + '\0')) return text.slice(KEYWORD.length + 1);
|
||||
}
|
||||
off += 2 + len;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
const sidecar = `${file}.json`;
|
||||
if (readMode) {
|
||||
let prompt = null;
|
||||
if (isPng) prompt = readPngText(buf);
|
||||
else if (isJpeg) prompt = readJpegCom(buf);
|
||||
if (prompt == null && fs.existsSync(sidecar)) {
|
||||
try { prompt = JSON.parse(fs.readFileSync(sidecar, 'utf8')).prompt ?? null; } catch { /* fall through */ }
|
||||
}
|
||||
if (prompt == null) { console.error('embed-prompt: no embedded prompt found'); process.exit(2); }
|
||||
console.log(prompt);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const prompt = argOf('--prompt') ?? (argOf('--prompt-file') ? fs.readFileSync(argOf('--prompt-file'), 'utf8') : null);
|
||||
if (!prompt) { console.error('embed-prompt: --prompt or --prompt-file required'); process.exit(1); }
|
||||
|
||||
if (isPng) {
|
||||
// Insert (or replace) our tEXt chunk immediately before IEND.
|
||||
const iend = buf.indexOf(Buffer.from('IEND', 'ascii')) - 4;
|
||||
if (iend < 8) { console.error('embed-prompt: malformed PNG'); process.exit(1); }
|
||||
// Drop any existing chunk with our keyword to keep embedding idempotent.
|
||||
let body = buf.subarray(8, iend);
|
||||
const existing = readPngText(buf);
|
||||
if (existing != null) {
|
||||
const parts = [];
|
||||
let off = 8;
|
||||
while (off + 12 <= buf.length && off < iend + 12) {
|
||||
const len = buf.readUInt32BE(off);
|
||||
const type = buf.toString('ascii', off + 4, off + 8);
|
||||
const chunk = buf.subarray(off, off + 12 + len);
|
||||
const data = buf.subarray(off + 8, off + 8 + len);
|
||||
const nul = data.indexOf(0);
|
||||
const ours = (type === 'tEXt' || type === 'zTXt') && nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD;
|
||||
if (!ours && type !== 'IEND') parts.push(chunk);
|
||||
off += 12 + len;
|
||||
}
|
||||
body = Buffer.concat(parts).subarray(8 * 0); // parts exclude signature
|
||||
fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 8), body, pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), pngChunk('IEND', Buffer.alloc(0))]));
|
||||
} else {
|
||||
fs.writeFileSync(file, Buffer.concat([buf.subarray(0, iend), pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), buf.subarray(iend)]));
|
||||
}
|
||||
console.log(`EMBEDDED: ${file} (png tEXt, ${prompt.length} chars)`);
|
||||
} else if (isJpeg) {
|
||||
const seg = Buffer.from(`${KEYWORD}\0${prompt}`, 'utf8');
|
||||
if (seg.length + 2 > 0xffff) { console.error('embed-prompt: prompt too long for a JPEG segment'); process.exit(1); }
|
||||
const com = Buffer.alloc(4 + seg.length);
|
||||
com[0] = 0xff; com[1] = 0xfe; com.writeUInt16BE(seg.length + 2, 2); seg.copy(com, 4);
|
||||
fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 2), com, buf.subarray(2)]));
|
||||
console.log(`EMBEDDED: ${file} (jpeg COM, ${prompt.length} chars)`);
|
||||
} else {
|
||||
fs.writeFileSync(sidecar, JSON.stringify({ prompt, createdAt: new Date().toISOString() }, null, 2));
|
||||
console.log(`EMBEDDED: ${sidecar} (sidecar fallback for this format)`);
|
||||
}
|
||||
@@ -229,9 +229,12 @@ if (!b64) {
|
||||
process.exit(1);
|
||||
}
|
||||
fs.writeFileSync(out, Buffer.from(b64, 'base64'));
|
||||
// The prompt travels with the asset: any thread that later composes this image
|
||||
// can recover the intent behind it without the generating thread's context.
|
||||
// The prompt travels with the asset: embedded in the file itself (EXIF-class
|
||||
// metadata via embed-prompt.mjs) so intent survives copies across harnesses,
|
||||
// plus a sidecar for anything that indexes rather than opens the image.
|
||||
try {
|
||||
const { spawnSync } = await import('node:child_process');
|
||||
spawnSync(process.execPath, [new URL('./embed-prompt.mjs', import.meta.url).pathname, out, '--prompt', prompt], { stdio: 'ignore' });
|
||||
fs.writeFileSync(`${out}.json`, JSON.stringify({ prompt, createdAt: new Date().toISOString(), tool: 'generate-image.mjs', model: 'gpt-image-2' }, null, 2));
|
||||
} catch { /* sidecar is best-effort */ }
|
||||
console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); prompt sidecar at ${out}.json`);
|
||||
} catch { /* embedding is best-effort */ }
|
||||
console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); prompt embedded + sidecar at ${out}.json`);
|
||||
|
||||
Reference in New Issue
Block a user