quoxcli 0.3.1 → 0.4.0

package/vendor/dragonlab/design/seer/v4/watch.mjs

@@ -0,0 +1,56 @@
+import {performance} from 'node:perf_hooks';
+import {SEER_CLIPS,renderSeer,renderStory,STORY_DURATION} from './character.mjs';
+import {composeMessage} from '../../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../../vendor/quox-dragon/qart.js';
+
+/** One bounded performance. No alternate screen or full-screen clearing. */
+export async function watch(paths,options,config){
+  if(!process.stdout.isTTY||!process.stdin.isTTY)throw new Error('--watch/--intro needs an interactive terminal. Use --scene and --at for snapshots.');
+  const {terminalCols,terminalRows,scene,large,message}=config;
+  const clip=scene?SEER_CLIPS.find(c=>c.id===scene):null;
+  const duration=(config.arrival&&options.deck?4400:clip?.duration??STORY_DURATION)+(config.arrival?6000:0);
+  const realCols=process.stdout.columns,realRows=process.stdout.rows;
+  const start=performance.now();
+  const render=t=>{
+    const r=scene?renderSeer(paths,scene,t,options):renderStory(paths,t,options);
+    if(!r?.ok)throw new Error(r?.code??'Invalid story frame');
+    const caption=message??'SEER · '+r.clip+'\n'+r.caption;
+    return large?[...cellsToAnsi(r.frame),...caption.split('\n')]:composeMessage(r.frame,caption,{terminalCols});
+  };
+  // Reserve enough lines for captions too; keep within the real terminal.
+  const height=options.rows+3;
+  if(height>=terminalRows)throw new Error('Animation needs room for its caption; reduce --rows.');
+  let ended=false,drawn=false,timer,resolveDone,rejectDone;
+  const wasRaw=Boolean(process.stdin.isRaw);
+  const done=new Promise((resolve,reject)=>{resolveDone=resolve;rejectDone=reject;});
+  const cleanup=(error)=>{
+    if(ended)return;ended=true;clearInterval(timer);
+    process.stdin.off('data',key);process.stdout.off('resize',resized);
+    process.off('SIGINT',sigint);process.off('SIGTERM',sigterm);
+    process.stdin.setRawMode(wasRaw);process.stdin.pause();
+    if(drawn)process.stdout.write(`\x1b[${height}B\r`);
+    process.stdout.write('\x1b[0m\x1b[?25h');
+    error?rejectDone(error):resolveDone();
+  };
+  const key=data=>{if(data.includes(3)||data.toString().includes('q'))cleanup();};
+  const sigint=()=>cleanup(),sigterm=()=>cleanup();
+  const resized=()=>cleanup(new Error('Terminal resized; rerun for the new art slot.'));
+  try{
+    process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',key);
+    process.stdout.on('resize',resized);process.on('SIGINT',sigint);process.on('SIGTERM',sigterm);
+    process.stdout.write('\x1b[?25l');
+    // Allocate the block once; each frame replaces only these lines.
+    process.stdout.write('\n'.repeat(height)+`\x1b[${height}A`);drawn=true;
+    const tick=()=>{
+      try{
+        if(process.stdout.columns!==realCols||process.stdout.rows!==realRows)return resized();
+        const t=Math.min(performance.now()-start,duration-1),lines=render(t);
+        if(lines.length>height)throw new Error('Message exceeds the animation block; use a shorter message or a static preview.');
+        process.stdout.write(Array.from({length:height},(_,i)=>'\r\x1b[2K'+(lines[i]??'')+'\n').join('')+`\x1b[${height}A`);
+        if(performance.now()-start>=duration)cleanup();
+      }catch(e){cleanup(e);}
+    };
+    tick();if(!ended)timer=setInterval(tick,1000/12);
+    await done;
+  }catch(e){cleanup(e);await done;}
+}

