@hatiolab/figure-model 0.1.29 → 0.1.31

package/docs/prototypes/v3-authoring-session.test.mjs

@@ -0,0 +1,65 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {createAuthoringSession} from './v3-authoring-session.mjs'
+import {repeatedBinding} from './v3-repeated-binding.mjs'
+import {forkliftBindings} from './v3-capability-samples.mjs'
+import {defaults as conveyorDefaults} from './v3-full-conveyor.mjs'
+import {defaults as forkliftDefaults} from './v3-full-forklift.mjs'
+const doc=s=>({version:'figure-v3-prototype-1',model:s.model,capabilities:s.declaration})
+const edit=(input,value,unit='mm',kind='set-design')=>({kind,input,value,unit})
+const request=(changes,expectedRevision=0,origin='ui')=>({origin,expectedRevision,changes})
+const session=()=>createAuthoringSession(doc(repeatedBinding()),{...conveyorDefaults,selectedIndex:13})
+test('UI and AI use identical transactions and get identical candidate geometry',()=>{
+ const ui=session(),ai=session(),changes=[edit('length',3000)]
+ const a=ui.apply(request(changes,0,'ui')),b=ai.apply(request(changes,0,'ai'))
+ assert.deepEqual(a.evaluation,b.evaluation);assert.deepEqual(a.inputs,b.inputs);assert.deepEqual(a.report.effects,b.report.effects)
+ assert.equal(a.report.effects.geometry.added.length,4);assert.equal(a.revision,1)
+ assert.equal(a.report.validation.collision,'unverified')
+})
+test('preview is detached and read-only; apply reevaluates the request instead of trusting preview result',()=>{
+ const s=session(),before=s.read(),q=request([edit('length',3000)]),preview=s.preview(q)
+ assert.deepEqual(s.read(),before);preview.candidate.inputs.length=1;preview.candidate.evaluation.geometry.length=0
+ const result=s.apply(q);assert.equal(result.inputs.length,3000);assert.ok(result.evaluation.geometry.length>0)
+})
+test('broken repeated reference rolls back everything; a valid batch retargets explicitly',()=>{
+ const s=session(),before=s.read()
+ assert.throws(()=>s.apply(request([edit('length',900)])),e=>e.code==='TARGET_ABSENT');assert.deepEqual(s.read(),before)
+ const r=s.apply(request([edit('length',900),edit('selectedIndex',0,'count')]))
+ assert.equal(r.revision,1);assert.equal(r.inputs.selectedIndex,0);assert.equal(r.report.effects.geometry.removed.length,10)
+ assert.notEqual(r.evaluation.bindings[0].targetGeometryId,before.evaluation.bindings[0].targetGeometryId)
+})
+test('stale AI proposal cannot overwrite a UI edit, including after undo (no revision reuse)',()=>{
+ const s=session(),old=request([edit('length',3000)],0,'ai');s.preview(old)
+ s.apply(request([edit('length',2550)]));assert.throws(()=>s.apply(old),e=>e.code==='REVISION_CONFLICT')
+ const restored=s.undo({origin:'ui',expectedRevision:1});assert.equal(restored.inputs.length,2400);assert.equal(restored.revision,2)
+ assert.throws(()=>s.apply(old),e=>e.code==='REVISION_CONFLICT')
+})
+test('undo/redo restore geometry and binding; failed edits and no-ops preserve redo',()=>{
+ const s=session(),base=s.read(),changed=s.apply(request([edit('length',3000)]))
+ const back=s.undo({origin:'ai',expectedRevision:1});assert.deepEqual(back.evaluation,base.evaluation)
+ assert.throws(()=>s.apply(request([edit('length',900)],2)),e=>e.code==='TARGET_ABSENT')
+ const noop=s.apply(request([edit('length',2400)],2));assert.equal(noop.revision,2);assert.equal(noop.canRedo,true)
+ const redone=s.redo({origin:'ui',expectedRevision:2});assert.deepEqual(redone.evaluation,changed.evaluation)
+ s.undo({origin:'ui',expectedRevision:3});s.apply(request([edit('length',2550)],4));assert.equal(s.read().canRedo,false)
+})
+test('role, unit, duplicate, range and unknown input errors cannot partially edit',()=>{
+ const s=session(),before=s.read()
+ for(const changes of [[edit('angle',37,'deg')],[edit('length',3,'m')],[edit('length',3000),edit('length',2400)],[edit('width',0)],[edit('missing',1)],[edit('length',3000),edit('width',NaN)]]){
+  assert.throws(()=>s.apply(request(changes)));assert.deepEqual(s.read(),before)
+ }
+})
+test('simultaneous forklift design/state edit moves bindings once and survives undo',()=>{
+ const s=createAuthoringSession(doc(forkliftBindings()),forkliftDefaults),before=s.read()
+ const r=s.apply(request([edit('forkLength',1275),edit('lift',1000,'mm','set-state'),edit('reach',200,'mm','set-state')],0,'ai'))
+ assert.deepEqual(r.evaluation.bindings[0].pose.t,[-260,1057,1197.5]);assert.equal(r.revision,1)
+ assert.deepEqual(s.undo({origin:'ui',expectedRevision:1}).evaluation,before.evaluation)
+})
+test('bounded history and externally mutated snapshots cannot corrupt future edits',()=>{
+ const s=session()
+ for(let i=0;i<55;i++)s.apply(request([edit('length',i%2?2400:2550)],i))
+ let view=s.read();view.inputs.length=0;view.evaluation.geometry.length=0
+ assert.ok(s.read().evaluation.geometry.length>0)
+ for(let i=0;i<50;i++)s.undo({origin:'ui',expectedRevision:55+i})
+ assert.equal(s.read().canUndo,false);assert.equal(s.read().canRedo,true)
+ assert.throws(()=>s.undo({origin:'ui',expectedRevision:105}),e=>e.code==='NOTHING_TO_UNDO')
+})

package/docs/prototypes/v3-capability-plan.mjs

@@ -0,0 +1 @@
+export {compileV3Capabilities as compileCapabilities} from '../../src/v3-capabilities.ts'

package/docs/prototypes/v3-capability-plan.test.mjs

