@12ui/design 0.2.67 → 0.2.68

package/runtime/codex-conversion/src/project/run.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import sharp from 'sharp';
+import {withRunLock,hash,writeJson,readJson} from '../run-store.mjs';
+import {prepareHome} from '../codex/home.mjs';
+import {pinRuntime} from '../runtime-pin.mjs';
+import {inventory,changedFiles,excluded} from './source.mjs';
+import {projectPrompt} from './prompt.mjs';
+import {invokeProject,completion} from './invoke.mjs';
+async function implementation() {
+ const here=path.dirname(fileURLToPath(import.meta.url));
+ const files=['run.mjs','source.mjs','prompt.mjs','invoke.mjs','../codex/home.mjs','../codex/events.mjs','../run-store.mjs','../run-store-io.mjs','../runtime-pin.mjs'];
+ return hash(JSON.stringify(await Promise.all(files.map(async f=>[f,hash(await fs.readFile(path.join(here,f)))]))));
+}
+async function image(file) {
+ const bytes=await fs.readFile(file), metadata=await sharp(bytes).metadata();
+ if(!['png','jpeg','webp'].includes(metadata.format??'')||!metadata.width||!metadata.height)throw Error('Images must be PNG, JPEG or WebP');
+ return {bytes,width:metadata.width,height:metadata.height,sha256:hash(bytes)};
+}
+export async function prepareProject(options) {
+ for(const key of ['project','target','sourceCapture','instructions','runDir'])if(!path.isAbsolute(options[key]??''))throw Error(`Absolute ${key} required`);
+ const projectDir=await fs.realpath(options.project), runDir=path.join(await fs.realpath(path.dirname(options.runDir)),path.basename(options.runDir));
+ if(runDir===projectDir||runDir.startsWith(projectDir+path.sep)||projectDir.startsWith(runDir+path.sep))throw Error('Run directory must be outside project');
+ const target=await image(options.target), source=await image(options.sourceCapture), instructions=await fs.readFile(options.instructions,'utf8');
+ if(!instructions.trim())throw Error('Explicit project instructions required');
+ const width=options.width??target.width,height=options.height??target.height,timeoutMs=options.timeoutMs??1800000;
+ if(![width,height].every(n=>Number.isSafeInteger(n)&&n>0)||!Number.isSafeInteger(timeoutMs)||timeoutMs<1||timeoutMs>1800000)throw Error('Positive viewport and timeout up to 1800000ms required');
+ const config={schemaVersion:1,projectDir,width,height,timeoutMs,instructions,model:'gpt-6-astra',effort:'low',targetSha256:target.sha256,sourceSha256:source.sha256,implementationSha256:await implementation()};
+ const before=await inventory(projectDir),prompt=projectPrompt(config,runDir);
+ await fs.mkdir(runDir);
+ await pinRuntime(runDir);
+ await fs.writeFile(path.join(runDir,'target.image'),target.bytes,{flag:'wx'});await fs.writeFile(path.join(runDir,'source.image'),source.bytes,{flag:'wx'});
+ await fs.writeFile(path.join(runDir,'prompt.txt'),prompt,{flag:'wx'});
+ await writeJson(path.join(runDir,'before.json'),before);
+ await writeJson(path.join(runDir,'project.json'),{...config,promptSha256:hash(prompt),beforeSha256:hash(JSON.stringify(before)),createdAt:new Date().toISOString(),inventoryExclusions:[...excluded],inventoryNote:'Private names, database/key/log files and symlink targets are not read. Hash inventory is not a backup.'});
+ return {status:'prepared',runDir,projectDir,width,height,dispatched:false};
+}
+async function verify(runDir) {
+ const config=await readJson(path.join(runDir,'project.json'));
+ if(!config)throw Error('Project run not prepared');
+ if(await fs.realpath(config.projectDir)!==config.projectDir)throw Error('Project directory identity changed');
+ if(hash(projectPrompt(config,runDir))!==config.promptSha256)throw Error('Frozen project configuration changed');
+ if(config.implementationSha256!==await implementation())throw Error('Project runtime changed; inspect existing run before using a new run');
+ for(const [name,expected] of [['target.image',config.targetSha256],['source.image',config.sourceSha256],['prompt.txt',config.promptSha256]])if(hash(await fs.readFile(path.join(runDir,name)))!==expected)throw Error(`Frozen ${name} changed`);
+ const before=await readJson(path.join(runDir,'before.json'));
+ if(hash(JSON.stringify(before))!==config.beforeSha256)throw Error('Frozen source inventory changed');
+ return {config,before};
+}
+async function reconcile(runDir,config,before) {
+ const claim=await readJson(path.join(runDir,'dispatch.json'));
+ if(!claim)return {status:'prepared',runDir,projectDir:config.projectDir,dispatched:false};
+ const terminal=await completion(runDir),after=await inventory(config.projectDir);
+ // First observation is immutable evidence; later source edits stay separately visible.
+ let observed=await readJson(path.join(runDir,'after.json'));
+ if(!observed){await writeJson(path.join(runDir,'after.json'),after);observed=after;}
+ const result={schemaVersion:1,...terminal,runDir,projectDir:config.projectDir,dispatched:true,changedFiles:changedFiles(before,observed),changesSinceObservation:changedFiles(observed,after),sourceObservationAt:(await fs.stat(path.join(runDir,'after.json'))).mtime.toISOString(),quality:'Requires independent real-browser and behavior review; CLI completion is not a quality verdict.',assetRequests:'asset-requests.json, if produced; parent execution required',costBasis:'Subscription CLI usage; no inferred dollar cost',reconciledAt:new Date().toISOString()};
+ await writeJson(path.join(runDir,'result.json'),result);return result;
+}
+/** Resume is reconciliation only, including prepared runs. It never invokes Codex. */
+export async function resumeProject({runDir}) {
+ runDir=await fs.realpath(runDir);
+ return withRunLock(runDir,async()=>{const {config,before}=await verify(runDir);return reconcile(runDir,config,before);});
+}
+/** Dependencies are injectable only for deterministic execution/custody tests. */
+export async function applyProject({runDir,authHome,binary='codex'},dependencies={prepareHome,invokeProject}) {
+ runDir=await fs.realpath(runDir);
+ return withRunLock(runDir,async()=>{
+  const {config,before}=await verify(runDir);
+  if(await readJson(path.join(runDir,'dispatch.json')))return reconcile(runDir,config,before);
+  if(JSON.stringify(await inventory(config.projectDir))!==JSON.stringify(before))throw Error('Project source changed since preparation');
+  if(!authHome)throw Error('authHome required for a new application');
+  const prepared=await dependencies.prepareHome({authHome,binary,runDir,reasoning:'low'});
+  try {
+   // Durable dispatch precedes spawning; no automatic redispatch after this point.
+   await writeJson(path.join(runDir,'dispatch.json'),{startedAt:new Date().toISOString(),model:'gpt-6-astra',effort:'low',toolEnabled:true});
+   try {await dependencies.invokeProject({config,runDir,home:prepared.home,binary,prompt:await fs.readFile(path.join(runDir,'prompt.txt'),'utf8')});}
+   catch {await writeJson(path.join(runDir,'invocation-error.json'),{message:'Execution interrupted or failed; source changes retained. Inspect saved execution records before any new inference.'});}
+   return await reconcile(runDir,config,before);
+  }finally{await fs.rm(prepared.home,{recursive:true,force:true});}
+ });
+}
+export async function improveProject(options) {await prepareProject(options);return applyProject(options);}