package/vendor/dragonlab/design/stage3/companion-review.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// One-shot Sentinel review for the companions launcher: node dragon.mjs sentinel [--scene ID] [--message TEXT] ...
+import {renderSentinelCharacter,SENTINEL_CLIPS} from './sentinel-character.js';
+import {renderSentinelIcon} from './sentinel-icon.js';
+import {artSlot,composeMessage} from '../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../vendor/quox-dragon/qart.js';
+const args=process.argv.slice(2),values=new Set(['--cols','--rows','--terminal-cols','--terminal-rows','--message','--scene','--at']);
+for(let i=0;i<args.length;i++){
+  if(values.has(args[i])){if(!args[i+1]||args[i+1].startsWith('--'))throw Error('Missing option value');i++;}
+  else if(!['--large','--mono','--help','--watch','--attach','--intro','--still','--list'].includes(args[i]))throw Error('Unknown option: '+args[i]);
+}
+const value=(name,fallback)=>args.includes(name)?args[args.indexOf(name)+1]:fallback;
+if(args.includes('--help')){console.log('Sentinel companion review (one frame). --scene ID --at MS --list --large --mono --still --message TEXT --cols N --rows N --terminal-cols N --terminal-rows N. Below 48x16 cells the approved shield icon is shown.');process.exit(0);}
+if(args.includes('--list')){console.log(SENTINEL_CLIPS.map(c=>c.id+' · '+c.title).join('\n'));process.exit(0);}
+const w=Number(value('--terminal-cols',process.stdout.columns||80)),h=Number(value('--terminal-rows',process.stdout.rows||24));
+if(!Number.isSafeInteger(w)||!Number.isSafeInteger(h)||w<1||h<1)throw Error('Invalid terminal size');
+const slot=artSlot(w,h),large=args.includes('--large')||args.includes('--intro');
+const cols=Number(value('--cols',large?Math.min(88,w-4):slot.cols)),rows=Number(value('--rows',large?Math.min(25,h-4):slot.rows));
+const message=value('--message','SENTINEL\nOn watch.');
+if(!slot.showArt&&!large&&!args.includes('--cols')){console.log(composeMessage(null,message,{terminalCols:w}).join('\n'));}
+else{
+  const scene=value('--scene',args.includes('--attach')||args.includes('--intro')?'greeting':'idle');
+  const opts={cols,rows,mono:args.includes('--mono'),still:args.includes('--still')};
+  let r=renderSentinelCharacter(scene,Number(value('--at',0)),opts);
+  if(!r.ok&&r.code==='ICON_FALLBACK'){const ih=Math.max(6,Math.min(rows,10));r=renderSentinelIcon({cols:Math.min(cols,ih*2),rows:ih,mono:opts.mono});}
+  if(!r.ok)throw Error(r.code);
+  console.log((large?[...cellsToAnsi(r.frame),...composeMessage(null,message,{terminalCols:w})]:composeMessage(r.frame,message,{terminalCols:w})).join('\n'));
+}

package/vendor/dragonlab/design/stage3/sentinel-art.js

@@ -0,0 +1,39 @@
+/**
+ * Design-stage prototype geometry. Body, horns, wings, tail, cheeks and
+ * mouth are transcribed from Stage 2 Aegis Bean. A2 eyes are the user's
+ * provisional "stronger white + separation" study, not final approval.
+ * This file is NOT a production mascot.
+ *
+ * Source masters:
+ *   design/stage2/source/sentinel-geometry.json (candidate A)
+ *   design/stage2/refinement/sentinel-a-solid-bold-whites.svg (eye A2)
+ */
+export const SENTINEL_ART=Object.freeze({
+  source:'design/stage2/refinement/sentinel-a-solid-bold-whites.svg',
+  viewBox:[0,0,320,240],
+  paths:Object.freeze({
+    body:'M141 53 C115 49 103 69 99 102 C91 121 94 146 103 168 C108 192 130 212 154 209 C184 211 202 188 209 155 C217 126 212 98 198 76 C186 57 163 52 141 53 Z',
+    wingL:'M104 111 C83 85 57 57 38 49 L46 83 Q31 78 24 66 C25 100 44 118 73 126 Q45 126 34 114 C46 142 76 152 103 143 Z',
+    wingR:'M202 107 C226 77 248 49 266 47 L259 81 Q280 69 284 61 C291 98 270 117 247 127 Q276 125 289 116 C279 144 246 151 204 145 Z',
+    hornL:'M116 65 Q108 49 110 18 C96 32 93 51 100 72 Z',
+    hornR:'M172 61 Q195 37 192 13 C210 28 211 50 194 78 Z',
+    tail:'M206 178 C232 164 239 189 255 185 C271 181 272 165 268 152 L286 157 L289 169 L300 160 C300 180 288 196 272 200 C253 206 230 185 209 190 Z',
+    footL:'M116 199 Q115 210 127 215 Q135 214 137 207 Z',
+    footR:'M172 199 Q175 213 185 214 Q197 210 197 192 Z',
+    belly:'M123 161 C132 193 152 200 173 184 C155 211 136 210 120 188 Q115 174 123 161 Z',
+    mouth:'M143 165 Q158 179 174 163',
+    browL:'M101 72 Q125 64 142 75',
+    browR:'M167 73 Q187 64 204 77',
+  }),
+  eyes:Object.freeze({
+    islands:{centres:[[126,112],[181,111]],whiteRadius:[21,27],pupil:.45},
+    bold:{centres:[[125,113],[182,112]],whiteRadius:[23,29],pupil:.44},
+  }),
+  cheeks:Object.freeze([[99,159,8],[211,150,6.5]]),
+  nose:Object.freeze([99,152,3.3]),
+  colors:Object.freeze({
+    body:'#5799EE',wing:'#356CB9',horn:'#86D2FF',tail:'#5799EE',
+    foot:'#366CB9',belly:'#8ECFFF',cheek:'#FA93B7',brow:'#B3E7FF',
+    eyeWhite:'#FFFFFF',
+  }),
+});