@@ -0,0 +1,56 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {compileCapabilities} from './v3-capability-plan.mjs'
+import {robotBinding,forkliftBindings} from './v3-capability-samples.mjs'
+import {defaults as robotDefaults} from './v3-full-robot.mjs'
+import {defaults as forkDefaults} from './v3-full-forklift.mjs'
+import {compile} from './v3-typed-plan.mjs'
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-7)
+const run=s=>compileCapabilities(s.model,s.declaration)
+test('robot grip follows changing links and six joints without creating or hiding solids',()=>{
+ const s=robotBinding(),p=run(s),core=compile(s.model);let cases=0
+ for(const upperLength of [210,420,840])for(const foreLength of [190,380,760])for(const angle of [-60,0,60])for(const gripper of [0,50,100]){
+  const args={...robotDefaults,upperLength,foreLength,gripper,'base-pan':angle,'shoulder-lift':angle,'elbow-flex':angle,'wrist-pitch':angle,'wrist-yaw':angle,'tool-roll':angle}
+  const result=p.evaluate(args),base=core.evaluate(args)
+  assert.deepEqual(result.geometry,base.geometry);assert.equal(result.geometry.length,10)
+  assert.ok(result.geometry.some(g=>g.id==='tool-seat'))
+  assert.deepEqual(result.bindings[0].pose,base.values.flangeWorldTop)
+  for(const key of ['spatial','collision','safety'])assert.equal(result.bindings[0].checks[key].status,'unverified')
+  cases++
+ }
+ console.log({robotBindingStates:cases})
+})
+test('both forklift seats follow actual top faces through lift, reach and fork length exactly once',()=>{
+ const s=forkliftBindings(),p=run(s);let cases=0
+ for(const forkLength of [425,850,1700])for(const lift of [0,1000,2000])for(const reach of [0,200,400]){
+  const r=p.evaluate({...forkDefaults,forkLength,lift,reach});assert.equal(r.geometry.length,20)
+  for(const b of r.bindings){near(b.pose.t[0],-260);near(b.pose.t[1],(b.id==='load-low'?57:457)+lift);near(b.pose.t[2],360+forkLength/2+reach);assert.equal(b.contacts.length,2);near(b.contacts[1].pose.t[0],260);assert.equal(b.region,null)}
+  cases++
+ }
+ console.log({forkliftBindingStates:cases})
+})
+test('eligibility is separate from fit/collision/safety, no occupancy mutation or reservation',()=>{
+ const p=run(robotBinding())
+ for(const [request,status] of [[undefined,'unverified'],[{type:'BOX',occupied:0},'satisfied'],[{type:'PALLET',occupied:0},'failed'],[{type:'BOX',occupied:1},'failed']]){
+  const requests=request?{'tool-grip':request}:{},before=structuredClone(requests),r=p.evaluate(robotDefaults,requests)
+  assert.equal(r.bindings[0].checks.eligibility.status,status);assert.equal(r.bindings[0].checks.collision.status,'unverified');assert.deepEqual(requests,before)
+ }
+ assert.throws(()=>p.evaluate(robotDefaults,{'tool-grip':{type:'BOX',occupied:-1}}),e=>e.code==='OCCUPANCY')
+ assert.throws(()=>p.evaluate(robotDefaults,{unknown:{type:'BOX',occupied:0}}),e=>e.code==='SCHEMA')
+})
+test('missing references, wrong frame, wrong units, duplicate ids and ambiguous roles fail closed',()=>{
+ const checks=[['TARGET_ABSENT',b=>b.pose='deleted'],['FRAME_TYPE',b=>b.frame='wrong'],['ROLE',b=>b.role='slot'],['CAPACITY',b=>b.capacity=1.5],['TYPE',b=>b.region={kind:'centered-box',dimensions:['gripper','upperLength','foreLength']}],['SCHEMA',b=>b.region=null],['SCHEMA',b=>b.hidden=true]]
+ for(const [code,edit] of checks){const s=robotBinding();edit(s.declaration.bindings[0]);assert.throws(()=>run(s),e=>e.code===code)}
+ const s=robotBinding();s.declaration.bindings.push(structuredClone(s.declaration.bindings[0]));assert.throws(()=>run(s),e=>e.code==='DUPLICATE_BINDING')
+})
+test('region values have canonical mm, are not solid meshes, reject zero and recover atomically',()=>{
+ const s=robotBinding();s.model.inputs.push({id:'clearance',unit:'cm',min:0,max:10});s.declaration.bindings[0].region={kind:'centered-box',dimensions:['upperLength','foreLength','clearance']}
+ const p=run(s),args={...robotDefaults,clearance:2},first=p.evaluate(args)
+ assert.deepEqual(first.bindings[0].region.dimensions,[420,380,20]);assert.equal(first.geometry.length,10);assert.equal(first.bindings[0].checks.spatial.status,'unverified')
+ assert.throws(()=>p.evaluate({...args,clearance:0}),e=>e.code==='REGION_DOMAIN');assert.deepEqual(p.evaluate(args),first)
+})
+test('compiled declaration and returned results are isolated from external mutation',()=>{
+ const s=robotBinding(),p=run(s),a=p.evaluate(robotDefaults),snapshot=structuredClone(a)
+ s.declaration.bindings[0].pose='deleted';s.model.nodes.length=0;a.bindings[0].pose.t[0]=999;a.geometry.length=0
+ assert.deepEqual(p.evaluate(robotDefaults),snapshot)
+})

package/docs/prototypes/v3-capability-samples.mjs

