devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/_resources/assets/facility2d_app.mjs

@@ -0,0 +1,45 @@
+import {collectFloors,renderFacility2D} from './facility2d_core.mjs';
+import {showDeviceControls} from './equipment_controls.mjs';
+import {installFacility2DSimulation} from './facility2d_simulation.mjs';
+const model=JSON.parse(document.getElementById('project-data').textContent);
+const controlPlan=JSON.parse(document.getElementById('control-plan').textContent);
+const $=id=>document.getElementById(id);
+$('site-title').textContent=model.name;
+const warehouse=/warehouse|parcel|distribution|fulfill|sortation/i.test((model.industry||'')+' '+(model.description||''));
+$('hmi-page-title').textContent=warehouse?'Warehouse overview':'Facility overview';
+$('work-items-title').textContent=warehouse?'PARCELS ON SYSTEM':'ITEMS IN PROCESS';
+$('asset-total').textContent=String(model.equipment.length);
+$('signal-total').textContent=String(model.signals.length);
+const floors=collectFloors(model.equipment),select=$('floor-selector');
+for(const f of floors){const el=document.createElement('option');el.value=f;el.textContent='Floor '+f;select.append(el);}
+const zoneSelect=$('zone-selector');let currentId='',filterFloor=floors[0]||'1',filterZone='all',zoom=1,focused=false,selectedCenter=null,sim=null;
+select.value=filterFloor;
+function zones(){zoneSelect.replaceChildren(new Option('All areas','all'));const visible=model.equipment.filter(a=>filterFloor==='all'||String(a.floor||1)===filterFloor);for(const z of [...new Set(visible.map(a=>a.zone||'UNASSIGNED'))])zoneSelect.append(new Option(z,z));}
+function pick(a){currentId=a.id;$('selected-name').textContent=a.name||a.id;$('selected-id').textContent=a.id;$('selected-type').textContent=a.kind.toUpperCase()+' · FLOOR '+(a.floor||1);$('selected-zone').textContent='Zone: '+(a.zone||'UNASSIGNED');const list=$('selected-signals');list.replaceChildren();let own=model.signals.filter(s=>s.asset_id===a.id);if(!own.length){const r=document.createElement('div');r.textContent='No source signals declared · NOT MAPPED';r.className='signal-row';list.append(r);}for(const s of own){const row=document.createElement('div');row.className='signal-row';const title=document.createElement('span'),value=document.createElement('b');title.textContent=s.role.replaceAll('_',' ').toUpperCase();value.textContent=`UNKNOWN · ${s.datatype}${s.unit?' / '+s.unit:''}`;row.append(title,value);list.append(row);}$('selected-count').textContent=own.length+' declared signals';showDeviceControls(controlPlan,a,$('device-controls'));paint();sim?.render();}
+function paint(){const results=renderFacility2D($('facility-map'),model.equipment,model.connections,{floor:filterFloor,zone:filterZone,selected:currentId,onSelect:pick,onPortal:changeFloor});$('map-count').textContent='Floor '+filterFloor+' · '+results.equipment+' equipment · '+results.links+' internal links';
+renderTransitions();$('area-total').textContent=String([...new Set(model.equipment.map(a=>a.zone||'UNASSIGNED'))].length);$('no-source-note').textContent='UNVERIFIED MAPPINGS · NO LIVE PLC DATA';selectedCenter=results.selectedCenter;
+ const focus=focused&&selectedCenter;
+ const width=1180/zoom,height=660/zoom;
+ const cx=focus?selectedCenter.x:590,cy=focus?selectedCenter.y:330;
+ const x=Math.max(0,Math.min(1180-width,cx-width/2));
+ const y=Math.max(0,Math.min(660-height,cy-height/2));
+ $('facility-map').setAttribute('viewBox',`${x} ${y} ${width} ${height}`);
+ $('map-inner').style.transform='none';sim?.render();}
+function changeFloor(next){if(!floors.includes(String(next)))return;filterFloor=String(next);select.value=filterFloor;filterZone='all';zoom=1;focused=false;currentId='';$('selected-id').textContent='Select equipment';$('selected-name').textContent='Click equipment on Floor '+filterFloor; $('selected-type').textContent='';$('selected-signals').replaceChildren();$('device-controls').replaceChildren();zones();paint();}
+const tabs=$('floor-tabs');for(const f of floors){const b=document.createElement('button');b.type='button';b.textContent='Floor '+f;b.dataset.floor=f;b.addEventListener('click',()=>changeFloor(f));tabs.append(b);}
+function renderTransitions(){for(const b of tabs.querySelectorAll('button')){const active=b.dataset.floor===filterFloor;b.classList.toggle('active',active);b.setAttribute('aria-current',active?'page':'false');}
+ const panel=$('floor-transfers');panel.replaceChildren();const byId=new Map(model.equipment.map(a=>[a.id,a]));
+ for(const c of model.connections){const a=byId.get(c.from),b=byId.get(c.to);if(!a||!b||String(a.floor)===String(b.floor))continue;const fromFloor=String(a.floor),toFloor=String(b.floor);if(fromFloor!==filterFloor&&toFloor!==filterFloor)continue;const outbound=fromFloor===filterFloor;const target=outbound?toFloor:fromFloor;
+ const btn=document.createElement('button');btn.type='button';btn.className='floor-transfer-link';btn.textContent=(outbound?'→ TO FLOOR ':'← FROM FLOOR ')+target+' · '+c.from+' → '+c.to;btn.addEventListener('click',()=>changeFloor(target));panel.append(btn);}
+ panel.hidden=!panel.childElementCount; }
+select.addEventListener('change',()=>changeFloor(select.value));zoneSelect.addEventListener('change',()=>{filterZone=zoneSelect.value;paint();});
+$('zoom-in').addEventListener('click',()=>{zoom=Math.min(1.8,+(zoom+.15).toFixed(2));paint();});$('zoom-out').addEventListener('click',()=>{zoom=Math.max(.6,+(zoom-.15).toFixed(2));paint();});$('zoom-fit').addEventListener('click',()=>{zoom=1;focused=false;paint();});
+$('focus-selected').addEventListener('click',()=>{
+ const asset=model.equipment.find(a=>a.id===currentId);if(!asset)return;
+ if(String(asset.floor)!==filterFloor){changeFloor(String(asset.floor));}
+ filterZone='all';zoneSelect.value='all';zoom=2.3;focused=true;paint();
+});
+zones();paint();
+// Read-only source tracking and operator writes to in-memory simulation ONLY.
+// No connection to PLC/OPC UA or Ignition is created here.
+sim=installFacility2DSimulation({model,selectedId:()=>currentId});

devagent_spatial/_resources/assets/facility2d_core.mjs