package/vendor/dragonlab/design/stage3/sentinel-braille.js

@@ -0,0 +1,216 @@
+/**
+ * Sentinel Aegis Bean / A2 solid-eye braille PROTOTYPE.
+ *
+ * Uses the ACTUAL original Q modules for mask-field->Braille conversion,
+ * deterministic blink/gaze and exclusive terminal-cell eye ownership.
+ * Only source SVG geometry is newly rasterised. No terminal API / Node I/O.
+ *
+ * opt-in prototype on an isolated branch; not called by the Lair or Quox CLI.
+ */
+import {makeField,fieldToCells} from '../../vendor/quox-dragon/qart.js';
+import {eyeCells,eyeState,overlay,GOOGLY,EYE_WHITE} from '../../vendor/quox-dragon/qeyes.js';
+import {SENTINEL_ART as ART} from './sentinel-art.js';
+import {flattenPath,sampleShape} from './svg-coverage.js';
+import {renderWardenEyes} from './sentinel-warden-eyes.js';
+
+const BASE=Object.freeze({cols:88,rows:25,mono:false,theme:'dark',eyes:'bold',still:false});
+const AXIS=.41;
+const CACHE=new Map();
+const BASE_CACHE=new Map();
+function cachedBase(key,make){
+  if(BASE_CACHE.has(key))return BASE_CACHE.get(key);
+  const item=make();
+  if(BASE_CACHE.size>=16)BASE_CACHE.delete(BASE_CACHE.keys().next().value);
+  BASE_CACHE.set(key,item);
+  return item;
+}
+const clamp=(x,a,b)=>Math.min(b,Math.max(a,x));
+function hex(s){return [1,3,5].map(i=>parseInt(s.slice(i,i+2),16));}
+const TONES=Object.fromEntries(Object.entries(ART.colors).map(([k,v])=>[k,hex(v)]));
+function polygon(path){
+  if(!CACHE.has(path))CACHE.set(path,flattenPath(path));
+  return CACHE.get(path);
+}
+function circle(x,y,r){
+  const a=[];for(let k=0;k<36;k++){const th=k*Math.PI*2/36;a.push([x+Math.cos(th)*r,y+Math.sin(th)*r*.63]);}
+  return [a];
+}
+function bounds(frame){
+  let minX=frame[0].length,maxX=-1,minY=frame.length,maxY=-1,n=0;
+  for(let y=0;y<frame.length;y++)for(let x=0;x<frame[y].length;x++)
+    if(frame[y][x].ch!==' '&&frame[y][x].ch!=='\u2800'){
+      minX=Math.min(x,minX);maxX=Math.max(x,maxX);
+      minY=Math.min(y,minY);maxY=Math.max(y,maxY);n++;
+    }
+  return {minX,maxX,minY,maxY,cells:n,
+    width:n?maxX-minX+1:0,height:n?maxY-minY+1:0};
+}
+function pack(field,inks,mono){
+  // This is the production qart.js cell packer: same BR dot-order,
+  // same visual threshold, same per-cell bitmask and no invented font.
+  const rows=fieldToCells(field,{color:!mono,quant:false,tint:TONES.body});
+  if(mono)return rows.map(row=>row.map(c=>({...c,rgb:null,bg:null})));
+  const W=field.W;
+  return rows.map((row,y)=>row.map((c,x)=>{
+    if(c.ch===' ')return {...c,bg:null};
+    let winner=-1,m=0;
+    for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++){
+      const i=(y*4+dy)*W+x*2+dx;
+      if(field.v[i]>m){m=field.v[i];winner=i;}
+    }
+    const f=.28+.72*Math.min(1,m),flash=clamp(m-1,0,1);
+    const k=winner*3;
+    const rgb=[inks[k],inks[k+1],inks[k+2]]
+      .map(v=>Math.round(v*f+(255-v*f)*flash*.9));
+    return {...c,rgb,bg:null};
+  }));
+}
+function eyeGeometry(eyeVariant,scale,ox,oy,cols,rows){
+  const style=ART.eyes[eyeVariant];
+  const [[lx,ly],[rx,ry]]=style.centres;
+  const designHeight=200,Hq=scale*designHeight;
+  const axis=(lx+rx)*.5;
+  // Source-space coordinates mapped to Q's actual symmetric, even-dot eye rig.
+  // Artistic eye asymmetry is knowingly deferred for this first parity proof.
+  const geo={cols,rows,Hq,ox:ox+axis*scale-AXIS*Hq,oy};
+  const variant={...GOOGLY,
+    r:style.whiteRadius[0]/designHeight,
+    sep:(rx-lx)/(2*designHeight),
+    y:((ly+ry)/2)/designHeight,
+    pupil:style.pupil,
+    ox:1.01,oy:1.04,rim:Math.max(1,1.8*scale),
+    rest:[.45,.65],
+  };
+  return {geo,variant};
+}
+
+// Static silhouette poses are kept to a few identifiable acting beats.
+// Resting geometry is byte-for-byte the already loved A2 prototype.
+const POSES=Object.freeze(['rest','alert','brace']);
+const MOUTHS=Object.freeze(['smile','flat','roar']);
+function moved(polygons,centre,angle){
+  if(!angle)return polygons;
+  const sin=Math.sin(angle),cos=Math.cos(angle),[cx,cy]=centre;
+  return polygons.map(poly=>poly.map(([x,y])=>[
+    cx+(x-cx)*cos-(y-cy)*sin,
+    cy+(x-cx)*sin+(y-cy)*cos
+  ]));
+}
+function renderBase(cols,rows,mono,pose='rest',mouth='smile',stern=false,poseAmount=0){
+  const W=cols*2,H=rows*4;
+  const scale=Math.min((W-10)/320,(H-10)/240,.55);
+  const ox=(W-320*scale)/2,oy=(H-240*scale)/2;
+  const F=makeField(W,H);
+  const priority=new Float32Array(W*H),inks=new Uint8Array(W*H*3);
+  const apply=(polygons,colour,z,intensity=1,erase=false)=>{
+    const tone=TONES[colour]||TONES.body;
+    sampleShape(polygons,{W,H,scale,ox,oy},(x,y)=>{
+      const i=y*W+x;if(z<priority[i])return;
+      priority[i]=z;F.v[i]=erase?0:intensity;
+      inks.set(tone,i*3);
+    });
+  };
+  const stroked=(source,width,colour,z,intensity=1,erase=false)=>{
+    const tone=TONES[colour]||TONES.body;
+    sampleShape(polygon(source),{W,H,scale,ox,oy,stroke:width},(x,y)=>{
+      const i=y*W+x;if(z<priority[i])return;
+      priority[i]=z;F.v[i]=erase?0:intensity;
+      inks.set(tone,i*3);
+    });
+  };
+  // Same painter's order as Q: wings/tail first, body above, eyes last.
+  // Pose intensity is quantised into seven deterministic wing/tail poses.
+  // The eye compositor still owns its cells, and the original rest pose is
+  // exactly preserved when the incoming amount is zero.
+  const bend=Math.max(0,Math.min(1,poseAmount));
+  const wingAngle=pose==='brace'?.27*bend:pose==='alert'?.12*bend:0;
+  const tailAngle=pose==='brace'?-.15*bend:pose==='alert'?.07*bend:0;
+  apply(moved(polygon(ART.paths.wingL),[104,111],wingAngle),'wing',1,.60);
+  apply(moved(polygon(ART.paths.wingR),[202,107],-wingAngle*.83),'wing',1,.60);
+  apply(moved(polygon(ART.paths.tail),[207,180],tailAngle),'tail',2,.90);
+  apply(polygon(ART.paths.footL),'foot',2.5,.83);
+  apply(polygon(ART.paths.footR),'foot',2.5,.83);
+  apply(polygon(ART.paths.hornL),'horn',3,1);
+  apply(polygon(ART.paths.hornR),'horn',3,1);
+  apply(polygon(ART.paths.body),'body',4,1);
+  apply(polygon(ART.paths.belly),'belly',4.1,.92);
+  for(const [x,y,r] of ART.cheeks)
+    apply(circle(x,y,r),'cheek',5,1.03);
+  apply(circle(...ART.nose),'brow',6,1.1);
+  // No floating "oh lovely!" raised brows in Sentinel's serious mode.
+  // His menace comes from the SHAPE of the eyelids and eye whites themselves.
+  if(!stern){
+    stroked(ART.paths.browL,3,'brow',6,1);
+    stroked(ART.paths.browR,3,'brow',6,1);
+  }
+  const mouthPath=mouth==='flat'
+    ?'M143 165 Q158 164 174 163'
+    :mouth==='roar'?'M137 164 Q153 148 174 156 Q160 171 137 164 Z'
+    :ART.paths.mouth;
+  if(mouth==='roar')apply(polygon(mouthPath),'body',7,0,true);
+  else stroked(mouthPath,mouth==='flat'?4:5,'body',7,0,true);
+
+  const base=pack(F,inks,mono);
+  return {base,scale,ox,oy};
+}
+
+/**
+ * Deterministic pure render of the stage-2 approved-direction A solid body.
+ *
+ * We intentionally refuse the tiny width, instead of claiming that shrinking
+ * this character works at 32 columns. A separately approved icon is needed.
+ */
+export function renderSentinelPrototype(ms=1200,options={}){
+  const opts={...BASE,...options},{cols,rows}=opts;
+  if(!Number.isSafeInteger(cols)||!Number.isSafeInteger(rows)||cols<=0||rows<=0)
+    return {ok:false,code:'INVALID_VIEWPORT',reason:'Positive integer art cell dimensions required.'};
+  if(cols>200||rows>72)return {ok:false,code:'TOO_LARGE',reason:'Art grid exceeds 200×72 cells.'};
+  if(cols<48||rows<16)
+    return {ok:false,code:'ICON_FALLBACK',reason:'Sentinel A requires at least 48×16 art cells; use icon or text.'};
+  if(!['dark','light'].includes(opts.theme))
+    return {ok:false,code:'UNKNOWN_THEME',reason:'Theme must be dark or light.'};
+  if(!Object.hasOwn(ART.eyes,opts.eyes))
+    return {ok:false,code:'UNKNOWN_EYES',reason:'Use bold or islands eye study.'};
+  const pose=opts.pose??'rest',mouth=opts.mouth??'smile',stern=Boolean(opts.stern);
+  if(opts.poseAmount!==undefined&&(!Number.isFinite(opts.poseAmount)||opts.poseAmount<0||opts.poseAmount>1))
+    return {ok:false,code:'INVALID_POSE_AMOUNT',reason:'Pose amount must be between 0 and 1.'};
+  const poseAmount=opts.poseAmount===undefined?1:Math.round(opts.poseAmount*6)/6;
+  if(!POSES.includes(pose))return {ok:false,code:'UNKNOWN_POSE',reason:'Unknown Sentinel wing/tail pose.'};
+  if(!MOUTHS.includes(mouth))return {ok:false,code:'UNKNOWN_MOUTH',reason:'Unknown Sentinel mouth shape.'};
+  const cacheKey=[cols,rows,Boolean(opts.mono),pose,mouth,stern,poseAmount].join(':');
+  const {base,scale,ox,oy}=cachedBase(
+    cacheKey,()=>renderBase(cols,rows,Boolean(opts.mono),pose,mouth,stern,poseAmount)
+  );
+  const {geo,variant}=eyeGeometry(opts.eyes,scale,ox,oy,cols,rows);
+  const time=opts.still?0:Number.isFinite(ms)?Math.max(0,ms):0;
+  // EXACT original Q eyeCells and overlay, including whole-cell footprint
+  // ownership. The underlying solid body NEVER bleeds into an eye cell.
+  const warden=opts.warden;
+  const eyeLayer=warden
+    ?renderWardenEyes(geo,variant,{...warden,mono:Boolean(opts.mono)})
+    :eyeCells(geo,opts.eyeOverride??eyeState(opts.still?'open':'idle',time),variant);
+  const eyes=opts.mono?eyeLayer.map(row=>row.map(c=>c?{...c,rgb:null,bg:null}:null)):eyeLayer;
+  const frame=overlay(base,eyes).map(row=>row.map(c=>({
+    ch:c.ch,rgb:c.rgb||null,bg:null,
+  })));
+  const b=bounds(frame);
+  if(b.minX<1||b.maxX>=cols-1||b.minY<1||b.maxY>=rows-1)
+    return {ok:false,code:'ART_CLIPPED',reason:'Art touches its reserved safe margin.',bounds:b};
+  return {ok:true,frame,dragon:'Sentinel',prototype:true,
+    design:'Aegis Bean A2 · solid body',eyeVariant:opts.eyes,
+    pose,poseAmount,mouth,expression:warden?'warden':'rest',
+    cols,rows,artSize:b,scale,
+    // Snout points LEFT in the A silhouette; mouth for defensive fire must
+    // follow this geometry, not the legacy Q body's assumed mouth position.
+    anchors:{mouth:{
+      x:(ox+ART.nose[0]*scale)/2,
+      y:(oy+ART.nose[1]*scale)/4,
+    }},
+    source:ART.source,method:'qart.fieldToCells + qeyes.eyeCells/overlay',
+    diagnostics:{
+      eyeOwnedCells:eyeLayer.flat().filter(c=>c!==null).length,
+      eyeWhiteCells:eyeLayer.flat().filter(c=>c?.ch&&c.ch!==' ').length,
+      eyeCutoutCells:eyeLayer.flat().filter(c=>c?.ch===' ').length,
+    },
+  };
+}

