quoxcli 0.2.0 → 0.4.0

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

@@ -0,0 +1,103 @@
+/**
+ * Original Sentinel shield-face icon at small terminal art sizes.
+ * Source: design/stage2/refinement/sentinel-a-tiny-shield-icon.svg.
+ *
+ * This is deliberately separate icon geometry, not a crushed full dragon.
+ * SVG paths are resampled to 2×4 Braille dots using the actual qart packer.
+ * No backgrounds, no terminal control codes, deterministic in colour/mono.
+ */
+import {makeField,fieldToCells} from '../../vendor/quox-dragon/qart.js';
+import {flattenPath,sampleShape} from './svg-coverage.js';
+
+const SHAPE=Object.freeze({
+  leftHorn:'M12 15 Q9 12 10 4 Q15 7 17 13 Z',
+  rightHorn:'M31 13 Q36 8 37 4 Q40 12 37 17 Z',
+  shield:'M9 14 Q23 7 39 14 L37 28 Q34 40 24 44 Q13 39 10 28 Z',
+  smile:'M20 35 Q24 38 28 34',
+});
+const rgba={
+  horn:[141,218,255],body:[87,153,238],rim:[20,39,68],
+  eye:[255,253,246],cheek:[250,147,183],
+};
+function ellipse(cx,cy,rx,ry){
+  const pts=[];
+  for(let k=0;k<72;k++){const th=k*Math.PI*2/72;pts.push([cx+rx*Math.cos(th),cy+ry*Math.sin(th)]);}
+  return [pts];
+}
+function mask(renderer,source,paint,stroke=0){
+  renderer(source,paint,stroke);
+}
+function showBounds(frame){
+  let x0=Infinity,x1=-1,y0=Infinity,y1=-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'){
+      n++;x0=Math.min(x0,x);x1=Math.max(x1,x);y0=Math.min(y0,y);y1=Math.max(y1,y);
+    }
+  return n?{x0,x1,y0,y1,cells:n}:null;
+}
+export function renderSentinelIcon({cols=16,rows=8,mono=false,mood='cute'}={}){
+  if(!Number.isSafeInteger(cols)||!Number.isSafeInteger(rows)||cols<=0||rows<=0)
+    return {ok:false,code:'INVALID_VIEWPORT',reason:'Icon viewport needs positive cell dimensions.'};
+  if(cols>200||rows>72)return {ok:false,code:'TOO_LARGE',reason:'Icon viewport exceeds supported limit.'};
+  if(cols<12||rows<6)return {ok:false,code:'TEXT_FALLBACK',reason:'Use a shield symbol plus Sentinel label.'};
+  if(!['cute','alert','warden'].includes(mood))
+    return {ok:false,code:'UNKNOWN_MOOD',reason:'Icon mood must be cute, alert or warden.'};
+  const W=cols*2,H=rows*4;
+  const scale=Math.min((W-4)/48,(H-4)/48,1.5);
+  const ox=(W-48*scale)/2,oy=(H-48*scale)/2;
+  const field=makeField(W,H),layers=new Float32Array(W*H),rgb=new Uint8Array(W*H*3);
+  const stamp=(polys,color,z,erase=false,stroke=0)=>{
+    sampleShape(polys,{W,H,scale,ox,oy,stroke},(x,y)=>{
+      const p=y*W+x;if(z<layers[p])return;
+      layers[p]=z;field.v[p]=erase?0:1;
+      if(!erase)rgb.set(color,p*3);
+    });
+  };
+  const P=(p)=>flattenPath(p);
+  stamp(P(SHAPE.leftHorn),rgba.horn,1);
+  stamp(P(SHAPE.rightHorn),rgba.horn,1);
+  stamp(P(SHAPE.shield),rgba.body,2);
+  const angry=mood==='warden',watch=mood!=='cute';
+  for(const [cx,cy,rx,ry,px,py] of [
+    [18,23,5.7,6.8,20,23],[31,23,5.2,6.2,33,23],
+  ]){
+    // Physical dark margin must cut out the solid body first. Whole Braille
+    // cells containing white eyes are given eye-only colour ownership below.
+    stamp(ellipse(cx,cy,rx+1.0,ry+1.0),rgba.rim,3,true);
+    stamp(ellipse(cx,cy,rx,ry),rgba.eye,4);
+    stamp(ellipse(px,py+(watch?.5:0),angry?2.2:2.4,angry?3.0:3.3),rgba.rim,5,true);
+    if(angry){
+      // The tiny expression follows the same inward-V white cut,
+      // only after the stronger eye white has been drawn.
+      const side=cx<25?-1:1;
+      const triangle=[];
+      for(let x=0;x<8;x++){
+        const outside=cx+side*(-rx+x*.92);
+        triangle.push([outside,cy-ry-.2+(7-x)*.42]);
+      }
+      stamp([triangle],rgba.rim,6,true);
+    }
+  }
+  if(mood==='cute')stamp(P(SHAPE.smile),rgba.rim,6,true,1.5);
+  else stamp(P('M20 35 L28 35'),rgba.rim,6,true,1.4);
+
+  const frame=fieldToCells(field,{color:false,quant:false,tint:rgba.body});
+  // Recolour complete Braille cells based on the majority surviving pixels.
+  // Unlike direct stacking, there can be no blue body ink in an eye-white
+  // terminal cell. Mono reproduces the exact same dot mask.
+  for(let cy=0;cy<rows;cy++)for(let cx=0;cx<cols;cx++){
+    const cell=frame[cy][cx];cell.bg=null;
+    if(mono||cell.ch===' '){cell.rgb=null;continue;}
+    const counts=new Map();
+    for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++){
+      const p=(cy*4+dy)*W+cx*2+dx;
+      if(field.v[p]<=0)continue;
+      const c=[rgb[p*3],rgb[p*3+1],rgb[p*3+2]].join(',');
+      counts.set(c,(counts.get(c)||0)+1);
+    }
+    const color=[...counts].sort((a,b)=>b[1]-a[1])[0]?.[0];
+    cell.rgb=color?color.split(',').map(Number):rgba.body;
+  }
+  return {ok:true,frame,cols,rows,icon:true,mood,source:'stage2/refinement/sentinel-a-tiny-shield-icon.svg',
+    bounds:showBounds(frame),visualOnly:true};
+}