@@ -0,0 +1,23 @@
+import {fullModel as robotModel} from './v3-full-robot.mjs'
+import {fullModel as forkliftModel} from './v3-full-forklift.mjs'
+export function robotBinding(){
+ const model=robotModel()
+ // Explicit experimental grip reference. Original tool-seat solid is NOT removed.
+ const declaration={version:'r3-capability-3',assetFrame:'world',bindings:[{id:'tool-grip',label:'툴 파지 기준',role:'grip',frame:'flangetop',pose:'flangeWorldTop',accepts:['BOX','WORKPIECE'],capacity:1}]}
+ return {model,declaration}
+}
+export function forkliftBindings(){
+ const model=forkliftModel(),bindings=[]
+ const n=(id,op,args,outputs,params)=>model.nodes.push({id,op,args,outputs,...(params?{params}:{})})
+ for(const level of ['low','high']){
+  const frames=[]
+  for(const side of ['left','right']){
+   const id=`fork-${level}-${side}`
+   n(id+'Top','feature@1',[id+'Shape'],{pose:id+'Top'},{frame:id+'Top',name:'top'})
+   n(id+'WorldTop','compose@1',[id+'PartPose',id+'Top'],{pose:id+'WorldTop'});frames.push(id+'WorldTop')
+  }
+  // Binding at the left support face, not an invented solid spanning the fork gap.
+  bindings.push({id:`load-${level}`,label:level==='low'?'하단 포크 받침 기준':'상단 포크 받침 기준',role:'seat',frame:`fork-${level}-leftTop`,pose:frames[0],contacts:['left','right'].map(side=>({placement:`fork-${level}-${side}Placed`,feature:`fork-${level}-${side}Top`})),accepts:['PALLET'],capacity:1})
+ }
+ return {model,declaration:{version:'r3-capability-3',assetFrame:'world',bindings}}
+}

package/docs/prototypes/v3-document.mjs

@@ -0,0 +1,2 @@
+export {compileV3Document as compileDocument,parseV3Document as parseDocument,serializeV3Document as serializeDocument} from '../../src/v3-document.ts'
+export {assertV3Json as jsonOnly,parseV3Json as parseStrictJson,V3_JSON_MAX_BYTES as MAX_BYTES,v3Utf8ByteLength} from '../../src/v3-json.ts'