@@ -0,0 +1,114 @@
+/* DevAgent 2D facility flow engine — source-qualified read-only conceptual geometry.
+   Render ONLY customer supplied asset IDs and links. Never represent live PLC values. */
+const NS='http://www.w3.org/2000/svg';
+const svgEl=(tag,attrs={},parent)=>{const n=document.createElementNS(NS,tag);for(const [k,v] of Object.entries(attrs))n.setAttribute(k,String(v));if(parent)parent.appendChild(n);return n;};
+const label=(parent,txt,x,y,attributes={})=>{const n=svgEl('text',{x,y,...attributes},parent);n.textContent=String(txt??'');return n;};
+const key=v=>String(v??'').trim();
+const isTransport=k=>['conveyor','spiral','sorter','junction'].includes(k);
+const clipLabel=(v,max=19)=>String(v??'').length>max?String(v).slice(0,max-1)+'…':String(v??'');
+export function collectFloors(assets){return [...new Set((assets||[]).map(a=>String(a.floor??1)))].sort((a,b)=>Number(a)-Number(b)||a.localeCompare(b));}
+export function renderFacility2D(svg, assets, connections, {floor='all',zone='all',selected='',onSelect=()=>{},onPortal=()=>{}}={}){
+ // Standard 2D never overlays multiple physical floors. An unspecified floor resolves to Floor 1 (or first declared floor).
+ const floorList=collectFloors(assets);if(floor==='all')floor=floorList[0]||'1';
+ svg.replaceChildren();svg.setAttribute('viewBox','0 0 1180 660');svg.setAttribute('preserveAspectRatio','xMidYMid meet');
+ const defs=svgEl('defs',{},svg);
+ const pat=svgEl('pattern',{id:'v0752grid',width:24,height:24,patternUnits:'userSpaceOnUse'},defs);
+ svgEl('path',{d:'M24 0H0V24',fill:'none',stroke:'#25485b','stroke-width':.5,opacity:.65},pat);
+ const filtered=(assets||[]).filter(a=>(floor==='all'||String(a.floor??1)===String(floor))&&(zone==='all'||key(a.zone||'OTHER')===zone));
+ const byId=new Map(filtered.map(a=>[a.id,a]));
+ const links=(connections||[]).filter(c=>byId.has(c.from)&&byId.has(c.to));
+ svgEl('rect',{width:1180,height:660,fill:'#0b1f2d'},svg);
+ svgEl('rect',{width:1180,height:660,fill:'url(#v0752grid)'},svg);
+ if(!filtered.length){label(svg,'No equipment on selected floor / zone',590,324,{'text-anchor':'middle',fill:'#90a8b8','font-size':19});label(svg,'CONCEPT ONLY  ·  NO VERIFIED LIVE DATA',590,356,{'text-anchor':'middle',fill:'#577c8c','font-size':11,'letter-spacing':2});return {equipment:0,links:0};}
+ const multiFloor=false; // explicit single-floor 2D view; 3D owns full-facility spatial view
+ const category=a=>key(a.zone)||'UNASSIGNED';
+ const zones=[...new Set(filtered.map(category))];
+ const ordered=zones.length>9?zones.slice(0,8).concat(['OTHER AREAS']):zones;
+ const inCategory=(a,z)=>z==='OTHER AREAS'?!ordered.slice(0,8).includes(category(a)):category(a)===z;
+ const pad=62,usable=1056;
+ // Each 2D page presents only equipment and zones of one selected floor.
+ const zoneW=usable/Math.max(1,ordered.length);
+ ordered.forEach((z,i)=>{
+  svgEl('rect',{x:pad+i*zoneW+5,y:52,width:Math.max(65,zoneW-10),height:548,rx:12,
+   stroke:'#32566a','stroke-width':1,'stroke-dasharray':'5 7',fill:i%2?'#0d2331':'#0d2635'},svg);
+  label(svg,String(i+1).padStart(2,'0')+' / '+clipLabel(z.toUpperCase(),17),pad+i*zoneW+22,81,
+   {fill:'#91b3c5','font-size':12,'font-weight':750,'letter-spacing':1.4});
+ });
+ // Ordering uses only explicitly declared links and does not infer physical sensor or drive associations.
+ const order=new Map(filtered.map(a=>[a.id,0]));
+ for(let iteration=0;iteration<Math.min(filtered.length,50);iteration++){
+  let changed=false;for(const c of links){let next=Math.min(20,(order.get(c.from)||0)+1);if(next>(order.get(c.to)||0)){order.set(c.to,next);changed=true;}}
+  if(!changed)break;
+ }
+ const nodes=[];
+ ordered.forEach((z,i)=>{
+  const group=filtered.filter(a=>inCategory(a,z));
+  const transport=group.filter(a=>isTransport(a.kind)).sort((a,b)=>(order.get(a.id)||0)-(order.get(b.id)||0)||a.id.localeCompare(b.id));
+  const accessories=group.filter(a=>!isTransport(a.kind)).sort((a,b)=>a.id.localeCompare(b.id));
+  const zoneW=usable/Math.max(1,ordered.length),left=pad+i*zoneW;
+  transport.forEach((a,j)=>nodes.push({asset:a,x:left+(j+.5)*(zoneW/Math.max(1,transport.length)),y:320}));
+  accessories.forEach((a,j)=>nodes.push({asset:a,x:left+(j+.5)*(zoneW/Math.max(1,accessories.length)),y:166+(j%2)*276}));
+ });
+ const coordinates=new Map(nodes.map(o=>[o.asset.id,o]));
+ const drawLink=(c)=>{
+  const a=coordinates.get(c.from),b=coordinates.get(c.to);if(!a||!b)return;
+  const x1=a.x+35,y1=a.y,x2=b.x-35,y2=b.y;
+  const reversed=x2<x1-40;
+  const curve=Math.max(24,Math.abs(x2-x1)*.32);
+  const d=reversed?`M ${x1} ${y1} Q ${(x1+x2)/2} ${(y1+y2)/2+32}, ${x2} ${y2}`:`M ${x1} ${y1} C ${x1+curve} ${y1}, ${x2-curve} ${y2}, ${x2} ${y2}`;
+  const g=svgEl('g',{'aria-label':`${c.from} to ${c.to}: declared topology (not as-built)`},svg);
+  svgEl('path',{d,stroke:'#395361','stroke-width':26,'stroke-linecap':'round',fill:'none'},g);
+  svgEl('path',{d,stroke:'#102f3c','stroke-width':16,'stroke-linecap':'round',fill:'none'},g);
+  svgEl('path',{d,stroke:'#619ca4','stroke-width':2.5,'stroke-dasharray':'8 15',opacity:.86,fill:'none'},g);
+ };
+ links.forEach(drawLink);
+ // Explicit cross-floor links are *portals*, never physical continuous belt geometry.
+ // The linked endpoint's floor and association must originate in customer-provided topology.
+ const allAssets=new Map((assets||[]).map(a=>[a.id,a]));
+ const transfers=(connections||[]).filter(c=>{
+  const a=allAssets.get(c.from),b=allAssets.get(c.to);
+  return a&&b&&String(a.floor??1)!==String(b.floor??1) &&
+    (String(a.floor??1)===String(floor)||String(b.floor??1)===String(floor));
+ });
+ for(const [i,c] of transfers.entries()){
+  const a=coordinates.get(c.from)||coordinates.get(c.to);
+  if(!a)continue;
+  const source=allAssets.get(c.from),dest=allAssets.get(c.to);
+  const outgoing=String(source.floor??1)===String(floor);
+  const other=outgoing?String(dest.floor??1):String(source.floor??1);
+  const dir=outgoing?'TO':'FROM';
+  const x=Math.min(1040,Math.max(110,a.x+85));
+  const y=Math.min(560,Math.max(135,a.y-58-(i%3)*36));
+  const g=svgEl('g',{role:'button',tabindex:0,cursor:'pointer',
+    'aria-label':`${dir} Floor ${other} via declared ${c.from} to ${c.to}; switch floor`},svg);
+  svgEl('path',{d:`M${a.x+16} ${a.y-16} L${x} ${y+11}`,stroke:'#d9ae72','stroke-width':2,'stroke-dasharray':'4 6',fill:'none'},g);
+  svgEl('rect',{x:x-12,y:y-10,width:145,height:35,rx:6,fill:'#164052',stroke:'#d4ac6f','stroke-width':1},g);
+  label(g,`${dir} FLOOR ${other} ↗`,x+58,y+12,{'text-anchor':'middle',fill:'#f0d2a2','font-size':12,'font-weight':850});
+  const nav=()=>onPortal(other);
+  g.addEventListener('click',nav);
+  g.addEventListener('keydown',e=>{if(e.key==='Enter'||e.key===' '){e.preventDefault();nav();}});
+ }
+ // Draw every declared asset, including those without flow links; do not infer new connections.
+ for(const n of nodes){const {asset:a,x,y}=n,g=svgEl('g',{role:'button',tabindex:0,'aria-label':`Inspect ${a.id}`,cursor:'pointer'},svg);
+  const active=selected===a.id;
+  const transport=isTransport(a.kind);
+  if(transport){
+   svgEl('rect',{x:x-42,y:y-18,width:84,height:36,rx:9,fill:'#16384a',stroke:active?'#b5ffee':'#5f8698','stroke-width':active?3:1.2},g);
+   svgEl('path',{d:`M ${x-35} ${y} H ${x+35}`,stroke:'#67a9b6','stroke-width':4,'stroke-dasharray':'4 10',opacity:.88},g);
+  }else if(a.kind==='photoeye'){
+   svgEl('path',{d:`M${x} ${y+14}v30`,stroke:'#8399a6','stroke-width':5},g);
+   svgEl('circle',{cx:x,cy:y,r:13,fill:'#75cfc0',stroke:active?'#fff':'#b9eee8','stroke-width':3},g);
+  }else{
+   svgEl('rect',{x:x-25,y:y-24,width:50,height:48,rx:7,fill:a.kind==='scanner'?'#b7a376':'#517687',stroke:active?'#efffff':'#a1bbc5','stroke-width':active?3:1},g);
+   svgEl('rect',{x:x-18,y:y-13,width:36,height:9,rx:2,fill:'#15394a',opacity:.9},g);
+  }
+  const w=Math.min(118,Math.max(61,a.id.length*7+18));
+  svgEl('rect',{x:x-w/2,y:y+25,width:w,height:25,rx:5,fill:active?'#0a5260':'#0b2231',stroke:active?'#9ae7da':'#416a7c','stroke-width':1},g);
+  label(g,clipLabel(a.id,17),x,y+42,{'text-anchor':'middle',fill:'#dff4fa','font-size':11,'font-weight':800});
+  g.addEventListener('click',()=>onSelect(a));
+  g.addEventListener('keydown',ev=>{if(ev.key==='Enter'||ev.key===' '){ev.preventDefault();onSelect(a);}});
+ }
+ label(svg,'DECLARED MATERIAL FLOW  ·  CONCEPTUAL / NOT TO SCALE',24,637,{fill:'#679cb1','font-size':10,'font-weight':800,'letter-spacing':1.4});
+ label(svg,filtered.length+' ASSETS  /  '+links.length+' DECLARED LINKS',1150,637,{'text-anchor':'end',fill:'#6d9bae','font-size':10,'font-weight':800,'letter-spacing':1.1});
+ return {equipment:filtered.length,links:links.length,portals:transfers.length,selectedCenter:coordinates.get(selected)?{x:coordinates.get(selected).x,y:coordinates.get(selected).y}:null};
+}