package/vendor/dragonlab/design/stage3/sentinel-warden-eyes.js

@@ -0,0 +1,95 @@
+/**
+ * Sentinel-specific "Warden V" face rig.
+ *
+ * Resting eyes continue to use the EXACT canonical Q eyeCells().
+ * During action, dot whites turn into rounded triangular shields whose TOP
+ * EDGES descend toward the bridge. No floating shocked / raised eyebrows.
+ *
+ * Deliberately preserves qeyes' most important rule: an eye owns WHOLE
+ * terminal cells, including its dark pupil and empty eyelid cut-outs.
+ * Sentinel additions remain pure functions of time / geometry; no globals.
+ */
+import {eyeCells,EYE_WHITE} from '../../vendor/quox-dragon/qeyes.js';
+
+const BR=[[1,8],[2,16],[4,32],[64,128]];
+const clamp=(n,a=0,b=1)=>Math.max(a,Math.min(b,n));
+
+export function renderWardenEyes(geo,variant,{
+  intensity=0, leftIntensity=null,rightIntensity=null,
+  gx=0,gy=.25,open=1, mono=false
+}={}){
+  const {cols,rows,Hq}=geo;
+  const valid=Number.isFinite(Hq)&&Hq>0&&
+    Number.isSafeInteger(cols)&&Number.isSafeInteger(rows)&&cols>0&&rows>0;
+  if(!valid)throw new RangeError('Invalid Sentinel eye geometry.');
+  const severity=clamp(Number.isFinite(intensity)?intensity:0);
+  if(severity===0&&leftIntensity==null&&rightIntensity==null){
+    // The familiar resting Sentinel look is real Quox art, unchanged.
+    const original=eyeCells(geo,{open:clamp(open),gx,gy},variant);
+    return original.map(row=>row.map(cell=>cell?
+      {ch:cell.ch,rgb:mono?null:cell.rgb,bg:null}:null));
+  }
+  const W=cols*2,H=rows*4;
+  const axis=2*Math.round((geo.ox+.41*Hq)/2);
+  const sep=2*Math.ceil(variant.sep*Hq/2);
+  const R=variant.r*Hq,cy=(geo.oy??0)+variant.y*Hq;
+  const lit=new Uint8Array(W*H),foot=new Uint8Array(cols*rows);
+  let visible=0;
+  const eyes=[
+    {side:-1,cx:axis-sep,level:clamp(leftIntensity??severity)},
+    {side:1,cx:axis+sep,level:clamp(rightIntensity??severity)}
+  ];
+  for(const {side,cx,level} of eyes){
+    const rx=R*variant.ox,ry=R*variant.oy;
+    const lean=level*0.72; // angled down *toward the bridge*
+    const lo=Math.floor(cx-rx-2),hi=Math.ceil(cx+rx+2);
+    const ty=Math.max(0,Math.floor(cy-ry-2)),by=Math.min(H-1,Math.ceil(cy+ry+2));
+    const pupilRadius=Math.max(1.1,R*variant.pupil*(1-level*.24));
+    const pupilX=cx+clamp(gx,-1,1)*Math.max(0,rx-pupilRadius-1)*.48;
+    const pupilY=cy+clamp(gy,-1,1)*Math.max(0,ry-pupilRadius-1)*.48+level*ry*.18;
+    for(let y=ty;y<=by;y++)for(let x=Math.max(0,lo);x<=Math.min(W-1,hi);x++){
+      const u=(x+.5-cx)/rx;
+      if(Math.abs(u)>1)continue;
+      const v=Math.sqrt(Math.max(0,1-u*u));
+      const inner=-side*u; // LEFT inner edge is right, RIGHT inner edge is left
+      const top=cy-ry*v+lean*ry*(.18+.42*clamp((inner+1)/2));
+      const bottom=cy+ry*v*(1-level*.14);
+      const yy=y+.5;
+      const inRoundEye=yy>=top-1.2&&yy<=bottom+1.1;
+      if(inRoundEye)foot[Math.floor(y/4)*cols+Math.floor(x/2)]=1;
+      if(yy<top||yy>bottom||clamp(open)<.12)continue;
+      // Keep an upper bright ridge, even for the severest glare.
+      const ridge=yy-top<1.15;
+      const dist=Math.hypot((x+.5-pupilX), (yy-pupilY));
+      const pupil=!ridge&&dist<pupilRadius;
+      const shine=pupil&&
+        Math.abs(x+.5-(pupilX-pupilRadius*.30))<.9&&
+        Math.abs(yy-(pupilY-pupilRadius*.40))<.9&&
+        pupilRadius>2.7;
+      if(!pupil||shine){
+        lit[y*W+x]=1;visible++;
+      }
+    }
+    // Cell-level margin: no solid blue body allowed to flood an eye's edge.
+    // The body is allowed around the two eyes but never inside either one.
+    for(let r=Math.max(0,Math.floor((cy-ry-2)/4));r<=Math.min(rows-1,Math.ceil((cy+ry+2)/4));r++)
+      for(let c=Math.max(0,Math.floor((cx-rx-2)/2));c<=Math.min(cols-1,Math.ceil((cx+rx+2)/2));c++){
+        const x=c*2+1,y=r*4+2;
+        if(((x-cx)/(rx+1.0))**2+((y-cy)/(ry+1.0))**2<=1)
+          foot[r*cols+c]=1;
+      }
+  }
+  const output=[];
+  for(let row=0;row<rows;row++){
+    const cells=[];
+    for(let col=0;col<cols;col++){
+      let bits=0;
+      for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++)
+        if(lit[(row*4+dy)*W+col*2+dx])bits|=BR[dy][dx];
+      cells.push(bits?{ch:String.fromCodePoint(0x2800+bits),rgb:mono?null:EYE_WHITE,bg:null}:
+        foot[row*cols+col]?{ch:' ',rgb:null,bg:null}:null);
+    }
+    output.push(cells);
+  }
+  return output;
+}