package/docs/prototypes/v3-document.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Experimental V3 graph and capability document (not the complete Figure asset format)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "model", "capabilities"],
+  "properties": {
+    "version": {"const": "figure-v3-prototype-1"},
+    "model": {"$ref": "#/$defs/model"},
+    "capabilities": {"$ref": "#/$defs/capabilities"}
+  },
+  "$defs": {
+    "text": {"type": "string", "minLength": 1},
+    "ref": {"type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_.-]*$"},
+    "unit": {"enum": ["mm", "cm", "m", "rad", "deg", "s", "ratio", "percent", "count"]},
+    "input": {
+      "type": "object", "additionalProperties": false, "required": ["id", "unit", "min", "max"],
+      "properties": {"id": {"$ref": "#/$defs/ref"}, "unit": {"$ref": "#/$defs/unit"}, "min": {"type": "number"}, "max": {"type": "number"}, "role": {"enum": ["design", "state"]}}
+    },
+    "constant": {
+      "type": "object", "additionalProperties": false, "required": ["id", "unit", "value"],
+      "properties": {"id": {"$ref": "#/$defs/ref"}, "unit": {"$ref": "#/$defs/unit"}, "value": {"type": "number"}}
+    },
+    "node": {
+      "type": "object", "additionalProperties": false, "required": ["id", "op", "args", "outputs"],
+      "properties": {
+        "id": {"$ref": "#/$defs/ref"}, "op": {"type": "string", "pattern": "^[a-z-]+@[1-9][0-9]*$"},
+        "args": {"type": "array", "items": {"$ref": "#/$defs/ref"}},
+        "outputs": {"type": "object", "minProperties": 1, "additionalProperties": {"$ref": "#/$defs/ref"}},
+        "params": {"type": "object", "additionalProperties": {"$ref": "#/$defs/ref"}}
+      }
+    },
+    "model": {
+      "type": "object", "additionalProperties": false, "required": ["version", "inputs", "constants", "nodes"],
+      "properties": {
+        "version": {"enum": ["r3-scalar-1", "r3-spatial-1"]},
+        "inputs": {"type": "array", "items": {"$ref": "#/$defs/input"}},
+        "constants": {"type": "array", "items": {"$ref": "#/$defs/constant"}},
+        "nodes": {"type": "array", "items": {"$ref": "#/$defs/node"}}
+      }
+    },
+    "contact": {
+      "type": "object", "additionalProperties": false, "required": ["placement", "feature"],
+      "properties": {"placement": {"$ref": "#/$defs/ref"}, "feature": {"$ref": "#/$defs/ref"}}
+    },
+    "binding": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "label", "role", "frame", "pose", "accepts", "capacity"],
+      "properties": {
+        "id": {"$ref": "#/$defs/text"}, "label": {"$ref": "#/$defs/text"}, "role": {"enum": ["seat", "grip"]},
+        "frame": {"$ref": "#/$defs/text"}, "pose": {"oneOf": [{"$ref": "#/$defs/ref"}, {"$ref": "#/$defs/contact"}]},
+        "accepts": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
+        "capacity": {"type": "integer", "minimum": 1, "maximum": 9007199254740991},
+        "contacts": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/contact"}},
+        "region": {
+          "type": "object", "additionalProperties": false, "required": ["kind", "dimensions"],
+          "properties": {"kind": {"const": "centered-box"}, "dimensions": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"$ref": "#/$defs/ref"}}}
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object", "additionalProperties": false, "required": ["version", "assetFrame", "bindings"],
+      "properties": {"version": {"const": "r3-capability-3"}, "assetFrame": {"$ref": "#/$defs/text"}, "bindings": {"type": "array", "items": {"$ref": "#/$defs/binding"}}}
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import Ajv from '../../../things-factory/node_modules/ajv/lib/ajv.js'
+import {compileDocument,serializeDocument,parseDocument,MAX_BYTES} from './v3-document.mjs'
+import {compileCapabilities} from './v3-capability-plan.mjs'
+import {forkliftBindings,robotBinding} from './v3-capability-samples.mjs'
+import {defaults as forkDefaults} from './v3-full-forklift.mjs'
+import {defaults as robotDefaults} from './v3-full-robot.mjs'
+const envelope=s=>({version:'figure-v3-prototype-1',model:s.model,capabilities:s.declaration})
+const schema=JSON.parse(fs.readFileSync(new URL('./v3-document.schema.json',import.meta.url)))
+const validate=new Ajv({allErrors:true}).compile(schema)
+test('JSON Schema and semantic compiler: serialize/parse/recompile both complete models',()=>{
+ for(const [sample,args] of [[forkliftBindings(),{...forkDefaults,lift:1000,reach:200}],[robotBinding(),{...robotDefaults,'shoulder-lift':40}]]){
+  const doc=envelope(sample);assert.ok(validate(doc),JSON.stringify(validate.errors))
+  const text=serializeDocument(doc),restored=parseDocument(text);assert.deepEqual(restored,doc)
+  assert.deepEqual(compileDocument(restored).evaluate(args),compileDocument(doc).evaluate(args))
+ }
+ const d=envelope(forkliftBindings());d.capabilities.bindings[0].contacts[0].forged=true;assert.equal(validate(d),false);assert.throws(()=>compileDocument(d))
+})
+test('surface provenance rejects arbitrary transform, foreign shape, curved feature and duplicate contact',()=>{
+ for(const [code,edit] of [
+  ['SURFACE_PROVENANCE',s=>s.declaration.bindings[0].contacts[0].feature='mastPose'],
+  ['SURFACE_OWNER',s=>s.declaration.bindings[0].contacts[0].feature='fork-high-leftTop'],
+  ['DUPLICATE_CONTACT',s=>s.declaration.bindings[0].contacts.push(structuredClone(s.declaration.bindings[0].contacts[0]))],
+  ['TARGET_ABSENT',s=>s.declaration.bindings[0].contacts[0].placement='deleted']
+ ]){const s=forkliftBindings();edit(s);assert.throws(()=>compileCapabilities(s.model,s.declaration),e=>e.code===code)}
+ const s=robotBinding();s.model.nodes.push({id:'curved',op:'feature@1',args:['pedestalShape'],outputs:{pose:'curved'},params:{frame:'curvedFrame',name:'radialBottom'}})
+ s.declaration.bindings[0].contacts=[{placement:'pedestalPlaced',feature:'curved'}]
+ assert.throws(()=>compileCapabilities(s.model,s.declaration),e=>e.code==='SURFACE_UNSUPPORTED')
+})
+test('surface normal follows actual placement rotation, not provider feature frame axes',()=>{
+ const s=robotBinding();s.declaration.bindings[0].contacts=[{placement:'upper-armPlaced',feature:'upper-armtop'}]
+ const p=compileCapabilities(s.model,s.declaration)
+ for(const angle of [-90,0,90]){
+  const r=p.evaluate({...robotDefaults,'shoulder-lift':angle}),surface=r.bindings[0].contacts[0]
+  assert.equal(surface.geometryId,'upper-arm');assert.equal(surface.provenance,'verified-planar-surface')
+  const want=[0,Math.cos(angle*Math.PI/180),Math.sin(angle*Math.PI/180)]
+  want.forEach((v,i)=>assert.ok(Math.abs(surface.normal[i]-v)<1e-8))
+  assert.equal(r.bindings[0].checks.spatial.status,'unverified')
+ }
+})
+test('imports reject unknown versions, truncation, duplicate keys, oversized documents',()=>{
+ const d=envelope(forkliftBindings()),text=serializeDocument(d)
+ assert.throws(()=>parseDocument(text.slice(0,-1)),e=>e.code==='JSON_SYNTAX')
+ assert.throws(()=>parseDocument('{"version":0,'+text.slice(1)),e=>e.code==='JSON_DUPLICATE_KEY')
+ assert.throws(()=>parseDocument('{"x":1,"\\u0078":2}'),e=>e.code==='JSON_DUPLICATE_KEY')
+ assert.throws(()=>parseDocument(' '.repeat(MAX_BYTES+1)),e=>e.code==='DOCUMENT_LIMIT')
+ d.capabilities.version='r3-capability-1';assert.throws(()=>serializeDocument(d),e=>e.code==='VERSION')
+})
+test('serialization rejects lossy JS values rather than silently dropping or converting them',()=>{
+ for(const value of [undefined,NaN,Infinity,()=>1,new Date()]){const d=envelope(robotBinding());d.model.constants[0].value=value;assert.throws(()=>serializeDocument(d),e=>e.code==='JSON_VALUE')}
+ const d=envelope(robotBinding());d.model.nodes.push(d);assert.throws(()=>serializeDocument(d),e=>e.code==='JSON_VALUE')
+ const sparse=envelope(robotBinding());delete sparse.model.nodes[0];assert.throws(()=>serializeDocument(sparse),e=>e.code==='JSON_VALUE')
+})

package/docs/prototypes/v3-dryroom-mesh.mjs

