@hatiolab/figure-model 0.1.30 → 0.1.31

package/docs/prototypes/v3-kernel.mjs

@@ -0,0 +1,147 @@
+// Experimental executable contract. No product imports and no model-name branches.
+// Scalars are numeric in documented fixture units, NOT statically unit checked yet.
+export class DesignError extends Error {
+  constructor(code, path, detail) { super(`${code}: ${path}: ${detail}`); this.code=code; this.path=path }
+}
+const fail=(code,path,detail)=>{throw new DesignError(code,path,detail)}
+const finite=(x,path)=>{if(!Number.isFinite(x))fail('NON_FINITE',path,String(x));return x}
+const add=(a,b)=>a.map((v,i)=>v+b[i])
+const sub=(a,b)=>a.map((v,i)=>v-b[i])
+const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
+const I=()=>[[1,0,0],[0,1,0],[0,0,1]]
+const mv=(r,v)=>r.map(row=>dot(row,v))
+const mm=(a,b)=>a.map(row=>[0,1,2].map(i=>dot(row,b.map(r=>r[i]))))
+export const point=(f,p)=>add(mv(f.rotation,p),f.position)
+function rot(axis,degrees,path) {
+  const norm=Math.hypot(...axis)
+  if(Math.abs(norm-1)>1e-10)fail('AXIS',path,'unit axis required')
+  const [x,y,z]=axis,c=Math.cos(degrees*Math.PI/180),s=Math.sin(degrees*Math.PI/180),k=1-c
+  return [[c+x*x*k,x*y*k-z*s,x*z*k+y*s],[y*x*k+z*s,c+y*y*k,y*z*k-x*s],[z*x*k-y*s,z*y*k+x*s,c+z*z*k]]
+}
+
+export function resolve(model,inputs) {
+  const values={},active=new Set(),defs=model.values??{},spec=model.inputs??{}
+  for(const k of Object.keys(inputs))if(!Object.hasOwn(spec,k))fail('UNKNOWN_INPUT',k,'not declared')
+  for(const [k,s] of Object.entries(spec)) {
+    if(Object.hasOwn(defs,k))fail('DUPLICATE_WRITER',k,'input and derived')
+    const x=finite(inputs[k],k)
+    if(x<s.min||x>s.max)fail('INPUT_RANGE',k,`${x} outside [${s.min},${s.max}]`)
+    values[k]=x
+  }
+  function expression(e,path='expression') {
+    if(typeof e==='number')return finite(e,path)
+    if(typeof e==='string')return value(e)
+    if(!e||!Array.isArray(e.args))fail('EXPRESSION',path,'expected number, reference or operator')
+    const a=e.args.map(x=>expression(x,path))
+    if(e.op==='add')return finite(a.reduce((s,x)=>s+x,0),path)
+    if(e.op==='mul'&&a.length===2)return finite(a[0]*a[1],path)
+    fail('EXPRESSION',path,'unsupported operator/arity')
+  }
+  function value(k) {
+    if(Object.hasOwn(values,k))return values[k]
+    if(!Object.hasOwn(defs,k))fail('UNKNOWN_REFERENCE',k,'no definition')
+    if(active.has(k))fail('VALUE_CYCLE',k,[...active,k].join(' -> '))
+    active.add(k);values[k]=expression(defs[k],k);active.delete(k);return values[k]
+  }
+  for(const k of Object.keys(defs))value(k)
+  for(const c of model.assertions??[]) {
+    const left=expression(c.left,c.id),right=expression(c.right,c.id)
+    if(c.op!=='gte')fail('ASSERTION_OPERATOR',c.id,c.op)
+    if(left<right)fail('ASSERTION',c.id,`${left} < ${right}; deficit=${right-left}`)
+  }
+  const frames={},visiting=new Set(),nodes={...model.frames},geometry={...model.geometry},shapeCache={}
+  function vector(v,path) {
+    if(!Array.isArray(v)||v.length!==3)fail('VECTOR',path,'three coordinates required')
+    return v.map(e=>expression(e,path))
+  }
+  function repeatPlan(r,id) {
+    const pitch=expression(r.pitch,id),axis=vector(r.axis,id)
+    if(!(pitch>0)||Math.abs(Math.hypot(...axis)-1)>1e-10)fail('REPEAT_DOMAIN',id,'positive pitch and unit axis')
+    const count=r.mode==='fixed'?expression(r.count,id):r.mode==='pitch'?Math.floor(expression(r.span,id)/pitch):NaN
+    if(!Number.isInteger(count)||count<1||!Number.isInteger(r.limit)||count>r.limit)fail('REPEAT_DOMAIN',id,`count=${count}, limit=${r.limit}`)
+    return {count,pitch,axis}
+  }
+  // Lower one-level repeated assemblies into the SAME frame/geometry evaluator.
+  // No index-dependent scripting, cross-instance references or nested patterns yet.
+  for(const [name,p] of Object.entries(model.patterns??{})) {
+    const {count,pitch,axis}=repeatPlan(p.repeat,name)
+    const localFrames=p.frames??{},localShapes=p.geometry??{}
+    for(let i=0;i<count;i++) {
+      const prefix=kind=>id=>JSON.stringify(['pattern',name,i,kind,id])
+      const fid=prefix('frame'),gid=prefix('geometry'),root=fid('$root')
+      const insert=(target,id,value)=>{if(Object.hasOwn(target,id))fail('DUPLICATE_ID',id,'expanded pattern');target[id]=value}
+      if(Object.hasOwn(localFrames,'$root'))fail('RESERVED_ID',name,'$root')
+      insert(nodes,root,{parent:p.parent,position:axis.map(x=>x*i*pitch)})
+      for(const [id,n] of Object.entries(localFrames)) {
+        if(n.feature&&n.parent)fail('DUPLICATE_PARENT',id,'feature and parent')
+        if(n.parent&&!Object.hasOwn(localFrames,n.parent))fail('PATTERN_REFERENCE',name,n.parent)
+        if(n.feature&&!Object.hasOwn(localShapes,n.feature.geometry))fail('PATTERN_REFERENCE',name,n.feature.geometry)
+        insert(nodes,fid(id),{...n,parent:n.feature?undefined:n.parent?fid(n.parent):root,
+          ...(n.feature?{feature:{...n.feature,geometry:gid(n.feature.geometry)}}:{})})
+      }
+      for(const [id,g] of Object.entries(localShapes)) {
+        if(!Object.hasOwn(localFrames,g.frame))fail('PATTERN_REFERENCE',name,g.frame)
+        if(g.repeat)fail('NESTED_REPEAT',name,id)
+        insert(geometry,gid(id),{...g,frame:fid(g.frame)})
+      }
+    }
+  }
+  function shape(id) {
+    if(Object.hasOwn(shapeCache,id))return shapeCache[id]
+    if(!Object.hasOwn(geometry,id))fail('UNKNOWN_GEOMETRY',id,'no definition')
+    const g=geometry[id],dimensions=Object.fromEntries(Object.entries(g.dimensions).map(([k,v])=>[k,expression(v,id)]))
+    const required=g.kind==='box'?['width','height','depth']:g.kind==='cylinder'?['radius','length']:null
+    if(!required||Object.keys(dimensions).length!==required.length||required.some(k=>!(dimensions[k]>0)))fail('GEOMETRY_DOMAIN',id,'positive provider dimensions required')
+    return shapeCache[id]={g,dimensions,orientation:g.orientation?rot(vector(g.orientation.axis,id),expression(g.orientation.angle,id),id):I()}
+  }
+  function featureFrame(feature,id) {
+    const {g,dimensions:d,orientation}=shape(feature.geometry)
+    if(g.repeat)fail('AMBIGUOUS_FEATURE',id,'use a pattern instance, not a repeated primitive')
+    const owner=frame(g.frame),shapeFrame={position:owner.position,rotation:mm(owner.rotation,orientation)}
+    // Named points retain provider axes. These are NOT normal-oriented attachment frames.
+    const points=g.kind==='box'?{'x-':[-d.width/2,0,0],'x+':[d.width/2,0,0],'y-':[0,-d.height/2,0],'y+':[0,d.height/2,0],'z-':[0,0,-d.depth/2],'z+':[0,0,d.depth/2]}:
+      {'start':[0,-d.length/2,0],'end':[0,d.length/2,0]}
+    if(!Object.hasOwn(points,feature.point))fail('UNKNOWN_FEATURE',id,feature.point)
+    return {position:point(shapeFrame,points[feature.point]),rotation:shapeFrame.rotation}
+  }
+  function frame(id) {
+    if(Object.hasOwn(frames,id))return frames[id]
+    const node=nodes[id]
+    if(!Object.hasOwn(nodes,id))fail('UNKNOWN_FRAME',id,'no definition')
+    if(visiting.has(id))fail('FRAME_CYCLE',id,[...visiting,id].join(' -> '))
+    visiting.add(id)
+    if(node.feature&&node.parent)fail('DUPLICATE_PARENT',id,'feature and parent')
+    const parent=node.feature?featureFrame(node.feature,id):node.parent?frame(node.parent):{position:[0,0,0],rotation:I()}
+    const offset=vector(node.position??[0,0,0],id)
+    const rest=node.orientation?rot(vector(node.orientation.axis,id),expression(node.orientation.angle),id):I()
+    let localOffset=offset,localRotation=rest
+    if(node.joint) {
+      const j=node.joint,axis=vector(j.axis,id),q=expression(j.value,id)
+      if(Math.abs(Math.hypot(...axis)-1)>1e-10)fail('AXIS',id,'unit axis required')
+      if(j.type==='slide')localOffset=add(offset,mv(rest,axis.map(x=>x*q)))
+      else if(j.type==='hinge') {
+        const pivot=vector(j.pivot??[0,0,0],id),r=rot(axis,q,id)
+        localOffset=add(offset,mv(rest,sub(pivot,mv(r,pivot))));localRotation=mm(rest,r)
+      } else fail('JOINT',id,j.type)
+    }
+    frames[id]={position:point(parent,localOffset),rotation:mm(parent.rotation,localRotation)}
+    if(![...frames[id].position,...frames[id].rotation.flat()].every(Number.isFinite))fail('NON_FINITE',id,'frame')
+    visiting.delete(id);return frames[id]
+  }
+  for(const id of Object.keys(nodes))frame(id)
+  const instances=[]
+  for(const [id,g] of Object.entries(geometry)) {
+    const owner=frame(g.frame),{dimensions,orientation}=shape(id)
+    let count=1,pitch=0,axis=[1,0,0]
+    if(g.repeat) {
+      ;({count,pitch,axis}=repeatPlan(g.repeat,id))
+    }
+    // Shape-local orientation follows placement. It does not rotate the repetition row.
+    for(let i=0;i<count;i++) {
+      // Start-anchored identity policy for this experiment. Not approved migration semantics.
+      instances.push({id:JSON.stringify([id,i]),source:id,index:i,kind:g.kind,dimensions:{...dimensions},
+        frame:{rotation:mm(owner.rotation,orientation),position:point(owner,axis.map(x=>x*i*pitch))}})
+    }
+  }
+  return {values,frames,instances}
+}