package/vendor/dragonlab/design/stage3/svg-coverage.js

@@ -0,0 +1,148 @@
+/**
+ * Tiny, deterministic absolute SVG path parser and 2x2-coverage shape helper.
+ * Only M/L/H/V/C/Q/Z are accepted; unsupported commands fail closed.
+ * No DOM, browser APIs, canvas dependency, third-party SVG parser or I/O.
+ *
+ * Unlike naive point-stamping, all fills are tested at sub-dot offsets identical
+ * to Quox's 2x2 vector->Braille rasterisation in qart.js and qdragon.js.
+ */
+const TOKEN=/[MLHVCQZ]|[-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?/g;
+const CMD=/^[MLHVCQZ]$/;
+const PTS=[0.25,0.75];
+
+export function flattenPath(source){
+  if(typeof source!=='string'||source.length>24000)
+    throw new TypeError('A path must be a short SVG path string.');
+  const tokens=source.match(TOKEN)||[];
+  // Reject SVG commands we have not deliberately implemented, including
+  // arc and relative-path syntax. Silently skipping them corrupts the art.
+  if(source.replace(TOKEN,'').replace(/[\s,]/g,'')!=='')
+    throw new RangeError('Unsupported SVG path command or syntax.');
+  if(!tokens.length||tokens[0]!=='M')throw new RangeError('Path must start with absolute M.');
+  const polygons=[];let poly=[],point=[0,0],start=[0,0],i=0,cmd=null,loops=0;
+  const take=()=>{
+    const v=tokens[i++];
+    if(v===undefined||CMD.test(v))throw new RangeError('Invalid SVG numeric argument.');
+    const n=Number(v);if(!Number.isFinite(n))throw new RangeError('Invalid SVG numeric coordinate.');
+    return n;
+  };
+  const push=(p)=>{point=p;poly.push(p);};
+  while(i<tokens.length){
+    if(++loops>20000)throw new RangeError('SVG path command limit reached.');
+    if(CMD.test(tokens[i]))cmd=tokens[i++];
+    if(!cmd)throw new RangeError('Unexpected coordinate before command.');
+    if(cmd==='M'){
+      if(poly.length>2)polygons.push(poly);
+      poly=[];start=[take(),take()];push(start);cmd='L';continue;
+    }
+    if(cmd==='L'){push([take(),take()]);continue;}
+    if(cmd==='H'){push([take(),point[1]]);continue;}
+    if(cmd==='V'){push([point[0],take()]);continue;}
+    if(cmd==='Q'){
+      const a=point,b=[take(),take()],c=[take(),take()];
+      const n=24;
+      for(let j=1;j<=n;j++){
+        const u=j/n,v=1-u;
+        push([v*v*a[0]+2*v*u*b[0]+u*u*c[0],
+          v*v*a[1]+2*v*u*b[1]+u*u*c[1]]);
+      }
+      continue;
+    }
+    if(cmd==='C'){
+      const a=point,b=[take(),take()],c=[take(),take()],d=[take(),take()];
+      const n=36;
+      for(let j=1;j<=n;j++){
+        const u=j/n,v=1-u;
+        push([v*v*v*a[0]+3*v*v*u*b[0]+3*v*u*u*c[0]+u*u*u*d[0],
+          v*v*v*a[1]+3*v*v*u*b[1]+3*v*u*u*c[1]+u*u*u*d[1]]);
+      }
+      continue;
+    }
+    if(cmd==='Z'){
+      if(poly.length>=3)polygons.push(poly);
+      poly=[];point=start;cmd=null;continue;
+    }
+    throw new RangeError('SVG command not supported: '+cmd);
+  }
+  if(poly.length>=2)polygons.push(poly);
+  if(!polygons.length)throw new RangeError('SVG path has no drawable coordinates.');
+  return polygons;
+}
+
+export function inside(polygons,x,y){
+  let yes=false;
+  for(const poly of polygons){
+    for(let i=0,j=poly.length-1;i<poly.length;j=i++){
+      const [ax,ay]=poly[i],[bx,by]=poly[j];
+      if((ay>y)!==(by>y)&&x<(bx-ax)*(y-ay)/(by-ay)+ax)yes=!yes;
+    }
+  }
+  return yes;
+}
+
+function segmentDistSq(px,py,ax,ay,bx,by){
+  const dx=bx-ax,dy=by-ay,dd=dx*dx+dy*dy;
+  const t=dd?Math.max(0,Math.min(1,((px-ax)*dx+(py-ay)*dy)/dd)):0;
+  const a=px-(ax+dx*t),b=py-(ay+dy*t);
+  return a*a+b*b;
+}
+export function nearStroke(polygons,x,y,width){
+  const radius=width*.5,limit=radius*radius;
+  for(const poly of polygons)
+    for(let i=1;i<poly.length;i++)
+      if(segmentDistSq(x,y,...poly[i-1],...poly[i])<=limit)return true;
+  return false;
+}
+
+/**
+ * Callback receives target dot x/y only if >=2 of the same four supersamples
+ * that the production Q uses lie within the source-space predicate.
+ */
+export function sampleShape(polygons,{W,H,scale,ox,oy,stroke=0},put){
+  const points=polygons.flat();
+  const xx=points.map(p=>p[0]),yy=points.map(p=>p[1]);
+  const guard=stroke?stroke*.5+1:1;
+  const x0=Math.max(1,Math.floor(ox+(Math.min(...xx)-guard)*scale)-1);
+  const x1=Math.min(W-2,Math.ceil(ox+(Math.max(...xx)+guard)*scale)+1);
+  const y0=Math.max(1,Math.floor(oy+(Math.min(...yy)-guard)*scale)-1);
+  const y1=Math.min(H-2,Math.ceil(oy+(Math.max(...yy)+guard)*scale)+1);
+  if(stroke){
+    // Short brows and mouth outlines still use the straightforward
+    // segment-distance test, which is exact for these narrow contours.
+    for(let y=y0;y<=y1;y++)for(let x=x0;x<=x1;x++){
+      let n=0;
+      for(const sy of PTS)for(const sx of PTS)
+        if(nearStroke(polygons,(x+sx-ox)/scale,(y+sy-oy)/scale,stroke))n++;
+      if(n>=2)put(x,y);
+    }
+    return;
+  }
+  // Scanline fill: EXACTLY the same even/odd polygon rule and four sample
+  // locations, but calculate intersections once per sub-dot row instead of
+  // walking hundreds of SVG edges for every single dot. This dramatically
+  // reduces cold-frame latency while preserving the original Q 2x2 coverage.
+  const width=x1-x0+1,counts=new Uint8Array(width*(y1-y0+1));
+  const edges=[];
+  for(const poly of polygons)for(let i=0,j=poly.length-1;i<poly.length;j=i++){
+    const [ax,ay]=poly[j],[bx,by]=poly[i];
+    if(ay===by)continue;
+    edges.push([ax,ay,(bx-ax)/(by-ay),Math.min(ay,by),Math.max(ay,by)]);
+  }
+  for(let y=y0;y<=y1;y++)for(const sy of PTS){
+    const ys=(y+sy-oy)/scale;
+    const crosses=[];
+    for(const [ax,ay,slope,lo,hi] of edges)
+      if(ys>=lo&&ys<hi)crosses.push(ox+(ax+(ys-ay)*slope)*scale);
+    crosses.sort((a,b)=>a-b);
+    for(let i=0;i+1<crosses.length;i+=2){
+      const a=crosses[i],b=crosses[i+1];
+      for(const sx of PTS){
+        const start=Math.max(x0,Math.ceil(a-sx));
+        const end=Math.min(x1,Math.ceil(b-sx)-1);
+        for(let x=start;x<=end;x++)counts[(y-y0)*width+x-x0]++;
+      }
+    }
+  }
+  for(let y=y0;y<=y1;y++)for(let x=x0;x<=x1;x++)
+    if(counts[(y-y0)*width+x-x0]>=2)put(x,y);
+}

package/vendor/dragonlab/factory/svg-rig.mjs

@@ -0,0 +1,63 @@
+/** Shared authored SVG → original Q cells, supporting independently owned eyes. */
+import {flattenPath,sampleShape} from '../design/stage3/svg-coverage.js';
+import {makeField,fieldToCells} from '../vendor/quox-dragon/qart.js';
+const attr=(s,k)=>s.match(new RegExp(`(?:^|\\s)${k}="([^"]*)"`))?.[1];
+export function parseSvgRig(svg){
+ if(!svg.includes('viewBox="0 0 800 480"'))throw Error('Expected authored 800x480 master');
+ const ids=new Set(),groups=new Map(),stack=[];
+ for(const [tag]of svg.matchAll(/<g\s[^>]*>|<\/g>|<path\s[^>]*\/>/g)){
+  if(tag.startsWith('<g '))stack.push(attr(tag,'id'));else if(tag==='</g>')stack.pop();else groups.set(attr(tag,'id'),stack.at(-1));
+ }
+ const paths=[...svg.matchAll(/<path\s[^>]*\/>/g)].map(([tag])=>{
+  const id=attr(tag,'id'),d=attr(tag,'d'),stroke=attr(tag,'stroke'),fill=attr(tag,'fill');
+  if(!id||ids.has(id)||!d)throw Error('Every path requires unique id and geometry');ids.add(id);
+  const colour=stroke||fill;if(!/^#[0-9a-f]{6}$/i.test(colour))throw Error('Explicit hex colour required');
+  const width=stroke?Number(attr(tag,'stroke-width')):0;
+  if(!Number.isFinite(width)||width<0||width>30)throw Error('Invalid stroke width');
+  return {id,group:groups.get(id),polygons:flattenPath(d),rgb:[1,3,5].map(i=>parseInt(colour.slice(i,i+2),16)),stroke:width,erase:colour==='#080d19'};
+ });
+ const eyes=paths.filter(p=>p.id.endsWith('-eye-socket')).map(p=>{
+  const name=p.id.slice(0,-11),white=paths.find(p=>p.id===name+'-eye-white'),pupil=paths.find(p=>p.id===name+'-pupil');
+  if(!white||!pupil)throw Error('Every eye needs white and pupil');return {name,socket:p,white,pupil};
+ });
+ if(!paths.length||!eyes.length)throw Error('Missing anatomy or eyes');
+ const points=paths.flatMap(p=>p.polygons.flat());
+ const x=points.map(p=>p[0]),y=points.map(p=>p[1]);
+ return {paths,eyes,bounds:{left:Math.min(...x),top:Math.min(...y),right:Math.max(...x),bottom:Math.max(...y)}};
+}
+export function renderSvgRig(rig,{cols=39,rows=11,mono=false}={}){
+ if(!Number.isSafeInteger(cols)||!Number.isSafeInteger(rows)||cols<28||rows<10||cols>200||rows>72)throw RangeError('Art needs 28–200 columns and 10–72 rows');
+ if(typeof mono!=='boolean')throw TypeError('mono must be boolean');
+ const W=cols*2,H=rows*4,{left,top,right,bottom}=rig.bounds;
+ const scale=Math.min((W-4)/(right-left),(H-4)/(bottom-top));
+ const geometry={W,H,scale,ox:(W-(right-left)*scale)/2-left*scale,oy:(H-(bottom-top)*scale)/2-top*scale};
+ const field=makeField(W,H),labels=new Array(W*H).fill(''),colour=new Array(W*H).fill(null);
+ const coverage=p=>{const indices=[];sampleShape(p.polygons,{...geometry,stroke:p.stroke},(x,y)=>indices.push(y*W+x));return indices;};
+ const eyeIds=new Set(rig.eyes.flatMap(e=>[e.socket.id,e.white.id,e.pupil.id]));
+ function paint(p){for(const i of coverage(p)){field.v[i]=p.erase?0:1;labels[i]=p.id;colour[i]=p.rgb;}}
+ for(const p of rig.paths)if(!eyeIds.has(p.id))paint(p);
+ // Clear all eye-owned cells FIRST, so the far eye cannot erase the near eye.
+ const owned=new Set();
+ for(const e of rig.eyes)for(const i of coverage(e.socket))owned.add(Math.floor(i%W/2)+Math.floor(Math.floor(i/W)/4)*cols);
+ for(const cell of owned){const x=cell%cols*2,y=Math.floor(cell/cols)*4;for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++){const i=(y+dy)*W+x+dx;field.v[i]=0;labels[i]='';colour[i]=null;}}
+ const pupilDots={};
+ for(const e of rig.eyes){
+  paint(e.white);let dots=coverage(e.pupil);
+  if(!dots.length){
+   // Optical correction is local to THIS eye; no Lucid-specific coordinates.
+   const points=e.pupil.polygons.flat(),cx=points.reduce((n,p)=>n+p[0],0)/points.length,cy=points.reduce((n,p)=>n+p[1],0)/points.length;
+   let best=-1,d=Infinity;
+   for(let i=0;i<labels.length;i++)if(labels[i]===e.white.id&&field.v[i]){const q=(i%W+.5-(geometry.ox+cx*scale))**2+(Math.floor(i/W)+.5-(geometry.oy+cy*scale))**2;if(q<d){best=i;d=q;}}
+   if(best>=0)dots=[best];
+  }
+  for(const i of dots){field.v[i]=0;labels[i]=e.pupil.id;colour[i]=null;}
+  pupilDots[e.name]=dots.length;
+ }
+ const frame=fieldToCells(field,{color:false,quant:false});let ink=0;
+ for(let y=0;y<rows;y++)for(let x=0;x<cols;x++){
+  const c=frame[y][x];c.bg=null;c.rgb=null;let chosen=-1,rank=-1;
+  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])continue;const r=labels[i].endsWith('-eye-white')?2:1;if(r>rank){rank=r;chosen=i;}}
+  if(chosen>=0){ink++;if(!mono)c.rgb=[...colour[chosen]];}
+ }
+ return {ok:true,frame,geometry,metrics:{cols,rows,ink,pupilDots,eyeOwnedCells:owned.size},visualOnly:true,demo:true};
+}