package/runtime/codex-conversion/src/project/source.mjs

@@ -0,0 +1,21 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {hash} from '../run-store.mjs';
+// Inventory source identities only. Never follow symlinks or read credentials/runtime state.
+export const excluded = new Set(['.git','node_modules','.wrangler','dist','build','.next','.nuxt','.vite','coverage','test-results','playwright-report','.tmp','tmp','logs','.codex','.aws','.ssh','.vercel','.netlify']);
+export function privateName(name) { return name.startsWith('.env') || /(?:^|[._-])(?:secret|secrets|credentials|auth|cookies)(?:[._-]|$)/i.test(name) || /\.(?:pem|key|p12|pfx|sqlite|sqlite3|db|log)$/i.test(name); }
+export async function inventory(root, prefix='') {
+  const result=[];
+  for(const entry of await fs.readdir(path.join(root,prefix),{withFileTypes:true})) {
+    if(excluded.has(entry.name)||privateName(entry.name))continue;
+    const relative=path.join(prefix,entry.name), file=path.join(root,relative);
+    if(entry.isSymbolicLink())result.push({path:relative,symlink:await fs.readlink(file)});
+    else if(entry.isDirectory())result.push(...await inventory(root,relative));
+    else if(entry.isFile())result.push({path:relative,sha256:hash(await fs.readFile(file))});
+  }
+  return result.sort((a,b)=>a.path.localeCompare(b.path));
+}
+export function changedFiles(before,after) {
+  const old=new Map(before.map(f=>[f.path,JSON.stringify(f)])), next=new Map(after.map(f=>[f.path,JSON.stringify(f)]));
+  return [...new Set([...old.keys(),...next.keys()])].filter(p=>old.get(p)!==next.get(p)).sort().map(p=>({path:p,before:before.find(f=>f.path===p)??null,after:after.find(f=>f.path===p)??null}));
+}

package/runtime/codex-conversion/src/references.mjs