@@ -0,0 +1,60 @@
+// Isolated mesh experiment; reuses installed Three.js, never changes seed assets.
+import fs from 'node:fs'
+import {fileURLToPath} from 'node:url'
+import * as THREE from '../../../things-scene/node_modules/three/build/three.module.js'
+import {compile} from './v3-typed-plan.mjs'
+export const seed=JSON.parse(fs.readFileSync(new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url))).find(s=>s.type==='DRY_ROOM').source
+const c=(id,value,unit='mm')=>({id,value,unit})
+const n=(id,op,args,outputs,params)=>({id,op,args,outputs,...(params?{params}:{})})
+const rigid=(id,from,to,xyz,rot=['a0','a0','a0'])=>n(id,'rigid@1',[...xyz,...rot],{pose:id},{from,to})
+export function evaluatePortal(name,worldBottom){
+  const p=seed.parts.find(p=>p.name===name),lamp=seed.parts.find(p=>p.name===name.replace('portal','lamp')),path=p.shape.path
+  if(p.transform.rotation.x!==-90)throw Error('adapter requires source -90 X orientation')
+  const t=p.transform.position,lt=lamp.transform.position
+  // Preserve the original non-centred XY profile. Original +90 extrusion and -90 placement cancel.
+  const m={version:'r3-spatial-1',inputs:[{id:'bottom',unit:'mm',min:-2000,max:path[2].y}],constants:[
+    c('left',path[0].x),c('right',path[5].x),c('top',path[6].y),c('il',path[1].x),c('ir',path[3].x),c('it',path[2].y),c('depth',p.transform.size.y),
+    c('x',t.x),c('y',t.y),c('z',t.z),c('zero',0),c('a0',0,'rad'),c('turn',90,'deg'),
+    c('lampRadius',lamp.transform.size.x/2),c('lampLength',lamp.transform.size.y),
+    c('lampX',lt.x-t.x),c('lampY',lt.y-t.y-path[6].y),c('lampZ',lt.z-t.z-p.transform.size.y/2)
+  ],nodes:[
+    n('profile','portal-profile@1',['left','right','bottom','top','il','ir','it','depth'],{shape:'shape'},{frame:'portal'}),
+    rigid('pose','portal','world',['x','y','z']),
+    n('surface','feature@1',['shape'],{pose:'surface'},{frame:'topFront',name:'frontTop'}),
+    n('worldSurface','compose@1',['pose','surface'],{pose:'worldSurface'}),
+    rigid('lampOffset','lampLocal','topFront',['lampX','lampY','lampZ'],['turn','a0','a0']),
+    n('lampPose','compose@1',['worldSurface','lampOffset'],{pose:'lampPose'}),
+    n('lampShape','cylinder-shape@1',['lampRadius','lampLength'],{shape:'lampShape'},{frame:'lampLocal'}),
+    n('placedPortal','place@1',['shape','pose'],{placed:'placedPortal'}),n('placedLamp','place@1',['lampShape','lampPose'],{placed:'placedLamp'})]}
+  return compile(m).evaluate({bottom:worldBottom-t.y})
+}
+export function meshOf(placed){
+  const {shape,pose}=placed
+  let g
+  if(shape.provider==='portal'){
+    const p=shape.profile,s=new THREE.Shape();s.moveTo(p[0].x,p[0].y);p.slice(1).forEach(v=>s.lineTo(v.x,v.y));s.closePath()
+    g=new THREE.ExtrudeGeometry(s,{depth:shape.dimensions.depth,steps:1,bevelEnabled:false});g.translate(0,0,-shape.dimensions.depth/2)
+  } else if(shape.provider==='box')g=new THREE.BoxGeometry(shape.dimensions.width,shape.dimensions.height,shape.dimensions.depth)
+  else g=new THREE.CylinderGeometry(shape.dimensions.radius,shape.dimensions.radius,shape.dimensions.length,16)
+  const r=pose.r,t=pose.t,mat=new THREE.Matrix4().set(...r[0],t[0],...r[1],t[1],...r[2],t[2],0,0,0,1)
+  g.applyMatrix4(mat);return g.index?g.toNonIndexed():g
+}
+export function triangles(g){const p=g.attributes.position;return Array.from({length:p.count/3},(_,i)=>[0,1,2].map(j=>[p.getX(i*3+j),p.getY(i*3+j),p.getZ(i*3+j)]))}
+export function meshAudit(g){
+  const edges=new Map(),vertices=new Set();let volume=0,minArea=Infinity
+  for(const tri of triangles(g)){
+    const [a,b,c]=tri.map(v=>new THREE.Vector3(...v)),normal=b.clone().sub(a).cross(c.clone().sub(a))
+    minArea=Math.min(minArea,normal.length()/2);volume+=a.dot(b.clone().cross(c))/6
+    const ids=tri.map(v=>v.map(x=>Math.round(x*1e6)).join(','));ids.forEach(k=>vertices.add(k))
+    for(let i=0;i<3;i++){const a=ids[i],b=ids[(i+1)%3],key=[a,b].sort().join('|'),entry=edges.get(key)??{count:0,balance:0};entry.count++;entry.balance+=a<b?1:-1;edges.set(key,entry)}
+  }
+  return {faces:g.attributes.position.count/3,vertices:vertices.size,edges:edges.size,euler:vertices.size-edges.size+g.attributes.position.count/3,volume,minArea,badEdges:[...edges.values()].filter(e=>e.count!==2||e.balance!==0).length}
+}
+export function rayHit(g,x,y){
+  const m=new THREE.Mesh(g,new THREE.MeshBasicMaterial({side:THREE.DoubleSide}));m.updateMatrixWorld()
+  return new THREE.Raycaster(new THREE.Vector3(x,y,10000),new THREE.Vector3(0,0,-1)).intersectObject(m).length>0
+}
+if(process.argv[1]===fileURLToPath(import.meta.url)){
+  const panels=[-60,0].map(bottom=>{const result=evaluatePortal('portal-in',bottom);return {bottom,parts:result.geometry.map(g=>({id:g.id,triangles:triangles(meshOf(g))}))}})
+  console.log(JSON.stringify({threeRevision:THREE.REVISION,panels}))
+}

package/docs/prototypes/v3-dryroom-mesh.test.mjs

@@ -0,0 +1,30 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {evaluatePortal,meshOf,meshAudit,rayHit,seed} from './v3-dryroom-mesh.mjs'
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-5,`${a} != ${b}`)
+test('both actual portal profiles: baseline matches seed, bottom trim preserves top/opening/lamp',()=>{
+  for(const name of ['portal-in','portal-out']){
+    const before=evaluatePortal(name,-60),after=evaluatePortal(name,0)
+    assert.deepEqual(before.values.shape.profile.map(({x,y})=>({x,y})),seed.parts.find(p=>p.name===name).shape.path)
+    assert.deepEqual(before.values.lampPose,after.values.lampPose)
+    for(const key of ['top','openingLeft','openingRight','openingTop','depth'])assert.equal(before.values.shape.dimensions[key],after.values.shape.dimensions[key])
+    for(const [out,bottom] of [[before,-60],[after,0]]){
+      const g=meshOf(out.geometry[0]);g.computeBoundingBox();near(g.boundingBox.min.y,bottom);near(g.boundingBox.max.y,2900)
+      const a=meshAudit(g),d=out.values.shape.dimensions
+      assert.equal(a.badEdges,0);assert.equal(a.euler,2);assert.ok(a.minArea>0)
+      const area=(d.right-d.left)*(d.top-d.bottom)-(d.openingRight-d.openingLeft)*(d.openingTop-d.bottom)
+      near(a.volume,area*d.depth)
+      assert.equal(rayHit(g,0,1000),false);assert.equal(rayHit(g,0,2500),true);assert.equal(rayHit(g,1000,1000),true)
+      assert.equal(rayHit(g,1000,-30),bottom===-60)
+      console.log(JSON.stringify({name,bottom,...a}));g.dispose()
+    }
+    near(meshAudit(meshOf(before.geometry[0])).volume-meshAudit(meshOf(after.geometry[0])).volume,21600000)
+  }
+})
+test('boundary edit rejects disappearing opening instead of silently changing topology',()=>{
+  assert.throws(()=>evaluatePortal('portal-in',2200),e=>e.code==='GEOMETRY_DOMAIN')
+  for(const bottom of [-60,0,100,1000,2199]){
+    const r=evaluatePortal('portal-in',bottom),g=meshOf(r.geometry[0]),a=meshAudit(g)
+    assert.equal(a.badEdges,0);assert.equal(a.euler,2);assert.ok(a.volume>0);g.dispose()
+  }
+})