package/vendor/dragonlab/integration/companions-v1/characters.mjs

@@ -0,0 +1,88 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {activityView as baseView} from '../hyperion-v3/activity.mjs';
+
+export const CHARACTERS=Object.freeze({
+  lucid:{name:'Lucid',version:'recovery V5',review:'../../design/lucid/recovery/review.mjs',power:'sweep',powerName:'Horizon Sweep',powerDuration:3200,arrival:{scene:'attach',duration:3200}},
+  hyperion:{name:'Hyperion',version:'V2 acting',review:'../../design/hyperion/v2/review.mjs',power:'cluster',powerName:'Cluster Forge',powerDuration:4800,arrival:{scene:'attach',duration:3400}},
+  seer:{name:'Seer',version:'V4 flowing eight',review:'../../design/seer/v4/review.mjs',power:'pattern',powerName:'Pattern Sight',powerDuration:5200,arrival:{scene:'swim',duration:5800}},
+  sentinel:{name:'Sentinel',version:'A solid (provisional)',review:'../../design/stage3/companion-review.mjs',power:'scorch',powerName:'Aegis Inferno',powerDuration:3800,arrival:{scene:'greeting',duration:2400}},
+  cipher:{name:'Cipher',version:'V2 network acting',review:'../../design/cipher/v2/review.mjs',power:'trace',powerName:'Trace Route',powerDuration:4800,arrival:{scene:'attach',duration:3200}},
+  drago:{name:'Drago',version:'V4 scoped inferno',review:'../../design/drago/v4/review.mjs',power:'fire',powerName:'Scoped Inferno',powerDuration:6800,arrival:{scene:'attach',duration:3800}},
+});
+const ids=Object.keys(CHARACTERS);
+// Host scene -> art clip. Sentinel never shows 'all-clear' (needs verified evidence); Drago has no 'proud'/'curious'/'focus' clips.
+const SCENES=Object.freeze({
+  sentinel:{curious:'scan',focus:'scan',concerned:'failure',proud:'idle'},
+  // Cipher claims no network facts: 'restored'/'delay'/'broken' routes are simulated, so completion stays on plain listening.
+  cipher:{curious:'inspect',focus:'inspect',standby:'idle',concerned:'broken',proud:'idle'},
+  drago:{curious:'inspect',focus:'active',concerned:'concerned',proud:'acknowledge'},
+});
+const SENTINEL_MOOD=Object.freeze({idle:'cute',greeting:'cute',standby:'cute',scan:'alert',approval:'alert',failure:'alert',warden:'warden',brace:'warden',scorch:'warden'});
+export function character(id){
+  if(!Object.hasOwn(CHARACTERS,id))throw new Error(`Choose ${ids.slice(0,-1).join(', ')} or ${ids.at(-1)}.`);
+  return CHARACTERS[id];
+}
+export function modulePath(id){character(id);return fileURLToPath(new URL(`./${id}.mjs`,import.meta.url));}
+export function reviewPath(id){return fileURLToPath(new URL(character(id).review,import.meta.url));}
+/** Brief compact entrance on attach. Host facts that need attention (approval, issue) always pre-empt it. */
+export function arrivalView(id,state,now){
+  const {arrival}=character(id),elapsed=now-state.started;
+  if(!arrival||!(elapsed>=0)||elapsed>=arrival.duration)return null;
+  if(state.approvals.length||state.issue||state.terminal)return null;
+  return {scene:arrival.scene,time:elapsed,motionTime:elapsed,caption:state.phase==='connecting'?'Connecting…':'Following the conversation.'};
+}
+export function activityView(id,state,now,{arrival=false}={}){
+  const spec=character(id);
+  const entrance=arrival?arrivalView(id,state,now):null;
+  if(entrance)return entrance;
+  const v=baseView(state,now);
+  if(v.scene==='cluster')return {...v,scene:spec.power,time:v.time*spec.powerDuration/4800,caption:`Working · ${spec.powerName} visual`};
+  if(id==='lucid')return {...v,scene:({concerned:'uncertain',proud:'delighted'})[v.scene]??v.scene};
+  if(SCENES[id])return {...v,scene:(id==='sentinel'&&state.approvals.length?'approval':SCENES[id][v.scene])??v.scene};
+  return v;
+}
+export async function loadCharacter(id){
+  const spec=character(id);
+  if(id==='lucid'){
+    const [{parseMaster},{renderLucidCharacter}]=await Promise.all([
+      import('../../design/lucid/recovery/render.mjs'),import('../../design/lucid/recovery/character.mjs'),
+    ]);
+    const rig=parseMaster(await readFile(new URL('../../design/lucid/recovery/lucid-master.svg',import.meta.url),'utf8'));
+    return {...spec,render:(scene,time,options)=>renderLucidCharacter(rig,scene,time,options)};
+  }
+  if(id==='sentinel'){
+    const [{renderSentinelCharacter},{renderSentinelIcon}]=await Promise.all([
+      import('../../design/stage3/sentinel-character.js'),import('../../design/stage3/sentinel-icon.js'),
+    ]);
+    return {...spec,render:(scene,time,{cols,rows,mono=false,still=false}={})=>{
+      // The authored character refuses below 48x16 cells (shrinking it was never approved). Smaller slots get the approved shield icon.
+      if(cols<48||rows<16){
+        const h=Math.max(6,Math.min(rows,10)),w=Math.max(12,Math.min(cols,h*2));
+        return renderSentinelIcon({cols:w,rows:h,mono,mood:SENTINEL_MOOD[scene]??'cute'});
+      }
+      // Scan is not a loop; bounce it so a long job keeps sweeping without a restart pop.
+      const t=scene==='scan'&&!still?(u=>u<2500?u:5000-u)(time%5000):time;
+      return renderSentinelCharacter(scene,t,{cols,rows,mono,still});
+    }};
+  }
+  const {parseSvgRig}=await import('../../factory/svg-rig.mjs');
+  if(id==='cipher'){
+    const [rig,{renderCipher}]=await Promise.all([
+      readFile(new URL('../../design/cipher/v1/cipher-master.svg',import.meta.url),'utf8').then(parseSvgRig),
+      import('../../design/cipher/v2/character.mjs'),
+    ]);
+    return {...spec,render:(scene,time,options)=>renderCipher(rig,scene,time,options)};
+  }
+  if(id==='drago'){
+    const [rig,{renderDrago}]=await Promise.all([
+      readFile(new URL('../../design/drago/v1/drago-master.svg',import.meta.url),'utf8').then(parseSvgRig),
+      import('../../design/drago/v4/character.mjs'),
+    ]);
+    return {...spec,render:(scene,time,options)=>renderDrago(rig,scene,time,options)};
+  }
+  const source=id==='seer'?'../../design/seer/v1/seer-master.svg':'../../design/hyperion/v1/hyperion-master.svg';
+  const rig=parseSvgRig(await readFile(new URL(source,import.meta.url),'utf8'));
+  const render=id==='seer'?(await import('../../design/seer/v4/character.mjs')).renderSeer:(await import('../../design/hyperion/v2/character.mjs')).renderHyperion;
+  return {...spec,render:(scene,time,options)=>render(rig,scene,time,options)};
+}

