@zixcel/dom-renderer 0.10.4 → 0.10.5

package/src/world-events.mjs

@@ -0,0 +1,120 @@
+import { eventDetail } from './world-api.mjs';
+import { movePose, lookPose, clamp, pickWorld } from './world-model.mjs';
+import { keyDirection } from './world-input.mjs';
+export function bindWorldEvents(ctx) {
+    ctx.hint.addEventListener('click', () => { ctx.nearby.open = true; }, { signal: ctx.signal });
+    ctx.shell?.addEventListener('world-anchor-request', event => { const detail = eventDetail(event); if (detail.id === null || typeof detail.id === 'string') {
+        ctx.anchorId = detail.id;
+        ctx.publishAnchor();
+    } }, { signal: ctx.signal });
+    ctx.query.addEventListener('input', ctx.filterDirectory, { signal: ctx.signal });
+    ctx.host.closest('.delivery-shell')?.addEventListener('frame-panel-open', () => { ctx.nearby.open = false; ctx.map.open = false; ctx.updates.open = false; ctx.closeConversation(); }, { signal: ctx.signal });
+    ctx.nearby.addEventListener('toggle', () => { ctx.map.hidden = ctx.nearby.open; if (ctx.nearby.open) {
+        ctx.map.open = false;
+        ctx.updates.open = false;
+        ctx.closeConversation();
+    } }, { signal: ctx.signal });
+    ctx.updates.addEventListener('toggle', () => { if (ctx.updates.open) {
+        ctx.nearby.open = false;
+        ctx.closeConversation();
+    } }, { signal: ctx.signal });
+    ctx.map.addEventListener('toggle', () => { if (ctx.map.open) {
+        ctx.nearby.open = false;
+        ctx.updates.open = false;
+        ctx.closeConversation();
+        ctx.stopInput();
+    } }, { signal: ctx.signal });
+    ctx.orbit.addEventListener('change', () => { if (ctx.syncing)
+        return; ctx.pose = { x: ctx.orbitCamera.position.x, y: ctx.orbitCamera.position.y, z: ctx.orbitCamera.position.z, yaw: -ctx.orbitCamera.rotation.y, pitch: ctx.orbitCamera.rotation.x, focus: { x: ctx.orbit.target.x, y: ctx.orbit.target.y, z: ctx.orbit.target.z } }; ctx.needsFit = false; ctx.invalidate(); });
+    ctx.mapList.addEventListener('click', event => { const id = (event.target instanceof ctx.window.Element ? event.target.closest('[data-map-id]') : null)?.dataset.mapId; if (id)
+        ctx.focusObject(id); }, { signal: ctx.signal });
+    ctx.mapButton.addEventListener('click', () => { if (!ctx.selectedId)
+        return; ctx.markedId = ctx.markedId === ctx.selectedId ? null : ctx.selectedId; ctx.wrap.dataset.markedId = ctx.markedId ?? ''; for (const [id, node] of ctx.labelNodes)
+        node.dataset.marked = String(id === ctx.markedId); ctx.renderMap(); }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('pointerdown', ctx.enableOrbit, { signal: ctx.signal, capture: true });
+    ctx.canvas.addEventListener('wheel', ctx.enableOrbit, { signal: ctx.signal, capture: true });
+    ctx.updateList.addEventListener('click', event => {
+        const id = (event.target instanceof ctx.window.Element ? event.target.closest('[data-change-id]') : null)?.dataset.changeId;
+        if (!id)
+            return;
+        if (ctx.view.pattern === 'garden' && !ctx.model.items.some(item => item.id === id)) {
+            ctx.updates.open = false;
+            ctx.onActivate(id);
+            return;
+        }
+        const group = ctx.projection?.groups.find(group => group.memberIds.includes(id));
+        if (group) {
+            ctx.view = { ...ctx.view, group: group.id, page: 0 };
+            ctx.update(ctx.sourceObjects, ctx.sourceRelations);
+            const index = (ctx.view.pattern === 'garden' ? group.memberIds : [...ctx.sourceObjects.filter(i => i.kind === 'character').map(i => i.id), ...group.memberIds]).indexOf(id);
+            if (index >= 24) {
+                ctx.view = { ...ctx.view, page: Math.floor(index / 24) };
+                ctx.update(ctx.sourceObjects, ctx.sourceRelations);
+            }
+        }
+        ctx.updates.open = false;
+        ctx.focusObject(id);
+    }, { signal: ctx.signal });
+    ctx.labels.addEventListener('click', event => ctx.activate((event.target instanceof ctx.window.Element ? event.target.closest('[data-world-id]') : null)?.dataset.worldId), { signal: ctx.signal });
+    ctx.list.addEventListener('click', event => {
+        const control = (event.target instanceof ctx.window.Element ? event.target.closest('button') : null), id = control?.closest('[data-directory-id]')?.dataset.directoryId;
+        if (!id || !control)
+            return;
+        if (control.dataset.focus === 'true') {
+            ctx.focusObject(id);
+            ctx.nearby.open = false;
+            ctx.canvas.focus({ preventScroll: true });
+        }
+        else
+            ctx.activate(id);
+    }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('keydown', ctx.onKey, { signal: ctx.signal });
+    ctx.window.addEventListener('keyup', event => { const key = keyDirection(event.code); if (key) {
+        ctx.keys.delete(key);
+        ctx.invalidate();
+    } }, { signal: ctx.signal });
+    ctx.bubble.addEventListener('keydown', event => { if (event.key === 'Escape') {
+        event.stopPropagation();
+        ctx.closeConversation();
+    } }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('pointerdown', event => { if (!event.isPrimary) {
+        ctx.drag = null;
+        return;
+    } if (event.button !== 0 || ctx.inputBlocked())
+        return; ctx.canvas.focus({ preventScroll: true }); ctx.drag = { id: event.pointerId, x: event.clientX, y: event.clientY, startX: event.clientX, startY: event.clientY }; ctx.canvas.setPointerCapture(event.pointerId); }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('pointermove', event => { if (!ctx.drag || ctx.drag.id !== event.pointerId)
+        return; if (ctx.navigation === 'explore')
+        ctx.pose = lookPose(ctx.pose, event.clientX - ctx.drag.x, event.clientY - ctx.drag.y); ctx.drag.x = event.clientX; ctx.drag.y = event.clientY; ctx.invalidate(); }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('pointerup', event => { if (!ctx.drag || ctx.drag.id !== event.pointerId)
+        return; const clicked = Math.hypot(event.clientX - ctx.drag.startX, event.clientY - ctx.drag.startY) < 5; ctx.drag = null; if (clicked) {
+        const r = ctx.canvas.getBoundingClientRect();
+        ctx.activate(pickWorld(ctx.model.items, ctx.pose, event.clientX - r.left, event.clientY - r.top, r.width, r.height, ctx.zoom));
+    } }, { signal: ctx.signal, capture: true });
+    for (const type of ['pointercancel', 'lostpointercapture'])
+        ctx.canvas.addEventListener(type, () => ctx.drag = null, { signal: ctx.signal });
+    ctx.canvas.addEventListener('wheel', event => { if (ctx.navigation === 'overview' || event.ctrlKey || event.metaKey || ctx.inputBlocked() || !Number.isFinite(event.deltaY))
+        return; event.preventDefault(); const amount = clamp(-event.deltaY * (event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? ctx.host.clientHeight : 1) / 100, -2, 2); ctx.pose = { ...ctx.pose, x: clamp(ctx.pose.x + Math.sin(ctx.pose.yaw) * amount, -28, 28), z: clamp(ctx.pose.z - Math.cos(ctx.pose.yaw) * amount, -350, 28) }; ctx.invalidate(); }, { signal: ctx.signal, passive: false });
+    for (const [direction, icon] of [['forward', '↑'], ['left', '←'], ['back', '↓'], ['right', '→'], ['rise', '⇧'], ['descend', '⇩']]) {
+        const b = ctx.button(icon, 'Walk ' + direction, () => { }, ctx.walk);
+        b.addEventListener('pointerdown', event => { if (event.button || ctx.inputBlocked())
+            return; event.preventDefault(); b.setPointerCapture(event.pointerId); ctx.keys.add(direction); ctx.invalidate(); }, { signal: ctx.signal });
+        for (const type of ['pointerup', 'pointercancel', 'lostpointercapture'])
+            b.addEventListener(type, () => { ctx.keys.delete(direction); ctx.invalidate(); }, { signal: ctx.signal });
+        b.addEventListener('click', event => { if (event.detail === 0 && !ctx.inputBlocked()) {
+            ctx.pose = movePose(ctx.pose, direction === 'forward' ? 1 : direction === 'back' ? -1 : 0, direction === 'right' ? 1 : direction === 'left' ? -1 : 0, .05, direction === 'rise' ? 1 : direction === 'descend' ? -1 : 0);
+            ctx.invalidate();
+        } }, { signal: ctx.signal });
+    }
+    ctx.nearby.addEventListener('toggle', () => { if (ctx.nearby.open)
+        ctx.stopInput(); }, { signal: ctx.signal });
+    ctx.window.addEventListener('blur', () => { ctx.wrap.dataset.motionPaused = 'true'; ctx.stopInput(); ctx.stopFrame(); }, { signal: ctx.signal });
+    ctx.window.addEventListener('focus', () => { ctx.wrap.dataset.motionPaused = 'false'; ctx.invalidate(); }, { signal: ctx.signal });
+    ctx.document.addEventListener('visibilitychange', () => { ctx.wrap.dataset.motionPaused = String(ctx.document.hidden); ctx.stopInput(); if (ctx.document.hidden)
+        ctx.stopFrame();
+    else
+        ctx.invalidate(); }, { signal: ctx.signal });
+    ctx.window.addEventListener('pagehide', () => { ctx.paused = true; ctx.stopInput(); ctx.stopFrame(); }, { signal: ctx.signal });
+    ctx.window.addEventListener('pageshow', () => { ctx.paused = false; ctx.invalidate(); }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('webglcontextlost', event => { event.preventDefault(); ctx.lost = true; ctx.gpu?.close(); ctx.gpu = null; ctx.fail(Error('WorldGraphicsContextLost')); }, { signal: ctx.signal });
+    ctx.canvas.addEventListener('webglcontextrestored', ctx.initialize, { signal: ctx.signal });
+}

package/src/world-gpu.d.mts

@@ -1,15 +1,3 @@
-export function createGpu(canvas: any): {
-    pattern(value: any): void;
-    upload(data: any, ranges?: any[]): void;
-    motionStates(states: any): void;
-    draw(pose: any, aspect: any, zoom: any, size: any, milliseconds?: number, visibleActors?: Set<any>): void;
-    readonly count: any;
-    readonly stats: {
-        calls: any;
-        triangles: any;
-        geometries: any;
-        textures: any;
-    };
-    close: () => void;
-};
-export function worldGeometry(model: any, actors?: any[]): Float32Array<ArrayBuffer>;
+import type { Gpu, ActorRange, WorldModel } from './world-types.mjs';
+export declare function createGpu(canvas: HTMLCanvasElement): Gpu;
+export declare function worldGeometry(model: WorldModel, actors?: ActorRange[]): Float32Array<ArrayBuffer>;

package/src/world-gpu.mjs

@@ -1,79 +1,164 @@
+import { disposeGraphics } from './graphics-disposal.mjs';
+import { admitGeometry } from './geometry-policy.mjs';
 // One instanced cube mesh, one program, no textures, physics, asset fetches or semantic state.
-import {WebGLRenderer,Scene,PerspectiveCamera,BoxGeometry,MeshLambertMaterial,InstancedMesh,Matrix4,Color,DirectionalLight,AmbientLight,Fog} from 'three'
-import {worldLimits,viewCamera} from './world-model.mjs'
-import {objectTemplates} from './object-presentation.mjs'
-import {npcMotion} from './npc-motion.mjs'
-export function createGpu(canvas){
- let renderer=null,geometry=null,material=null,mesh=null,closed=false,bufferWidth=0,bufferHeight=0,previous=null,pendingStart=Infinity,pendingEnd=0,baseCount=0,actors=[],actorStates=new Map(),lastVisible=new Set()
- const scene=new Scene(),camera=new PerspectiveCamera(70,1,.08,120),matrix=new Matrix4(),color=new Color()
- function close(){if(closed)return;closed=true;previous=null;actors=[];actorStates.clear();lastVisible.clear();mesh?.dispose();geometry?.dispose();material?.dispose();scene.clear();renderer?.dispose()}
- try{
-  renderer=new WebGLRenderer({canvas,alpha:false,antialias:false,stencil:false,preserveDrawingBuffer:false,powerPreference:'low-power'})
-  scene.background=new Color('#b8d4de');scene.fog=new Fog('#b8d4de',16,64)
-  scene.add(new AmbientLight(0xffffff,1.7));const light=new DirectionalLight(0xffffff,2);light.position.set(-4,10,6);scene.add(light)
-  geometry=new BoxGeometry(1,1,1);material=new MeshLambertMaterial()
-  mesh=new InstancedMesh(geometry,material,worldLimits.instances);mesh.count=0;mesh.frustumCulled=false;scene.add(mesh)
-  return {
-   pattern(value){const space=value==='constellation',background=space?'#101b35':'#b8d4de';scene.background.set(background);scene.fog=new Fog(background,space?40:16,space?100:64)},
-   upload(data,ranges=[]){
-    if(closed)throw Error('WorldDisposed')
-    if(data.length%9||data.length/9>=worldLimits.instances)throw Error('WorldGeometryLimitExceeded')
-    baseCount=data.length/9;mesh.count=baseCount
-    for(let i=0;i<baseCount;i++){
-     const j=i*9;if(previous&&data.subarray(j,j+9).every((value,index)=>value===previous[j+index]))continue
-     matrix.makeScale(data[j+3],data[j+4],data[j+5]);matrix.setPosition(data[j],data[j+1],data[j+2]);mesh.setMatrixAt(i,matrix);mesh.setColorAt(i,color.setRGB(data[j+6],data[j+7],data[j+8]))
-     pendingStart=Math.min(pendingStart,i);pendingEnd=Math.max(pendingEnd,i+1)
+import { WebGLRenderer, Scene, PerspectiveCamera, BoxGeometry, MeshLambertMaterial, InstancedMesh, Matrix4, Color, DirectionalLight, AmbientLight, Fog } from 'three';
+import { worldLimits, viewCamera } from './world-model.mjs';
+import { objectTemplates } from './object-presentation.mjs';
+import { npcMotion } from './npc-motion.mjs';
+export function createGpu(canvas) {
+    let disposableRenderer = null, disposableGeometry = null, disposableMaterial = null, disposableMesh = null;
+    let closed = false, bufferWidth = 0, bufferHeight = 0, previous = null, pendingStart = Infinity, pendingEnd = 0, baseCount = 0, actors = [], actorStates = new Map(), lastVisible = new Set();
+    const scene = new Scene(), camera = new PerspectiveCamera(70, 1, .08, 120), matrix = new Matrix4(), color = new Color();
+    function close() { if (closed)
+        return; closed = true; previous = null; actors = []; actorStates.clear(); lastVisible.clear(); disposeGraphics([() => disposableMesh?.dispose(), () => disposableGeometry?.dispose(), () => disposableMaterial?.dispose(), () => scene.clear(), () => disposableRenderer?.dispose()]); }
+    try {
+        const renderer = disposableRenderer = new WebGLRenderer({ canvas, alpha: false, antialias: false, stencil: false, preserveDrawingBuffer: false, powerPreference: 'low-power' });
+        const background = new Color('#b8d4de');
+        let fog = new Fog('#b8d4de', 16, 64);
+        scene.background = background;
+        scene.fog = fog;
+        scene.add(new AmbientLight(0xffffff, 1.7));
+        const light = new DirectionalLight(0xffffff, 2);
+        light.position.set(-4, 10, 6);
+        scene.add(light);
+        const geometry = disposableGeometry = new BoxGeometry(1, 1, 1);
+        const material = disposableMaterial = new MeshLambertMaterial();
+        const mesh = disposableMesh = new InstancedMesh(geometry, material, worldLimits.instances);
+        mesh.count = 0;
+        mesh.frustumCulled = false;
+        scene.add(mesh);
+        return {
+            pattern(value) { if (closed)
+                throw Error('WorldDisposed'); const space = value === 'constellation', shade = space ? '#101b35' : '#b8d4de'; background.set(shade); fog = new Fog(shade, space ? 40 : 16, space ? 100 : 64); scene.fog = fog; },
+            upload(data, ranges = []) {
+                if (closed)
+                    throw Error('WorldDisposed');
+                admitGeometry(data, ranges);
+                baseCount = data.length / 9;
+                mesh.count = baseCount;
+                for (let i = 0; i < baseCount; i++) {
+                    const j = i * 9;
+                    if (previous && data.subarray(j, j + 9).every((value, index) => value === previous[j + index]))
+                        continue;
+                    matrix.makeScale(data[j + 3], data[j + 4], data[j + 5]);
+                    matrix.setPosition(data[j], data[j + 1], data[j + 2]);
+                    mesh.setMatrixAt(i, matrix);
+                    mesh.setColorAt(i, color.setRGB(data[j + 6], data[j + 7], data[j + 8]));
+                    pendingStart = Math.min(pendingStart, i);
+                    pendingEnd = Math.max(pendingEnd, i + 1);
+                }
+                previous = data;
+                actors = ranges;
+            },
+            motionStates(states) { if (closed)
+                throw Error('WorldDisposed'); if (states.size > worldLimits.objects)
+                throw Error('WorldGeometryLimitExceeded'); actorStates = new Map(states); },
+            draw(pose, aspect, zoom, size, milliseconds = 0, visibleActors = new Set()) {
+                if (closed)
+                    return;
+                if (size.width !== bufferWidth || size.height !== bufferHeight) {
+                    renderer.setSize(size.width, size.height, false);
+                    bufferWidth = size.width;
+                    bufferHeight = size.height;
+                }
+                const distance = pose.focus ? Math.hypot(pose.x - pose.focus.x, pose.y - pose.focus.y, pose.z - pose.focus.z) : 0;
+                fog.near = Math.max(16, distance * .75);
+                fog.far = Math.max(64, distance * 2 + 20);
+                mesh.count = baseCount + (pose.cameraMode === 'third-person' ? 1 : 0);
+                let matrixStart = pendingStart, matrixEnd = pendingEnd, colorStart = pendingStart, colorEnd = pendingEnd;
+                const coordinates = previous;
+                if (coordinates)
+                    for (const actor of actors) {
+                        if (!visibleActors.has(actor.id) && !lastVisible.has(actor.id))
+                            continue;
+                        const motion = visibleActors.has(actor.id) ? npcMotion(actor.id, milliseconds, actorStates.get(actor.id)) : { x: 0, y: 0, swing: 0 };
+                        for (let i = actor.start; i < actor.end; i++) {
+                            const j = i * 9, part = i - actor.start, limb = part === 1 || part === 4 ? 1 : part === 2 || part === 5 ? -1 : 0;
+                            matrix.makeScale(coordinates[j + 3], coordinates[j + 4], coordinates[j + 5]);
+                            matrix.setPosition(coordinates[j] + motion.x, coordinates[j + 1] + motion.y + limb * motion.swing, coordinates[j + 2]);
+                            mesh.setMatrixAt(i, matrix);
+                        }
+                        matrixStart = Math.min(matrixStart, actor.start);
+                        matrixEnd = Math.max(matrixEnd, actor.end);
+                    }
+                lastVisible = new Set(visibleActors);
+                if (pose.cameraMode === 'third-person') {
+                    matrix.makeScale(.48, .9, .42);
+                    matrix.setPosition(pose.x, pose.y - 1.4, pose.z);
+                    mesh.setMatrixAt(baseCount, matrix);
+                    mesh.setColorAt(baseCount, color.setRGB(.96, .76, .28));
+                    matrixStart = Math.min(matrixStart, baseCount);
+                    matrixEnd = Math.max(matrixEnd, baseCount + 1);
+                    colorStart = Math.min(colorStart, baseCount);
+                    colorEnd = Math.max(colorEnd, baseCount + 1);
+                }
+                const updates = [[mesh.instanceMatrix, matrixStart, matrixEnd, 16], [mesh.instanceColor, colorStart, colorEnd, 3]];
+                for (const [attribute, start, end, size] of updates)
+                    if (attribute) {
+                        attribute.clearUpdateRanges();
+                        if (start !== Infinity) {
+                            attribute.addUpdateRange(start * size, (end - start) * size);
+                            attribute.needsUpdate = true;
+                        }
+                    }
+                viewCamera(pose, aspect, zoom, camera);
+                renderer.render(scene, camera);
+                pendingStart = Infinity;
+                pendingEnd = 0;
+            },
+            get count() { return mesh.count; }, get stats() { return { calls: renderer.info.render.calls, triangles: renderer.info.render.triangles, geometries: renderer.info.memory.geometries, textures: renderer.info.memory.textures }; }, close
+        };
     }
-    previous=data;actors=ranges
-   },
-   motionStates(states){actorStates=states},
-   draw(pose,aspect,zoom,size,milliseconds=0,visibleActors=new Set()){if(closed)return;if(size.width!==bufferWidth||size.height!==bufferHeight){renderer.setSize(size.width,size.height,false);bufferWidth=size.width;bufferHeight=size.height}const distance=pose.focus?Math.hypot(pose.x-pose.focus.x,pose.y-pose.focus.y,pose.z-pose.focus.z):0;scene.fog.near=Math.max(16,distance*.75);scene.fog.far=Math.max(64,distance*2+20)
-    mesh.count=baseCount+(pose.cameraMode==='third-person'?1:0)
-    let matrixStart=pendingStart,matrixEnd=pendingEnd,colorStart=pendingStart,colorEnd=pendingEnd
-    for(const actor of actors){if(!visibleActors.has(actor.id)&&!lastVisible.has(actor.id))continue;const motion=visibleActors.has(actor.id)?npcMotion(actor.id,milliseconds,actorStates.get(actor.id)):{x:0,y:0,swing:0}
-     for(let i=actor.start;i<actor.end;i++){const j=i*9,part=i-actor.start,limb=part===1||part===4?1:part===2||part===5?-1:0;matrix.makeScale(previous[j+3],previous[j+4],previous[j+5]);matrix.setPosition(previous[j]+motion.x,previous[j+1]+motion.y+limb*motion.swing,previous[j+2]);mesh.setMatrixAt(i,matrix)}
-     matrixStart=Math.min(matrixStart,actor.start);matrixEnd=Math.max(matrixEnd,actor.end)
+    catch (error) {
+        try {
+            close();
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], 'Graphics initialization and cleanup failed');
+        }
+        throw error;
     }
-    lastVisible=new Set(visibleActors)
-    if(pose.cameraMode==='third-person'){
-     matrix.makeScale(.48,.9,.42);matrix.setPosition(pose.x,pose.y-1.4,pose.z);mesh.setMatrixAt(baseCount,matrix);mesh.setColorAt(baseCount,color.setRGB(.96,.76,.28))
-     matrixStart=Math.min(matrixStart,baseCount);matrixEnd=Math.max(matrixEnd,baseCount+1);colorStart=Math.min(colorStart,baseCount);colorEnd=Math.max(colorEnd,baseCount+1)
-    }
-    for(const [attribute,start,end,size]of [[mesh.instanceMatrix,matrixStart,matrixEnd,16],[mesh.instanceColor,colorStart,colorEnd,3]])if(attribute){attribute.clearUpdateRanges();if(start!==Infinity){attribute.addUpdateRange(start*size,(end-start)*size);attribute.needsUpdate=true}}
-    viewCamera(pose,aspect,zoom,camera);renderer.render(scene,camera);pendingStart=Infinity;pendingEnd=0},
-   get count(){return mesh.count},get stats(){return {calls:renderer.info.render.calls,triangles:renderer.info.render.triangles,geometries:renderer.info.memory.geometries,textures:renderer.info.memory.textures}},close
-  }
- }catch(error){close();throw error}
 }
-const palette=[[.39,.68,.64],[.62,.49,.79],[.89,.61,.38],[.37,.59,.79],[.76,.43,.53]]
-export function worldGeometry(model,actors=[]){
- let offsetY=0
- const values=[],cube=(x,y,z,sx,sy,sz,color)=>values.push(x,y+offsetY,z,sx,sy,sz,...color)
- // A bounded, decorative thinking garden. Terrain does not assert knowledge or relationships.
- if(model.pattern==='constellation'){
-  // Fixed procedural background, no texture loading or permanent animation loop.
-  for(let i=0;i<96;i++)cube(Math.sin(i*2.399)*35,2+(i%13)*2.5,-15-(i%17)*3,.07,.07,.07,[.64,.74,.92])
- }else{
- cube(0,-.65,-150,60,1.2,370,[.55,.65,.55])
- cube(0,-.015,-150,2.3,.06,368,[.83,.82,.68])
- }
- const byId=new Map(model.items.map(item=>[item.id,item]))
- for(const edge of model.relations){
-  const from=byId.get(edge.from),to=byId.get(edge.to),color=edge.active?[.92,.61,.21]:[.24,.55,.62],fy=(from.y??0)+.2,ty=(to.y??0)+.2
-  // Orthogonal connectors use the same instanced mesh; only declared edges.
-  cube((from.x+to.x)/2,fy,from.z,Math.abs(to.x-from.x)+.06,.06,.06,color)
-  cube(to.x,(fy+ty)/2,from.z,.06,Math.abs(ty-fy)+.06,.06,color)
-  cube(to.x,ty,(from.z+to.z)/2,.06,.06,Math.abs(to.z-from.z)+.06,color)
- }
- for(const item of model.items){
-  const start=values.length/9
-  const hash=[...item.id].reduce((v,c)=>(Math.imul(v,31)+c.charCodeAt(0))|0,0),color=item.disabled?[.52,.54,.56]:palette[(hash>>>0)%palette.length],{x,z}=item
-  offsetY=item.y??0
-  if(item.form!=='book')cube(x,.07,z,2,.18,1.8,item.selected?[.98,.77,.34]:[.75,.80,.70])
-  const tints={accent:item.needsReview?[.9,.61,.16]:color,dark:[.25,.31,.4],face:[.89,.77,.63],light:[.94,.96,.96],warning:[.9,.61,.16]}
-  for(const [dx,y,dz,sx,sy,sz,tint]of objectTemplates[item.form])cube(x+dx,y,z+dz,sx,sy,sz,tints[tint])
-  if(item.kind==='character')actors.push({id:item.id,start,end:values.length/9})
- }
- if(values.length/9>=worldLimits.instances)throw Error('WorldGeometryLimitExceeded')
- return new Float32Array(values)
+const palette = [[.39, .68, .64], [.62, .49, .79], [.89, .61, .38], [.37, .59, .79], [.76, .43, .53]];
+export function worldGeometry(model, actors = []) {
+    let offsetY = 0;
+    const values = [], cube = (x, y, z, sx, sy, sz, color) => values.push(x, y + offsetY, z, sx, sy, sz, ...color);
+    // A bounded, decorative thinking garden. Terrain does not assert knowledge or relationships.
+    if (model.pattern === 'constellation') {
+        // Fixed procedural background, no texture loading or permanent animation loop.
+        for (let i = 0; i < 96; i++)
+            cube(Math.sin(i * 2.399) * 35, 2 + (i % 13) * 2.5, -15 - (i % 17) * 3, .07, .07, .07, [.64, .74, .92]);
+    }
+    else {
+        cube(0, -.65, -150, 60, 1.2, 370, [.55, .65, .55]);
+        cube(0, -.015, -150, 2.3, .06, 368, [.83, .82, .68]);
+    }
+    const byId = new Map(model.items.map(item => [item.id, item]));
+    for (const edge of model.relations) {
+        const from = byId.get(edge.from), to = byId.get(edge.to);
+        if (!from || !to)
+            throw Error('WorldIdentityInvalid');
+        const color = edge.active ? [.92, .61, .21] : [.24, .55, .62], fy = (from.y ?? 0) + .2, ty = (to.y ?? 0) + .2;
+        // Orthogonal connectors use the same instanced mesh; only declared edges.
+        cube((from.x + to.x) / 2, fy, from.z, Math.abs(to.x - from.x) + .06, .06, .06, color);
+        cube(to.x, (fy + ty) / 2, from.z, .06, Math.abs(ty - fy) + .06, .06, color);
+        cube(to.x, ty, (from.z + to.z) / 2, .06, .06, Math.abs(to.z - from.z) + .06, color);
+    }
+    for (const item of model.items) {
+        const start = values.length / 9;
+        const hash = [...item.id].reduce((v, c) => (Math.imul(v, 31) + c.charCodeAt(0)) | 0, 0);
+        const color = item.disabled ? [.52, .54, .56] : palette[(hash >>> 0) % palette.length];
+        const { x, z } = item;
+        offsetY = item.y ?? 0;
+        if (item.form !== 'book')
+            cube(x, .07, z, 2, .18, 1.8, item.selected ? [.98, .77, .34] : [.75, .80, .70]);
+        const tints = { accent: item.needsReview ? [.9, .61, .16] : color, dark: [.25, .31, .4], face: [.89, .77, .63], light: [.94, .96, .96], warning: [.9, .61, .16] };
+        for (const [dx, y, dz, sx, sy, sz, tint] of objectTemplates[item.form])
+            cube(x + dx, y, z + dz, sx, sy, sz, tints[tint]);
+        if (item.kind === 'character')
+            actors.push({ id: item.id, start, end: values.length / 9 });
+    }
+    if (values.length / 9 >= worldLimits.instances)
+        throw Error('WorldGeometryLimitExceeded');
+    return new Float32Array(values);
 }

package/src/world-input.d.mts

@@ -1,3 +1,3 @@
+export declare const keyDirection: (code: string) => string | undefined;
 /** @param {Document} document */
-export function worldControlGuide(document: Document): HTMLElement;
-export function keyDirection(code: any): any;
+export declare function worldControlGuide(document: Document): HTMLElement;

package/src/world-input.mjs

@@ -1,21 +1,31 @@
 // Presentation input only: shared movement bindings and on-demand control guide.
-const movement=[
- ['forward','W / ↑',['KeyW','ArrowUp']],['back','S / ↓',['KeyS','ArrowDown']],
- ['left','A / ←',['KeyA','ArrowLeft']],['right','D / →',['KeyD','ArrowRight']],
- ['rise','R / Page Up',['KeyR','PageUp']],['descend','F / Page Down',['KeyF','PageDown']]
-]
-const directions=new Map(movement.flatMap(([action,,codes])=>codes.map(code=>[code,action])))
-export const keyDirection=code=>directions.get(code)
+const movement = [
+    ['forward', 'W / ↑', ['KeyW', 'ArrowUp']], ['back', 'S / ↓', ['KeyS', 'ArrowDown']],
+    ['left', 'A / ←', ['KeyA', 'ArrowLeft']], ['right', 'D / →', ['KeyD', 'ArrowRight']],
+    ['rise', 'R / Page Up', ['KeyR', 'PageUp']], ['descend', 'F / Page Down', ['KeyF', 'PageDown']]
+];
+const directions = new Map(movement.flatMap(([action, , codes]) => codes.map(code => [code, action])));
+export const keyDirection = (code) => directions.get(code);
 /** @param {Document} document */
-export function worldControlGuide(document){
- const guide=document.createElement('section');guide.setAttribute('aria-label','World controls')
- const section=(title,rows)=>{const heading=document.createElement('h3'),list=document.createElement('dl');heading.textContent=title
-  for(const [input,action]of rows){const term=document.createElement('dt'),description=document.createElement('dd');term.textContent=input;description.textContent=action;list.append(term,description)}
-  guide.append(heading,list)
- }
- section('Overview', [['Drag','Pan across the world'],['Wheel / pinch','Zoom'],['Click / tap an object','Select a target and open its context'],['Map / M','Find a projected target by the same reference'],['View all','Fit the whole space']])
- const note=document.createElement('p');note.textContent='Choose Walk through world under In this space → Navigation, then close the panel and select the world to use movement keys.';guide.append(note)
- section('Walk through world',movement.map(([action,label])=>[label,action[0].toUpperCase()+action.slice(1)]).concat([['Drag','Look around'],['Wheel','Move forward / back'],['E','Inspect the aimed object'],['M','Open or close Map'],['Q','Mark the aimed or selected target'],['Escape','Pause movement or close the open panel']]))
- section('Keyboard navigation',[['Tab / Shift + Tab','Move between controls'],['Enter / Space','Activate the focused button']])
- return guide
+export function worldControlGuide(document) {
+    const guide = document.createElement('section');
+    guide.setAttribute('aria-label', 'World controls');
+    const section = (title, rows) => {
+        const heading = document.createElement('h3'), list = document.createElement('dl');
+        heading.textContent = title;
+        for (const [input, action] of rows) {
+            const term = document.createElement('dt'), description = document.createElement('dd');
+            term.textContent = input;
+            description.textContent = action;
+            list.append(term, description);
+        }
+        guide.append(heading, list);
+    };
+    section('Overview', [['Drag', 'Pan across the world'], ['Wheel / pinch', 'Zoom'], ['Click / tap an object', 'Select a target and open its context'], ['Map / M', 'Find a projected target by the same reference'], ['View all', 'Fit the whole space']]);
+    const note = document.createElement('p');
+    note.textContent = 'Choose Walk through world under In this space → Navigation, then close the panel and select the world to use movement keys.';
+    guide.append(note);
+    section('Walk through world', movement.map(([action, label]) => [label, action[0].toUpperCase() + action.slice(1)]).concat([['Drag', 'Look around'], ['Wheel', 'Move forward / back'], ['E', 'Inspect the aimed object'], ['M', 'Open or close Map'], ['Q', 'Mark the aimed or selected target'], ['Escape', 'Pause movement or close the open panel']]));
+    section('Keyboard navigation', [['Tab / Shift + Tab', 'Move between controls'], ['Enter / Space', 'Activate the focused button']]);
+    return guide;
 }

package/src/world-lifecycle.d.mts

@@ -0,0 +1,12 @@
+import type { Camera } from '@zixcel/projection-client';
+import type { WorldOptions, WorldSnapshot } from './world-api.mjs';
+import type { WorldContext } from './world-context.mjs';
+export declare function onKeyWorld(ctx: WorldContext, event: KeyboardEvent): void;
+export declare function snapshotWorld(ctx: WorldContext): WorldSnapshot;
+export declare function parkWorld(ctx: WorldContext): void;
+export declare function mountWorld(ctx: WorldContext, nextHost: HTMLElement, options: WorldOptions): void;
+export declare function closeWorld(ctx: WorldContext): void;
+export declare function activityWorld(ctx: WorldContext, value: unknown): void;
+export declare function applyWorld(ctx: WorldContext, value: Camera): void;
+export declare function changeWorld(ctx: WorldContext, action: string): void;
+export declare function pauseWorld(ctx: WorldContext, value: boolean): void;

package/src/world-lifecycle.mjs

@@ -0,0 +1,172 @@
+import { copyPose } from './world-api.mjs';
+import { disposeWorldResources } from './world-resources.mjs';
+import { initialPose, movePose, clamp } from './world-model.mjs';
+import { spatialPattern } from './spatial-patterns.mjs';
+import { keyDirection } from './world-input.mjs';
+export function onKeyWorld(ctx, event) {
+    if (event.target !== ctx.canvas || event.ctrlKey || event.metaKey || event.altKey || event.isComposing)
+        return;
+    if (event.type === 'keydown' && event.code === 'KeyM') {
+        event.preventDefault();
+        ctx.map.open = !ctx.map.open;
+        return;
+    }
+    if (event.type === 'keydown' && event.code === 'KeyQ') {
+        event.preventDefault();
+        const target = ctx.hovered ?? ctx.selectedId;
+        if (target) {
+            ctx.selectedId = target;
+            ctx.mapButton.click();
+        }
+        return;
+    }
+    if (ctx.navigation === 'overview') {
+        if (event.type === 'keydown' && event.code === 'KeyE')
+            ctx.activate(ctx.hovered);
+        return;
+    }
+    const key = keyDirection(event.code);
+    if (key) {
+        event.preventDefault();
+        if (event.type === 'keydown' && !ctx.inputBlocked())
+            ctx.keys.add(key);
+        else
+            ctx.keys.delete(key);
+        ctx.invalidate();
+    }
+    else if (event.type === 'keydown' && !event.repeat) {
+        if (event.code === 'KeyE') {
+            event.preventDefault();
+            ctx.activate(ctx.hovered);
+        }
+        if (event.code === 'Escape') {
+            ctx.stopInput();
+            ctx.canvas.blur();
+        }
+    }
+}
+export function snapshotWorld(ctx) { return { ...copyPose(ctx.pose), target: ctx.target, presentation: { ...ctx.view }, navigation: ctx.navigation, populated: ctx.fittedPopulation }; }
+export function parkWorld(ctx) { ctx.attached = false; ctx.paused = true; ctx.stopInput(); ctx.stopFrame(); ctx.orbit.enabled = false; ctx.resize.disconnect(); ctx.wrap.remove(); }
+export function mountWorld(ctx, nextHost, options) {
+    if (ctx.closed)
+        throw Error('WorldDisposed');
+    const nextTarget = options.target ?? null;
+    spatialPattern(options.objects ?? [], options.relations ?? [], ctx.target !== nextTarget ? (ctx.poses.get(nextTarget)?.presentation ?? { pattern: options.pattern ?? 'ground' }) : ctx.view);
+    const changedTarget = ctx.target !== (options.target ?? null);
+    const changedContext = ctx.context !== (options.context ?? null);
+    ctx.context = options.context ?? null;
+    if (changedTarget) {
+        ctx.poses.set(ctx.target, ctx.snapshot());
+        while (ctx.poses.size > 8)
+            ctx.poses.delete(ctx.poses.keys().next().value);
+    }
+    ctx.host = nextHost;
+    ctx.attached = true;
+    ctx.host.prepend(ctx.wrap);
+    ctx.resize.disconnect();
+    ctx.resize.observe(ctx.host);
+    ctx.onActivate = options.onActivate ?? (() => { });
+    ctx.conversation = options.conversation ?? null;
+    ctx.workActivity = options.activity ?? null;
+    ctx.target = options.target ?? null;
+    ctx.wrap.dataset.target = ctx.target ?? '';
+    ctx.paused = false;
+    ctx.engine.panel.hidden = options.pattern === 'garden';
+    if (ctx.conversationId)
+        ctx.closeConversation();
+    if (changedTarget) {
+        const saved = ctx.poses.get(ctx.target);
+        ctx.view = saved?.presentation ?? { pattern: options.pattern ?? 'ground', groupBy: 'declared', group: null, page: 0 };
+        ctx.navigation = saved?.navigation ?? 'overview';
+        ctx.pose = saved ? copyPose(saved) : initialPose();
+        ctx.fittedPopulation = Boolean(saved?.populated);
+        ctx.needsFit = !saved;
+        ctx.sourceObjects = [];
+        ctx.recent.clear();
+        ctx.query.value = '';
+        ctx.updates.open = false;
+        ctx.nearby.open = false;
+        ctx.map.open = false;
+        ctx.selectedId = null;
+        ctx.markedId = null;
+        ctx.wrap.dataset.selectedId = '';
+        ctx.wrap.dataset.markedId = '';
+        ctx.model = { items: [], relations: [] };
+    }
+    else if (changedContext) {
+        ctx.view = { ...ctx.view, group: null, page: 0 };
+        ctx.sourceObjects = [];
+        ctx.recent.clear();
+        ctx.query.value = '';
+        ctx.updates.open = false;
+    }
+    ctx.navigationSelect.value = ctx.navigation;
+    ctx.walk.hidden = ctx.navigation !== 'explore';
+    ctx.update(options.objects ?? [], options.relations);
+    ctx.syncOrbit();
+    ctx.invalidate();
+}
+export function closeWorld(ctx) {
+    if (ctx.closed)
+        return;
+    ctx.closed = true;
+    ctx.attached = false;
+    const previousGpu = ctx.gpu;
+    ctx.gpu = null;
+    ctx.geometry = null;
+    ctx.objects = [];
+    ctx.relations = [];
+    ctx.sourceObjects = [];
+    ctx.sourceRelations = [];
+    ctx.actorRanges = [];
+    ctx.projected = [];
+    ctx.projection = null;
+    ctx.model = { items: [], relations: [] };
+    ctx.restored = null;
+    try {
+        disposeWorldResources(ctx, previousGpu);
+    }
+    finally {
+        ctx.workActivity = null;
+        ctx.conversation = null;
+        ctx.onActivate = () => { };
+        ctx.activityPresentation = {};
+    }
+}
+export function activityWorld(ctx, value) { if (ctx.closed)
+    throw Error('WorldDisposed'); ctx.workActivity = value ?? null; ctx.update(ctx.sourceObjects, ctx.sourceRelations); }
+export function applyWorld(ctx, value) { const next = clamp(value.z, .65, 1.5); if (next !== ctx.zoom) {
+    ctx.zoom = next;
+    ctx.syncOrbit();
+    ctx.invalidate();
+} }
+export function changeWorld(ctx, action) {
+    ctx.fitViewport();
+    if (action === 'reset') {
+        ctx.overview();
+        return;
+    }
+    if (ctx.navigation === 'overview') {
+        ctx.syncOrbit();
+        if (action === 'in')
+            ctx.orbit.dollyIn(1 / 1.2);
+        else if (action === 'out')
+            ctx.orbit.dollyOut(1 / 1.2);
+        else
+            ctx.orbit.pan(action === 'left' ? 40 : action === 'right' ? -40 : 0, action === 'up' ? 40 : action === 'down' ? -40 : 0);
+        ctx.orbit.update();
+        return;
+    }
+    else if (['in', 'out', 'up', 'down', 'left', 'right'].includes(action)) {
+        const forward = ['in', 'up'].includes(action) ? 1 : ['out', 'down'].includes(action) ? -1 : 0, side = action === 'left' ? -1 : action === 'right' ? 1 : 0;
+        for (let i = 0; i < 5; i++)
+            ctx.pose = movePose(ctx.pose, forward, side, .05);
+    }
+    ctx.invalidate();
+}
+export function pauseWorld(ctx, value) { ctx.paused = value; if (value) {
+    ctx.stopInput();
+    ctx.stopFrame();
+}
+else
+    ctx.invalidate(); }