package/docs/prototypes/v3-editor-browser.mjs

@@ -0,0 +1,97 @@
+// Isolated UI integration harness. No product server, DB or saved assets are touched.
+import {createServer} from 'node:http'
+import {readFile,mkdtemp,rm} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+import {randomUUID} from 'node:crypto'
+import {chromium} from '/Users/super/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright/index.mjs'
+import assert from 'node:assert/strict'
+import {createEditorWorkspace} from './v3-editor-workspace.mjs'
+import {sampleAsset} from './v3-asset-samples.mjs'
+import {serializeAsset} from './v3-asset.mjs'
+import {createV3Asset} from '../../src/v3-create.ts'
+import {createAssetStore} from './v3-asset-store.mjs'
+import {geometryOf as ordinary} from './v3-full-conveyor.mjs'
+import {geometryOf as portal} from './v3-full-dryroom.mjs'
+const directory=await mkdtemp(join(tmpdir(),'v3-editor-store-'))
+const store=createAssetStore(directory),workspace=createEditorWorkspace();let saved=null,storage=null
+const view=()=>{const v=workspace.read();return {...v,render:v.geometry.map(g=>{const mesh=(g.shape.provider==='portal'?portal:ordinary)(g);const json=mesh.toJSON();mesh.dispose();return {id:g.id,geometry:json,material:g.material}})}}
+const html=`<!doctype html><meta charset="utf-8"><title>V3 편집 연결 검증</title>
+<style>body{margin:0;font:14px system-ui;color:#263543;background:#eef2f6}header{padding:16px;display:flex;gap:10px;align-items:center;background:white;border-bottom:1px solid #ccd5dd}main{display:grid;grid-template-columns:1fr 340px;height:650px}aside{padding:18px;background:white;overflow:auto}h2{font-size:15px;margin:22px 0 12px}label{display:grid;grid-template-columns:110px 1fr 46px;align-items:center;gap:8px;margin:8px 0}input,button,select{height:36px;box-sizing:border-box;border:1px solid #bdc9d2;border-radius:5px;background:white;padding:5px 8px}input{min-width:0;width:100%}button{cursor:pointer}#canvas{overflow:hidden}#status{padding:12px}#error{color:#a12626;white-space:pre-wrap}small{color:#526574}</style>
+<header><strong>V3 편집 연결 검증</strong><button id="new">새 Figure</button><button id="add">상자 추가</button><select id="model"><option value="forklift">포크리프트</option><option value="robot">로봇암</option><option value="conveyor">컨베이어</option><option value="dryroom">드라이룸</option></select><button id="open">열기</button><button id="undo">되돌리기</button><button id="redo">다시 실행</button><button id="save">검증 저장</button><button id="reload">저장본 열기</button><button id="close">빈 화면</button></header>
+<main><section><div id="canvas"></div><div id="status"></div></section><aside><small>제품 화면이 아닌 격리된 실험 UI · 임시 파일에 저장</small><div id="fields"></div><p id="error" role="alert"></p></aside></main>
+<script type="module">
+import * as T from '/three.module.js';
+const host=document.querySelector('#canvas'),renderer=new T.WebGLRenderer({antialias:true});renderer.setSize(830,590);renderer.setClearColor('#edf2f6');host.append(renderer.domElement);
+const scene=new T.Scene(),group=new T.Group();scene.add(group,new T.HemisphereLight(0xffffff,0x738295,3));const light=new T.DirectionalLight(0xffffff,3);light.position.set(3000,5000,6000);scene.add(light);
+const camera=new T.PerspectiveCamera(38,830/590,1,50000);let current;
+const labels={forkLength:'포크 길이',lift:'포크 높이',reach:'내밈',drive:'바퀴 회전',upperLength:'상완 길이',foreLength:'전완 길이',length:'길이',width:'폭',rollerHeight:'롤러 높이',angle:'롤러 회전',gripper:'그리퍼'};
+function fieldLabel(id){const m=/^(.+)\\.(size|position|rotation)\\.([xyz])$/.exec(id);return labels[id]||(m?({size:'크기',position:'위치',rotation:'회전'}[m[2]]+' '+m[3].toUpperCase()):id)}
+function show(v){current=v;window.lastView=v;document.querySelector('#fields').replaceChildren();
+ for(const category of ['design','state']){const fields=v.fields.filter(f=>(f.role==='state'?'state':'design')===category);if(!fields.length)continue;const h=document.createElement('h2');h.textContent=category==='design'?'설계':'동작 미리보기';document.querySelector('#fields').append(h);
+  for(const f of fields){const label=document.createElement('label'),name=document.createElement('span'),input=document.createElement('input'),button=document.createElement('button');name.textContent=fieldLabel(f.id)+' ('+f.unit+')';input.type='number';input.id=f.id;input.value=f.value;input.min=f.min;input.max=f.max;input.setAttribute('aria-label',fieldLabel(f.id));button.textContent='적용';button.dataset.input=f.id;button.onclick=()=>run('apply',{request:{context:current.context,origin:'ui',expectedRevision:current.revision,changes:[{kind:category==='state'?'set-state':'set-design',input:f.id,unit:f.unit,value:Number(input.value)}]}});label.append(name,input,button);document.querySelector('#fields').append(label)}
+ }
+ for(const child of [...group.children]){group.remove(child);child.geometry.dispose();child.material.dispose()}
+ for(const item of v.render){const mat=new T.MeshStandardMaterial({color:v.palette[item.material.token]||'#96989b',roughness:.5});group.add(new T.Mesh(new T.BufferGeometryLoader().parse(item.geometry),mat))}
+ if(group.children.length){const box=new T.Box3().setFromObject(group),size=box.getSize(new T.Vector3()),center=box.getCenter(new T.Vector3()),radius=Math.max(size.x,size.y,size.z);camera.position.copy(center).add(new T.Vector3(radius*1.1,radius*.85,radius*1.5));camera.lookAt(center)}
+ renderer.render(scene,camera);window.meshCount=group.children.length;
+ document.querySelector('#status').textContent=(v.name||'빈 상태')+' · 파트 '+group.children.length+' · revision '+v.revision+' · '+(v.dirty?'저장하지 않은 설계 변경':'저장 기준과 일치');
+}
+async function run(action,args={}){document.querySelector('#error').textContent='';try{const r=await fetch('/api',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({action,...args})});const body=await r.json();if(!r.ok)throw Error(body.error);show(body.view)}catch(e){document.querySelector('#error').textContent=e.message}}
+document.querySelector('#open').onclick=()=>run('open',{kind:document.querySelector('#model').value});document.querySelector('#undo').onclick=()=>run('undo',{context:current.context,revision:current.revision});document.querySelector('#save').onclick=()=>run('save',{context:current.context});document.querySelector('#reload').onclick=()=>run('reload');document.querySelector('#close').onclick=()=>run('close');
+document.querySelector('#new').onclick=()=>run('new');document.querySelector('#add').onclick=()=>run('add',{context:current.context,revision:current.revision});document.querySelector('#redo').onclick=()=>run('redo',{context:current.context,revision:current.revision});
+await run('open',{kind:'forklift'});window.ready=true;
+</script>`
+const server=createServer(async(req,res)=>{try{
+ if(req.url==='/'){res.setHeader('Content-Type','text/html');res.end(html);return}
+ if(['/three.module.js','/three.core.js'].includes(req.url)){res.setHeader('Content-Type','text/javascript');res.end(await readFile(new URL('../../../things-scene/node_modules/three/build'+req.url,import.meta.url)));return}
+ if(req.url!=='/api'||req.method!=='POST'){res.statusCode=404;res.end();return}
+ let body='';for await(const chunk of req){body+=chunk;if(body.length>20000)throw Error('request too large')}
+ const q=JSON.parse(body)
+ if(q.action==='open'){workspace.open(serializeAsset(sampleAsset(q.kind)));storage={scope:'isolated-browser',id:randomUUID(),expectedRevision:null}}
+ else if(q.action==='new'){workspace.open(serializeAsset(createV3Asset('새 Figure')));storage={scope:'isolated-browser',id:randomUUID(),expectedRevision:null}}
+ else if(q.action==='add'){const id='box'+(workspace.read().revision+1);workspace.addBox({context:q.context,origin:'ui',expectedRevision:q.revision,box:{id,size:{x:800,y:1000,z:600},position:{x:0,y:500,z:0}}})}
+ else if(q.action==='redo')workspace.redo({context:q.context,origin:'ui',expectedRevision:q.revision})
+ else if(q.action==='apply')workspace.apply(q.request)
+ else if(q.action==='undo')workspace.undo({context:q.context,origin:'ui',expectedRevision:q.revision})
+ else if(q.action==='save'){
+  const snapshot=workspace.export({context:q.context}),target={...storage}
+  const record=await store.save({...target,text:snapshot.text})
+  saved={scope:record.scope,id:record.id,expectedRevision:record.revision}
+  if(workspace.read().context===snapshot.context)storage={...saved}
+  workspace.acknowledgeSaved(snapshot)
+ }
+ else if(q.action==='reload'){if(!saved)throw Error('no saved snapshot');const record=await createAssetStore(directory).read(saved);workspace.open(record.text);storage={...saved,expectedRevision:record.revision}}
+ else if(q.action==='close'){workspace.close();storage=null}
+ else throw Error('unknown action')
+ res.setHeader('Content-Type','application/json');res.end(JSON.stringify({view:view()}))
+ }catch(e){res.statusCode=['CONFLICT','CONTEXT_CONFLICT','REVISION_CONFLICT'].includes(e.code)?409:400;res.setHeader('Content-Type','application/json');res.end(JSON.stringify({error:e.message,code:e.code}))}})
+await new Promise(r=>server.listen(0,'127.0.0.1',r));let browser
+try{
+ browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage({viewport:{width:1180,height:740}}),errors=[];page.on('pageerror',e=>errors.push(String(e)))
+ await page.goto('http://127.0.0.1:'+server.address().port);await page.waitForFunction(()=>window.ready&&window.meshCount===20)
+ const old=await page.evaluate(()=>({context:lastView.context,revision:lastView.revision}))
+ await page.locator('#forkLength').fill('1275');await page.locator('button[data-input="forkLength"]').click();await page.waitForFunction(()=>lastView.revision===1)
+ assert.equal(await page.evaluate(()=>lastView.geometry.find(g=>g.id==='fork-low-left').shape.dimensions.depth),1275)
+ await page.locator('#save').click();await page.waitForFunction(()=>!lastView.dirty)
+ await page.screenshot({path:'/private/tmp/figure-v3-editor.png',fullPage:true})
+ await page.locator('#model').selectOption('robot');await page.locator('#open').click();await page.waitForFunction(()=>window.meshCount===10)
+ const stale=await page.evaluate(async old=>{const r=await fetch('/api',{method:'POST',body:JSON.stringify({action:'apply',request:{context:old.context,expectedRevision:0,origin:'ai',changes:[{kind:'set-design',input:'forkLength',unit:'mm',value:1500}]}})});return r.json()},old);assert.match(stale.error,/CONTEXT_CONFLICT/)
+ await page.locator('#reload').click();await page.waitForFunction(()=>window.meshCount===20);assert.equal(await page.locator('#forkLength').inputValue(),'1275')
+ await page.locator('#close').click();await page.waitForFunction(()=>window.meshCount===0);assert.equal(await page.locator('#fields input').count(),0)
+ await page.screenshot({path:'/private/tmp/figure-v3-editor-empty.png',fullPage:true})
+ await page.locator('#new').click();await page.waitForFunction(()=>lastView.name==='새 Figure'&&meshCount===0)
+ await page.locator('#add').click();await page.waitForFunction(()=>meshCount===1&&lastView.dirty)
+ await page.locator('[id="box1.size.y"]').fill('1500');await page.locator('button[data-input="box1.size.y"]').click();await page.waitForFunction(()=>lastView.revision===2)
+ await page.locator('#undo').click();await page.waitForFunction(()=>lastView.revision===3)
+ assert.equal(await page.locator('[id="box1.size.y"]').inputValue(),'1000')
+ await page.locator('#undo').click();await page.waitForFunction(()=>meshCount===0&&lastView.revision===4)
+ await page.locator('#redo').click();await page.waitForFunction(()=>meshCount===1&&lastView.revision===5)
+ await page.locator('#redo').click();await page.waitForFunction(()=>lastView.revision===6)
+ await page.locator('#save').click();await page.waitForFunction(()=>!lastView.dirty)
+ await page.locator('#reload').click();await page.waitForFunction(()=>lastView.revision===0)
+ assert.equal(await page.locator('[id="box1.size.y"]').inputValue(),'1500')
+ await page.screenshot({path:'/private/tmp/figure-v3-new-authoring.png',fullPage:true})
+ console.log('new empty asset -> add box -> edit -> undo edit -> undo creation -> redo both -> disk save/reload: passed')
+ assert.deepEqual(errors,[]);console.log(JSON.stringify({checks:['open asset','edit changes actual rendered geometry','save through HTTP to disk','switch 20 meshes to 10 without leftovers','reject stale AI context','reload edited design from independent disk store handle','close clears meshes and fields'],pageErrors:errors,screenshot:'/private/tmp/figure-v3-editor.png'},null,2))
+}finally{await browser?.close();await new Promise(r=>server.close(r));await rm(directory,{recursive:true,force:true})}