package/docs/prototypes/v3-kernel.test.mjs

@@ -0,0 +1,144 @@
+import fs from 'node:fs'
+import assert from 'node:assert/strict'
+import {test} from 'node:test'
+import {resolve,point,DesignError} from './v3-kernel.mjs'
+
+const seeds=JSON.parse(fs.readFileSync(new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url)))
+const robot=JSON.parse(fs.readFileSync(new URL('../../src/fixtures/robot-arm-6dof.json',import.meta.url)))
+const source=t=>seeds.find(s=>s.type===t).source
+const part=(s,n)=>s.parts.find(p=>p.name===n)
+const add=(...args)=>({op:'add',args}),mul=(a,b)=>({op:'mul',args:[a,b]})
+const range=(min,max)=>({min,max})
+const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-7,`${a} != ${b}`)
+const xyz=v=>[v.x,v.y,v.z]
+const equal=(a,b)=>a.forEach((v,i)=>near(v,b[i]))
+const diff=(a,b)=>a.map((x,i)=>x-b[i])
+
+// Authored fixture adapters only. They are not general-purpose v2 migration.
+function conveyor() {
+  const s=source('CONVEYOR'),p=part(s,'roller'),pitch=p.repeat.pitch,r=p.transform.size.x/2
+  return {inputs:{width:range(100,16000),depth:range(81,1800),angle:range(-360,360)},
+    values:{length:add('depth',-80)},assertions:[],
+    frames:{row:{position:[add(mul(-.5,'width'),pitch/2),p.transform.position.y,0],orientation:{axis:[1,0,0],angle:90},joint:{type:'hinge',axis:[0,1,0],value:'angle'}}},
+    geometry:{roller:{frame:'row',kind:'cylinder',dimensions:{radius:r,length:'length'},repeat:{mode:'pitch',span:'width',pitch,axis:[1,0,0],limit:100}}}}
+}
+// Repetition is a placement operation, not movement around the roller's own axis.
+// Give each roller a spinning feature via separate evaluation in the test below.
+// The candidate above deliberately exposes whether joint order corrupts row placement.
+function cradle() {
+  const s=source('ROLL_CRADLE'),roll=part(s,'roll'),core=part(s,'core')
+  return {inputs:{radial:range(.5,2),axial:range(.5,2),fed:range(0,100)},
+    values:{fraction:add(1,mul(-.0068,'fed')),radius:mul(mul(roll.transform.size.x/2,'radial'),'fraction'),coreRadius:mul(core.transform.size.x/2,'radial')},
+    assertions:[{id:'roll-outside-core',op:'gte',left:'radius',right:'coreRadius'}],
+    frames:{axis:{position:xyz(roll.transform.position),orientation:{axis:[0,0,1],angle:90}}},
+    geometry:{roll:{frame:'axis',kind:'cylinder',dimensions:{radius:'radius',length:mul(roll.transform.size.y,'axial')}},core:{frame:'axis',kind:'cylinder',dimensions:{radius:'coreRadius',length:mul(core.transform.size.y,'axial')}}}}
+}
+function robotModel() {
+  const model={inputs:{linkScale:range(.5,2)},values:{},frames:{},geometry:{}}
+  for(const j of robot.joints)model.inputs[j.name]=range(j.limits?.min??-360,j.limits?.max??360)
+  for(const p of robot.parts) {
+    const parent=p.parent?xyz(part(robot,p.parent).transform.position):[0,0,0]
+    const relative=diff(xyz(p.transform.position),parent),j=robot.joints.find(j=>j.child===p.name)
+    model.frames[p.name]={parent:p.parent,position:relative.map((v,i)=>i===1?mul(v,'linkScale'):v)}
+    if(j)model.frames[p.name].joint={type:'hinge',axis:xyz(j.axis),value:j.name,
+      pivot:diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?mul(v,'linkScale'):v)}
+    const size=p.transform.size
+    model.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?
+      {radius:size.x/2,length:mul(size.y,'linkScale')}:{width:size.x,height:mul(size.y,'linkScale'),depth:size.z}}
+  }
+  return model
+}
+function forklift() {
+  const s=source('FORKLIFT'),m={inputs:{heightScale:range(.5,2),lift:range(0,2000),reach:range(0,400)},values:{},frames:{},geometry:{}}
+  // Motion-only frames at rest origin; all descendants retain original source rest coordinates.
+  m.frames.reach={joint:{type:'slide',axis:[0,0,1],value:'reach'}}
+  m.frames.stage={parent:'reach',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
+  m.frames.carriageMotion={parent:'stage',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
+  for(const p of s.parts) {
+    const parent=p.name.startsWith('mast-')?'reach':p.name.startsWith('stage-')?'stage':(p.name==='carriage'||p.name.startsWith('fork-'))?'carriageMotion':undefined
+    m.frames[p.name]={parent,position:xyz(p.transform.position).map((v,i)=>i===1?mul(v,'heightScale'):v)}
+    if(p.transform.rotation)m.frames[p.name].orientation={axis:[0,0,1],angle:p.transform.rotation.z}
+    const d=p.transform.size
+    m.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?{radius:d.x/2,length:d.y}:{width:d.x,height:mul(d.y,'heightScale'),depth:d.z}}
+  }
+  return m
+}
+
+test('robot: common kernel, 3 link scales × 32 poses; shared pivots and rest geometry',()=>{
+  const model=robotModel();let checks=0
+  for(const scale of [.5,1,2])for(let n=0;n<32;n++) {
+    const inputs={linkScale:scale,...Object.fromEntries(robot.joints.map((j,i)=>[j.name,n===0?0:(j.limits?.min??-360)+(n*(i+1)%31)/30*((j.limits?.max??360)-(j.limits?.min??-360))]))}
+    const out=resolve(model,inputs)
+    assert.equal(out.instances.length,10)
+    for(const j of robot.joints) {
+      const p=part(robot,j.child),parent=part(robot,p.parent)
+      const childPivot=diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?v*scale:v)
+      const parentPivot=diff(xyz(j.origin),xyz(parent.transform.position)).map((v,i)=>i===1?v*scale:v)
+      equal(point(out.frames[p.name],childPivot),point(out.frames[parent.name],parentPivot));checks++
+    }
+    if(n===0)for(const p of robot.parts)equal(out.frames[p.name].position,xyz(p.transform.position).map((v,i)=>i===1?v*scale:v))
+  }
+  console.log({robotStates:96,pivotChecks:checks})
+})
+
+test('cradle: common kernel, 3 radial × 3 axial × 5 feed states',()=>{
+  const model=cradle()
+  for(const radial of [.5,1,2])for(const axial of [.5,1,2])for(const fed of [0,25,50,75,100]) {
+    const out=resolve(model,{radial,axial,fed}),[roll,core]=out.instances
+    near(roll.dimensions.radius,350*radial*(1-.0068*fed));near(roll.dimensions.length,1000*axial)
+    assert.ok(roll.dimensions.radius>=core.dimensions.radius)
+    equal(roll.frame.position,core.frame.position)
+  }
+})
+
+test('forklift: common kernel, 3 sizes × 3 lifts × 3 reaches, no double inheritance',()=>{
+  const model=forklift()
+  for(const heightScale of [.5,1,2])for(const lift of [0,1000,2000])for(const reach of [0,200,400]) {
+    const {frames:f,instances}=resolve(model,{heightScale,lift,reach})
+    assert.equal(instances.length,20)
+    equal(f.carriage.position,[0,260*heightScale+lift,338+reach])
+    near(f['stage-left'].position[1],940*heightScale+lift/2)
+    near(f['fork-high-left'].position[1]-f['fork-low-left'].position[1],400*heightScale)
+    near(f.body.position[2],-700)
+  }
+})
+
+test('conveyor: spin must not rotate repeat offsets; prototype rejects naive composition via oracle',()=>{
+  const m=conveyor(),a=resolve(m,{width:2400,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:90})
+  // Counterexample: placing repetition after owner joint makes the entire row orbit.
+  assert.ok(Math.hypot(...diff(a.instances[1].frame.position,b.instances[1].frame.position))>100)
+})
+
+test('conveyor: corrected placement-before-local-orientation, 5 widths × 3 depths × 3 spins',()=>{
+  const m=conveyor()
+  delete m.frames.row.joint
+  m.geometry.roller.orientation={axis:[0,1,0],angle:'angle'}
+  for(const width of [1200,2399.99,2400,2400.01,4800])for(const depth of [300,600,1200])for(const angle of [0,90,180]) {
+    const out=resolve(m,{width,depth,angle})
+    assert.equal(out.instances.length,Math.floor(width/150))
+    for(const [i,p] of out.instances.entries()) {
+      equal(p.frame.position,[-width/2+75+i*150,500,0])
+      near(p.dimensions.radius,48);near(p.dimensions.length,depth-80)
+      assert.ok(p.frame.position[0]-48>=-width/2&&p.frame.position[0]+48<=width/2)
+      equal(point(p.frame,[0,p.dimensions.length/2,0]),[p.frame.position[0],500,p.dimensions.length/2])
+    }
+  }
+  const a=resolve(m,{width:2399.99,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:0})
+  assert.deepEqual(a.instances.map(x=>x.id),b.instances.slice(0,15).map(x=>x.id))
+})
+
+test('rejection is explicit and does not mutate source; order independent',()=>{
+  const m=cradle(),before=JSON.stringify(m),input={radial:1,axial:1,fed:50}
+  const result=resolve(m,input),reversed={...m,values:Object.fromEntries(Object.entries(m.values).reverse()),frames:Object.fromEntries(Object.entries(m.frames).reverse())}
+  assert.deepEqual(resolve(reversed,input).instances,result.instances)
+  for(const [model,args,code] of [
+    [m,{...input,fed:101},'INPUT_RANGE'],
+    [{...m,values:{...m.values,radius:'missing'}},input,'UNKNOWN_REFERENCE'],
+    [{...m,values:{...m.values,radius:'radius'}},input,'VALUE_CYCLE'],
+    [{...m,frames:{axis:{parent:'axis'}}},input,'FRAME_CYCLE'],
+    [{...m,values:{...m.values,radius:0}},input,'ASSERTION'],
+    [conveyor(),{width:16000,depth:600,angle:0},'REPEAT_DOMAIN'],
+    [m,{...input,radial:NaN},'NON_FINITE']
+  ])assert.throws(()=>resolve(model,args),e=>e instanceof DesignError&&e.code===code)
+  assert.equal(JSON.stringify(m),before)
+})