package/vendor/dragonlab/design/stage3/sentinel-character.js

@@ -0,0 +1,257 @@
+/**
+ * SENTINEL, full-character acting rig. Stage 3, isolated prototype.
+ *
+ * All expression timing is pure / deterministic. Under threat, Sentinel's
+ * EYE WHITES become rounded triangular wedges angled inward into a V.
+ * It is NOT a surprised character with brows raised above round eyes.
+ *
+ * No security operations are performed here. "Aegis Inferno" is an
+ * explicitly-labelled, fictional DEMO unless a host supplies evidence.
+ */
+import {renderSentinelPrototype} from './sentinel-braille.js';
+import {renderPower} from '../../lib/power-effects.js';
+
+const clamp=(x,a=0,b=1)=>Math.max(a,Math.min(b,x));
+const ease=u=>{u=clamp(u);return u*u*(3-2*u);};
+const ramp=(t,a,b)=>ease((t-a)/Math.max(1,b-a));
+const approach=(a,b,u)=>a+(b-a)*clamp(u);
+
+export const SENTINEL_CLIPS=Object.freeze([
+  {id:'idle',title:'Clocktower',duration:4000,loop:true,message:'On watch'},
+  {id:'greeting',title:'Reporting In',duration:2000,message:'Sentinel attached. Ready to inspect.'},
+  {id:'scan',title:'Sweep',duration:2500,message:'Scanning'},
+  {id:'suspicious',title:'Something Moved',duration:1600,message:'Anomaly detected. Assessing.'},
+  {id:'warning',title:'Gate Warning',duration:1600,message:'Attention required'},
+  {id:'warden',title:'Warden V',duration:1500,message:'Threat confirmed. Holding position.'},
+  {id:'brace',title:'Hold the Gate',duration:2000,message:'Protective action in progress'},
+  {id:'scorch',title:'Aegis Inferno',duration:3800,message:'Aegis Inferno · demonstration only',demo:true},
+  {id:'holding',title:'Holding',duration:2400,message:'Control active; verification pending'},
+  {id:'all-clear',title:'All Clear',duration:1700,message:'Scoped result verified'},
+  {id:'failure',title:'Not Yet',duration:1500,message:'Unable to verify protection'},
+  {id:'approval',title:'Your Call',duration:2000,message:'Authorisation required'},
+  {id:'standby',title:'Low Watch',duration:3500,loop:true,message:'On standby'},
+]);
+export const SENTINEL_CLIP_IDS=Object.freeze(SENTINEL_CLIPS.map(c=>c.id));
+const CLIPS=new Map(SENTINEL_CLIPS.map(c=>[c.id,c]));
+
+// Scene pose is the character acting; effect is added only after face/wings
+// have moved. Holding/back-on-watch is a distinct posture from victory.
+function performance(scene,t){
+  const s=(a,b)=>ramp(t,a,b);
+  switch(scene){
+    case 'idle':return {pose:'rest',mouth:'smile',stern:false,
+      gaze:[Math.sin(t/900)*.28,.45],severity:0};
+    case 'greeting':return {pose:t>=420&&t<1000?'alert':'rest',
+      mouth:'smile',stern:false,gaze:[.15,-.08],severity:0,
+      softEyes:{open:1,gx:t<400?0:.22,gy:t<700?-.45:.35}};
+    case 'scan':return {pose:'rest',mouth:'flat',stern:true,
+      gaze:[Math.sin(t/460)*.85,.18],severity:.13+.08*s(350,900)};
+    case 'suspicious':{
+      const k=s(100,650);
+      return {pose:t>=500?'alert':'rest',mouth:'flat',stern:true,
+        gaze:[.42,.12],severity:.12+.54*k,
+        leftSeverity:.10+.49*k,rightSeverity:.18+.63*k};
+    }
+    case 'warning':return {pose:'alert',mouth:'flat',stern:true,
+      gaze:[.18,.05],severity:.45+.27*s(50,650)};
+    case 'warden':{
+      const k=s(120,480);
+      return {pose:t>=400?'brace':t>=170?'alert':'rest',
+        mouth:t>=420?'flat':'smile',stern:t>100,gaze:[0,.02],
+        severity:.97*k};
+    }
+    case 'brace':return {pose:t>=350?'brace':'alert',mouth:'flat',
+      stern:true,gaze:[-.5,.08],severity:.72+.26*s(90,550)};
+    case 'holding':return {pose:'brace',mouth:'flat',stern:true,
+      gaze:[-.30,.09],severity:.70};
+    case 'approval':return {pose:'rest',mouth:'flat',stern:true,
+      gaze:[-.30,.30],severity:.33,
+      leftSeverity:.25,rightSeverity:.49};
+    case 'failure':{
+      const k=s(220,750);
+      return {pose:t<850?'alert':'rest',mouth:'flat',stern:true,
+        gaze:[-.25,.60],severity:.62-.42*k,
+        leftSeverity:.55-.43*k,rightSeverity:.70-.34*k};
+    }
+    case 'standby':return {pose:'rest',mouth:'smile',stern:false,
+      gaze:[.2,.70],severity:0,
+      softEyes:{open:.50+.10*Math.sin(t/550),gx:.10,gy:.82}};
+    case 'all-clear':{
+      const release=s(230,980);
+      return {pose:t<1100?'brace':'rest',
+        mouth:t<500?'flat':'smile',stern:t<950,
+        gaze:[-.25+release*.42,.38],
+        severity:.95*(1-release)};
+    }
+    case 'scorch':{
+      const intent=s(340,760);
+      const recover=s(2920,3620);
+      const fire=t>=1850&&t<2790;
+      return {
+        pose:t>=800&&t<3650?'brace':t>=350&&t<800?'alert':'rest',
+        mouth:fire?'roar':t>=350&&t<3400?'flat':'smile',
+        stern:t>=320&&t<3600,
+        gaze:[-.64*intent+.25*recover,.13],
+        severity:Math.max(0,Math.min(.97,intent*.97)*(1-.8*recover)),
+        // A brief narrowed glare at the peak; eyes are NEVER blank for
+        // the entire flame. The V look comes before the fire begins.
+        openness:fire&&t>=2210&&t<2310?.64:1,
+      };
+    }
+    default:throw new RangeError('Unrecognised Sentinel clip: '+scene);
+  }
+}
+
+/**
+ * Smoothly animate two small wing rotations without introducing continuous
+ * non-deterministic geometry churn. The rest A2 art remains the canonical
+ * untouched pose. Transition from alert's 0.12 radians to brace's 0.27
+ * radians uses a matching 0.12 / 0.27 bridge, so pose changes don't snap.
+ */
+function posture(scene,t,pose){
+  if(pose==='rest')return 0;
+  if(scene==='greeting')return ramp(t,420,630)*(1-ramp(t,780,990));
+  if(scene==='scan')return .2;
+  if(scene==='suspicious')return ramp(t,500,1000);
+  if(scene==='warning')return ramp(t,0,400);
+  if(scene==='approval')return .2;
+  if(scene==='failure')return 1-ramp(t,350,840);
+  if(scene==='warden')return pose==='alert'
+    ?ramp(t,170,390)
+    :.45+.55*ramp(t,400,760);
+  if(scene==='brace')return pose==='alert'
+    ?ramp(t,0,345)
+    :.45+.55*ramp(t,350,800);
+  if(scene==='holding')return 1;
+  if(scene==='all-clear')return 1-ramp(t,200,1040);
+  if(scene==='scorch'){
+    if(pose==='alert')return ramp(t,350,795);
+    return (.45+.55*ramp(t,800,1350))*(1-ramp(t,3180,3610));
+  }
+  return 1;
+}
+
+const FRAME_BYTES=200*72*4;
+function checkFrame(frame,cols,rows){
+  if(!Array.isArray(frame)||frame.length!==rows||
+      frame.some(row=>!Array.isArray(row)||row.length!==cols))
+    return 'NON_RECTANGULAR_FRAME';
+  if(frame.flat().some(c=>!c||typeof c.ch!=='string'||c.bg!=null))
+    return 'INVALID_CELL_OR_BACKGROUND';
+  return null;
+}
+
+/**
+ * renderSentinelCharacter(scene, t, options)
+ *
+ * - Usable from a normal Quox CLI conversation art slot.
+ * - No global clocks, networking, user data, DOM, filesystem or timers.
+ * - Returns structured error and icon fallback below 48x16.
+ * - Always returns visualOnly:true, even for serious expressions.
+ * - No victory / all-clear implied by this renderer without host evidence.
+ */
+export function renderSentinelCharacter(scene='idle',ms=0,options={}){
+  const clip=CLIPS.get(scene);
+  if(!clip)return {ok:false,code:'UNKNOWN_CLIP',
+    reason:'Unknown Sentinel clip: '+String(scene),available:SENTINEL_CLIP_IDS};
+  const {cols=88,rows=25,mono=false,still=false,theme='dark',eyes='bold'}=options;
+  // LAB by default. A host may opt into real-status rendering ONLY with
+  // scoped evidence from its own verified execution engine.
+  const demo=options.demo!==false;
+  if(!demo&&scene==='all-clear'&&!(options.evidence?.verified===true&&
+       typeof options.evidence?.scope==='string'&&options.evidence.scope.trim()))
+    return {ok:false,code:'EVIDENCE_REQUIRED',
+      reason:'All Clear requires scoped, independently verified evidence.'};
+  if(!demo&&scene==='scorch'&&!(options.evidence?.approved===true&&
+       options.evidence?.verified===true))
+    return {ok:false,code:'EVIDENCE_REQUIRED',
+      reason:'Scorch in real-status mode requires approved, verified protective action.'};
+  if(!Number.isSafeInteger(cols)||!Number.isSafeInteger(rows)||cols<=0||rows<=0)
+    return {ok:false,code:'INVALID_VIEWPORT',reason:'Positive integer art dimensions required.'};
+  if(cols>200||rows>72)return {ok:false,code:'TOO_LARGE',
+    reason:'Maximum art budget is 200 by 72 cells.'};
+  if(cols<48||rows<16)return {ok:false,code:'ICON_FALLBACK',
+    reason:'At this size show a Sentinel face icon or a labelled text status.'};
+  let time=Number.isFinite(ms)?Math.max(0,ms):0;
+  if(still)time=scene==='scorch'?1580:
+    ['warden','brace','holding'].includes(scene)?930:Math.min(clip.duration*.55,2000);
+  else time=clip.loop?time%clip.duration:Math.min(time,clip.duration);
+  const p=performance(scene,time);
+  const mode=p.severity<=0?null:{
+    intensity:clamp(p.severity),gx:p.gaze[0],gy:p.gaze[1],
+    open:p.openness??1,
+    ...(p.leftSeverity===undefined?{}:{leftIntensity:p.leftSeverity}),
+    ...(p.rightSeverity===undefined?{}:{rightIntensity:p.rightSeverity}),
+  };
+  const base=renderSentinelPrototype(time,{
+    cols,rows,mono,still,theme,eyes,
+    pose:p.pose,poseAmount:posture(scene,time,p.pose),
+    mouth:p.mouth,stern:p.stern,
+    eyeOverride:p.softEyes??null,warden:mode
+  });
+  if(!base.ok)return base;
+  let frame=base.frame;
+  let effectPhase=null;
+  if(scene==='scorch'){
+    // Mapping aligns existing proven blue-shield/breath overlays with
+    // character beats: NOTICE -> JUDGE -> BRACE -> IMPACT -> SCORCH ->
+    // RECHECK. No action, exploit or mitigation command is executed.
+    const effectTime=time<350?time*.85:
+      time<750?300+(time-350)*.7:
+      time<1350?580+(time-750)*.7:
+      time<1850?1000+(time-1350)*.9:
+      time<2750?1500+(time-1850)*1.38:
+      time<3250?2750+(time-2750):
+      3250+(time-3250);
+    const mouth=base.anchors?.mouth??null;
+    frame=renderPower('power-sentinel',effectTime,frame,
+      {mono,theme,anchors:mouth?{mouth}:null,still:false});
+    effectPhase=time<350?'notice':time<750?'judge':
+      time<1350?'brace':time<1850?'impact':
+      time<2750?'scorch':time<3250?'recheck':'resolve';
+  }
+  const err=checkFrame(frame,cols,rows);
+  if(err)return {ok:false,code:err,reason:'Prototype emitted an invalid art rectangle.'};
+  const descriptor=demo?'DEMO · '+clip.message:clip.message;
+  return {
+    ...base,frame,
+    scene,clip:clip.title,time,duration:clip.duration,
+    pose:p.pose,poseAmount:base.poseAmount,
+    eyesShape:mode?'rounded-triangular-V':'Q-original-round',
+    expressionIntensity:mode?.intensity??0,
+    effectPhase,visualOnly:true,
+    demo,
+    verified:!demo&&options.evidence?.verified===true,
+    scope:!demo?(options.evidence?.scope??null):null,
+    accessibleLabel:'Sentinel · '+descriptor,
+    caption:descriptor,
+  };
+}
+
+/**
+ * Optional host adapter, NOT an instruction to run an operation.
+ * The visual state follows independently provided evidence; raw detection
+ * never authorizes a victorious smile or a completed fire effect.
+ */
+export function sentinelSceneForEvent(event={}){
+  const status=event.status??'idle';
+  switch(status){
+    case 'attached':return {scene:'greeting',label:'Ready to inspect'};
+    case 'scanning':return {scene:'scan',label:'Scan running'};
+    case 'anomaly':return {scene:'suspicious',label:'Anomaly under investigation'};
+    case 'warning':return {scene:'warning',label:'Attention required'};
+    case 'threat-confirmed':
+      return {scene:event.confirmed===true?'warden':'suspicious',
+        label:event.confirmed===true?'Threat confirmed':'Suspicious event'};
+    case 'approval-required':return {scene:'approval',label:'Authorisation required'};
+    case 'mitigation-running':return {scene:'brace',label:'Protective action in progress'};
+    case 'containment-unverified':return {scene:'holding',label:'Verification pending'};
+    case 'mitigation-verified':
+      if(event.verified===true&&typeof event.scope==='string'&&event.scope.trim())
+        return {scene:'all-clear',label:'Verified for '+event.scope.trim()};
+      return {scene:'holding',label:'Outcome not verified'};
+    case 'failed':case 'unknown':return {scene:'failure',label:'Protection not verified'};
+    case 'standby':return {scene:'standby',label:'Standby'};
+    default:return {scene:'idle',label:'Sentinel on watch (no security conclusion)'};
+  }
+}