package/docs/prototypes/v3-editor-workspace.mjs

@@ -0,0 +1 @@
+export {createV3EditorWorkspace as createEditorWorkspace} from '../../src/v3-editor-workspace.ts'

package/docs/prototypes/v3-editor-workspace.test.mjs

@@ -0,0 +1,35 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {createEditorWorkspace} from './v3-editor-workspace.mjs'
+import {sampleAsset} from './v3-asset-samples.mjs'
+import {serializeAsset} from './v3-asset.mjs'
+const text=kind=>serializeAsset(sampleAsset(kind))
+const edit=(view,id,value,kind='set-design')=>({context:view.context,origin:'ui',expectedRevision:view.revision,changes:[{kind,input:id,value,unit:'mm'}]})
+test('saved asset opens with fields/render appearance; edits and undo share the same session',()=>{
+ const w=createEditorWorkspace(),v=w.open(text('forklift')),changed=w.apply(edit(v,'forkLength',1275))
+ assert.equal(changed.fields.find(f=>f.id==='forkLength').value,1275);assert.equal(changed.geometry.find(g=>g.id==='fork-low-left').shape.dimensions.depth,1275);assert.equal(changed.dirty,true)
+ assert.deepEqual(w.undo({context:v.context,origin:'ui',expectedRevision:1}).geometry,v.geometry)
+})
+test('model switch and empty close do not retain canvas, binding, selection fields or undo',()=>{
+ const w=createEditorWorkspace(),old=w.open(text('forklift')),next=w.open(text('robot'))
+ assert.equal(next.geometry.length,10);assert.ok(next.geometry.every(g=>!g.id.startsWith('fork-')));assert.equal(next.revision,0);assert.equal(next.canUndo,false)
+ assert.throws(()=>w.apply({...edit(old,'forkLength',1275),origin:'ai'}),e=>e.code==='CONTEXT_CONFLICT')
+ const empty=w.close();assert.equal(empty.geometry.length,0);assert.equal(empty.fields.length,0);assert.equal(empty.bindings.length,0)
+ assert.throws(()=>w.preview(edit(next,'upperLength',630)),e=>e.code==='CONTEXT_CONFLICT')
+})
+test('unsaved design asks at departure; state-only preview does not; invalid open is atomic',()=>{
+ const w=createEditorWorkspace(),v=w.open(text('forklift'));w.apply(edit(v,'lift',1000,'set-state'))
+ assert.equal(w.read().dirty,false);const robot=w.open(text('robot'));w.apply(edit(robot,'upperLength',630))
+ const before=w.read();assert.throws(()=>w.open(text('conveyor')),e=>e.code==='UNSAVED_DESIGN');assert.deepEqual(w.read(),before)
+ assert.throws(()=>w.open('broken',{discardDesignChanges:true}));assert.deepEqual(w.read(),before)
+ assert.equal(w.close({discardDesignChanges:true}).geometry.length,0)
+})
+test('export is not save; storage acknowledgement is revision/context-bound; reopen resets transient state',()=>{
+ const w=createEditorWorkspace(),v=w.open(text('forklift')),a=w.apply(edit(v,'forkLength',1275));w.apply(edit(a,'lift',1000,'set-state'))
+ const exported=w.export({context:v.context});assert.equal(w.read().dirty,true)
+ w.acknowledgeSaved(exported);assert.equal(w.read().dirty,false)
+ const opened=w.open(exported.text);assert.equal(opened.fields.find(f=>f.id==='forkLength').value,1275);assert.equal(opened.fields.find(f=>f.id==='lift').value,0)
+ assert.throws(()=>w.acknowledgeSaved(exported),e=>e.code==='CONTEXT_CONFLICT')
+ const stale=w.export({context:opened.context});w.apply(edit(opened,'forkLength',1500))
+ assert.throws(()=>w.acknowledgeSaved(stale),e=>e.code==='REVISION_CONFLICT');assert.equal(w.read().dirty,true)
+})