package/vendor/dragonlab/integration/companions-v1/cipher.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('cipher',options);

package/vendor/dragonlab/integration/companions-v1/companion.mjs

@@ -0,0 +1,63 @@
+import {performance} from 'node:perf_hooks';
+import {composeMessage} from '../../design/lucid/recovery/layout.mjs';
+import {character,CHARACTERS} from './characters.mjs';
+const ENTRANCE_MS=Object.fromEntries(Object.entries(CHARACTERS).map(([k,v])=>[k,v.arrival.duration]));
+import {loadDragonView} from './view.mjs';
+import {initialActivity,activityEvent} from '../hyperion-v3/activity.mjs';
+
+/** Shared display lifecycle. Host events choose expressions; art makes no decisions. */
+export async function createDragonCompanion(id,{output=process.stdout,now=()=>performance.now(),still=false,arrival=true,mono=false,persist=true}={}){
+  character(id);
+  // Piped output does not need to load or render any art.
+  const actor=output.isTTY?await loadDragonView(id,{still,arrival,mono}):null;
+  let state=initialActivity(now()),height=0,boundary=true,closed=false,disabled=false,timer,closing;
+  const erase=()=>{
+    if(!height)return;
+    output.write(`\x1b[${height}A\r`);
+    for(let i=0;i<height;i++)output.write('\x1b[2K\n');
+    output.write(`\x1b[${height}A\r`);height=0;
+  };
+  const draw=()=>{
+    if(closed||disabled||!output.isTTY||!boundary)return;
+    const cols=output.columns||80,rows=output.rows||24;
+    if(rows<5||cols<16)return;
+    const started=state.started;
+    // greeting-only: after the entrance the block is withdrawn for good (host text is untouched).
+    if(!persist&&!still&&now()-started>=ENTRANCE_MS[id]&&!state.approvals.length){erase();disabled=true;clearInterval(timer);return;}
+    const v=actor.view(state,now(),{cols,rows});
+    const lines=composeMessage(v.frame,actor.name.toUpperCase()+'\n'+v.caption,{terminalCols:cols});
+    if(lines.length>=rows)return;
+    erase();output.write(lines.join('\n')+'\n');height=lines.length;
+  };
+  const safeDraw=()=>{try{draw();}catch{disabled=true;clearInterval(timer);try{erase();}catch{}}};
+  // Reflow invalidates old cursor coordinates. Do not erase after resize.
+  const resize=()=>{height=0;disabled=true;clearInterval(timer);};
+  output.on?.('resize',resize);
+  safeDraw();
+  if(output.isTTY&&!disabled){timer=setInterval(safeDraw,1000/6);timer.unref?.();}
+  return {
+    event(event){if(!closed&&!closing){state=activityEvent(state,event,now());safeDraw();}},
+    write(text){
+      if(closed)return;
+      erase();output.write(text);
+      if(text.length)boundary=text.endsWith('\n');
+      if(boundary)safeDraw();
+    },
+    suspend(){erase();disabled=true;clearInterval(timer);},
+    close(){
+      if(closing)return closing;
+      // Set closing before starting async work so concurrent closes share cleanup.
+      closing=Promise.resolve().then(async()=>{
+        state=activityEvent(state,{type:'stream.closed'},now());
+        try{
+          if(output.isTTY&&!disabled&&!still&&state.phase==='complete'&&!state.issue&&!state.approvals.length){
+            const remaining=Math.max(0,2600-(now()-state.changed));
+            if(remaining)await new Promise(resolve=>setTimeout(resolve,remaining));
+          }
+          safeDraw();
+        }finally{closed=true;clearInterval(timer);output.off?.('resize',resize);}
+      });
+      return closing;
+    },
+  };
+}