devagent_spatial/_resources/assets/facility2d_simulation.mjs

@@ -0,0 +1,167 @@
+/* Read-only 2D telemetry + explicitly synthetic operator control.
+   No production OPC / PLC connection, no tag write capability.
+   Controls are dynamically unlocked ONLY for a confirmed in-memory demo session.
+   Device commands remain fail-closed without separate approved contracts.
+*/
+export function installFacility2DSimulation({model, selectedId}) {
+  const $=id=>document.getElementById(id);
+  const ids=['start','stop','reset','ack'];
+  const buttons=Object.fromEntries(ids.map(id=>[id,document.querySelector('.facility-command.fc-'+id)]));
+  const badge=document.querySelector('.facility-control-locked');
+  const banner=document.querySelector('.top .status');
+  const metrics=document.querySelectorAll('.metrics .metric strong');
+  const projectId=location.pathname.match(/^\/projects\/([a-z0-9-]{1,100})\/viewer\/index\.html$/)?.[1];
+  const policy=JSON.parse($('operations-policy').textContent);
+  const expected=new Map(model.signals.map(s=>[s.id,s]));
+  let frame=null,virtualPE=new Map(),busy=false,inflight=false,abort=null,lastPoll=0;
+  const set=(node,value)=>{if(node)node.textContent=String(value);};
+  function lock(message='🔒 CONTROL LOCKED'){
+    for(const button of Object.values(buttons)){if(!button)continue;button.disabled=true;button.setAttribute('aria-disabled','true');}
+    set(badge,message);badge?.classList.remove('sim-linked');
+  }
+  function valid(data){
+    if(data?.status!=='PASS_SYNTHETIC_PREVIEW_ONLY'||
+       data?.source!=='IN_MEMORY_SYNTHETIC_NOT_OPC'||data?.opc_writes!==false||
+       data?.production!=='HOLD'||data?.receipt?.origin!=='SYNTHETIC_OFFLINE_FIXTURE'||
+       data?.receipt?.mapping_digest!==policy.mapping_digest ||
+       !Array.isArray(data?.receipt?.frames) || !data.receipt.frames.length ||
+       !Array.isArray(data?.virtual_pe) ||
+       data.virtual_pe_source!=='CONCEPTUAL_SYNTHETIC_PORTS_NOT_MAPPED')return false;
+    const rows=data.receipt.frames.at(-1)?.signals;
+    if(!Array.isArray(rows)||rows.length!==expected.size)return false;
+    const seen=new Set();
+    for(const row of rows){
+      const src=expected.get(row?.signal_id);
+      if(!src||seen.has(row.signal_id)||row.asset_id!==src.asset_id||row.role!==src.role||
+         !['GOOD','BAD','UNCERTAIN','STALE','MISSING'].includes(row.quality)||typeof row.valid!=='boolean')return false;
+      seen.add(row.signal_id);
+    }
+    return true;
+  }
+  function assetStates(){const m=new Map();for(const row of frame?.signals||[]){
+    if(!m.has(row.asset_id))m.set(row.asset_id,[]);
+    m.get(row.asset_id).push(row);
+  }return m;}
+  function equipmentState(states){
+    if(!states?.length||states.some(s=>!s.valid))return 'UNKNOWN';
+    if(states.some(s=>s.role==='fault'&&s.active===true))return 'FAULT';
+    const run=states.find(s=>s.role==='run_feedback');
+    if(run)return run.value===true?'RUNNING':'STOPPED';
+    const pe=states.find(s=>s.role==='photoeye_blocked');
+    if(pe)return pe.active===true?'BLOCKED':'CLEAR';
+    return 'DECLARED';
+  }
+  function mapColors(){
+    const byAsset=assetStates();
+    for(const g of $('facility-map').querySelectorAll('g[aria-label^="Inspect "]')){
+      const id=g.getAttribute('aria-label').slice('Inspect '.length);
+      const part=g.querySelector('rect, circle, path');
+      if(!part)continue;
+      if(!part.hasAttribute('data-raw-stroke'))part.setAttribute('data-raw-stroke',part.getAttribute('stroke')||'');
+      const state=equipmentState(byAsset.get(id));
+      const color={RUNNING:'#41cdb1',FAULT:'#f07883',STOPPED:'#95aaba',BLOCKED:'#e3b66a',
+                   CLEAR:'#41cdb1'}[state];
+      if(color && frame)part.setAttribute('stroke',color);
+      else {
+        const raw=part.getAttribute('data-raw-stroke');
+        if(raw)part.setAttribute('stroke',raw);else part.removeAttribute('stroke');
+      }
+      g.setAttribute('data-synthetic-state',frame?state:'UNAVAILABLE');
+    }
+  }
+  function selection(){
+    const id=selectedId();
+    const list=$('selected-signals');
+    if(!id||!list)return;
+    const states=(frame?.signals||[]).filter(s=>s.asset_id===id);
+    for(const row of list.querySelectorAll('.signal-row')){
+      const label=row.querySelector('span'),output=row.querySelector('b');
+      if(!label||!output)continue;
+      const role=label.textContent.toLowerCase().replaceAll(' ','_');
+      const entry=states.find(s=>s.role===role);
+      if(!frame||!entry||!entry.valid){set(output,'UNKNOWN');continue;}
+      const value=(role==='photoeye_blocked'||role==='fault')?(entry.active?'ACTIVE':'CLEAR'):
+                   role==='run_feedback'?(entry.value===true?'RUNNING':'STOPPED'):String(entry.value);
+      set(output,value+' · SIM');
+    }
+    const count=$('selected-count');
+    if(count&&frame)count.textContent=states.length+' SIGNALS · SYNTHETIC';
+    else if(count)count.textContent=model.signals.filter(s=>s.asset_id===id).length+' declared signals';
+  }
+  function render(){
+    mapColors();selection();
+    if(!frame){
+      set(banner,'● CONCEPT PREVIEW · NO LIVE PLC');
+      set($('no-source-note'),'UNVERIFIED MAPPINGS · NO LIVE PLC DATA');
+      if(metrics[0]){set(metrics[0],'UNKNOWN');metrics[0].classList.add('unavailable');}
+      if(metrics[2])set(metrics[2],'N/A');
+      if(metrics[4])set(metrics[4],'N/A');
+      return;
+    }
+    set(banner,'● SYNTHETIC DIGITAL TWIN · NOT OPC / PLC');
+    set($('no-source-note'),'SYNTHETIC DIGITAL TWIN · CUSTOMER OPC IDENTITY NOT VERIFIED');
+    const good=frame.signals.every(s=>s.valid);
+    set(metrics[0],good?'SIM · GOOD QUALITY':'SIM · DATA QUALITY ISSUE');
+    metrics[0]?.classList.toggle('unavailable',!good);
+    set(metrics[2],String(currentParcels));
+    set(metrics[4],String(frame.active_alarms?.length??'N/A'));
+  }
+  let currentParcels=0;
+  function setSource(data){
+    if(!valid(data)){
+      frame=null;virtualPE.clear();currentParcels=0;lock();render();return;
+    }
+    frame=data.receipt.frames.at(-1);
+    currentParcels=Array.isArray(data.parcels)?data.parcels.length:0;
+    virtualPE=new Map(data.virtual_pe.map(p=>[p.asset_id,p]));
+    // Never enable a control against a read-only OPC lab or production source.
+    const fault=!!data.fault_asset,paused=!!data.paused;
+    const enable={start:paused&&!fault,stop:!paused,reset:paused,ack:fault&&!data.acknowledged};
+    for(const id of ids){
+      const b=buttons[id];if(!b)continue;
+      const disabled=busy||!enable[id];b.disabled=disabled;
+      b.setAttribute('aria-disabled',String(disabled));
+    }
+    set(badge,'SIMULATOR LINKED · NO PLC');badge?.classList.add('sim-linked');
+    render();
+  }
+  async function poll(){
+    if(!projectId||inflight)return;
+    inflight=true;
+    const controller=new AbortController();abort=controller;
+    const timeout=setTimeout(()=>controller.abort(),6000);
+    try{
+      const response=await fetch('/api/live-lab/'+encodeURIComponent(projectId)+'/readings',
+        {cache:'no-store',credentials:'same-origin',signal:controller.signal});
+      const data=await response.json();
+      if(!response.ok)throw Error('READBACK_NOT_APPROVED');
+      lastPoll=Date.now();setSource(data);
+    }catch(_err){setSource(null);}
+    finally{clearTimeout(timeout);inflight=false;abort=null;}
+  }
+  for(const id of ids){
+    const button=buttons[id];
+    if(!button)continue;
+    button.addEventListener('click',async()=>{
+      if(!projectId||button.disabled||busy||!frame||Date.now()-lastPoll>3500){lock();return;}
+      if(id==='reset'&&!confirm('Reset SYNTHETIC demo fault and parcel position? NO PLC write.'))return;
+      busy=true;lock('SIM '+id.toUpperCase()+' PENDING · NO PLC');
+      try{
+        const response=await fetch('/api/preview-sim/'+encodeURIComponent(projectId)+'/operator/'+id,{
+          method:'POST',credentials:'same-origin',
+          headers:{'Content-Type':'application/json','X-DevAgent-Operator':'synthetic-session-v1'},
+          body:JSON.stringify({confirm:'SYNTHETIC_OPERATOR_ONLY'})
+        });
+        const result=await response.json();
+        if(!response.ok||result.command_authority!=='SYNTHETIC_SIMULATOR_ONLY'||
+           result.opc_writes!==false)throw Error(result.reason||'SIM_COMMAND_HOLD');
+        set(badge,'SIM '+id.toUpperCase()+' ACCEPTED · NOT PLC');
+      }catch(_err){lock('SIM COMMAND HOLD · NO PLC');}
+      finally{busy=false;await poll();}
+    });
+  }
+  lock();
+  if(projectId){poll();setInterval(()=>{if(document.visibilityState==='visible')poll();},1000);
+    document.addEventListener('visibilitychange',()=>{if(document.visibilityState==='visible')poll();});}
+  return {render,sourceUnavailable:()=>setSource(null)};
+}