@@ -0,0 +1,114 @@
+import {parse} from 'parse5';
+import * as css from 'css-tree';
+import {createHash} from 'node:crypto';
+
+/** Inspect parsed syntax, patch reference and interactive editability spans in the original bytes. */
+export function bindHtml(html, assets, {supplementalNames=[]} = {}) {
+ if (typeof html !== 'string') throw Error('Expected HTML string');
+ const document = parse(html, {sourceCodeLocationInfo:true});
+ const seen = new Set(), recoveries = [], supplemental = [], externalDependencies = [], edits = [];
+ let hasHtml = false, hasBody = false;
+ const replace = (start,end,value) => edits.push({start,end,value});
+ function reference(value, kind) {
+  const asset = assets.find(a => [a.id, `asset:${a.id}`, `${a.id}.png`].includes(value));
+  if (asset) {
+   seen.add(asset.id);
+   const target = `${asset.id}.png`;
+   if (value !== target) recoveries.push({from:value,to:target,kind:value.startsWith('asset:')?'standard':'exact-declared-ID'});
+   return target;
+  }
+  if (value.startsWith('#') || supplementalNames.includes(value)) return value;
+  if (kind === 'font' && /^https:\/\/fonts\.(?:googleapis|gstatic)\.com\//i.test(value)) {
+   externalDependencies.push({url:value,kind:'font',bundled:false}); return value;
+  }
+  if (value.startsWith('data:image/svg+xml,')) {
+   const bytes = Buffer.from(decodeURIComponent(value.slice('data:image/svg+xml,'.length)));
+   const name = `inline-${createHash('sha256').update(bytes).digest('hex').slice(0,16)}.svg`;
+   // Inline SVG is artwork, not a route around the no-script/no-external-resource contract.
+   if (/<(?:script|foreignObject|iframe)\b|\bon\w+\s*=|(?:href\s*=\s*["']?\s*(?!#)|url\(\s*["']?\s*(?!#))/i.test(bytes.toString())) throw Error('Unsupported SVG dependency');
+   if (!supplemental.some(a=>a.name===name)) supplemental.push({name,bytes,sourceUri:value});
+   return name;
+  }
+  throw Error(`Unbound or prohibited ${kind} reference: ${value}`);
+ }
+ function style(text, offset, context='stylesheet') {
+  let ast;
+  try { ast=css.parse(text,{context,positions:true,parseCustomProperty:true}); } catch { throw Error('Invalid CSS'); }
+  /** @type {import("css-tree").EnterOrLeaveFn} */
+  const enter = function(node) {
+   if (node.type === 'Raw') throw Error('Unsupported CSS syntax');
+   if (node.type === 'Atrule' && node.name.toLowerCase() === 'import') {
+    css.walk(node.prelude, child => {
+     if (child.type === 'String') reference(child.value,'font');
+    });
+   }
+   if (node.type !== 'Url') return;
+   let parent = this.atrule;
+   const kind = parent && ['font-face','import'].includes(parent.name.toLowerCase()) ? 'font' : 'artwork';
+   const value = reference(node.value,kind);
+   if (value !== node.value) {
+    const raw = text.slice(node.loc.start.offset,node.loc.end.offset);
+    const start = raw.indexOf('(')+1, end=raw.lastIndexOf(')');
+    const inside=raw.slice(start,end), match=inside.match(/^(\s*)(["']?)([\s\S]*?)\2(\s*)$/);
+    replace(offset+node.loc.start.offset+start+match[1].length+match[2].length,offset+node.loc.start.offset+end-match[4].length-match[2].length,value);
+   }
+  };
+  css.walk(ast, {enter});
+ }
+ function walk(node, inheritedEditable=false) {
+  if (node.tagName === 'html' && node.sourceCodeLocation) hasHtml=true;
+  if (node.tagName === 'body' && node.sourceCodeLocation) hasBody=true;
+  if (['script','iframe','canvas','object','embed','base'].includes(node.tagName)) throw Error(`Prohibited element ${node.tagName}`);
+  const attrs = node.attrs ?? [];
+  const ownEditable = attrs.find(a => a.name === 'contenteditable')?.value.toLowerCase();
+  let editable = ownEditable === 'false' ? false : ['', 'true', 'plaintext-only'].includes(ownEditable) ? true : inheritedEditable;
+  // Editable anchor hosts suppress the browser's native navigation. Keep labels
+  // and other inline markup intact; explicit editable descendants remain editable.
+  if (node.tagName === 'a' && attrs.some(a => a.name === 'href') && editable) {
+   const loc = node.sourceCodeLocation?.attrs?.contenteditable;
+   if (loc) replace(loc.startOffset, loc.endOffset, 'contenteditable="false"');
+   else {
+    const start = node.sourceCodeLocation.startTag.endOffset - 1;
+    replace(start, start, ' contenteditable="false"');
+   }
+   recoveries.push({kind:'interactive-editability', from:ownEditable ?? 'inherited', to:'false'});
+   editable = false;
+  }
+  if (node.tagName === 'meta' && attrs.some(a => a.name === 'http-equiv' && a.value.trim().toLowerCase() === 'refresh')) throw Error('Prohibited active HTML refresh');
+  for (const attr of attrs) {
+   const key = attr.prefix ? `${attr.prefix}:${attr.name}` : attr.name;
+   if (/^on/i.test(key) || key === 'srcdoc' || /^(?:javascript|vbscript):/i.test(attr.value.replace(/[\t\n\r]/g, '').replace(/^[\u0000-\u0020]+/, ''))) throw Error('Prohibited active HTML');
+   const loc = node.sourceCodeLocation?.attrs?.[key];
+   if (!loc) continue;
+   const raw=html.slice(loc.startOffset,loc.endOffset), m=raw.match(/^[^=]+=(\s*)(["']?)/);
+   const start=loc.startOffset+(m?.[0].length ?? raw.length), end=loc.endOffset-(m?.[2] ? 1:0);
+   if (key === 'style') { style(html.slice(start,end),start,'declarationList'); continue; }
+   if (key === 'srcset') throw Error('Unsupported raster srcset; use declared asset references');
+   const href = ['href','xlink:href'].includes(key);
+   const font = node.tagName === 'link' && attrs.some(a=>a.name==='rel' && a.value.toLowerCase()==='stylesheet');
+   const resource = ['src','poster','background'].includes(key) || href && (font || ['image','use','link'].includes(node.tagName));
+   if (!resource) continue;
+   const value=reference(attr.value,font?'font':'artwork');
+   if (value !== attr.value) replace(start,end,value);
+  }
+  if (node.tagName === 'style') for (const child of node.childNodes ?? []) if (child.nodeName==='#text') style(child.value,child.sourceCodeLocation.startOffset);
+  for (const child of node.childNodes ?? []) walk(child, editable);
+  if (node.content) walk(node.content, editable);
+ }
+ walk(document);
+ if (!hasHtml || !hasBody) throw Error('Invalid complete HTML document');
+ for (const a of assets) if (!seen.has(a.id)) throw Error(`Omitted artwork ${a.id}`);
+ for (const edit of edits.sort((a,b)=>b.start-a.start)) html=html.slice(0,edit.start)+edit.value+html.slice(edit.end);
+ return {html,supplemental,recoveries,externalDependencies};
+}
+export const validateBind = bindHtml;
+
+/** Keep the saved document available to bounded repair when a fact is unresolved. */
+export function normalizeHtml(html, assets, options) {
+ try { return {ok:true,...bindHtml(html,assets,options),issues:[]}; }
+ catch(error) {
+  const message=String(error.message ?? error);
+  const syntax=/CSS|SVG/.test(message);
+  return {ok:false,html,supplemental:[],recoveries:[],externalDependencies:[],issues:[{code:syntax?'unresolved-document-syntax':'unresolved-document-reference',message,repairable:true,requiresModel:true,instruction:syntax?'Preserve the intended appearance and all content. Express the reported syntax in supported HTML/CSS/SVG; parser rejection alone is not evidence the design is invalid.':'Preserve every declared owner. Correct the reported reference or incomplete HTML structure using exact declared IDs; do not omit artwork or introduce fallback images.'}]};
+ }
+}

package/runtime/codex-conversion/src/run-store-io.mjs

@@ -0,0 +1,38 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, rename, readFile, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** @param {string | Uint8Array} bytes */
+export const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** @param {string} path */
+export async function syncDirectory(path) {
+  const handle = await open(path, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+/** @param {string} path @param {string | Uint8Array} bytes */
+export async function writeBytes(path, bytes) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); }
+  finally { await handle.close(); }
+  try { await rename(temporary, path); await syncDirectory(dirname(path)); }
+  finally { await unlink(temporary).catch(() => {}); }
+}
+/** @param {string} path @param {unknown} value */
+export async function writeJson(path, value) { await writeBytes(path, `${JSON.stringify(value, null, 2)}\n`); }
+/** @param {string} path @returns {Promise<any>} */
+export async function readJson(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); }
+  catch (error) { if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return null; throw error; }
+}
+/** Strict canonical JSON prevents identity collisions from unsupported values. @param {unknown} value @returns {string} */
+export function canonical(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    const record = /** @type {Record<string, unknown>} */ (value);
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+  }
+  throw new Error('Request identity requires plain JSON values');
+}

package/runtime/codex-conversion/src/run-store.mjs

@@ -0,0 +1,114 @@
+import { mkdir, readFile, unlink, open } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonical, hash, readJson, writeJson, writeBytes, syncDirectory } from './run-store-io.mjs';
+export { hash, readJson, writeJson } from './run-store-io.mjs';
+/** @typedef {{bytes: Buffer, metadata?: any}} Response */
+/** @param {string} message @param {string} code */
+function failure(message, code) { return Object.assign(new Error(message), { code }); }
+/** @param {string} runDir */
+export function createStore(runDir) {
+  const active = new Set();
+  return {
+    /** @param {string} id @param {unknown} request
+     * @param {(context: {persistMetadata: (metadata: any) => Promise<void>, callDir: string}) => Promise<Response>} callback
+     * @param {{prepare?: (context: {callDir: string}) => Promise<void>, recover?: (context: {callDir: string, metadata: any}) => Promise<Response | null>}} options */
+    async runCall(id, request, callback, options = {}) {
+      if (active.has(id)) throw failure(`Call ${id} is already active`, 'CALL_LOCKED');
+      active.add(id);
+      try {
+        const callDir = join(runDir, 'calls', hash(id));
+        await mkdir(callDir, { recursive: true });
+        await syncDirectory(dirname(runDir));
+        await syncDirectory(runDir);
+        await syncDirectory(join(runDir, 'calls'));
+        const statePath = join(callDir, 'state.json');
+        const requestHash = hash(canonical(request));
+        let state = await readJson(statePath);
+        if (state && (state.requestHash !== requestHash || state.id !== id)) throw failure(`Request changed for ${id}`, 'REQUEST_CHANGED');
+        if (!state) {
+          state = { id, requestHash, status: 'prepared', metadata: null };
+          await writeJson(join(callDir, 'request.json'), request);
+          await writeJson(statePath, state);
+        }
+        /** @param {Response} response @param {boolean} reused */
+        const receive = async (response, reused) => {
+          if (!Buffer.isBuffer(response.bytes)) throw new Error('Call response bytes must be a Buffer');
+          const metadata = response.metadata ?? state.metadata;
+          // Custody commits expected bytes first; raw publication is atomic and synced.
+          await writeJson(join(callDir, 'custody.json'), { requestHash, responseHash: hash(response.bytes), length: response.bytes.length, metadata });
+          await writeBytes(join(callDir, 'response.bin'), response.bytes);
+          state = { ...state, status: 'received', metadata, responseHash: hash(response.bytes) };
+          await writeJson(statePath, state);
+          return { bytes: response.bytes, metadata, reused };
+        };
+        if (state.status !== 'prepared') {
+          const custody = await readJson(join(callDir, 'custody.json'));
+          let bytes = null;
+          try { bytes = await readFile(join(callDir, 'response.bin')); }
+          catch (error) { if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error; }
+          if (bytes && custody?.requestHash === requestHash && custody.length === bytes.length && custody.responseHash === hash(bytes)) {
+            state = { ...state, status: 'received', metadata: custody.metadata, responseHash: custody.responseHash };
+            await writeJson(statePath, state);
+            return { bytes, metadata: custody.metadata, reused: true };
+          }
+          if (state.status === 'dispatched' && options.recover) {
+            const recovered = await options.recover({ callDir, metadata: state.metadata });
+            if (recovered) return await receive(recovered, true);
+          }
+          throw failure(`Call ${id} needs reconciliation; it will not be dispatched again`, 'NEEDS_RECONCILIATION');
+        }
+        await options.prepare?.({ callDir });
+        state.status = 'dispatched';
+        await writeJson(statePath, state);
+        try {
+          const response = await callback({ callDir, persistMetadata: async metadata => {
+            state = { ...state, metadata };
+            await writeJson(statePath, state);
+          } });
+          return await receive(response, false);
+        } catch (cause) {
+          // Provider errors can contain credentials or response bodies: retain the
+          // cause for programmatic inspection without copying it into the message.
+          throw Object.assign(failure(`Call ${id} failed after dispatch and needs reconciliation`, 'NEEDS_RECONCILIATION'), { cause });
+        }
+      } finally { active.delete(id); }
+    },
+  };
+}
+/** @template T @param {string} runDir @param {() => Promise<T>} callback @returns {Promise<T>} */
+export async function withRunLock(runDir, callback) {
+  await mkdir(runDir, { recursive: true });
+  const path = join(runDir, 'run.lock');
+  const token = randomUUID();
+  const owner = { pid: process.pid, hostname: hostname(), token };
+  const acquire = async () => {
+    const handle = await open(path, 'wx', 0o600);
+    try { await handle.writeFile(JSON.stringify(owner)); await handle.sync(); } finally { await handle.close(); }
+    await syncDirectory(runDir);
+  };
+  try { await acquire(); }
+  catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') throw error;
+    // A separate exclusive reclaim marker prevents competing stale-lock removals.
+    const guardPath = join(runDir, 'run.lock.reclaim');
+    let guard;
+    try { guard = await open(guardPath, 'wx', 0o600); }
+    catch { throw failure('Run is locked', 'RUN_LOCKED'); }
+    try {
+      let previous;
+      try { previous = await readJson(path); } catch { throw failure('Run lock is unreadable', 'RUN_LOCKED'); }
+      if (previous?.hostname !== hostname() || !Number.isInteger(previous.pid) || previous.pid <= 0) throw failure('Run is locked', 'RUN_LOCKED');
+      try { process.kill(previous.pid, 0); throw failure('Run is locked', 'RUN_LOCKED'); }
+      catch (probe) { if (/** @type {NodeJS.ErrnoException} */ (probe).code !== 'ESRCH') throw failure('Run is locked', 'RUN_LOCKED'); }
+      await unlink(path);
+      try { await acquire(); } catch { throw failure('Run is locked', 'RUN_LOCKED'); }
+    } finally { await guard.close(); await unlink(guardPath); }
+  }
+  try { return await callback(); }
+  finally {
+    const current = await readJson(path);
+    if (current?.token === token) { await unlink(path); await syncDirectory(runDir); }
+  }
+}

package/runtime/codex-conversion/src/run.mjs

@@ -0,0 +1,108 @@
+import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+import { createStore, withRunLock, hash, writeJson, readJson } from './run-store.mjs';
+import { buildInitialPrompt, initialSchema } from './contracts/initial.mjs';
+import { resolveContract } from './contract-repair.mjs';
+import { executeImages } from './images/execute.mjs';
+import { invokeCodex, recoverCodex } from './codex/invoke.mjs';
+import { prepareHome } from './codex/home.mjs';
+import { publishOutput } from './output.mjs';
+import { pinRuntime } from './runtime-pin.mjs';
+
+/** @typedef {{source?:string,runDir:string,authHome?:string,binary?:string,timeoutMs?:number,reasoning?:string,cleanAssets?:string,imageBackend?:string,env?:NodeJS.ProcessEnv,progress?:(message:string)=>void}} Options */
+
+async function implementationHash() {
+  const root = path.dirname(fileURLToPath(import.meta.url));
+  /** @param {string} dir @returns {Promise<string[]>} */
+  async function visit(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const all = await Promise.all(entries.map(entry => entry.isDirectory() ? visit(path.join(dir, entry.name)) : [path.join(dir, entry.name)]));
+    return all.flat();
+  }
+  const files = (await visit(root)).sort();
+  files.push(path.join(root, '../package.json'));
+  return hash(JSON.stringify(await Promise.all(files.map(async file => [path.relative(root, file), hash(await readFile(file))]))));
+}
+
+/** Initialize immutable source and configuration without dispatching. @param {Options} options */
+async function initialize(options) {
+  if (!options.source) throw new Error('convert requires source');
+  const bytes = await readFile(options.source); const metadata = await sharp(bytes).metadata();
+  if (!['png', 'jpeg', 'webp'].includes(metadata.format ?? '') || !metadata.width || !metadata.height) throw new Error('Source must be PNG, JPEG, or WebP');
+  const timeoutMs = options.timeoutMs ?? 1800000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1800000) throw new Error('timeoutMs must be 1–1800000');
+  const source = { path: 'source.image', sha256: hash(bytes), width: metadata.width, height: metadata.height, mimeType: `image/${metadata.format}` };
+  const effort = options.reasoning ?? 'low';
+  if (!['low', 'medium'].includes(effort)) throw new Error('reasoning must be low or medium');
+  const imageBackend = options.imageBackend ?? 'external';
+  if (!['external', 'native'].includes(imageBackend)) throw new Error('imageBackend must be external or native');
+  const cleanAssets=options.cleanAssets??'enhance';
+  if(!['crop','enhance'].includes(cleanAssets))throw Error('cleanAssets must be crop or enhance');
+  const config = { cleanAssets, imageBackend, model: 'gpt-6-astra', effort, timeoutMs, imageEndpoint: options.env?.CODEX_CONVERSION_IMAGE_ENDPOINT ?? process.env.CODEX_CONVERSION_IMAGE_ENDPOINT ?? 'https://api.openai.com/v1/images/edits' };
+  const endpoint = new URL(config.imageEndpoint);
+  if (endpoint.username || endpoint.password || endpoint.search || !['https:', 'http:'].includes(endpoint.protocol)) throw new Error('Image endpoint must be an HTTP(S) URL without credentials or query parameters');
+  const identity = { schemaVersion: 1, source, config, implementationSha256: await implementationHash(), promptSha256: hash(buildInitialPrompt(source,config.cleanAssets)), schemaSha256: hash(JSON.stringify(initialSchema)) };
+  // Exclusive directory creation prevents overwriting any previous namespace.
+  await mkdir(options.runDir);
+  await pinRuntime(options.runDir);
+  await writeFile(path.join(options.runDir, source.path), bytes, { flag: 'wx' });
+  await writeJson(path.join(options.runDir, 'run.json'), { ...identity, createdAt: new Date().toISOString() });
+}
+
+/** @param {Options} options */
+export async function convert(options) {
+  const runDir = path.resolve(options.runDir);
+  await initialize({ ...options, runDir });
+  return resume({ ...options, runDir });
+}
+
+/** Resume never repeats a paid dispatch whose outcome is unknown. @param {Options} options */
+export async function resume(options) {
+  const runDir = path.resolve(options.runDir); const progress = options.progress ?? (() => {});
+  const resumedAt = Date.now();
+  return withRunLock(runDir, async () => {
+    try {
+      const identity = await readJson(path.join(runDir, 'run.json'));
+      if (identity.implementationSha256 !== await implementationHash()) throw new Error('Implementation changed; use a new run directory');
+      const sourcePath = path.join(runDir, identity.source.path);
+      if (hash(await readFile(sourcePath)) !== identity.source.sha256) throw new Error('Immutable source changed');
+      if (hash(buildInitialPrompt(identity.source,identity.config.cleanAssets)) !== identity.promptSha256 || hash(JSON.stringify(initialSchema)) !== identity.schemaSha256) throw new Error('Immutable planner configuration changed');
+      if (options.source && hash(await readFile(options.source)) !== identity.source.sha256) throw new Error('Source differs from immutable run input');
+      if (options.timeoutMs && options.timeoutMs !== identity.config.timeoutMs) throw new Error('Timeout differs from immutable run configuration');
+      if (options.reasoning !== undefined && options.reasoning !== identity.config.effort) throw new Error('Reasoning differs from immutable run configuration');
+      if(options.cleanAssets!==undefined && options.cleanAssets!==identity.config.cleanAssets)throw Error('Clean asset preference differs from immutable run configuration');
+      if (options.imageBackend !== undefined && options.imageBackend !== (identity.config.imageBackend ?? 'external')) throw new Error('Image backend differs from immutable run configuration');
+      const env = { ...(options.env ?? process.env) };
+      if (env.CODEX_CONVERSION_IMAGE_ENDPOINT && env.CODEX_CONVERSION_IMAGE_ENDPOINT !== identity.config.imageEndpoint) throw new Error('Image endpoint differs from immutable run configuration');
+      env.CODEX_CONVERSION_IMAGE_ENDPOINT = identity.config.imageEndpoint;
+      const store = createStore(runDir);
+      progress('Resolving planner response');
+      const prompt = buildInitialPrompt(identity.source,identity.config.cleanAssets);
+      let preparedHome;
+      const planner = await store.runCall('planner', { source: identity.source.sha256, prompt: identity.promptSha256, schema: identity.schemaSha256, model: identity.config.model, effort: identity.config.effort }, async ({ callDir }) => {
+        if (!options.authHome) throw new Error('authHome is required for a new planner call');
+        const schemaPath = path.join(callDir, 'schema.json'); await writeJson(schemaPath, initialSchema);
+        await writeFile(path.join(callDir, 'prompt.txt'), prompt);
+        return invokeCodex({ callDir, runDir, authHome: path.resolve(options.authHome), binary: options.binary, sourcePath, schemaPath, prompt, timeoutMs: identity.config.timeoutMs, reasoning: identity.config.effort, preparedHome });
+      }, { recover: recoverCodex, prepare: async () => {
+        if (!options.authHome) throw new Error('authHome is required for a new planner call');
+        preparedHome = (await prepareHome({ authHome: path.resolve(options.authHome), binary: options.binary ?? 'codex', runDir, reasoning: identity.config.effort })).home;
+      } });
+      const contract = await resolveContract({planner,source:identity.source,sourcePath,runDir,store,authHome:options.authHome?path.resolve(options.authHome):undefined,binary:options.binary,timeoutMs:identity.config.timeoutMs});
+      if(!contract.ok){const result={schemaVersion:1,status:'failed',error:{message:'Contract remains unusable after one bounded repair',issues:contract.issues},receipts:'calls/',usage:{codex:planner.metadata,contractRepair:contract.repair?.metadata}};await writeJson(path.join(runDir,'result.json'),result);return result;}
+      const {plan,normalized}=contract;
+      await writeJson(path.join(runDir, 'plan.json'), plan);
+      await writeJson(path.join(runDir, 'normalization.json'), { recoveries: contract.recoveries, externalDependencies: normalized.externalDependencies });
+      progress(`Resolving ${plan.groups.length} ${identity.config.imageBackend ?? 'external'} image groups`);
+      const images = await executeImages({ plan, sourcePath, runDir, store, env, imageBackend: identity.config.imageBackend ?? 'external', codexBinary: options.binary, codexHome: options.authHome, nativeModel: 'gpt-6-astra', timeoutMs: identity.config.timeoutMs, progress: event => progress(JSON.stringify(event)) });
+      const output = await publishOutput({ runDir, normalized, assets: images.assets, source: identity.source, plan });
+      const result = { schemaVersion: 1, status: 'complete', output, receipts: 'calls/', uncertainties: plan.uncertainties, timing: { createdAt: identity.createdAt, completedAt: new Date().toISOString(), elapsedSinceCreationMs: Date.now() - Date.parse(identity.createdAt), thisResumeMs: Date.now() - resumedAt }, usage: { codex: planner.metadata, contractRepair:contract.repair?.metadata??null, externalImages: images.usage } };
+      try{await writeJson(path.join(runDir, 'result.json'), result);}catch(error){return {...result,diagnostics:[{code:'result-journal-failed',message:'Valid published artifact retained; result receipt could not be saved'}]};}return result;
+    } catch (error) {
+      const result = { schemaVersion: 1, status: error.code === 'NEEDS_RECONCILIATION' ? 'needs-reconciliation' : 'failed', error: { message: error.message }, receipts: 'calls/' };
+      await writeJson(path.join(runDir, 'result.json'), result); return result;
+    }
+  });
+}

package/runtime/codex-conversion/src/runtime-pin.mjs

@@ -0,0 +1,12 @@
+import {open} from 'node:fs/promises';
+import path from 'node:path';
+import {syncDirectory} from './run-store-io.mjs';
+/** Pin the bootstrap's immutable cached payload before any model dispatch. */
+export async function pinRuntime(runDir,env=process.env) {
+ const key=env.TWELVE_UI_CODEX_RUNTIME_KEY;
+ if(key===undefined)return;
+ if(!/^[a-f0-9]{64}$/.test(key))throw Error('Invalid bootstrap runtime key');
+ const handle=await open(path.join(runDir,'.12ui-runtime.json'),'wx',0o600);
+ try{await handle.writeFile(JSON.stringify({schemaVersion:1,key})+'\n');await handle.sync();}finally{await handle.close();}
+ await syncDirectory(runDir);
+}

package/runtime/codex-conversion/templates/initial.schema.json

@@ -0,0 +1,90 @@
+{
+  "type": "object",
+  "properties": {
+    "html": {
+      "type": "string"
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "source_bbox_px": {
+            "type": "array",
+            "items": {
+              "type": "integer"
+            }
+          },
+          "background": {
+            "type": "string",
+            "enum": [
+              "opaque",
+              "transparent"
+            ]
+          },
+          "request_group": {
+            "type": "string"
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "preserve-source",
+              "remove-named-overlays",
+              "crop-source"
+            ]
+          },
+          "desired_owner": {
+            "type": "string"
+          },
+          "named_removals": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "source_bbox_px": {
+                  "type": "array",
+                  "items": {
+                    "type": "integer"
+                  }
+                },
+                "text_or_element": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "source_bbox_px",
+                "text_or_element"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "source_bbox_px",
+          "background",
+          "request_group",
+          "operation",
+          "desired_owner",
+          "named_removals"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "uncertainties": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "html",
+    "assets",
+    "uncertainties"
+  ],
+  "additionalProperties": false
+}

package/runtime/codex-conversion/templates/initial.txt

@@ -0,0 +1,22 @@
+This is a schema-only response task. Inspect the attached source image directly. Do not call any tool, run commands, read files, browse, generate images, or delegate. Return the requested JSON as your final response. Asset operations are performed outside this CLI invocation by the experiment executor.
+
+Reconstruct this source screenshot in ONE response as complete semantic responsive HTML/CSS/SVG plus source-registered artwork declarations. Return only JSON {html,assets,uncertainties}. There is no separate planner or later code-model pass. The executor will execute declared artwork operations in parallel, deliver each exact source owner, and substitute asset:ID references into your HTML. Complete this first pass without relying on any later repair.
+
+The original source is the sole authority for visible words/data, typography, placement, geometry, material ownership and controls. Include only confidently readable exact source text/data. Do not invent plausible footer labels, microcopy, dates, chart values or continuation beyond screenshot edges. Record ambiguity in uncertainties. Noninteractive text must be meaningful editable DOM with contenteditable=true, including readable depicted interface labels when separated from a photograph. Navigational anchors with href must remain contenteditable=false, including inside editable containers, so normal clicks navigate. Preserve inline label markup; an editable child span may hold the label when needed. Reconstructible chart/icon geometry remains SVG/CSS; no hidden UI in a convenient full-page raster. Do not invent a working backend.
+
+Use ONE source-coordinate definition for each asset: id, source_bbox_px:[left,top,width,height] in original source integer pixels, background opaque/transparent, request_group, operation, desired_owner, named_removals. The bbox is the exact source-owned artwork including edge material/shadow it owns. Do not declare separate output widths/heights or imagined aspect ratios. Asset native display size/position in your HTML uses this original source frame; executor's2x pixel density is not CSS viewport width. Each asset must appear in HTML using its exact asset:ID in img or CSS url.
+
+Declare0–12 actual source-owned art responsibilities, never a quota. Keep irreducible photographs, illustration and distinctive material appearance in art. CSS owns panel geometry, clipping, edges/shadows, text and simple UI. Preserve meaningful subtle material such as paper texture with an intrinsic fill rather than flattening it to a bare rectangle. Reuse only visibly shared material through explicitly intentional owner clipping; do not consolidate unrelated UI into a sheet. A coherent photograph stays coherent. The model declares the desired intrinsic owner and actual named overlays to remove, using exact original-source boxes. Intrinsic scene writing is preserved unless explicitly assigned to editable DOM; never paint a label in both owners.
+
+For AI image operations (preserve-source and remove-named-overlays), the image executor will expand a narrow/short asset bbox using the minimum legal rectangle of ORIGINAL neighboring source pixels, ask for the entire context at exact2x, then crop exactly the declared owner coordinates. No padding, stretching, localization or recentering. Your code must therefore reserve the exact native frame now; do not expect generic square/landscape outputs or adjust layout later. Group a depicted-text overlay with its photo owner so moving that group preserves registration. Artwork bytes are not yet attached: use faithful source frames as the contract, not an invented composition.
+
+At native source width retain source layout/typographic metrics and z-order. At390px use sensible normal-flow grid/flex reflow retaining every meaningful navigation/control/text/art owner. Native details/summary or keyboard-accessible scroll groups are allowed; no hidden sidebar content, scaled fixed canvas, oversized blank strips or fixed-height remnants. Headings and body text must wrap naturally. Do not use nowrap, fixed heights or mandatory manual linebreaks for heading fit. Preserve spaces between spans. A longer replacement heading/value must reflow within the page without overflow/collision/ghosttext. Keep shrinking grid/flex minimums and appropriate overflow-wrap.
+
+Keep complete visible bar series, curves, legend labels and map silhouette; approximate unreadable underlying data only with declared uncertainty, never delete visible marks. Apply fill/stroke on actual SVG geometry. Use reusable concise CSS/SVG, valid complete HTML document with inline CSS, system or Google Fonts CSS only. No external raster images, scripts, external JS, canvas, iframe or base64. All substantive styling/content comes from source evidence, not a new design.
+
+Each asset has request_group: a shared identifier only for disjoint owners with compatible ground/edit instructions that should share one original-source context image. Their positions are never rearranged. Nearby material thumbnails may share a request and remain separate delivered assets. Otherwise use the asset id. For AI image operations, the executor validates non-overlap and common background, computes a legal source-contained context around the union, and crops each declared owner at exact2x coordinates.
+
+Preserve source-visible navigation at native width. If you introduce a narrow-screen disclosure, its initial state and CSS must leave the source navigation visible and operable at desktop width as well. A hidden summary around a closed details element does not expose its contents. Check both initial desktop and narrow states in the HTML/CSS you return. Every source control must remain reachable by keyboard; do not depend on scripts or a later finalize pass.
+
+Each asset explicitly chooses operation. Use preserve-source when its delivered rectangle already contains only the desired intrinsic material/artwork, without any page text/control to remove. Its named_removals must be empty. The executor then uses only the tested whole-context source-preserving upscale prompt, leaving ALL neighboring words/captions and gaps intact outside the delivered owner. Do not demand reconstruction, new framing, or exclusion of neighboring content for clean owners.
+Use remove-named-overlays only when editable page overlays actually intersect the owner. desired_owner is a compact positive description of the underlying material/artwork to retain. named_removals lists each actual source text/control/overlap with source_bbox_px and text_or_element. Every removal must intersect this asset; only that intersection is edited. Preserve intrinsic scene detail/writing unless specifically assigned to independent DOM. Never ask to remove an overlay that the HTML does not recreate once. Group only disjoint owners with identical operation and background; compatible clean material thumbnails may share original context, never repack them. The executor rejects unsupported geometry or request counts before any image dispatch.