package/vendor/dragonlab/integration/companions-v1/drago.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('drago',options);

package/vendor/dragonlab/integration/companions-v1/hyperion.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('hyperion',options);

package/vendor/dragonlab/integration/companions-v1/lucid.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('lucid',options);

package/vendor/dragonlab/integration/companions-v1/seer.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('seer',options);

package/vendor/dragonlab/integration/companions-v1/sentinel.mjs

@@ -0,0 +1,2 @@
+import {createDragonCompanion} from './companion.mjs';
+export const createCompanion=options=>createDragonCompanion('sentinel',options);

package/vendor/dragonlab/integration/companions-v1/view.mjs

@@ -0,0 +1,28 @@
+import {artSlot} from '../../design/lucid/recovery/layout.mjs';
+import {initialActivity,activityEvent} from '../hyperion-v3/activity.mjs';
+import {character,loadCharacter,activityView} from './characters.mjs';
+
+/**
+ * Pure per-frame view for hosts that own their own screen (Quoxon's Ink, the CLI block).
+ * Same reducer, same renderer, same priorities as the line-based companion; no timers, no terminal control.
+ * view() returns {frame,caption,slot,name,scene}; frame is null when the terminal is too small for art.
+ */
+export async function loadDragonView(id,{still=false,arrival=true,mono=false,persist=true}={}){
+  character(id);
+  const actor=await loadCharacter(id);
+  return {
+    id,name:actor.name,arrivalMs:character(id).arrival.duration,
+    initial:initialActivity,
+    reduce:activityEvent,
+    view(state,now,{cols=80,rows=24}={}){
+      // Greeting-only: withdrawn for good once the entrance is over, unless an approval is pending.
+      if(!persist&&!still&&now-state.started>=character(id).arrival.duration&&!state.approvals.length)return {frame:null,caption:null,hidden:true,name:actor.name,scene:null};
+      const slot=artSlot(cols,Math.max(1,rows));
+      if(id==='seer'||id==='cipher'){slot.cols=Math.min(39,slot.cols);slot.rows=Math.min(11,slot.rows);}
+      const v=activityView(id,state,now,{arrival:arrival&&!still});
+      const result=slot.showArt?actor.render(v.scene,v.time,{...slot,still,mono,motionTime:v.motionTime}):null;
+      if(result&&!result.ok)throw new Error(result.code);
+      return {frame:result?.frame??null,caption:v.caption,slot,name:actor.name,scene:v.scene};
+    },
+  };
+}