devagent_spatial/_resources/assets/facility2d_viewer.html

@@ -0,0 +1,7 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>DevAgent · Facility Flow Overview</title><link rel="stylesheet" href="./facility2d.css"></head><body>
+<div class="app"><nav class="rail" aria-label="Application"><div class="brand">D<span style="color:#31bba9">·</span></div><span>▦</span><span>⌁</span><span>◈</span><span>⚙</span></nav><main class="content"><header class="top"><div><div class="kicker">DEVAGENT / INDUSTRIAL OPERATIONS</div><div class="site" id="site-title">Facility Operations</div></div><div class="status">● CONCEPT PREVIEW · NO LIVE PLC</div></header><div class="body"><div class="heading"><div><div class="breadcrumb">OPERATIONS &nbsp; / &nbsp; FACILITY VISIBILITY</div><h1 id="hmi-page-title">Facility overview</h1><div class="sub">Industrial 2D material flow overview · one floor at a time.</div></div><span class="tag">DESIGN REVIEW · READ ONLY</span></div>
+<div class="metrics"><div class="metric"><small>SYSTEM HEALTH</small><strong class="unavailable">UNKNOWN</strong><p>Live equipment states not verified</p></div><div class="metric"><small>THROUGHPUT</small><strong>N/A</strong><p>No authorized source</p></div><div class="metric"><small id="work-items-title">ITEMS IN TRANSIT</small><strong>N/A</strong><p>Requires WCS or validated telemetry</p></div><div class="metric"><small>ASSETS MODELED</small><strong id="asset-total">—</strong><p>From customer equipment register</p></div><div class="metric"><small>ACTIVE ALARMS</small><strong>N/A</strong><p>Unknown does not mean zero</p></div></div>
+<section class="facility-control-strip" aria-label="Facility controls (not authorized)"><div class="facility-control-label"><strong>Facility controls</strong></div><div class="facility-control-buttons" role="group" aria-label="Facility commands locked"><button type="button" class="facility-command fc-start" disabled aria-disabled="true" title="START unavailable: no approved command mapping, roles or interlocks">START</button><button type="button" class="facility-command fc-stop" disabled aria-disabled="true" title="STOP unavailable: not a safety-rated emergency stop">STOP</button><button type="button" class="facility-command fc-reset" disabled aria-disabled="true" title="RESET unavailable: approved device command contract required">RESET</button><button type="button" class="facility-command fc-ack" disabled aria-disabled="true" title="ACK unavailable: alarm acknowledgement and audit not configured">ACK</button></div><span class="facility-control-locked" role="status">🔒 CONTROL LOCKED</span></section>
+<div class="layout"><section class="panel"><div class="panel-title"><div><div class="kicker">01 / FACILITY MAP</div><h2>Material flow & equipment</h2></div><span class="pill" id="map-count">—</span></div><div class="controlbar"><div class="group"><label for="floor-selector">FLOOR</label><select id="floor-selector" aria-label="Select floor"></select><div class="floor-tabs" id="floor-tabs" aria-label="Floor navigation"></div><label for="zone-selector">AREA</label><select id="zone-selector"><option value="all">All areas</option></select></div><div class="group"><button id="zoom-out" title="Zoom out">−</button><button id="zoom-in" title="Zoom in">+</button><button id="zoom-fit">FIT VIEW</button><button id="focus-selected" title="Zoom to selected equipment">FOCUS DEVICE</button></div></div><div class="map-canvas" role="region" aria-label="Read-only conceptual 2D equipment map"><div class="map-inner" id="map-inner"><svg id="facility-map" xmlns="http://www.w3.org/2000/svg" aria-label="Declared equipment and topology"></svg></div></div><div id="floor-transfers" class="floor-transfers" aria-label="Customer-declared inter-floor links (unverified)"></div><div class="map-note" id="no-source-note">UNVERIFIED MAPPINGS · NO LIVE PLC DATA</div><div class="map-caption"><span>LEGEND: cyan paths = declared connections · symbols = declared equipment only</span><span>NOT TO SCALE</span></div></section>
+<aside class="panel"><div class="panel-title"><div><div class="kicker">02 / NETWORK INSIGHTS</div><h2>Equipment diagnostics</h2></div></div><div class="inspector"><div class="panel-kicker">DESIGN METADATA</div><h3 id="selected-id">Select equipment</h3><div class="muted" id="selected-name">Click equipment in the map for declared information.</div><p class="muted" id="selected-type">Live values are unavailable.</p><p class="muted" id="selected-zone">—</p><div class="divider"></div><div class="panel-kicker" id="selected-count">SIGNALS · NOT VERIFIED</div><div id="selected-signals"></div><div class="divider"></div><div class="panel-kicker">DEVICE COMMANDS</div><div id="device-controls" aria-label="Device control intents (locked)"></div><div class="divider"></div><div class="panel-kicker">LAYOUT SUMMARY</div><p class="muted"><span id="area-total">0</span> declared areas · <span id="signal-total">0</span> signal declarations</p><div class="safety">No PLC writes · No live telemetry · Signal associations and machine status require source verification and FAT.</div></div></aside></div><div class="footer">DEVAGENT ENGINEERING CANDIDATE · 2D DESIGN CONCEPT · IGNITION / PHYSICAL FAT NOT EXECUTED</div></div></main></div>
+<script type="application/json" id="project-data">__EMBEDDED_PROJECT__</script><script type="application/json" id="operations-policy">__EMBEDDED_OPERATIONS_POLICY__</script><script type="application/json" id="control-plan">__EMBEDDED_CONTROL_PLAN__</script><script type="module" src="./facility2d_app.mjs"></script></body></html>