package/docs/prototypes/v3-layout.test.mjs

@@ -0,0 +1,281 @@
+// Design witnesses only. Not imported by production; not a complete v3 evaluator.
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const eps = 1e-8
+const near = (a, b) => assert.ok(Math.abs(a - b) < eps, `${a} != ${b}`)
+const sum = xs => xs.reduce((a, b) => a + b, 0)
+const finite = x => assert.ok(Number.isFinite(x))
+const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x))
+
+// Share an amount proportionally, freezing capped members simultaneously.
+// A production implementation can sort breakpoints to reduce O(n²) to O(n log n).
+function share(amount, capacities, weights) {
+  assert.ok(amount >= 0 && Number.isFinite(amount))
+  capacities.forEach(c => assert.ok(c >= 0 && !Number.isNaN(c)))
+  weights.forEach(w => assert.ok(Number.isFinite(w) && w >= 0))
+  assert.equal(capacities.length, weights.length)
+  const result = capacities.map(() => 0)
+  let active = weights.map((w, i) => i).filter(i => weights[i] > 0 && capacities[i] > 0)
+  let remaining = amount
+  while (remaining > 0 && active.length) {
+    const total = sum(active.map(i => weights[i]))
+    const frozen = active.filter(i => remaining * weights[i] / total >= capacities[i])
+    if (!frozen.length) {
+      for (const i of active) result[i] = remaining * weights[i] / total
+      remaining = 0
+      break
+    }
+    for (const i of frozen) {
+      result[i] = capacities[i]
+      remaining -= capacities[i]
+    }
+    const set = new Set(frozen)
+    active = active.filter(i => !set.has(i))
+  }
+  return { values: result, remaining: Math.max(0, remaining) }
+}
+
+function flex(length, gap, items, justify = 'start') {
+  assert.ok(Number.isFinite(length) && length >= 0)
+  assert.ok(Number.isFinite(gap) && gap >= 0)
+  assert.ok(['start', 'center', 'end', 'space-between'].includes(justify))
+  for (const i of items) {
+    finite(i.basis); finite(i.min); finite(i.grow); finite(i.shrink)
+    assert.ok(i.min >= 0 && i.max >= i.min && !Number.isNaN(i.max))
+    assert.ok(i.grow >= 0 && i.shrink >= 0)
+  }
+  const available = length - gap * Math.max(0, items.length - 1)
+  const base = items.map(i => clamp(i.basis, i.min, i.max))
+  const delta = available - sum(base)
+  const shares = share(Math.abs(delta),
+    items.map((i, k) => delta >= 0 ? i.max - base[k] : base[k] - i.min),
+    items.map(i => delta >= 0 ? i.grow : i.shrink))
+  const sizes = base.map((v, i) => v + (delta >= 0 ? 1 : -1) * shares.values[i])
+  const leftover = available - sum(sizes)
+  const free = Math.max(0, leftover)
+  let leading = 0, effectiveGap = gap
+  if (leftover >= 0) {
+    if (justify === 'center') leading = free / 2
+    if (justify === 'end') leading = free
+    if (justify === 'space-between' && items.length > 1) effectiveGap += free / (items.length - 1)
+  }
+  let cursor = -length / 2 + leading
+  const centers = sizes.map(s => {
+    const center = cursor + s / 2
+    cursor += s + effectiveGap
+    return center
+  })
+  return { sizes, centers, overflow: Math.max(0, -leftover), free, effectiveGap }
+}
+const item = (basis, grow = 0, min = 0, max = Infinity, shrink = 0) =>
+  ({ basis, grow, min, max, shrink })
+
+function gridFr(length, gap, tracks) {
+  const bases = tracks.map(t => t.kind === 'fixed' ? t.size : t.min)
+  const available = length - gap * Math.max(0, tracks.length - 1)
+  const extra = share(Math.max(0, available - sum(bases)),
+    tracks.map((t, i) => t.kind === 'fixed' ? 0 : t.max - bases[i]),
+    tracks.map(t => t.kind === 'fixed' ? 0 : t.weight))
+  const sizes = bases.map((s, i) => s + extra.values[i])
+  return { sizes, overflow: Math.max(0, sum(sizes) - available) }
+}
+const fr = (weight = 1, min = 0, max = Infinity) => ({ kind: 'fr', weight, min, max })
+
+function autoTracks(tracks, requirements, gap) {
+  const sizes = tracks.map(t => t.kind === 'fixed' ? t.size : t.min)
+  const sorted = [...requirements].sort((a, b) => a.span-b.span || a.start-b.start ||
+    (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  for (const r of sorted) {
+    assert.ok(r.start >= 0 && r.span > 0 && r.start+r.span <= tracks.length)
+    const current = sum(sizes.slice(r.start, r.start+r.span)) + gap*(r.span-1)
+    const indices = Array.from({ length: r.span }, (_, k) => r.start+k)
+    const extra = share(Math.max(0, r.preferred-current),
+      indices.map(i => tracks[i].kind === 'auto' ? tracks[i].max-sizes[i] : 0),
+      indices.map(i => tracks[i].kind === 'auto' ? 1 : 0))
+    indices.forEach((i, k) => { sizes[i] += extra.values[k] })
+  }
+  return sizes
+}
+
+// Minimal value-DAG witness. No source-schema or production diagnostics implementation.
+function evaluateValues(nodes) {
+  const values = new Map(), visiting = new Set()
+  const byId = new Map(nodes.map(n => [n.id, n]))
+  assert.equal(byId.size, nodes.length, 'duplicate writer')
+  function visit(id) {
+    if (values.has(id)) return values.get(id)
+    assert.ok(byId.has(id), 'unknown reference')
+    assert.ok(!visiting.has(id), 'layout-cycle')
+    visiting.add(id)
+    const n = byId.get(id)
+    const result = n.compute(...n.deps.map(visit))
+    finite(result)
+    visiting.delete(id); values.set(id, result)
+    return result
+  }
+  nodes.forEach(n => visit(n.id))
+  return values
+}
+
+function vecNear(a, b) { a.forEach((v, i) => near(v, b[i])) }
+const add = (a, b) => a.map((v, i) => v + b[i])
+const rotateZ = (p, a) => [Math.cos(a)*p[0]-Math.sin(a)*p[1],
+  Math.sin(a)*p[0]+Math.cos(a)*p[1], p[2]]
+
+test('two door leaves preserve margins, gap, and fully-open inner edges over 100 widths', () => {
+  for (let k = 0; k < 100; k++) {
+    const width = 60 + k * 73, margin = 10, gap = 10
+    const f = flex(width - 2*margin, gap, [item(0, 1), item(0, 1)])
+    const w = (width - 30)/2
+    near(f.sizes[0], w); near(f.sizes[1], w)
+    near(f.centers[0] - w/2, -width/2 + margin)
+    near(f.centers[1] - w/2 - (f.centers[0]+w/2), gap)
+    near(f.centers[1] + w/2, width/2 - margin)
+    const travel = (width-gap)/2
+    near(f.centers[0] - travel + w/2, -width/2)
+    near(f.centers[1] + travel - w/2, width/2)
+    near(f.overflow, 0)
+  }
+})
+
+test('grow saturates max then redistributes instead of losing space', () => {
+  const f = flex(300, 0, [item(50, 1, 0, 80), item(50, 3)])
+  vecNear(f.sizes, [80, 220])
+  near(sum(f.sizes), 300)
+})
+
+test('shrink freezes minima, remaining deficit is explicit', () => {
+  const f = flex(100, 0, [item(100, 0, 80, Infinity, 1), item(100, 0, 40, Infinity, 1)])
+  vecNear(f.sizes, [80, 40])
+  near(f.overflow, 20)
+  near(f.centers[0] - f.sizes[0]/2, -50)
+})
+
+test('zero weights do not silently resize fixed items', () => {
+  const f = flex(300, 10, [item(40), item(50)], 'center')
+  vecNear(f.sizes, [40, 50])
+  near(f.free, 200)
+  vecNear(f.centers, [-30, 25])
+})
+
+test('single and empty space-between have defined finite behavior', () => {
+  const one = flex(100, 5, [item(20)], 'space-between')
+  vecNear(one.centers, [-40])
+  assert.deepEqual(flex(100, 5, [], 'space-between').sizes, [])
+})
+
+test('gap itself can overflow without negative sizes or negative gap', () => {
+  const f = flex(5, 10, [item(0), item(0)])
+  near(f.overflow, 5)
+  vecNear(f.sizes, [0, 0])
+  near(f.effectiveGap, 10)
+})
+
+test('fr distributes after fixed tracks, gaps and minima', () => {
+  const f = gridFr(420, 10, [{ kind: 'fixed', size: 100 }, fr(1), fr(2)])
+  vecNear(f.sizes, [100, 100, 200])
+  near(f.overflow, 0)
+})
+
+test('fr maximum caps and fixed-track overflow are not hidden', () => {
+  vecNear(gridFr(500, 0, [fr(1, 0, 100), fr(1)]).sizes, [100, 400])
+  near(gridFr(100, 10, [{ kind: 'fixed', size: 60 }, { kind: 'fixed', size: 60 }]).overflow, 30)
+})
+
+test('50% plus 50% and a gap overflows, while 1fr plus 1fr fits', () => {
+  near(gridFr(100, 10, [{ kind: 'fixed', size: 50 }, { kind: 'fixed', size: 50 }]).overflow, 10)
+  vecNear(gridFr(100, 10, [fr(), fr()]).sizes, [45, 45])
+})
+
+test('rotated slot alignment preserves a chosen face center under global rigid transform', () => {
+  for (const a of [0, Math.PI/2, 0.713]) {
+    const target = [30, 80, 100], size = [40, 60, 20]
+    const anchorOffset = rotateZ([0, size[1]/2, 0], a)
+    const center = target.map((v, i) => v-anchorOffset[i])
+    vecNear(add(center, anchorOffset), target)
+    const worldOrigin = [-200, 500, 80], globalAngle = 0.421
+    vecNear(add(add(worldOrigin, rotateZ(center, globalAngle)), rotateZ(anchorOffset, globalAngle)),
+      add(worldOrigin, rotateZ(target, globalAngle)))
+  }
+})
+
+test('contain of a 90-degree rotated box uses rotated extent, not original dimensions', () => {
+  const original = [200, 100, 50], slot = [100, 100, 100]
+  const rotatedExtent = [original[1], original[0], original[2]]
+  const scale = Math.min(...slot.map((s, i) => s/rotatedExtent[i]))
+  near(scale, 0.5)
+  vecNear(rotatedExtent.map(x => x*scale), [50, 100, 25])
+})
+
+test('constant-weight allocation satisfies bounds and conservation across deterministic cases', () => {
+  let seed = 1847
+  const random = () => { seed = (1664525*seed+1013904223) >>> 0; return seed/2**32 }
+  for (let n = 1; n <= 8; n++) {
+    for (let run = 0; run < 100; run++) {
+      const caps = Array.from({ length: n }, () => random()*200)
+      const weights = Array.from({ length: n }, () => random()<0.2 ? 0 : 1+random()*4)
+      const amount = random()*1000
+      const result = share(amount, caps, weights)
+      result.values.forEach((x, i) => {
+        assert.ok(x >= -eps && x <= caps[i]+eps)
+        if (!weights[i]) near(x, 0)
+      })
+      near(sum(result.values)+result.remaining, amount)
+      near(sum(result.values), Math.min(amount, sum(caps.filter((_, i) => weights[i]>0))))
+    }
+  }
+})
+
+test('min/max branch boundaries are continuous but not one global affine formula', () => {
+  const evaluate = L => flex(L, 0, [item(0, 1, 0, 50), item(0, 1)]).sizes
+  vecNear(evaluate(99), [49.5, 49.5])
+  vecNear(evaluate(100), [50, 50])
+  vecNear(evaluate(101), [50, 51])
+  // Endpoints alone cannot establish an interior bound for a general piecewise-affine function.
+  const f = x => Math.min(x, 2-x)
+  near(f(0), 0); near(f(2), 0); near(f(1), 1)
+})
+
+test('invalid geometry-independent allocation inputs fail instead of becoming NaN', () => {
+  assert.throws(() => flex(NaN, 0, []))
+  assert.throws(() => flex(100, -1, []))
+  assert.throws(() => flex(100, 0, [item(5, -1)]))
+  assert.throws(() => flex(100, 0, [item(5, 1, 10, 2)]))
+})
+
+test('auto grid span allocation is stable under item array reordering and honors maxima', () => {
+  const tracks = Array.from({ length: 3 }, () => ({ kind: 'auto', min: 0, max: 100 }))
+  const requirements = [
+    { id: 'b', start: 1, span: 2, preferred: 180 },
+    { id: 'a', start: 0, span: 2, preferred: 150 }
+  ]
+  vecNear(autoTracks(tracks, requirements, 10), [70, 100, 70])
+  vecNear(autoTracks(tracks, [...requirements].reverse(), 10), [70, 100, 70])
+})
+
+test('span can retain unmet intrinsic demand without exceeding auto maxima', () => {
+  const sizes = autoTracks([
+    { kind: 'fixed', size: 20 }, { kind: 'auto', min: 0, max: 30 }
+  ], [{ id: 'a', start: 0, span: 2, preferred: 200 }], 10)
+  vecNear(sizes, [20, 30])
+  near(200-sum(sizes)-10, 140) // Must be reported/checked after final slot allocation.
+})
+
+test('parent intrinsic versus child percentage cycle is rejected, not guessed', () => {
+  assert.throws(() => evaluateValues([
+    { id: 'parent.measure', deps: ['child.size'], compute: x => x+20 },
+    { id: 'child.size', deps: ['parent.measure'], compute: x => x/2 }
+  ]), /layout-cycle/)
+})
+
+test('defined parent and intrinsic children resolve independently of source node order', () => {
+  const nodes = [
+    { id: 'child.size', deps: ['parent.size'], compute: x => x/2 },
+    { id: 'parent.size', deps: [], compute: () => 400 }
+  ]
+  near(evaluateValues(nodes).get('child.size'), 200)
+  near(evaluateValues([...nodes].reverse()).get('child.size'), 200)
+  assert.throws(() => evaluateValues([...nodes, nodes[0]]), /duplicate writer/)
+  assert.throws(() => evaluateValues([nodes[0]]), /unknown reference/)
+})