@zixcel/dom-renderer 0.0.0-stage → 0.10.0

package/src/index.mjs

@@ -0,0 +1,205 @@
+// Trusted installed DOM primitives. All external values are text, never HTML.
+// Hatter downstream 2026: one bounded DOM tree for spatial and structured Scenes.
+import {validateInputDeclaration,validateInputValues} from '@zixcel/interaction/input'
+import {spatialView} from './spatial.mjs'
+import {symbol} from './symbol.mjs'
+import {reconcileChildren} from './reconcile.mjs'
+import {createWorldSurface} from './world-surface.mjs'
+import {bookReader} from './book-reader.mjs'
+export {createWorldSurface} from './world-surface.mjs'
+export {symbol} from './symbol.mjs'
+export {windowFrame} from './frame.mjs'
+export {worldControlGuide} from './world-input.mjs'
+export {spatialView} from './spatial.mjs'
+export {structureGraph} from './structure-graph.mjs'
+export const renderBounds=Object.freeze({nodes:8192,depth:20,textBytes:524288})
+const fail=code=>{throw Object.assign(Error(code),{code})}
+/** @template {keyof HTMLElementTagNameMap} K
+ * @param {Document} document
+ * @param {K} tag
+ * @param {unknown} [text]
+ * @param {Record<string,unknown>} [attrs]
+ * @returns {HTMLElementTagNameMap[K]} */
+export function element(document,tag,text=null,attrs={}){
+ const node=document.createElement(tag);if(text!==null)node.textContent=String(text)
+ for(const [key,value]of Object.entries(attrs))if(value!==null)node.setAttribute(key,String(value))
+ return node
+}
+/** @param {Document} document
+ * @param {unknown} value
+ * @param {{nodes:number,bytes:number}} [budget]
+ * @returns {HTMLElement} */
+export function valueView(document,value,budget={nodes:0,bytes:0}){
+ const walk=(value,depth)=>{
+  if(++budget.nodes>renderBounds.nodes||depth>renderBounds.depth)fail('RenderLimitExceeded')
+  if(value===null||typeof value!=='object'){
+   const text=JSON.stringify(value);if(typeof text!=='string')fail('InvalidRenderValue')
+   budget.bytes+=new TextEncoder().encode(text).length;if(budget.bytes>renderBounds.textBytes)fail('RenderLimitExceeded')
+   return element(document,'span',text,{'data-projection-scalar':text})
+  }
+  if(Object.keys(value).length>4096)fail('RenderLimitExceeded')
+  if(!Object.keys(value).length)return element(document,'span',Array.isArray(value)?'[]':'{}',{'data-empty-value':Array.isArray(value)?'array':'object'})
+  const list=element(document,Array.isArray(value)?'ol':'dl')
+  for(const [key,child]of Object.entries(value)){
+   if(Array.isArray(value)){const item=element(document,'li');item.append(walk(child,depth+1));list.append(item)}
+   else{const name=element(document,'dt',key),item=element(document,'dd');item.append(walk(child,depth+1));list.append(name,item)}
+  }
+  return list
+ }
+ return walk(value,0)
+}
+export class SceneRenderer{
+ #root;#events;#abort=null;#actionHandles=new Map();#spatial=null;#slots;#pose=null;#poseKey=null;#speaker=null;#surface;#ownsSurface;#garden=null
+ /** @param {HTMLElement} root
+  * @param {(kind:string,value:string|import('@zixcel/projection-client').ActionHandle|undefined)=>void} onEvent
+  * @param {{tools?:HTMLElement,details?:HTMLElement,actions?:HTMLElement}} [slots]
+  * @param {ReturnType<typeof createWorldSurface>|null} [surface] */
+ constructor(root,onEvent,slots={},surface=null){this.#root=root;this.#events=onEvent;this.#slots=slots;this.#surface=surface??createWorldSurface();this.#ownsSurface=!surface}
+ /** @param {import('@zixcel/projection-client').RenderPlan} plan */
+ render(plan){
+  const root=this.#root,document=root.ownerDocument,focused=document.activeElement?.dataset.control
+  const previous=root.querySelector('[data-render-key]'),oldViewport=root.querySelector('.scene-viewport')
+  const scroll=previous?.dataset.renderKey===plan.projectionKey&&previous.dataset.viewMode===plan.viewMode&&oldViewport
+    ?{left:oldViewport.scrollLeft,top:oldViewport.scrollTop}:null
+  if(this.#poseKey===plan.projectionKey)this.#pose=this.#spatial?.snapshot()??this.#pose
+  else this.#pose=null
+  this.#poseKey=plan.projectionKey
+  this.#spatial?.close();this.#spatial=null;this.#abort?.abort();this.#abort=new AbortController();this.#actionHandles.clear()
+  if(!['spatial','structured'].includes(plan.viewMode)||!Array.isArray(plan.relations)||plan.relations.length>512)fail('InvalidRenderPlan')
+  const section=element(document,'section',null,{'data-render-revision':plan.projectionRevision,'data-render-key':plan.projectionKey,'data-view-mode':plan.viewMode,'aria-label':'Scene content',tabindex:'-1',class:'semantic-scene'})
+  const button=(label,kind,id,attrs={})=>element(document,'button',label,{type:'button','data-kind':kind,'data-control':JSON.stringify([kind,id]),'data-target':id,...attrs})
+  const views=element(document,'div',null,{role:'group','aria-label':'Scene view',class:'scene-view-controls'})
+  for(const [mode,label]of [['spatial','Spatial view'],['structured','List view']])views.append(button(label,'view',mode,{'aria-pressed':plan.viewMode===mode}))
+  const tools=this.#slots.tools??section;tools.replaceChildren();tools.append(views)
+  const viewport=element(document,'div',null,{class:'scene-viewport',tabindex:'0','aria-label':'Explore information in this space'}),board=element(document,'div',null,{class:'spatial-board'})
+  for(const person of this.#garden?.actors??(this.#speaker?[this.#speaker]:[])){const actor=button('',this.#garden?'actor':'conversation',person.id,{'data-world-object':person.id,'data-selected':person.id===this.#speaker?.id,'data-observation-label':person.preparation?.label??''});actor.append(element(document,'strong',person.title));actor.disabled=person.status!==undefined&&person.status!=='Available';board.append(actor)}
+  const camera=element(document,'div',null,{role:'group','aria-label':'View position',class:'scene-camera'})
+  for(const [id,label,icon]of [['left','Move left','←'],['right','Move right','→'],['in','Zoom in','+'],['out','Zoom out','−'],['reset','View all','⛶']])camera.append(button(icon,'camera',id,{'aria-label':label,title:label}))
+  if(plan.viewMode==='spatial')tools.append(camera)
+  viewport.append(board);(plan.viewMode==='structured'?tools:section).append(viewport)
+  if(plan.empty)section.append(element(document,'p','No projected information is available.',{role:'status'}))
+  if(plan.truncated)section.append(element(document,'p','The source reports incomplete information.',{role:'status'}))
+  const groups=[...plan.regions,...(plan.unplaced.length?[{id:'unplaced',role:'Context',items:plan.unplaced}]:[])]
+  if(groups.length>17||plan.actions.length>64)fail('RenderLimitExceeded')
+  for(const group of groups){
+   const region=element(document,'section',null,{'data-region':group.id}),list=element(document,'ul',null,{class:'scene-items'})
+   region.append(element(document,'h2',group.role),list)
+   for(const item of group.items){
+    const row=element(document,'li',null,{'data-item-id':item.id,'data-selected':item.selected,'data-related':item.related,'data-focused':item.focused}),toolbar=element(document,'div',null,{class:'item-tools'})
+    const itemButton=(label,kind,attrs={})=>button(label,kind,item.id,{'data-control':JSON.stringify([group.id,kind,item.id]),...attrs})
+    toolbar.append(itemButton(item.display?.title??item.content.reason??'Display not configured','select',{'aria-pressed':item.selected}),itemButton('View details','inspect',{'aria-expanded':plan.inspector?.id===item.id,'aria-haspopup':'dialog'}))
+    if(item.content.reason)toolbar.append(itemButton('Review','resolve'))
+    const solid=element(document,'span',null,{class:'object-solid','aria-hidden':'true'})
+    solid.append(symbol(document,item.display?.symbol??'nodes'));row.append(solid,toolbar)
+    if(item.display?.summary)row.append(element(document,'p',item.display.summary,{'data-item-summary':item.id}))
+    const fields=element(document,'dl',null,{class:'object-fields'})
+    for(const field of item.display?.fields??[])fields.append(element(document,'dt',field.label),element(document,'dd',field.value===null?'Not set':String(field.value),{'data-projection-scalar':JSON.stringify(field.value)}))
+    row.append(fields)
+    if(!item.display)row.append(element(document,'p',item.content.reason?'This information is not yet resolved. Review the available choices or the missing requirements.':'Display information is not configured. Inspect this object in System.'))
+    list.append(row)
+   }
+   board.append(region)
+  }
+  const time=element(document,'section',null,{'aria-label':'Scene time',class:'scene-time'})
+  time.append(element(document,'h2',plan.temporal?.label??'Time'))
+  if(plan.temporal?.items.length){
+   time.append(button('All times','time','',{'aria-pressed':plan.temporal.cursor===null}))
+   for(const item of plan.temporal.items){const control=button(item.at+' · '+item.itemId,'time',item.itemId,{'aria-pressed':plan.temporal.cursor===item.itemId});time.append(control)}
+  }else time.append(element(document,'p','No event time has been declared by this source.',{role:'status'}))
+  tools.append(time)
+  if(plan.relations.length){
+   const relations=element(document,'details',null,{'aria-label':'Relationships'}),list=element(document,'ul',null,{class:'scene-relations'})
+   relations.append(element(document,'summary','Relationships ('+plan.relations.length+')'),list)
+   for(const relation of plan.relations){
+    const row=element(document,'li',null,{'data-relation-id':relation.id,'data-active':relation.active})
+    row.append(button(relation.from,'select',relation.from,{'data-control':JSON.stringify(['relation',relation.id,'from']),'aria-label':'Select related '+relation.from}),element(document,'span','→ '+relation.relationRef+' →'),button(relation.to,'select',relation.to,{'data-control':JSON.stringify(['relation',relation.id,'to']),'aria-label':'Select related '+relation.to}))
+    list.append(row)
+   }
+   tools.append(relations)
+  }
+  const actions=this.#slots.actions??tools;if(this.#slots.actions)actions.replaceChildren()
+  // Unresolved owner observations are conversation material too, including
+  // when no executable choice exists. This does not manufacture an action.
+  const pending=groups.flatMap(group=>group.items).filter(item=>item.content.reason)
+  if(pending.length){
+   const questions=element(document,'section',null,{'aria-label':'Information needing clarification'})
+   questions.append(element(document,'h3','Why this information needs review'))
+   for(const item of pending){
+    const row=element(document,'div',null,{'data-unresolved-ref':item.id})
+    const explanation=this.#slots.describeUnresolved?.(item.content.reason)??{label:String(item.content.reason),detail:'The source owner reported this unresolved reason.'}
+    row.append(button(item.display?.title??explanation.label,'resolve',item.id),element(document,'small',explanation.detail))
+    questions.append(row)
+   }
+   actions.append(questions)
+  }
+  for(const action of plan.actions){this.#actionHandles.set(action.handle.actionId,action.handle);actions.append(button(action.descriptor.label,'action',action.handle.actionId))}
+  const lastBook=(this.#slots.details??root).querySelector('[data-book-id]'),bookPosition=lastBook?{id:lastBook.dataset.bookId,revision:lastBook.dataset.bookRevision,page:Number(lastBook.dataset.bookPage)}:null
+  this.#slots.details?.replaceChildren()
+  if(plan.inspector){
+   const chosen=groups.flatMap(r=>r.items).find(i=>i.id===plan.inspector.id)
+   if(chosen)(this.#slots.details??section).append(bookReader(document,chosen,plan.projectionRevision,button('Close book','dismiss',plan.inspector.id),this.#abort.signal,bookPosition))
+  }
+  reconcileChildren(root,[section])
+  const activeViewport=plan.viewMode==='spatial'?root.querySelector('.scene-viewport'):viewport,activeBoard=activeViewport.querySelector('.spatial-board')
+  if(plan.viewMode==='spatial'||this.#garden)this.#spatial=spatialView(this.#garden?.host??activeViewport,activeBoard,plan.camera,plan.relations,this.#abort.signal,this.#pose,null,{
+   surface:this.#surface,activity:this.#garden?.activity,target:this.#garden?'garden':plan.projectionKey,context:this.#garden?plan.projectionKey:null,pattern:this.#garden?'garden':'constellation',items:new Map(groups.flatMap(region=>region.items.map(item=>[item.id,{
+    anchor:this.#speaker?.id,group:item.content.group,semanticRef:item.content.semanticRef,sourceRefs:item.content.sourceRefs,scalars:(item.display?.fields??[]).map(f=>f.value),unresolved:Boolean(item.content.reason),changeKey:JSON.stringify(item.display?.fields??[])
+   }])))
+  })
+  if(this.#garden&&plan.viewMode==='structured')activeBoard.hidden=false
+  for(const host of new Set([root,this.#slots.tools,this.#slots.details,this.#slots.actions].filter(Boolean)))host.addEventListener('click',event=>{
+   const target=event.target.closest('button[data-kind]');if(!target||!host.contains(target))return
+   if(target.dataset.kind==='camera'){this.#spatial?.change(target.dataset.target);return}
+   this.#events(target.dataset.kind,target.dataset.kind==='action'?this.#actionHandles.get(target.dataset.target):target.dataset.target)
+  },{signal:this.#abort.signal})
+  if(focused)[...root.querySelectorAll('[data-control]')].find(n=>n.dataset.control===focused)?.focus({preventScroll:true})
+  if(scroll){viewport.scrollLeft=scroll.left;viewport.scrollTop=scroll.top}
+ }
+ /** @param {import('@zixcel/projection-client').Camera} value */
+ camera(value){this.#spatial?.apply(value)}
+ speaker(value){this.#speaker=value}
+ garden(value){this.#garden=value}
+ activity(value){this.#spatial?.activity(value)}
+ /** @param {'in'|'out'|'up'|'down'|'left'|'right'|'reset'} action */
+ changeCamera(action){this.#spatial?.change(action)}
+ close(){this.#spatial?.close();this.#spatial=null;this.#abort?.abort();this.#actionHandles.clear();this.#root.replaceChildren();for(const slot of new Set([this.#slots.tools,this.#slots.details,this.#slots.actions].filter(Boolean)))slot.replaceChildren();if(this.#ownsSurface){this.#surface.close();this.#surface=createWorldSurface()}}
+ dispose(){this.close();if(this.#ownsSurface)this.#surface.close()}
+}
+/** @param {Document} document
+ * @param {import('@zixcel/interaction/input').InputDeclaration} declaration
+ * @param {(values:Record<string,string|boolean|number>)=>unknown|Promise<unknown>} onSubmit */
+export function inputForm(document,declaration,onSubmit){
+ if(validateInputDeclaration(declaration).length)fail('InvalidInputDeclaration')
+ const form=element(document,'form'),fields=new Map(),abort=new AbortController(),prefix='input-'+crypto.randomUUID()
+ const fieldIds=[...new Set([...declaration.action.input_schema.required,...Object.keys(declaration.fields)])]
+ for(const id of fieldIds){
+  const field=declaration.fields[id]
+  const schema=declaration.action.input_schema.fields[id],label=element(document,'label'),name=element(document,'span',field.label)
+  let input
+  if(field.choices){input=element(document,'select');input.append(element(document,'option','Choose…',{value:''}));for(const choice of field.choices)input.append(element(document,'option',choice.label,{value:choice.value}))}
+  else if(schema.type==='string'&&!field.sensitive&&schema.max_length>255){input=element(document,'textarea');input.rows=4;input.maxLength=schema.max_length}
+  else{input=element(document,'input');input.type=schema.type==='boolean'?'checkbox':['integer','number'].includes(schema.type)?'number':field.sensitive?'password':'text'
+   if(schema.type==='string')input.maxLength=schema.max_length??4096
+   if(schema.type==='integer')input.step='1'
+   if(schema.type==='number')input.step='any'
+   if(schema.minimum!==undefined)input.min=String(schema.minimum)
+   if(schema.maximum!==undefined)input.max=String(schema.maximum)
+  }
+  input.id=prefix+'-'+fields.size;input.name=id;input.autocomplete='off';label.htmlFor=input.id;label.append(name);form.append(label,input);fields.set(id,{input,schema})
+ }
+ const submit=element(document,'button','Submit',{type:'submit'}),status=element(document,'div','',{role:'status'});form.append(submit,status)
+ form.addEventListener('submit',async event=>{
+  event.preventDefault();if(submit.disabled)return
+  const values={};for(const [id,{input,schema}]of fields){
+   // An absent optional value is not zero, null, false or an empty string.
+   if(input.value===''&&schema.type!=='boolean'&&!declaration.action.input_schema.required.includes(id))continue
+   values[id]=schema.type==='boolean'?input.checked:['number','integer'].includes(schema.type)?(input.value===''?null:Number(input.value)):input.value
+  }
+  if(validateInputValues(declaration,values).length){status.textContent='Check the declared input constraints.';return}
+  submit.disabled=true;form.setAttribute('aria-busy','true')
+  try{await onSubmit(values);if(!abort.signal.aborted)status.textContent='Submitted.'}
+  catch(error){if(!abort.signal.aborted){status.setAttribute('role','alert');status.replaceChildren(valueView(document,{code:error.code??'OperationUnavailable',...(error.ownerFailure?{ownerFailure:error.ownerFailure}:{})}))}}
+  finally{for(const {input}of fields.values())if(input.type==='password')input.value='';submit.disabled=false;form.setAttribute('aria-busy','false')}
+ },{signal:abort.signal})
+ return {form,close(){abort.abort();for(const {input}of fields.values())input.value='';form.remove()}}
+}

package/src/inspection-overview.d.mts

@@ -0,0 +1 @@
+export function inspectionOverview(document: any, host: any, view: any, onSource: any, signal: any): void;

package/src/inspection-overview.mjs

@@ -0,0 +1,35 @@
+// Owner-projected facts only. This renderer does not classify semantic modules.
+import {element} from './index.mjs'
+export function inspectionOverview(document,host,view,onSource,signal){
+ host.replaceChildren()
+ if(!view){host.append(element(document,'p','Responsibility overview is unavailable.'));return}
+ host.append(element(document,'h2',view.title),element(document,'p',view.note,{class:'inspection-note'}))
+ const groups=element(document,'ul',null,{class:'scene-items'})
+ groups.style.gridTemplateColumns='repeat(auto-fit,minmax(min(250px,100%),1fr))'
+ for(const group of view.groups){
+  const section=element(document,'li',null,{'aria-label':group.title,'data-responsibility':group.id})
+  const info=element(document,'details'),description=element(document,'summary','About these observations')
+  info.append(description,element(document,'p',group.note))
+  section.append(element(document,'h3',group.title),element(document,'p',group.state,{class:'inspection-state'}))
+  for(const measure of group.measures){
+   const row=element(document,'div',null,{class:'item-tools','data-measure':measure.unit})
+   row.append(element(document,'strong',measure.value===null?'Unavailable':String(measure.value)+(measure.partial?' +':'')),element(document,'span',measure.unit))
+   if(measure.documentId){const button=element(document,'button','Inspect',{type:'button','aria-label':'Inspect '+measure.unit});button.addEventListener('click',()=>onSource(measure.documentId),{signal});row.append(button)}
+   section.append(row)
+  }
+  if(group.values?.length)section.append(element(document,'p',group.values.join(' · ')))
+  section.append(info);groups.append(section)
+ }
+ host.append(groups,element(document,'h3','Adopted definition modules'))
+ if(!view.modulesAvailable){host.append(element(document,'p','Module data unavailable.'));return}
+ if(!view.modules.length){host.append(element(document,'p','No definition modules in the observed role.'));return}
+ const list=element(document,'ul',null,{class:'inspection-modules'})
+ for(const module of view.modules){
+  const item=element(document,'li'),button=element(document,'button',module.id,{type:'button'})
+  button.addEventListener('click',()=>onSource('definitions'),{signal})
+  item.append(button,element(document,'p',`${module.version} · ${module.terms} terms · ${module.expressions} expressions`),element(document,'p',module.dependencies.length?'Imports: '+module.dependencies.join(', '):'No declared imports'))
+  list.append(item)
+ }
+ host.append(list)
+ if(view.modulesPartial)host.append(element(document,'p','Module inventory is incomplete.'))
+}

package/src/npc-motion.d.mts

@@ -0,0 +1,5 @@
+export function npcMotion(id: any, milliseconds: any, state?: string): {
+    x: number;
+    y: number;
+    swing: number;
+};

package/src/npc-motion.mjs

@@ -0,0 +1,7 @@
+// Ambient presentation only. This never changes semantic position or Work.
+export function npcMotion(id,milliseconds,state='Idle'){
+ const seed=[...id].reduce((n,c)=>(Math.imul(n,31)+c.charCodeAt(0))|0,0)>>>0
+ const active=['Runnable','Running','AwaitingResult'].includes(state)
+ const phase=milliseconds/1000*(active?2.2:1.1)*(0.85+(seed%7)/20)+(seed%97)*.31
+ return {x:Math.sin(phase)*(active?.2:.08),y:Math.max(0,Math.sin(phase*1.7))*(active?.12:.04),swing:Math.sin(phase*1.4)*(active?.16:.08)}
+}

package/src/object-presentation.d.mts

@@ -0,0 +1,55 @@
+export function objectPresentation(item: any): {
+    form: any;
+    dataType?: undefined;
+    needsReview?: undefined;
+} | {
+    form: string;
+    dataType: any;
+    needsReview: boolean;
+};
+export const spacingPresets: Readonly<{
+    compact: {
+        person: number;
+        group: number;
+        member: number;
+    };
+    balanced: {
+        person: number;
+        group: number;
+        member: number;
+    };
+    spacious: {
+        person: number;
+        group: number;
+        member: number;
+    };
+}>;
+export const objectForms: Readonly<{
+    person: "Person";
+    organization: "Organization";
+    system: "System";
+    shelf: "Bookshelf";
+    book: "Book";
+}>;
+export const libraryLayout: Readonly<{
+    columns: 6;
+    rows: 4;
+    slotWidth: 0.46;
+    rowHeight: 0.63;
+    baseY: 0.32;
+    frontZ: 0.32;
+}>;
+export const objectBounds: Readonly<{
+    person: number[];
+    organization: number[];
+    system: number[];
+    shelf: number[];
+    book: number[];
+}>;
+export const objectTemplates: Readonly<{
+    person: (string | number)[][];
+    organization: (string | number)[][];
+    system: (string | number)[][];
+    shelf: (string | number)[][];
+    book: (string | number)[][];
+}>;

package/src/object-presentation.mjs

@@ -0,0 +1,24 @@
+// Trusted presentation policy, not semantic classification or operation authority.
+// Never infer meaning from a title, locator or a numeric magnitude.
+export const spacingPresets=Object.freeze({compact:{person:5,group:3,member:1.3},balanced:{person:7,group:4,member:1.8},spacious:{person:10,group:6,member:2.6}})
+export const objectForms=Object.freeze({person:'Person',organization:'Organization',system:'System',shelf:'Bookshelf',book:'Book'})
+// Temporary placement policy. Furniture is derived from nonempty view groups,
+// not persisted as semantic data. A page occupies six columns × four shelves.
+export const libraryLayout=Object.freeze({columns:6,rows:4,slotWidth:.46,rowHeight:.63,baseY:.32,frontZ:.32})
+export const objectBounds=Object.freeze({person:[1.5,2.5,1.1],organization:[2.8,3.2,2],system:[1.8,2,1],shelf:[3.4,3.2,.9],book:[.4,.62,.6]})
+// Each part is [x,y,z,width,height,depth,tint]. Local coordinates and closed
+// tint tokens keep assets declarative: no external scripts, images or model IO.
+export const objectTemplates=Object.freeze({
+ person:[[-.2,.48,0,.28,.8,.34,'dark'],[.2,.48,0,.28,.8,.34,'dark'],[0,1.26,0,.88,.86,.48,'accent'],[-.59,1.22,0,.25,.9,.3,'accent'],[.59,1.22,0,.25,.9,.3,'accent'],[0,2,0,.62,.62,.58,'face'],[0,2.34,0,.68,.15,.63,'dark'],[-.15,2.04,.302,.075,.08,.025,'dark'],[.15,2.04,.302,.075,.08,.025,'dark']],
+ organization:[[0,1.55,0,2.6,3,1.8,'accent'],[0,3.1,0,2.8,.2,2,'dark'],[-.6,1.8,.92,.55,.65,.08,'light'],[.6,1.8,.92,.55,.65,.08,'light'],[0,.5,.94,.7,.95,.08,'dark']],
+ system:[[0,.25,0,1.5,.5,.9,'dark'],[0,1.2,0,1.4,1.5,.3,'accent'],[0,1.35,.18,1.1,1,.05,'light'],[0,.6,.45,1.2,.1,.15,'warning']],
+ shelf:[[-1.55,1.5,0,.15,3,.65,'dark'],[1.55,1.5,0,.15,3,.65,'dark'],[0,1.5,-.32,3.25,3,.08,'accent'],...Array.from({length:5},(_,i)=>[0,.25+i*.63,0,3.25,.1,.7,'dark'])],
+ book:[[-.15,.3,0,.05,.58,.5,'accent'],[.15,.3,0,.05,.58,.5,'accent'],[0,.3,-.22,.3,.58,.06,'accent'],[0,.3,.025,.24,.5,.39,'light']]
+})
+export function objectPresentation(item){
+ if(item.form&&Object.hasOwn(objectForms,item.form))return {form:item.form}
+ if(item.kind==='character')return {form:'person'}
+ if(item.kind==='group')return {form:'shelf'}
+ const values=item.scalars??[],types=[...new Set(values.filter(v=>v!==null).map(v=>typeof v))]
+ return {form:'book',dataType:types.length===1?({string:'text',number:'number',boolean:'boolean'}[types[0]]??'record'):'record',needsReview:Boolean(item.unresolved)}
+}

package/src/open-world-projection.d.mts

@@ -0,0 +1,29 @@
+export function visibleProjection(sources: any, { x, z, radius, limit, marked }?: {
+    x?: number;
+    z?: number;
+    radius?: number;
+    limit?: number;
+    marked?: any;
+}): {
+    items: any[];
+    markers: any[];
+    total: number;
+    omitted: number;
+};
+export function mapProjection(sources: any, { selected, marked, limit }?: {
+    selected?: any;
+    marked?: any;
+    limit?: number;
+}): {
+    items: {
+        id: any;
+        title: any;
+        kind: any;
+        x: any;
+        z: any;
+        selected: boolean;
+        marked: boolean;
+    }[];
+    total: number;
+    omitted: number;
+};

package/src/open-world-projection.mjs

@@ -0,0 +1,26 @@
+// Read-only, bounded views over exact owner IDs. Coordinates are presentation,
+// never evidence of a semantic relation or an action authority.
+export function visibleProjection(sources,{x=0,z=0,radius=24,limit=200,marked=null}={}){
+ if(!Array.isArray(sources)||sources.length>10000||!Number.isFinite(x)||!Number.isFinite(z)
+  ||!Number.isFinite(radius)||radius<=0||!Number.isSafeInteger(limit)||limit<1||limit>200)throw Error('WorldProjectionLimitExceeded')
+ const candidates=[],seen=new Set();let mark=null
+ for(const source of sources){
+  if(typeof source.id!=='string'||!source.id||seen.has(source.id)||!Number.isFinite(source.x)||!Number.isFinite(source.z))throw Error('WorldProjectionSourceInvalid')
+  seen.add(source.id)
+  const dx=source.x-x,dz=source.z-z,distance=dx*dx+dz*dz
+  if(distance<=radius*radius)candidates.push({source,distance})
+  if(source.id===marked)mark=source
+ }
+ candidates.sort((a,b)=>a.distance-b.distance||a.source.id.localeCompare(b.source.id))
+ const items=candidates.slice(0,limit).map(({source})=>source)
+ return {items,markers:mark&&!items.some(item=>item.id===mark.id)?[mark]:[],total:sources.length,omitted:candidates.length-items.length}
+}
+
+export function mapProjection(sources,{selected=null,marked=null,limit=128}={}){
+ if(!Array.isArray(sources)||sources.length>10000||!Number.isSafeInteger(limit)||limit<1||limit>128)throw Error('WorldProjectionLimitExceeded')
+ const seen=new Set()
+ for(const item of sources){if(typeof item.id!=='string'||!item.id||seen.has(item.id)||!Number.isFinite(item.x)||!Number.isFinite(item.z))throw Error('WorldProjectionSourceInvalid');seen.add(item.id)}
+ const priority=sources.filter(item=>item.id===selected||item.id===marked),base=sources.filter(item=>item.id!==selected&&item.id!==marked)
+ const chosen=sources.length<=limit?sources:[...priority,...base].slice(0,limit)
+ return {items:chosen.map(item=>({id:item.id,title:item.title,kind:item.kind,x:item.x,z:item.z,selected:item.id===selected,marked:item.id===marked})),total:sources.length,omitted:sources.length-chosen.length}
+}

package/src/reconcile.d.mts

@@ -0,0 +1 @@
+export function reconcileChildren(parent: any, children: any): void;

package/src/reconcile.mjs

@@ -0,0 +1,21 @@
+// Trusted renderer output only. No user forms or independently owned DOM trees.
+const key=(node,index)=>node.nodeType===1
+ ?[node.tagName,...['data-item-id','data-world-object','data-region','data-control'].flatMap(k=>node.hasAttribute(k)?[k,node.getAttribute(k)]:[])].join(':')+(node.matches('[data-item-id],[data-world-object],[data-region],[data-control]')?'':':'+index)
+ :node.nodeType+':'+index
+export function reconcileChildren(parent,children){
+ const old=new Map([...parent.childNodes].map((node,index)=>[key(node,index),node])),wanted=[]
+ for(const [index,fresh]of [...children].entries()){
+  const identity=key(fresh,index),existing=old.get(identity)
+  if(existing&&existing.nodeType===fresh.nodeType&&existing.nodeName===fresh.nodeName){
+   old.delete(identity)
+   if(existing.nodeType===1){
+    for(const attribute of [...existing.attributes])if(!fresh.hasAttribute(attribute.name))existing.removeAttribute(attribute.name)
+    for(const attribute of fresh.attributes)if(existing.getAttribute(attribute.name)!==attribute.value)existing.setAttribute(attribute.name,attribute.value)
+    reconcileChildren(existing,fresh.childNodes)
+   }else if(existing.nodeValue!==fresh.nodeValue)existing.nodeValue=fresh.nodeValue
+   wanted.push(existing)
+  }else wanted.push(fresh)
+ }
+ for(const node of old.values())node.remove()
+ for(let index=0;index<wanted.length;index++)if(parent.childNodes[index]!==wanted[index])parent.insertBefore(wanted[index],parent.childNodes[index]??null)
+}

package/src/spatial-patterns.d.mts

@@ -0,0 +1,29 @@
+export function spatialPattern(objects: any, relations?: any[], options?: {}): {
+    objects: any;
+    relations: any[];
+    groups: any[];
+    state: {
+        pattern: any;
+        groupBy: any;
+        group: any;
+        page: number;
+    };
+    total: any;
+    pages: number;
+    label: string;
+} | {
+    objects: any[];
+    relations: any[];
+    groups: any[];
+    state: {
+        pattern: any;
+        groupBy: any;
+        group: any;
+        page: number;
+    };
+    total: number;
+    pages: number;
+    label: any;
+};
+export const spatialPatterns: readonly string[][];
+export const spatialGroupings: readonly string[][];

package/src/spatial-patterns.mjs

@@ -0,0 +1,43 @@
+import {layoutWorld} from './world-model.mjs'
+
+// View-local partitions, never entities, inferred meanings, relationships or commands.
+export const spatialPatterns=Object.freeze([['garden','Garden'],['ground','Ground · people and places'],['constellation','Constellation · information']])
+export const spatialGroupings=Object.freeze([['declared','Declared structure'],['meaning','Meaning reference'],['source','Source owner']])
+const pageSize=24
+export function spatialPattern(objects,relations=[],options={}){
+ layoutWorld(objects,relations) // Validate even when a collapsed view would hide bad input.
+ const pattern=options.pattern??'ground',groupBy=options.groupBy??'declared'
+ if(!spatialPatterns.some(([id])=>id===pattern))throw Error('SpatialPatternInvalid')
+ if(!spatialGroupings.some(([id])=>id===groupBy))throw Error('SpatialGroupingInvalid')
+ const state={pattern,groupBy,group:null,page:0}
+ if(pattern==='ground')return {objects,relations,groups:[],state,total:objects.length,pages:1,label:'All objects'}
+ const actors=objects.filter(i=>i.kind==='character'),records=objects.filter(i=>i.kind!=='character'),partitions=new Map(),ids=new Set(objects.map(i=>i.id))
+ for(const item of records){
+  let key=null,title='Unclassified'
+  if(groupBy==='declared'&&item.group?.kind&&item.group?.ref){key=[item.group.kind,item.group.ref];title=item.groupLabel??item.group.ref}
+  if(groupBy==='meaning'&&typeof item.semanticRef==='string'){key=item.semanticRef;title='Meaning · '+key}
+  if(groupBy==='source'){
+   const owners=[...new Set((item.sourceRefs??[]).map(s=>s.owner).filter(v=>typeof v==='string'))].sort()
+   if(owners.length){key=owners;title=owners.join(' + ')}
+  }
+  const identity=JSON.stringify([groupBy,key]);let group=partitions.get(identity)
+  if(!group){let id='view:group:'+identity;while(ids.has(id))id='view:'+id;ids.add(id);group={id,kind:'group',title,memberIds:[],members:[]};partitions.set(identity,group)}
+  group.memberIds.push(item.id);group.members.push(item)
+ }
+ const groups=[...partitions.values()],selected=groups.find(g=>g.id===options.group)
+ state.group=selected?.id??null
+ if(pattern==='garden'){
+  if(actors.length>32)throw Error('WorldCapacityExceeded')
+  // Records remain in the exact focused projection. A shelf is a local index
+  // for that person's information, not an entity standing beside the person.
+  state.group=null;state.page=0
+  const actorIds=new Set(actors.map(i=>i.id))
+  return {objects:actors,relations:relations.filter(r=>actorIds.has(r.from)&&actorIds.has(r.to)),groups:groups.map(({members,...g})=>g),state,total:actors.length,pages:1,label:'People'}
+ }
+ const candidates=selected?selected.members:groups.map(({members,...g})=>({...g,summary:g.memberIds.length+' records · Browse shelf'}))
+ // Actors share the same paging budget; no silent truncation or unbounded group expansion.
+ const all=[...actors,...candidates],pages=Math.max(1,Math.ceil(all.length/pageSize))
+ state.page=state.group!==options.group&&options.group?0:Math.min(pages-1,Math.max(0,Number.isSafeInteger(options.page)?options.page:0))
+ const visible=all.slice(state.page*pageSize,(state.page+1)*pageSize),visibleIds=new Set(visible.filter(i=>i.kind!=='group').map(i=>i.id))
+ return {objects:visible,relations:relations.filter(r=>visibleIds.has(r.from)&&visibleIds.has(r.to)),groups:groups.map(({members,...g})=>g),state,total:all.length,pages,label:selected?.title??'All groups'}
+}

package/src/spatial.d.mts

@@ -0,0 +1,8 @@
+export function spatialView(viewport: any, board: any, camera: any, relations: any, signal: any, pose: any, conversation?: any, presentation?: {}): {
+    change: any;
+    apply: any;
+    snapshot: any;
+    pause: any;
+    activity: any;
+    close: () => void;
+};

package/src/spatial.mjs

@@ -0,0 +1,27 @@
+import {createWorld} from './world-runtime.mjs'
+// Installed RenderPlan/role controls remain the only operation authority.
+export function spatialView(viewport,board,camera,relations,signal,pose,conversation=null,presentation={}){
+ const nodes=()=>[...board.querySelectorAll('[data-item-id],[data-world-object]')]
+ const declarations=()=>nodes().filter(node=>!node.hidden).map(node=>({
+  id:node.dataset.itemId??node.dataset.worldObject,
+  ...presentation.items?.get(node.dataset.itemId),
+  kind:node.hasAttribute('data-world-object')?'character':'record',
+  title:node.querySelector('strong,[data-kind=select]')?.textContent??'Information',
+  summary:node.querySelector('[data-item-summary]')?.textContent?.slice(0,80)??'',
+  observationLabel:node.dataset.observationLabel??'',
+  disabled:node.disabled===true,selected:node.dataset.selected==='true'
+ }))
+ const options={objects:declarations(),relations,pose,conversation,activity:presentation.activity,target:presentation.target,pattern:presentation.pattern,context:presentation.context,onActivate:id=>{
+  const node=nodes().find(node=>(node.dataset.itemId??node.dataset.worldObject)===id)
+  if(!node||node.hidden||node.disabled)return
+  ;(node.hasAttribute('data-world-object')?node:node.querySelector('[data-kind=inspect]'))?.click()
+ }}
+ const lease=presentation.surface?.attach(viewport,options),world=lease?.world??createWorld(viewport,options)
+ board.hidden=true;world.apply(camera)
+ const observer=new viewport.ownerDocument.defaultView.MutationObserver(()=>world.update(declarations(),relations))
+ observer.observe(board,{subtree:true,childList:true,characterData:true,attributes:true,attributeFilter:['hidden','data-selected','disabled']})
+ let closed=false
+ const close=()=>{if(closed)return;closed=true;observer.disconnect();if(lease)lease.release();else world.close();board.hidden=false}
+ signal.addEventListener('abort',close,{once:true})
+ return {change:world.change,apply:world.apply,snapshot:world.snapshot,pause:world.pause,activity:world.activity,close}
+}

package/src/structure-graph.d.mts

@@ -0,0 +1,16 @@
+export function graphDocuments(documents: any, { component, query, depth, maximum }?: {
+    component?: string;
+    query?: string;
+    depth?: number;
+    maximum?: number;
+}): {
+    nodes: any[];
+    edges: any[];
+    truncated: boolean;
+};
+export function structureGraph(document: any, host: any, view: any, onRole: any, onRefresh: any, { embedded }?: {
+    embedded?: boolean;
+}): {
+    update(next: any): void;
+    close(): void;
+};