devagent_spatial/_resources/assets/fallback_scene.js

@@ -0,0 +1,17 @@
+/** Offline 2.5D SVG conceptual fallback, explicitly NOT advertised as Three.js. */
+export function startFallback(model,host,onSelect){
+ const NS='http://www.w3.org/2000/svg';let zoom=1,dx=0,dy=0,selected=null,floor='all',mode='iso';
+ let replayAlarms=[];const svg=document.createElementNS(NS,'svg');svg.setAttribute('viewBox','0 0 1200 780');svg.setAttribute('role','img');svg.setAttribute('aria-label','Conceptual isometric equipment layout');host.append(svg);
+ function node(tag,attrs={},text){const n=document.createElementNS(NS,tag);for(const[k,v]of Object.entries(attrs))n.setAttribute(k,String(v));if(text!=null)n.textContent=String(text);return n;}
+ const coords=e=>{const x=e.position.x,y=e.position.y,z=e.position.z;return mode==='top'?[580+x*15,350+z*13-y*3]:mode==='side'?[580+x*16,550-y*17]:[600+x*19+z*12,420+z*5-x*4-y*14];};
+ function render(){svg.replaceChildren();svg.append(node('rect',{x:0,y:0,width:1200,height:780,fill:'#0b2031'}));const layer=node('g',{transform:`translate(${dx} ${dy}) translate(600 390) scale(${zoom}) translate(-600 -390)`});svg.append(layer);
+ for(const c of model.connections){const a=model.equipment.find(e=>e.id===c.from),b=model.equipment.find(e=>e.id===c.to);if(!a||!b||floor!=='all'&&(String(a.floor)!==floor||String(b.floor)!==floor))continue;const[x1,y1]=coords(a),[x2,y2]=coords(b);layer.append(node('path',{d:`M${x1} ${y1} L${x2} ${y2}`,fill:'none',stroke:'#3d9bb8','stroke-width':3,'stroke-dasharray':'6 5'}));}
+ for(const e of model.equipment){if(floor!=='all'&&String(e.floor)!==floor)continue;const[x,y]=coords(e),size=Math.min(80,Math.max(30,e.dimensions.x*7)),height=Math.max(17,Math.min(58,e.dimensions.z*8));const g=node('g',{tabindex:0,role:'button','aria-label':`Inspect ${e.id}`});const active=e.id===selected;const fill=e.kind==='scanner'?'#b18c4a':e.kind==='tank'?'#468596':e.kind==='photoeye'?'#3bc7bb':e.kind==='spiral'?'#318ea6':'#407f99';g.append(node('path',{d:`M${x-size/2} ${y} l${size*.27} -${height*.36} h${size} l-${size*.27} ${height*.36} Z`,fill:active?'#6ec8db':'#437f99',stroke:'#80a5b7'}));g.append(node('rect',{x:x-size/2,y:y,width:size,height:height,rx:3,fill,stroke:active?'#ccf7ff':'#2c566c','stroke-width':active?3:1}));const label=node('text',{x:x,y:y+height/2+4,'text-anchor':'middle',fill:'#eaf9ff','font-size':Math.min(13,Math.max(10,75/e.id.length)),'font-family':'system-ui','font-weight':'bold'},e.id);g.append(label);g.addEventListener('click',()=>onSelect(e.id));g.addEventListener('keydown',ev=>{if(ev.key==='Enter'||ev.key===' '){ev.preventDefault();onSelect(e.id);}});layer.append(g);}}
+ for(const alert of replayAlarms){const asset=model.equipment.find(e=>e.id===alert.asset_id);if(!asset||(floor!=='all'&&String(asset.floor)!==floor))continue;
+  const[x,y]=coords(asset);layer.append(node('circle',{cx:x,cy:y,r:46,fill:'none',stroke:alert.severity==='CRITICAL'?'#ff6582':'#edbb5a','stroke-width':5,'stroke-dasharray':'6 4'}));}
+ let pan=false,px,py;svg.addEventListener('pointerdown',e=>{pan=true;px=e.clientX;py=e.clientY;svg.setPointerCapture(e.pointerId);});svg.addEventListener('pointermove',e=>{if(!pan||e.buttons!==1)return;dx+=(e.clientX-px)*1200/svg.clientWidth;dy+=(e.clientY-py)*780/svg.clientHeight;px=e.clientX;py=e.clientY;render();});svg.addEventListener('pointerup',()=>pan=false);svg.addEventListener('wheel',e=>{e.preventDefault();zoom=Math.max(.35,Math.min(3,zoom*(e.deltaY<0?1.1:.9)));render();},{passive:false});function focus(id){const e=model.equipment.find(x=>x.id===id);if(!e)return false;
+  if(floor!=='all'&&String(e.floor)!==floor)floor=String(e.floor);
+  zoom=2;const [x,y]=coords(e);dx=(600-x)*zoom;dy=(390-y)*zoom;selected=id;render();return true;}
+ function overview(){zoom=1;dx=dy=0;render();}
+ render();return{focus,overview,operatingStates(_signals){/* 2.5D fallback does not claim mechanical state */},alarms(entries){replayAlarms=Array.isArray(entries)?entries:[];render();},select(id){selected=id;render();},floor(v){floor=v;render();},view(v){mode=v;dx=dy=0;zoom=1;render();}};
+}

