@12ui/design 0.2.67 → 0.2.68

package/runtime/codex-conversion/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@12ui/codex-conversion",
+  "version": "0.1.0",
+  "description": "Portable Codex HTML conversion with durable external image execution",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "12ui-convert": "bin/convert.mjs",
+    "12ui-convert-export": "bin/export.mjs",
+    "12ui-convert-finish": "bin/finish.mjs",
+    "12ui-improve": "bin/improve.mjs"
+  },
+  "exports": {
+    ".": "./src/run.mjs",
+    "./project": "./src/project/run.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "skill",
+    "npm-shrinkwrap.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc --allowJs --checkJs --noEmit --module nodenext --target es2022 --skipLibCheck src/*.mjs src/codex/*.mjs src/images/*.mjs src/contracts/*.mjs src/exports/*.mjs src/finish/*.mjs src/project/*.mjs bin/*.mjs"
+  },
+  "dependencies": {
+    "sharp": "0.34.5",
+    "parse5": "7.3.0",
+    "css-tree": "3.1.0",
+    "esbuild": "0.27.7",
+    "playwright": "1.55.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.0",
+    "@types/css-tree": "2.3.10",
+    "typescript": "5.8.3"
+  }
+}

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

@@ -0,0 +1,14 @@
+export const disabledFeatures = ['shell_tool', 'view_image', 'image_generation', 'multi_agent', 'apps', 'plugins', 'browser_use', 'computer_use'];
+
+/** Preserved A invocation treatment. @param {{workDir:string, finalPath:string, sourcePath?:string, imagePaths?:string[], schemaPath:string,reasoning?:string}} spec */
+export function buildArgv(spec) {
+  const args = ['-a', 'never', 'exec', '--ignore-user-config', '--ignore-rules', '--strict-config', '-C', spec.workDir,
+    '--skip-git-repo-check', '-s', 'danger-full-access', '-m', 'gpt-6-astra',
+    '-c', `model_reasoning_effort="${spec.reasoning ?? 'low'}"`, '-c', 'model_provider="openai"',
+    '-c', 'forced_login_method="chatgpt"', '-c', 'project_doc_max_bytes=0',
+    '--enable', 'skip_host_skill_discovery', '--json', '--color', 'never', '--output-last-message', spec.finalPath];
+  for (const feature of disabledFeatures) args.push('--disable', feature);
+  for (const image of spec.imagePaths ?? [spec.sourcePath]) { if (image) args.push('--image', image); }
+  args.push('--output-schema', spec.schemaPath, '-');
+  return args;
+}

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

@@ -0,0 +1,14 @@
+import { hash } from '../run-store.mjs';
+
+/** Terminal lifecycle facts decide success; generic errors remain diagnostics. @param {any} execution @param {Buffer} bytes */
+export function validateCompletion(execution, bytes) {
+  if (execution.exitCode !== 0 || execution.exitSignal || execution.timedOut || execution.interrupted || execution.spawnError) throw new Error('Planner execution did not complete; reconciliation required');
+  const { events, audit } = execution;
+  const effort = execution.expectedEffort ?? 'low';
+  if (!['low', 'medium'].includes(effort)) throw new Error('Unsupported expected planner effort');
+  if (!events || execution.eventReadError || events.malformedJsonlLines.length || events.failed.length || events.errorsAfterCompletion.length || events.tools.length || events.usage.length !== 1) throw new Error('Planner no-tool completion protocol violated');
+  if (!audit || execution.auditReadError || audit.tools.length || !audit.contexts.length || audit.contexts.some(context => context.model !== 'gpt-6-astra' || context.effort !== effort)) throw new Error(`Observed planner model/effort does not prove Astra ${effort}`);
+  if (execution.finalSha256 !== hash(bytes)) throw new Error('Planner final identity changed or final absent');
+  // Custody proves the request completed. Payload syntax belongs to normalization/repair.
+  return { sha256: hash(bytes), authentication: 'chatgpt', model: 'gpt-6-astra', effort, ...events, audit, finishedAt: execution.finishedAt, process: { exitCode: execution.exitCode, exitSignal: execution.exitSignal, timedOut: execution.timedOut, interrupted: execution.interrupted } };
+}

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

@@ -0,0 +1,41 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+/** @param {string} filename */
+export async function summarizeEvents(filename) {
+  const events = []; const malformedJsonlLines = [];
+  for (const [index,line] of (await readFile(filename, 'utf8')).split('\n').entries()) {
+    if (!line) continue;
+    try { events.push(JSON.parse(line)); } catch { malformedJsonlLines.push(index + 1); }
+  }
+  const items = events.filter(e => e.type === 'item.completed').map(e => e.item);
+  return {
+    threadId: events.find(e => e.type === 'thread.started')?.thread_id ?? null,
+    usage: events.filter(e => e.type === 'turn.completed').map(e => e.usage),
+    failed: events.filter(e => e.type === 'turn.failed'),
+    errors: events.filter(e => e.type === 'error'),
+    errorsAfterCompletion: events.filter((e, index) => e.type === 'error' && events.some((previous, before) => before < index && previous.type === 'turn.completed')),
+    malformedJsonlLines,
+    tools: items.filter(item => !['agent_message', 'reasoning', 'error'].includes(item.type)),
+  };
+}
+
+/** Inspect private rollouts without copying private session context into a run. @param {string} dir */
+export async function auditRollouts(dir) {
+  const tools = []; const contexts = [];
+  for (const entry of await readdir(dir, { withFileTypes: true }).catch(error => {
+    if (error.code === 'ENOENT') return []; throw error;
+  })) {
+    const filename = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await auditRollouts(filename); tools.push(...nested.tools); contexts.push(...nested.contexts);
+    } else if (entry.name.endsWith('.jsonl')) {
+      for (const line of (await readFile(filename, 'utf8')).split('\n').filter(Boolean)) {
+        const event = JSON.parse(line); const item = event.payload ?? {};
+        if (['custom_tool_call', 'function_call'].includes(item.type)) tools.push({ name: item.name, callId: item.call_id });
+        if (event.type === 'turn_context') contexts.push({ model: item.model, effort: item.effort });
+      }
+    }
+  }
+  return { tools, contexts };
+}

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

@@ -0,0 +1,37 @@
+import { mkdtemp, symlink, copyFile, readFile, realpath, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/** The planner receives an allowlisted environment, never provider credentials. @param {string} home */
+export function subscriptionEnv(home) {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { CODEX_HOME: home };
+  for (const key of ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'LC_ALL', 'SYSTEMROOT']) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
+/** @param {{authHome:string, binary:string, runDir:string,reasoning?:string}} options */
+export async function prepareHome({ authHome, binary, runDir, reasoning = 'low' }) {
+  const authRoot = await realpath(authHome);
+  const runRoot = await realpath(runDir);
+  if (authRoot === runRoot || authRoot.startsWith(runRoot + path.sep)) throw new Error('authHome must be outside runDir');
+  const authPath = await realpath(path.join(authRoot, 'auth.json'));
+  if (authPath === runRoot || authPath.startsWith(runRoot + path.sep)) throw new Error('Credentials must be outside runDir');
+  const home = await mkdtemp(path.join(tmpdir(), '12ui-codex-'));
+  await chmod(home, 0o700);
+  await symlink(authPath, path.join(home, 'auth.json'));
+  try { await copyFile(path.join(authRoot, 'models_cache.json'), path.join(home, 'models_cache.json')); }
+  catch (error) { throw new Error('Explicit authHome must contain models_cache.json', { cause: error }); }
+  const cache = JSON.parse(await readFile(path.join(home, 'models_cache.json'), 'utf8'));
+  if (!cache.models?.some(model => model.slug === 'gpt-6-astra' && model.supported_reasoning_levels?.some(level => level.effort === reasoning))) {
+    throw new Error(`Auth model cache does not support gpt-6-astra ${reasoning}`);
+  }
+  const login = spawnSync(binary, ['login', 'status'], { env: subscriptionEnv(home), encoding: 'utf8', timeout: 30000 });
+  if (login.status !== 0 || !`${login.stdout ?? ''}${login.stderr ?? ''}`.includes('Logged in using ChatGPT')) {
+    throw new Error('ChatGPT authentication unavailable; API authentication is not supported for the planner');
+  }
+  return { home, authentication: 'chatgpt' };
+}

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

@@ -0,0 +1,79 @@
+import { open, readFile, mkdir, rm } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { prepareHome, subscriptionEnv } from './home.mjs';
+import { buildArgv } from './arguments.mjs';
+import { summarizeEvents, auditRollouts } from './events.mjs';
+import { hash, writeJson } from '../run-store.mjs';
+import { validateCompletion } from './completion.mjs';
+
+/** Recover only a final proven complete and no-tool before interruption. @param {{callDir:string}} options */
+export async function recoverCodex({ callDir }) {
+  let receipt;
+  try { receipt = JSON.parse(await readFile(path.join(callDir, 'completion.json'), 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const bytes = await readFile(path.join(callDir, 'final.txt')).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!bytes) return null;
+  if (!receipt) {
+    let execution;
+    try { execution = JSON.parse(await readFile(path.join(callDir, 'execution.json'), 'utf8')); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    try { receipt = validateCompletion(execution, bytes); } catch { return null; }
+    await writeJson(path.join(callDir, 'completion.json'), receipt);
+  }
+  if (receipt.sha256 !== hash(bytes)) throw new Error('Planner final identity changed');
+  return { bytes, metadata: receipt };
+}
+
+/**
+ * One planner invocation. Caller must durably claim dispatch before entering.
+ * @param {{callDir:string,authHome:string,binary?:string,runDir:string,prompt:string,sourcePath?:string,imagePaths?:string[],schemaPath:string,timeoutMs:number,preparedHome?:string,reasoning?:string}} spec
+ */
+export async function invokeCodex(spec) {
+  const binary = spec.binary ?? 'codex';
+  const reasoning = spec.reasoning ?? 'low';
+  if (!['low', 'medium'].includes(reasoning)) throw new Error('reasoning must be low or medium');
+  const home = spec.preparedHome ?? (await prepareHome({ authHome: spec.authHome, binary, runDir: spec.runDir, reasoning })).home;
+  const workDir = path.join(home, 'work'); await mkdir(workDir);
+  const finalPath = path.join(spec.callDir, 'final.txt');
+  const args = buildArgv({ ...spec, workDir, finalPath });
+  // Record treatment, not private auth/runtime paths.
+  await writeJson(path.join(spec.callDir, 'invocation.json'), { model: 'gpt-6-astra', effort: reasoning, authentication: 'chatgpt', noTools: true, startedAt: new Date().toISOString() });
+  const stdout = await open(path.join(spec.callDir, 'events.jsonl'), 'wx');
+  const stderr = await open(path.join(spec.callDir, 'stderr.log'), 'wx');
+  let observationSaved = false;
+  try {
+    const child = spawn(binary, args, { cwd: workDir, env: subscriptionEnv(home), detached: true, stdio: ['pipe', stdout.fd, stderr.fd] });
+    let timedOut = false; let interrupted = false;
+    const stop = signal => { if (child.pid) { try { process.kill(-child.pid, signal); } catch (error) { if (error.code !== 'ESRCH') throw error; } } };
+    let killTimer;
+    const terminate = () => { stop('SIGTERM'); killTimer = setTimeout(() => stop('SIGKILL'), 5000); };
+    const timer = setTimeout(() => { timedOut = true; terminate(); }, spec.timeoutMs);
+    const signalHandler = () => { interrupted = true; terminate(); };
+    process.once('SIGINT', signalHandler); process.once('SIGTERM', signalHandler);
+    child.stdin.on('error', () => {}); child.stdin.end(spec.prompt);
+    let code = null; let exitSignal = null; let spawnError = null;
+    try {
+      code = await new Promise(resolve => { child.once('error', error => { spawnError = { name: error.name, code: /** @type {NodeJS.ErrnoException} */ (error).code ?? null }; }); child.once('close', (status, signal) => { exitSignal = signal; resolve(status); }); });
+    } finally {
+      clearTimeout(timer); clearTimeout(killTimer); stop('SIGTERM');
+      process.removeListener('SIGINT', signalHandler); process.removeListener('SIGTERM', signalHandler);
+      await stdout.sync(); await stderr.sync();
+    }
+    let events = null; let audit = null; let eventReadError = null; let auditReadError = null;
+    try { events = await summarizeEvents(path.join(spec.callDir, 'events.jsonl')); } catch { eventReadError = 'Event stream unreadable'; }
+    try { audit = await auditRollouts(path.join(home, 'sessions')); } catch { auditReadError = 'Private rollout audit unreadable'; }
+    const bytes = await readFile(finalPath).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (bytes) { const finalHandle = await open(finalPath, 'r'); await finalHandle.sync(); await finalHandle.close(); }
+    const execution = { expectedEffort: reasoning, exitCode: code, exitSignal, timedOut, interrupted, spawnError, events, audit, eventReadError, auditReadError, finalSha256: bytes ? hash(bytes) : null, finishedAt: new Date().toISOString() };
+    // Persist evidence before applying acceptance policy, including rejected calls.
+    await writeJson(path.join(spec.callDir, 'execution.json'), execution);
+    observationSaved = true;
+    const metadata = validateCompletion(execution, bytes ?? Buffer.alloc(0));
+    await writeJson(path.join(spec.callDir, 'completion.json'), metadata);
+    return { bytes: /** @type {Buffer} */ (bytes), metadata };
+  } finally {
+    await stdout.close(); await stderr.close();
+    if (observationSaved) await rm(home, { recursive: true, force: true });
+  }
+}

package/runtime/codex-conversion/src/contract-repair.mjs

@@ -0,0 +1,44 @@
+import {writeFile} from 'node:fs/promises';
+import path from 'node:path';
+import {hash,writeJson} from './run-store.mjs';
+import {initialSchema} from './contracts/initial.mjs';
+import {normalizePlannerPayload} from './contracts/compile.mjs';
+import {normalizeHtml} from './references.mjs';
+import {invokeCodex,recoverCodex} from './codex/invoke.mjs';
+import {prepareHome} from './codex/home.mjs';
+
+/** @param {Buffer} bytes @param {any} source */
+export function assessContract(bytes,source){
+ const compiled=normalizePlannerPayload(bytes.toString('utf8'),source);
+ if(!compiled.ok)return {...compiled,normalized:null};
+ const normalized=normalizeHtml(compiled.payload.html,compiled.plan.assets);
+ return {...compiled,ok:normalized.ok,normalized,issues:normalized.issues,recoveries:[...compiled.recoveries,...normalized.recoveries]};
+}
+
+/** @param {Buffer} bytes @param {any} assessment @param {any} source */
+export function buildContractRepairPrompt(bytes,assessment,source){
+ return `Repair representation/contract defects in your saved screenshot conversion. This is not visual judging or polish. Preserve source intent, readable source text, HTML layout and all valid asset ownership decisions. Use the attached original source only to resolve the explicit issues below. Correct only what prevents a usable artifact; do not invent content, delete meaningful content to satisfy validation, or redesign the page. Normalize redundant representation in your answer instead of introducing another planning pass. Return a complete object in the original schema. No tools. This is the only bounded contract repair round. Source: ${source.width}x${source.height}.\nExplicit unresolved issues:\n${JSON.stringify(assessment.issues)}\nDeterministic representation changes already established (apply these while preserving other facts):\n${JSON.stringify(assessment.recoveries)}\nExact saved response:\n${bytes.toString('utf8')}`;
+}
+
+/** One durable extra call only after deterministic normalization cannot deliver.
+ * @param {{planner:any,source:any,sourcePath:string,runDir:string,store:any,authHome?:string,binary?:string,timeoutMs:number,invoke?:(spec:any)=>Promise<any>}} spec */
+export async function resolveContract(spec){
+ const first=assessContract(spec.planner.bytes,spec.source);
+ await writeJson(path.join(spec.runDir,'contract-initial.json'),{responseSha256:hash(spec.planner.bytes),...first});
+ if(first.ok)return {...first,repair:null};
+ const prompt=buildContractRepairPrompt(spec.planner.bytes,first,spec.source);
+ const request={kind:'contract-repair-v1',parentResponseSha256:hash(spec.planner.bytes),issues:first.issues,normalizedChanges:first.recoveries,source:spec.source.sha256,promptSha256:hash(prompt),schemaSha256:hash(JSON.stringify(initialSchema)),model:'gpt-6-astra',effort:'medium'};
+ let preparedHome;
+ const repaired=await spec.store.runCall('contract-repair-1',request,async({callDir})=>{
+  if(!spec.authHome&&!spec.invoke)throw Error('authHome required for contract repair');
+  const schemaPath=path.join(callDir,'schema.json');await writeJson(schemaPath,initialSchema);await writeFile(path.join(callDir,'prompt.txt'),prompt);
+  return (spec.invoke??invokeCodex)({callDir,runDir:spec.runDir,authHome:spec.authHome,binary:spec.binary,sourcePath:spec.sourcePath,schemaPath,prompt,timeoutMs:spec.timeoutMs,reasoning:'medium',preparedHome});
+ },{recover:recoverCodex,prepare:async()=>{
+  if(spec.invoke)return;
+  if(!spec.authHome)throw Error('authHome required for contract repair');
+  preparedHome=(await prepareHome({authHome:spec.authHome,binary:spec.binary??'codex',runDir:spec.runDir,reasoning:'medium'})).home;
+ }});
+ const result=assessContract(repaired.bytes,spec.source);
+ await writeJson(path.join(spec.runDir,'contract-repair.json'),{responseSha256:hash(repaired.bytes),...result});
+ return {...result,repair:{metadata:repaired.metadata,reused:repaired.reused,responseSha256:hash(repaired.bytes)},initialIssues:first.issues};
+}

package/runtime/codex-conversion/src/contracts/compile.mjs

@@ -0,0 +1,53 @@
+import {normalizeDeclarations} from './normalize.mjs';
+import {compileJointAssets} from './contracts.mjs';import {compileGroups} from './groups.mjs';
+const str={type:'string'},arr=items=>({type:'array',items}),obj=properties=>({type:'object',properties,required:Object.keys(properties),additionalProperties:false});
+export const operationSchema=obj({html:str,assets:arr(obj({id:str,source_bbox_px:arr({type:'integer'}),background:{type:'string',enum:['opaque','transparent']},request_group:str,operation:{type:'string',enum:['preserve-source','remove-named-overlays','crop-source']},desired_owner:str,named_removals:arr(obj({source_bbox_px:arr({type:'integer'}),text_or_element:str}))})),uncertainties:arr(str)});
+function compile(result,source,{maxAssets=12,maxImageCalls=12}={}){
+ const compiled=compileJointAssets(result.assets.map(a=>({...a,prompt:a.desired_owner})),source,maxAssets);
+ const assets=compiled.map(a=>{const declared=result.assets.find(x=>x.id===a.id);if(declared.operation==='crop-source'&&declared.background!=='opaque')throw Error('Source crop requires an opaque owner');if(['preserve-source','crop-source'].includes(declared.operation)&&declared.named_removals.length)throw Error('Preservation owner declares removals');if(declared.operation==='remove-named-overlays'&&!declared.named_removals.length)throw Error('Removal operation has no named source overlays');
+  for(const r of declared.named_removals){const b=r.source_bbox_px;if(b.length!==4||!b.every(Number.isSafeInteger)||b[0]<0||b[1]<0||b[2]<=0||b[3]<=0||b[0]+b[2]>source.width||b[1]+b[3]>source.height||!r.text_or_element.trim())throw Error('Invalid named source removal');const o=a.owner;if(b[0]>=o.left+o.width||b[1]>=o.top+o.height||b[0]+b[2]<=o.left||b[1]+b[3]<=o.top)throw Error('Named removal does not intersect its owner');}
+  return {...a,operation:declared.operation,desired_owner:declared.desired_owner,named_removals:declared.named_removals};});
+ const declarations=[];for(const a of assets){let g=declarations.find(g=>g.key===a.request_group);if(!g){g={key:a.request_group,ids:[]};declarations.push(g);}g.ids.push(a.id);}
+ const groups=compileGroups(assets,source,declarations.map(g=>g.ids));if(groups.filter(g=>g.members[0].operation!=='crop-source').length>maxImageCalls)throw Error('Actual image requests exceed admission');for(const g of groups){if(new Set(g.members.map(a=>a.operation)).size!==1)throw Error('Group mixes incompatible operations');g.operation=g.members[0].operation;}
+ return {assets,groups,uncertainties:result.uncertainties};
+}
+
+/** Normalize redundant fields only; never invent an artwork or removal decision. */
+export function validatePlannerPayload(raw, source, limits) {
+ const result = typeof raw === 'string' ? JSON.parse(raw) : raw;
+ if (!result || typeof result !== 'object' || typeof result.html !== 'string' || !Array.isArray(result.assets)) throw Error('Expected HTML and asset declarations');
+ if (!Number.isSafeInteger(source.width) || !Number.isSafeInteger(source.height) || source.width <= 0 || source.height <= 0) throw Error('Invalid source dimensions');
+ const recoveries = [];
+ const assets = result.assets.map((asset, index) => {
+  if (!asset || typeof asset !== 'object') throw Error(`Invalid asset ${index}`);
+  const a = {...asset};
+  if (a.request_group == null || a.request_group === '') { a.request_group = a.id; recoveries.push({asset:a.id,field:'request_group',to:a.id,basis:'independent owner default'}); }
+  if (typeof a.request_group !== 'string' || !a.request_group.trim()) throw Error('Invalid request group');
+  if (!['opaque','transparent'].includes(a.background)) throw Error('Invalid asset background');
+  if (!['preserve-source','remove-named-overlays','crop-source'].includes(a.operation)) throw Error('Invalid asset operation');
+  if (typeof a.desired_owner !== 'string' || !a.desired_owner.trim()) throw Error('Missing desired owner');
+  if (a.named_removals == null && ['preserve-source','crop-source'].includes(a.operation)) { a.named_removals = []; recoveries.push({asset:a.id,field:'named_removals',to:[],basis:'preserve-source declares no removals'}); }
+  if (!Array.isArray(a.named_removals)) throw Error('Expected named removals');
+  for (const r of a.named_removals) if (!r || !Array.isArray(r.source_bbox_px) || typeof r.text_or_element !== 'string') throw Error('Invalid named source removal');
+  return a;
+ });
+ const uncertainties = result.uncertainties ?? [];
+ if (!Array.isArray(uncertainties) || uncertainties.some(x => typeof x !== 'string')) throw Error('Invalid uncertainties');
+ if (result.uncertainties == null) recoveries.push({field:'uncertainties',to:[],basis:'no uncertainty statements supplied'});
+ const plan=compile({...result, assets, uncertainties}, source, limits);
+ for(const group of plan.groups)if(group.frame.normalization)recoveries.push({field:`group:${group.id}.frame`,basis:group.frame.normalization.basis,input:group.frame.input,providerOutput:group.frame.providerOutput,deliveryOutput:group.frame.output});
+ return {...plan, recoveries};
+}
+export const compileOperations = validatePlannerPayload;
+
+/** A boundary outcome for the bounded repair workflow, rather than a terminal exception. */
+export function normalizePlannerPayload(raw, source, limits) {
+ let payload=raw, recoveries=[];
+ try {
+  ({payload,recoveries}=normalizeDeclarations(raw));
+  const plan=validatePlannerPayload(payload,source,limits);
+  return {ok:true,payload,plan:{...plan,recoveries:[...recoveries,...plan.recoveries]},recoveries:[...recoveries,...plan.recoveries],issues:[]};
+ } catch(error) {
+  return {ok:false,payload,plan:null,recoveries,issues:[{code:'unresolved-plan-contract',message:String(error.message ?? error),repairable:true,requiresModel:true,instruction:'Preserve all valid artwork decisions. Resolve only the reported missing or contradictory source fact; do not invent geometry, delete owners, or replace artwork with a fallback.'}]};
+ }
+}

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

@@ -0,0 +1,19 @@
+import {realContextFrame} from './geometry.mjs';
+function box(values,source){
+ if(!Array.isArray(values)||values.length!==4||!values.every(Number.isSafeInteger))throw Error('Expected four integer source coordinates');
+ const [left,top,width,height]=values;if(left<0||top<0||width<=0||height<=0||left+width>source.width||top+height>source.height)throw Error('Frame outside source');return {left,top,width,height};
+}
+function compilePlan(plan,source,maxAssets=12){
+ if(plan.assets.length>maxAssets)throw Error('Declared artwork exceeds admitted count');
+ const ids=new Set(),componentIds=new Set();
+ for(const a of plan.assets){if(!/^[a-z0-9_-]+$/.test(a.id)||ids.has(a.id))throw Error('Invalid or duplicate artwork id');ids.add(a.id);}
+ if(!plan.components.length)throw Error('No declared page components');
+ for(const c of plan.components){if(!c.id||componentIds.has(c.id))throw Error('Duplicate or empty component id');componentIds.add(c.id);box(c.source_frame,source);for(const id of c.artwork_ids)if(!ids.has(id))throw Error('Undeclared artwork reference');}
+ const assets=plan.assets.map(a=>{if(!plan.components.some(c=>c.artwork_ids.includes(a.id)))throw Error('Unowned artwork');const owner=box(a.source_bbox_px,source),frame=a.operation==='crop-source'?{supported:true,input:owner,output:{width:owner.width,height:owner.height},crop:{left:0,top:0,width:owner.width,height:owner.height}}:realContextFrame(source,owner);if(!frame.supported)throw Error(`Unsupported exact source frame for ${a.id}: ${'reason' in frame?frame.reason:'unsupported'}`);return {id:a.id,source_bbox_px:a.source_bbox_px,background:a.background,prompt:a.prompt,request_group:a.request_group,owner,frame,delivery:{path:a.id+'.png',width:owner.width*(a.operation==='crop-source'?1:2),height:owner.height*(a.operation==='crop-source'?1:2),nativeDisplayFrame:a.source_bbox_px,scale:a.operation==='crop-source'?1:2}};});
+ if(!assets.length&&!plan.no_artwork_reason.trim())throw Error('Missing artwork explanation');return {...plan,assets};
+}
+
+export function compileJointAssets(assets,source,maxAssets=12){
+ const proxy={style:'',components:assets.map(a=>({id:'owner-'+a.id,source_frame:a.source_bbox_px,editable_content:'',artwork_ids:[a.id],layout:''})),assets,no_artwork_reason:'Joint source-only response; zero-art suitability must be inspected',uncertainties:[]};
+ if(!assets.length)return [];return compilePlan(proxy,source,maxAssets).assets;
+}

package/runtime/codex-conversion/src/contracts/geometry.mjs

@@ -0,0 +1,38 @@
+import {gridBoundaryFrame} from './grid-frame.mjs';
+// Every input pixel and owner coordinate comes from the original source.
+// A source-boundary provider-grid mapping is explicit; no padding or localization.
+export function realContextFrame(source, target) {
+  for (const [key, value] of Object.entries({
+    sourceWidth: source.width, sourceHeight: source.height,
+    ...target,
+  })) if (!Number.isSafeInteger(value) || value < (key === 'left' || key === 'top' ? 0 : 1)) {
+    throw new RangeError(`Invalid source-frame ${key}`);
+  }
+  if (target.left + target.width > source.width || target.top + target.height > source.height) {
+    throw new RangeError('Target lies outside original source');
+  }
+  const up8 = n => Math.ceil(n / 8) * 8;
+  let best = null;
+  for (let width = up8(target.width); width <= Math.min(source.width, 1920); width += 8) {
+    const height = up8(Math.max(target.height, width / 3, 655360 / (4 * width)));
+    if (height > source.height || height > 1920 || height > width * 3
+      || width * height * 4 > 8294400) continue;
+    const area = width * height;
+    if (!best || area < best.area || (area === best.area && width < best.width)) {
+      best = { width, height, area };
+    }
+  }
+  if (!best) return gridBoundaryFrame(source,target) ?? { supported: false, reason: 'No legal exact-2x rectangle fits original source bounds' };
+  const left = Math.max(0, Math.min(source.width - best.width,
+    Math.floor(target.left - (best.width - target.width) / 2)));
+  const top = Math.max(0, Math.min(source.height - best.height,
+    Math.floor(target.top - (best.height - target.height) / 2)));
+  return {
+    supported: true,
+    input: { left, top, width: best.width, height: best.height },
+    output: { width: best.width * 2, height: best.height * 2 },
+    crop: { left: (target.left - left) * 2, top: (target.top - top) * 2,
+      width: target.width * 2, height: target.height * 2 },
+    inputAreaFraction: best.area / (source.width * source.height),
+  };
+}

package/runtime/codex-conversion/src/contracts/grid-frame.mjs

@@ -0,0 +1,22 @@
+// Only used after the established exact-2x grid search fails. Source pixels and
+// owner coordinates stay exact; only the provider's output canvas is rounded.
+export function gridBoundaryFrame(source,target){
+ const up8=n=>Math.ceil(n/8)*8,up16=n=>Math.ceil(n/16)*16;
+ const widths=[];for(let width=up8(target.width);width<=Math.min(source.width,1920);width+=8)widths.push(width);
+ if(source.width%8&&source.width<=1920)widths.push(source.width);
+ let best=null;
+ for(const width of widths){
+  if(width<target.width)continue;
+  const roundedHeight=up8(Math.max(target.height,width/3,655360/(4*width)));
+  const height=roundedHeight>source.height&&roundedHeight-source.height<8?source.height:roundedHeight;
+  if(height<target.height||height>source.height||height>1920||!(width%8||height%8))continue;
+  const providerOutput={width:up16(width*2),height:up16(height*2)};
+  const {width:w,height:h}=providerOutput,area=w*h;
+  if(w>3840||h>3840||w>h*3||h>w*3||area<655360||area>8294400)continue;
+  if(!best||width*height<best.area||(width*height===best.area&&width<best.width))best={width,height,area:width*height,providerOutput};
+ }
+ if(!best)return null;
+ const left=Math.max(0,Math.min(source.width-best.width,Math.floor(target.left-(best.width-target.width)/2)));
+ const top=Math.max(0,Math.min(source.height-best.height,Math.floor(target.top-(best.height-target.height)/2)));
+ return {supported:/** @type {true} */(true),input:{left,top,width:best.width,height:best.height},output:{width:best.width*2,height:best.height*2},crop:{left:(target.left-left)*2,top:(target.top-top)*2,width:target.width*2,height:target.height*2},inputAreaFraction:best.area/(source.width*source.height),providerOutput:best.providerOutput,normalization:{name:'provider-grid-to-exact-frame',kernel:'lanczos3',basis:'Exact source boundary cannot fit the provider output grid; owner and input pixels unchanged'}};
+}

package/runtime/codex-conversion/src/contracts/groups.mjs

@@ -0,0 +1,14 @@
+import {realContextFrame} from './geometry.mjs';
+// Groups keep the original spatial arrangement. They are never repacked into an atlas.
+export function compileGroups(assets,source,declarations=assets.map(a=>[a.id])){
+ const used=new Set();const groups=declarations.map((ids,index)=>{
+  if(!ids.length)throw Error('Empty artwork request group');
+  const members=ids.map(id=>{const asset=assets.find(a=>a.id===id);if(!asset||used.has(id))throw Error('Unknown or repeated group owner');used.add(id);return asset;});
+  if(new Set(members.map(a=>a.background)).size!==1)throw Error('Conflicting group backgrounds');
+  for(const [i,a] of members.entries())for(const b of members.slice(i+1))if(a.owner.left<b.owner.left+b.owner.width&&b.owner.left<a.owner.left+a.owner.width&&a.owner.top<b.owner.top+b.owner.height&&b.owner.top<a.owner.top+a.owner.height)throw Error('Overlapping group owners require separate requests');
+  const left=Math.min(...members.map(a=>a.owner.left)),top=Math.min(...members.map(a=>a.owner.top));
+  const owner={left,top,width:Math.max(...members.map(a=>a.owner.left+a.owner.width))-left,height:Math.max(...members.map(a=>a.owner.top+a.owner.height))-top};
+  const local=members.every(a=>a.operation==='crop-source');const frame=local?{supported:true,input:owner,output:{width:owner.width,height:owner.height}}:realContextFrame(source,owner);if(!frame.supported)throw Error('Unsupported artwork group frame');
+  return {id:'group-'+String(index+1).padStart(2,'0'),background:members[0].background,frame,members:members.map(a=>({...a,frame:{...frame,crop:{left:(a.owner.left-frame.input.left)*2,top:(a.owner.top-frame.input.top)*2,width:a.owner.width*2,height:a.owner.height*2}}}))};
+ });if(used.size!==assets.length)throw Error('Ungrouped artwork owner');return groups;
+}

package/runtime/codex-conversion/src/contracts/initial.mjs

@@ -0,0 +1,9 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+export const schemaPath = fileURLToPath(new URL('../../templates/initial.schema.json', import.meta.url));
+export const initialSchema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+const prompt = readFileSync(new URL('../../templates/initial.txt', import.meta.url), 'utf8');
+export function buildInitialPrompt({width,height}, cleanAssets = 'enhance') {
+ const preference = cleanAssets === 'crop' ? '\nUser clean-artwork preference: use crop-source for clean opaque owners needing no removal, transparency, enhancement or new details. crop-source delivers original pixels at native owner dimensions, with no 2x resampling. Declare named_removals: [] and reserve explicit source-sized CSS dimensions; do not rely on enhanced image intrinsic size. Keep preserve-source or remove-named-overlays for owners requiring AI work.' : '\nUser clean-artwork preference: enhance. Use preserve-source or remove-named-overlays as described; do not declare crop-source.';
+ return prompt + preference + `\nOriginal source dimensions ${width}×${height}. Maximum 12 actual assets and 12 compatible image-request groups. Inspect only the attached source image; do not use tools.`;
+}

package/runtime/codex-conversion/src/contracts/normalize.mjs

@@ -0,0 +1,46 @@
+/** Resolve representation only. Geometry and artwork decisions are never guessed. */
+export function normalizeDeclarations(raw) {
+ const recoveries=[];
+ let payload=raw;
+ if(typeof payload==='string') {
+  const trimmed=payload.trim(), fenced=trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i);
+  if(fenced) { payload=fenced[1]; recoveries.push({field:'payload',basis:'single JSON code fence removed'}); }
+  payload=JSON.parse(payload);
+ }
+ if(!payload || typeof payload!=='object') throw Error('Expected planner object');
+ payload=structuredClone(payload);
+ const set=(object,key,to,path,basis)=>{recoveries.push({field:path,from:object[key],to,basis});object[key]=to;};
+ const box=(object,key,path)=>{
+  const value=object[key];
+  if(Array.isArray(value) && value.length===4 && value.every(n=>Number.isSafeInteger(n) || typeof n==='string' && /^-?\d+$/.test(n.trim()) && Number.isSafeInteger(Number(n)))) {
+   const normalized=value.map(Number);
+   if(value.some((v,i)=>v!==normalized[i])) set(object,key,normalized,path,'lossless integer source coordinates');
+  }
+ };
+ if(payload.uncertainties==null) set(payload,'uncertainties',[],'uncertainties','no uncertainty statements supplied');
+ if(Array.isArray(payload.assets)) for(const [i,a] of payload.assets.entries()) {
+  if(!a || typeof a!=='object') continue;
+  const at=`assets[${i}]`;
+  for(const key of ['background','operation']) if(typeof a[key]==='string') {
+   const v=a[key].trim().toLowerCase();if(v!==a[key]) set(a,key,v,`${at}.${key}`,'enum spelling whitespace and case');
+  }
+  if(a.request_group==null || typeof a.request_group==='string' && !a.request_group.trim()) set(a,'request_group',a.id,`${at}.request_group`,'independent owner default');
+  if(['preserve-source','crop-source'].includes(a.operation) && a.named_removals==null) set(a,'named_removals',[],`${at}.named_removals`,'preserve-source declares no removals');
+  box(a,'source_bbox_px',`${at}.source_bbox_px`);
+  if(Array.isArray(a.named_removals)) for(const [j,r] of a.named_removals.entries()) if(r && typeof r==='object') box(r,'source_bbox_px',`${at}.named_removals[${j}].source_bbox_px`);
+ }
+ // Request grouping is an execution optimization, never an artwork ownership fact.
+ const groups=new Map();
+ for(const a of Array.isArray(payload.assets)?payload.assets:[]) if(a && typeof a.request_group==='string') groups.set(a.request_group,[...(groups.get(a.request_group) ?? []),a]);
+ let serial=0;
+ for(const [key,members] of groups) {
+  const validBox=a=>Array.isArray(a.source_bbox_px) && a.source_bbox_px.length===4 && a.source_bbox_px.every(Number.isSafeInteger);
+  const overlap=(a,b)=>{const [x,y,w,h]=a.source_bbox_px,[u,v,p,q]=b.source_bbox_px;return x<u+p && u<x+w && y<v+q && v<y+h;};
+  const incompatible=new Set(members.map(a=>a.background)).size>1 || new Set(members.map(a=>a.operation)).size>1 || members.every(validBox) && members.some((a,i)=>members.slice(i+1).some(b=>overlap(a,b)));
+  if(members.length>1 && incompatible) for(const a of members) {
+   let to;do {to=`normalized-group-${++serial}`;} while(groups.has(to));
+   set(a,'request_group',to,`asset:${a.id}.request_group`,'incompatible shared context split; exact owner and operation preserved');
+  }
+ }
+ return {payload,recoveries};
+}

package/runtime/codex-conversion/src/exports/browser.mjs

@@ -0,0 +1,26 @@
+import {createServer} from 'node:http';
+import {readFile} from 'node:fs/promises';
+import {resolve,extname,sep} from 'node:path';
+import {chromium} from 'playwright';
+import sharp from 'sharp';
+export async function serve(directory){const server=createServer(async(req,res)=>{try{const file=resolve(directory,'.'+decodeURIComponent(new URL(req.url,'http://localhost').pathname));if(file!==resolve(directory)&&!file.startsWith(resolve(directory)+sep))throw Error('Outside root');const path=extname(file)?file:resolve(file,'index.html');res.setHeader('Content-Type',({'.html':'text/html','.js':'text/javascript','.css':'text/css','.svg':'image/svg+xml','.png':'image/png','.webp':'image/webp','.jpg':'image/jpeg','.woff2':'font/woff2'})[extname(path)]??'application/octet-stream');res.end(await readFile(path));}catch{res.statusCode=404;res.end();}});await new Promise(r=>server.listen(0,'127.0.0.1',()=>r(undefined)));return {url:`http://127.0.0.1:${/** @type {import('node:net').AddressInfo} */ (server.address()).port}`,close:()=>new Promise((r,j)=>server.close(e=>e?j(e):r(undefined)))};}
+export async function render({outputDir,htmlFile,target,width,height,paginate=false}) {
+ const hosted=await serve(outputDir);let browser;
+ try {
+  browser=await chromium.launch({headless:true});
+  const page=await browser.newPage({viewport:{width,height},deviceScaleFactor:1});
+  await page.goto(`${hosted.url}/${htmlFile}`,{waitUntil:'networkidle'});
+  await page.evaluate(()=>document.fonts.ready);
+  if(target==='pdf') {
+   await page.emulateMedia({media:'screen'});
+   const contentHeight=await page.evaluate(()=>Math.ceil(Math.max(document.documentElement.scrollHeight,document.body.scrollHeight,document.documentElement.getBoundingClientRect().bottom,document.body.getBoundingClientRect().bottom)));
+   const pageHeight=paginate?height:contentHeight;
+   await page.pdf({path:resolve(outputDir,'render.pdf'),width:`${width}px`,height:`${pageHeight}px`,printBackground:true});
+   return {pdfPageWidth:width,pdfPageHeight:pageHeight,pdfPagination:paginate?'explicit height':'full content'};
+  }
+  const png=await page.screenshot({fullPage:true});
+  const dimensions=await sharp(png).metadata();
+  await sharp(png).toFormat(target==='jpg'?'jpeg':target).toFile(resolve(outputDir,`render.${target}`));
+  return {renderWidth:dimensions.width,renderHeight:dimensions.height};
+ } finally {await browser?.close();await hosted.close();}
+}

package/runtime/codex-conversion/src/exports/editable.mjs

@@ -0,0 +1,34 @@
+import {serialize} from 'parse5';
+
+// Match the javascript URL boundary in the bundled React 19.2 DOM renderer.
+// parse5 has already decoded entities; browsers ignore CR/LF/TAB in schemes.
+const javascriptProtocol=/^[\u0000-\u001F ]*j[\r\n\t]*a[\r\n\t]*v[\r\n\t]*a[\r\n\t]*s[\r\n\t]*c[\r\n\t]*r[\r\n\t]*i[\r\n\t]*p[\r\n\t]*t[\r\n\t]*:/i;
+const urlAttributes=new Set(['href','src','action','formaction','xlink:href']);
+
+
+export function ownsEditableMarkup(node) {
+ const value=node.attrs?.find(attribute=>attribute.name==='contenteditable')?.value.toLowerCase();
+ return value===''||value==='true'||value==='plaintext-only';
+}
+
+/** Editable descendants belong to the browser, not React's child reconciler. */
+export function editableMarkup(node,seams) {
+ function clean(parent) {
+  parent.childNodes=(parent.childNodes??[]).filter(child=>{
+   if(child.tagName==='script'){seams.push('Source script omitted; implement application behavior explicitly.');return false;}
+   child.attrs=child.attrs?.filter(attribute=>{
+    if(/^on/i.test(attribute.name)){seams.push(`Source ${attribute.name} handler omitted.`);return false;}
+    const name=attribute.prefix?`${attribute.prefix}:${attribute.name}`:attribute.name;
+    if((urlAttributes.has(name)||(name==='data'&&child.tagName==='object'))&&javascriptProtocol.test(attribute.value)){
+     seams.push(`Source javascript: ${name} URL omitted.`);return false;
+    }
+    return true;
+   });
+   clean(child);
+   if(child.content)clean(child.content);
+   return true;
+  });
+ }
+ clean(node);
+ return serialize(node);
+}

package/runtime/codex-conversion/src/exports/files.mjs

@@ -0,0 +1,7 @@
+import {cp,mkdir,readFile,writeFile,readdir} from 'node:fs/promises';
+import {resolve,relative,sep,dirname} from 'node:path';
+import {createHash} from 'node:crypto';
+export const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+export async function inventory(directory){const out=[];async function walk(dir){for(const entry of await readdir(dir,{withFileTypes:true})){const p=resolve(dir,entry.name);if(entry.isSymbolicLink())throw Error('Symbolic links are not portable output assets');if(entry.isDirectory())await walk(p);else{const b=await readFile(p);out.push({path:relative(directory,p),bytes:b.length,sha256:sha(b)});}}}await walk(directory);return out.sort((a,b)=>a.path.localeCompare(b.path));}
+export async function copyExclusive(sourceDir,outputDir){sourceDir=resolve(sourceDir);outputDir=resolve(outputDir);if(outputDir===sourceDir||outputDir.startsWith(sourceDir+sep))throw Error('Output must be outside source directory');await inventory(sourceDir);await mkdir(dirname(outputDir),{recursive:true});await mkdir(outputDir);await cp(sourceDir,outputDir,{recursive:true});}
+export async function refreshManifest(outputDir,changes={}){let original={};try{original=JSON.parse(await readFile(resolve(outputDir,'manifest.json'),'utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}const files=(await inventory(outputDir)).filter(f=>!['manifest.json','export-manifest.json'].includes(f.path)).map(f=>({...original.files?.find(x=>x.path===f.path),...f}));const manifest={...original,...changes,files};await writeFile(resolve(outputDir,'manifest.json'),JSON.stringify(manifest,null,2)+'\n');return manifest;}

package/runtime/codex-conversion/src/exports/index.mjs

@@ -0,0 +1,24 @@
+import {readFile,writeFile} from 'node:fs/promises';
+import {resolve,dirname,sep} from 'node:path';
+import {createRequire} from 'node:module';
+import {build} from 'esbuild';
+import {toReact} from './react.mjs';
+import {copyExclusive,inventory,refreshManifest} from './files.mjs';
+import {render} from './browser.mjs';
+import {exportViewport} from './viewport.mjs';
+const require=createRequire(import.meta.url);
+export async function buildReact(outputDir){await build({entryPoints:[resolve(outputDir,'main.jsx')],bundle:true,outfile:resolve(outputDir,'app.js'),nodePaths:['react','react-dom'].map(name=>resolve(dirname(require.resolve(name+'/package.json')),'..')),jsx:'automatic',external:['*.png','*.jpg','*.jpeg','*.webp','*.svg','*.woff','*.woff2'],logLevel:'silent'});}
+export async function exportOutput({sourceDir,htmlFile='index.html',outputDir,target,width=undefined,height=undefined}){
+ if(!['assets','png','jpg','webp','pdf','react'].includes(target))throw Error(`Unsupported target: ${target}`);
+ sourceDir=resolve(sourceDir);outputDir=resolve(outputDir);const sourceFile=resolve(sourceDir,htmlFile);if(!sourceFile.startsWith(sourceDir+sep))throw Error('HTML must be within source directory');
+ const viewport=await exportViewport(sourceDir,width,height);
+ const html=await readFile(sourceFile,'utf8');await copyExclusive(sourceDir,outputDir);await writeFile(resolve(outputDir,'original.html'),html);
+ const metadata={target,width:viewport.width,height:viewport.height,viewportBasis:viewport.basis,sourceHtml:htmlFile,originalHtml:'original.html'};
+ if(target==='react'){
+  const result=await toReact(html);Object.assign(metadata,{cssScope:result.cssScope,unresolvedActions:result.seams});await writeFile(resolve(outputDir,'ConvertedPage.jsx'),result.code);
+  await writeFile(resolve(outputDir,'main.jsx'),`import React from 'react';import{createRoot}from'react-dom/client';import ConvertedPage from './ConvertedPage.jsx';createRoot(document.getElementById('root')).render(<ConvertedPage/>);`);
+  await writeFile(resolve(outputDir,'index.html'),'<!doctype html><html><head><meta name="viewport" content="width=device-width,initial-scale=1"></head><body><div id="root" style="display:contents"></div><script type="module" src="./app.js"></script></body></html>');
+  await writeFile(resolve(outputDir,'package.json'),JSON.stringify({name:'converted-page',private:true,type:'module',scripts:{build:'esbuild main.jsx --bundle --outfile=app.js --loader:.js=jsx --external:*.png --external:*.jpg --external:*.jpeg --external:*.webp --external:*.svg --external:*.woff --external:*.woff2'},dependencies:{react:'19.2.0','react-dom':'19.2.0'},devDependencies:{esbuild:'0.27.7'}},null,2));await buildReact(outputDir);
+ }else if(target!=='assets'){Object.assign(metadata,await render({outputDir,htmlFile,target,...viewport}));if(target==='pdf')metadata.pdfSemantics='browser-render PDF; not native LayerDoc PDF';}
+ await refreshManifest(outputDir,{format:target,entrypoint:target==='react'?'index.html':htmlFile});metadata.files=(await inventory(outputDir)).filter(f=>f.path!=='export-manifest.json');await writeFile(resolve(outputDir,'export-manifest.json'),JSON.stringify(metadata,null,2)+'\n');return metadata;
+}