devagent_spatial/_resources/assets/flow_geometry.mjs

@@ -0,0 +1,218 @@
+/** DevAgent Spatial Operations: deterministic, display-only routing proposals.
+ * Explicit customer graph edges ONLY. Paths are illustrative, never measured as-built belts.
+ * No machine commands, signals, vendor access, inferred graph edges, or physics claims.
+ */
+const HANDLING = new Set(['conveyor', 'sorter', 'junction', 'spiral']);
+const FLAT = new Set(['conveyor', 'sorter', 'junction']);
+const EPS=1e-8;
+const clamp=(v,a,b)=>Math.max(a,Math.min(b,v));
+function point(e, y){ return {x:e.position.x,y,z:e.position.z}; }
+function port(e, toward, y, spiralOutlet=false){
+  const w=Number(e.dimensions.x), d=Number(e.dimensions.z);
+  const dx=toward.position.x-e.position.x, dz=toward.position.z-e.position.z;
+  const out=point(e,y);
+  // Port selection is based on equipment bounds, not an assertion about OEM interfaces.
+  if(e.kind==='spiral'){
+    const a=Math.atan2(dz,dx);
+    const r=Math.max(.35,Math.min(w,d)*.42);
+    out.x+=Math.cos(a)*r;out.z+=Math.sin(a)*r;
+  } else if(Math.abs(dx)/(w+EPS)>=Math.abs(dz)/(d+EPS)){
+    out.x+=Math.sign(dx||1)*w*.49;
+    if(e.kind==='sorter')out.z+=clamp(dz,-d*.33,d*.33);
+  } else {
+    out.z+=Math.sign(dz||1)*d*.49;
+    if(e.kind==='sorter')out.x+=clamp(dx,-w*.33,w*.33);
+  }
+  return out;
+}
+function controlPath(a,b){
+ const dx=b.x-a.x,dz=b.z-a.z;
+ const length=Math.hypot(dx,dz),side=clamp(length*.27,.45,3.3);
+ if(length<.1)return [a,b];
+ const ux=dx/length,uz=dz/length;
+ return [a,{x:a.x+ux*side,y:a.y+(b.y-a.y)*.25,z:a.z+uz*side},
+  {x:b.x-ux*side,y:a.y+(b.y-a.y)*.75,z:b.z-uz*side},b];
+}
+export function planSpatialRoutes(model){
+ const byId=new Map(model.equipment.map(e=>[e.id,e]));
+ const levels=[...new Set(model.equipment.map(e=>e.floor))].sort((a,b)=>a-b);
+ const result=[];
+ for(const edge of model.connections){
+   const a=byId.get(edge.from),b=byId.get(edge.to);
+   if(!a||!b)continue; // caller's deterministic contract separately rejects dangling IDs
+   const cross=a.floor!==b.floor;
+   const spiral=a.kind==='spiral'||b.kind==='spiral';
+   let kind='logical_unverified';
+   if(!cross&&HANDLING.has(a.kind)&&HANDLING.has(b.kind))kind='conceptual_conveyor_transition';
+   // A vertical material path may be drawn only when an explicit spiral participates.
+   if(cross&&spiral&&HANDLING.has(a.kind)&&HANDLING.has(b.kind))kind='conceptual_spiral_transfer';
+   const ya=a.position.y+1.1,yb=b.position.y+1.1;
+   const p=port(a,b,cross&&a.kind==='spiral'?yb:ya);
+   const q=port(b,a,cross&&b.kind==='spiral'?ya:yb);
+   // Cross-level spiral endpoints coincide with the served level; the spiral's helix
+   // visually represents vertical travel. The bridge itself is horizontal.
+   const pts=controlPath(p,q);
+   result.push({from:a.id,to:b.id,from_floor:a.floor,to_floor:b.floor,
+     kind,geometry_status:'CONCEPTUAL_CONNECTION_NEEDS_APPROVAL',points:pts});
+ }
+ return result;
+}
+export function commonFacilityBounds(model,pad=3.5){
+ if(!model.equipment.length)return null;
+ const xs=model.equipment.flatMap(e=>[e.position.x-e.dimensions.x/2,e.position.x+e.dimensions.x/2]);
+ const zs=model.equipment.flatMap(e=>[e.position.z-e.dimensions.z/2,e.position.z+e.dimensions.z/2]);
+ const minX=Math.min(...xs)-pad,maxX=Math.max(...xs)+pad;
+ const minZ=Math.min(...zs)-pad,maxZ=Math.max(...zs)+pad;
+ return {minX,maxX,minZ,maxZ,width:maxX-minX,depth:maxZ-minZ,
+  centerX:(minX+maxX)/2,centerZ:(minZ+maxZ)/2,
+  levels:[...new Set(model.equipment.map(e=>e.floor))].sort((a,b)=>a-b)};
+}
+export function nextSpiralRise(model,id){
+ const spiral=model.equipment.find(e=>e.id===id&&e.kind==='spiral');if(!spiral)return null;
+ const others=model.connections.filter(c=>c.from===id||c.to===id)
+  .map(c=>model.equipment.find(e=>e.id===(c.from===id?c.to:c.from))).filter(Boolean)
+  .filter(e=>e.floor!==spiral.floor);
+ if(!others.length)return null;
+ return Math.max(...others.map(e=>Math.abs(e.position.y-spiral.position.y)));
+}
+
+/**
+ * V0.5.4 preview assembly contract. Every visual port is owned by an existing
+ * customer asset, and every bridge is owned by one declared material-flow edge.
+ * This does not modify source coordinates or make OEM/mechanical claims.
+ */
+export function planVisualAssembly(model){
+ const byId=new Map(model.equipment.map(e=>[e.id,e]));
+ const parents=new Map(model.equipment.map(e=>[e.id,[]]));
+ const children=new Map(model.equipment.map(e=>[e.id,[]]));
+ for(const c of model.connections){
+  if(!byId.has(c.from)||!byId.has(c.to))throw Error('ASSEMBLY_DANGLING_CONNECTION');
+  parents.get(c.to).push(byId.get(c.from));children.get(c.from).push(byId.get(c.to));
+ }
+ const kindFlat=new Set(['conveyor','sorter','junction']);
+ const normalize=(x,z,fallback={x:1,z:0})=>{const n=Math.hypot(x,z);return n>1e-6?{x:x/n,z:z/n}:fallback;};
+ const vec=(a,b)=>normalize(b.position.x-a.position.x,b.position.z-a.position.z);
+ const P=(x,y,z)=>({x,y,z});
+ const add=(p,d,m)=>P(p.x+d.x*m,p.y,p.z+d.z*m);
+ const stations=new Map();
+ for(const e of model.equipment){
+  if(!kindFlat.has(e.kind)&&e.kind!=='spiral')continue;
+  const p=e.position,d=e.dimensions,baseY=p.y+1.1;
+  if(e.kind==='spiral'){
+   const input=parents.get(e.id).find(s=>s.floor===e.floor);
+   const output=children.get(e.id).find(s=>s.floor!==e.floor);
+   const inward=input?vec(input,e):{x:1,z:0};
+   const outward=output?vec(e,output):inward;
+   // Tangent-facing ports, not arbitrary points on the spiral radius.
+   const startAngle=Math.atan2(inward.z,inward.x)-Math.PI/2;
+   const goalAngle=Math.atan2(outward.z,outward.x)-Math.PI/2;
+   const sweep=(goalAngle-startAngle+Math.PI*10)%(Math.PI*2)+Math.PI*4;
+   const radius=Math.max(.72,Math.min(d.x,d.z)*.42);
+   const exitY=output?output.position.y+1.1:baseY+Math.max(2,d.y);
+   const sample=t=>{
+    const theta=startAngle+t*sweep;
+    return P(p.x+radius*Math.cos(theta),baseY+t*(exitY-baseY),p.z+radius*Math.sin(theta));
+   };
+   const at=t=>normalize(-Math.sin(startAngle+t*sweep),Math.cos(startAngle+t*sweep));
+   const helix=Array.from({length:193},(_,i)=>sample(i/192));
+   stations.set(e.id,{id:e.id,kind:e.kind,geometry_status:'CONCEPTUAL_ASSEMBLY_REVIEW_REQUIRED',
+    entry:helix[0],exit:helix.at(-1),entryTangent:at(0),exitTangent:at(1),helix,
+    length:0,radius,baseY,exitY});
+   continue;
+  }
+  const incoming=parents.get(e.id).filter(x=>x.floor===e.floor&&x.kind!=='spiral');
+  const outgoing=children.get(e.id).filter(x=>x.floor===e.floor&&x.kind!=='spiral');
+  const incomingAll=parents.get(e.id),outgoingAll=children.get(e.id);
+  const source=incoming[0]||incomingAll[0];
+  const targets=outgoing.length?outgoing:outgoingAll;
+  // Orient the bed to the ACTUAL material-flow direction, including reversals.
+  let direction;
+  if(source&&targets.length){const i=vec(source,e),o=vec(e,targets[0]);direction=normalize(i.x+o.x,i.z+o.z,o);}
+  else if(targets.length)direction=vec(e,targets[0]);
+  else if(source)direction=vec(source,e);
+  else direction={x:1,z:0};
+  const length=Math.max(.65,d.x*.93),center=P(p.x,baseY,p.z);
+  const entry=add(center,direction,-length/2),exit=add(center,direction,length/2);
+  const outlets={};
+  for(const t of outgoingAll){
+   let endpoint=exit,tangent=direction;
+   if(e.kind==='sorter'&&outgoingAll.length>1){
+    const towards=vec(e,t),lateral=direction.x*towards.z-direction.z*towards.x;
+    // A genuine branch chute must leave the sorter side, never float from its center.
+    if(Math.abs(lateral)>.12){
+     const side=Math.sign(lateral);
+     const perp={x:-direction.z*side,z:direction.x*side};
+     endpoint=add(add(center,direction,length*.10),perp,Math.max(.48,d.z*.46));
+     tangent=normalize(direction.x*.45+perp.x*.85,direction.z*.45+perp.z*.85);
+    }
+   }
+   outlets[t.id]={point:endpoint,tangent};
+  }
+  stations.set(e.id,{id:e.id,kind:e.kind,geometry_status:'CONCEPTUAL_ASSEMBLY_REVIEW_REQUIRED',
+   direction,length,entry,exit,entryTangent:direction,exitTangent:direction,outlets,
+   center,baseY,branches:Object.entries(outlets).filter(([,v])=>v.point!==exit).map(([id,v])=>({to:id,from:center,toPoint:v.point}))});
+ }
+ const routes=[];
+ for(const c of model.connections){
+  const a=byId.get(c.from),b=byId.get(c.to),sa=stations.get(c.from),sb=stations.get(c.to);
+  const cross=a.floor!==b.floor;
+  const spiral=a.kind==='spiral'||b.kind==='spiral';
+  const physical=!!sa&&!!sb&&(!cross||spiral);
+  let kind=physical?(cross?'conceptual_spiral_transfer':'conceptual_conveyor_transition'):'logical_unverified';
+  if(!physical){routes.push({from:c.from,to:c.to,kind,geometry_status:'LOGICAL_CONNECTION_UNVERIFIED',
+   points:[P(a.position.x,a.position.y+1.1,a.position.z),P(b.position.x,b.position.y+1.1,b.position.z)],from_floor:a.floor,to_floor:b.floor});continue;}
+  const out=sa.outlets?.[b.id]||{point:sa.exit,tangent:sa.exitTangent};
+  const p=out.point,q=sb.entry;
+  const diff=Math.hypot(q.x-p.x,q.y-p.y,q.z-p.z),lead=Math.min(2.2,Math.max(.15,diff*.23));
+  const pts=[p,add(p,out.tangent,lead),add(q,sb.entryTangent,-lead),q];
+  // Adjacent belts share EXACT generated port coordinates; no hand-wavy
+  // center-to-center lines or disconnected endpoint approximations.
+  routes.push({from:c.from,to:c.to,kind,geometry_status:'CONCEPTUAL_CONNECTION_NEEDS_APPROVAL',
+   points:pts,from_floor:a.floor,to_floor:b.floor,from_port:p,to_port:q,
+   endpoint_error:0,route_length:diff});
+ }
+ return {stations:Object.fromEntries(stations),routes,source_edges:model.connections.map(c=>c.from+'>'+c.to),
+  disclaimer:'PREVIEW_ONLY_NO_PHYSICAL_CLEARANCE_OR_PORT_CERTIFICATION'};
+}
+
+/** Attach a sensor gantry to the nearest conceptual material path ONLY in the
+ * preview. The customer asset position is preserved in source and compiled data.
+ * Inspector exposes the visual displacement; no as-built assertion is made.
+ */
+export function planSensorMounts(model,assembly){
+ const out={};
+ for(const e of model.equipment){
+  if(!['scanner','photoeye'].includes(e.kind))continue;
+  let candidate=null;
+  for(const belt of model.equipment){
+   if(!['conveyor','sorter','junction'].includes(belt.kind)||belt.floor!==e.floor)continue;
+   const station=assembly.stations[belt.id];if(!station)continue;
+   const a=station.entry,b=station.exit,dx=b.x-a.x,dz=b.z-a.z;
+   const len2=dx*dx+dz*dz;if(len2<1e-6)continue;
+   const t=clamp(((e.position.x-a.x)*dx+(e.position.z-a.z)*dz)/len2,.05,.95);
+   const x=a.x+t*dx,z=a.z+t*dz,dist=Math.hypot(x-e.position.x,z-e.position.z);
+   if(!candidate||dist<candidate.distance){candidate={equipment:belt.id,position:{x,y:e.position.y,z},direction:station.direction,
+      distance:dist,source_position:{...e.position},status:'PREVIEW_SNAP_NEEDS_CUSTOMER_APPROVAL'};}
+  }
+  if(candidate&&candidate.distance<=3.8)out[e.id]=candidate;
+ }
+ return out;
+}
+
+/** Smooth, exact-endpoint conceptual sorter diverter geometry shared by Creator
+ * and generated Operator preview. It models a visual transition, NOT an OEM
+ * diverter's timing, actuators, permissives, or physical belt configuration.
+ */
+export function sorterBranchPoints(station,targetId){
+ const branch=station?.outlets?.[targetId];
+ if(station?.kind!=='sorter'||!branch||!station.center||!station.direction)return null;
+ const p=station.center,q=branch.point;
+ const distance=Math.hypot(q.x-p.x,q.y-p.y,q.z-p.z);
+ if(distance<.01)return null;
+ const normal=(x,z)=>{const n=Math.hypot(x,z);return n>1e-9?{x:x/n,z:z/n}:{x:1,z:0};};
+ const inDir=normal(station.direction.x,station.direction.z);
+ const outDir=normal(branch.tangent.x,branch.tangent.z);
+ const lead=Math.min(.58,distance*.26);
+ return [p,{x:p.x+inDir.x*lead,y:p.y,z:p.z+inDir.z*lead},
+  {x:q.x-outDir.x*lead,y:q.y,z:q.z-outDir.z*lead},q];
+}