@zixcel/dom-renderer 0.10.4 → 0.10.5

package/src/world-model.d.mts

@@ -1,49 +1,38 @@
-export function layoutWorld(objects: any, relations?: any[], pattern?: string, spacing?: string): {
-    pattern?: string;
-    items: any[];
-    relations: any[];
-};
-export function initialPose(): {
+import type { Pose, WorldObject, WorldRelation, WorldModel } from './world-types.mjs';
+import { PerspectiveCamera } from 'three';
+export declare const worldLimits: Readonly<{
+    objects: 512;
+    relations: 512;
+    pixels: 1440000;
+    dpr: 1.5;
+    fps: 30;
+    instances: 8192;
+    radius: 28;
+}>;
+export declare const clamp: (value: number, min: number, max: number) => number;
+export declare function layoutWorld<T extends WorldObject>(objects: readonly T[], relations?: readonly WorldRelation[], pattern?: string, spacing?: string): WorldModel<T>;
+export declare function initialPose(): Pose;
+export declare function fitPose(items: readonly {
     x: number;
-    y: number;
+    y?: number;
     z: number;
-    yaw: number;
-    pitch: number;
-};
-export function fitPose(items: any, aspect?: number): {
-    x: any;
-    y: any;
-    z: any;
-    yaw: number;
-    pitch: number;
-    focus: {
-        x: any;
-        y: any;
-        z: any;
-    };
-};
-export function movePose(pose: any, forward: any, side: any, seconds: any, vertical?: number): any;
-export function lookPose(pose: any, dx: any, dy: any): any;
-export function viewCamera(pose: any, aspect: any, zoom?: number, camera?: any): any;
-export function cameraMatrix(pose: any, aspect: any, zoom?: number): any;
-export function screenPoint(matrix: any, x: any, y: any, z: any, width: any, height: any): {
+}[], aspect?: number): Pose;
+export declare function movePose(pose: Pose, forward: number, side: number, seconds: number, vertical?: number): Pose;
+export declare function lookPose(pose: Pose, dx: number, dy: number): Pose;
+export declare function viewCamera(pose: Pose, aspect: number, zoom?: number, camera?: PerspectiveCamera): PerspectiveCamera;
+export declare function cameraMatrix(pose: Pose, aspect: number, zoom?: number): import("three").Matrix4Tuple;
+export declare function screenPoint(matrix: readonly number[], x: number, y: number, z: number, width: number, height: number): {
     x: number;
     y: number;
     depth: number;
     visible: boolean;
-};
-export function renderSize(width: any, height: any, dpr: any): {
+} | null;
+export declare function renderSize(width: number, height: number, dpr: number): {
     width: number;
     height: number;
 };
-export function pickWorld(items: any, pose: any, x: any, y: any, width: any, height: any, zoom?: number): any;
-export const worldLimits: Readonly<{
-    objects: 512;
-    relations: 512;
-    pixels: 1440000;
-    dpr: 1.5;
-    fps: 30;
-    instances: 8192;
-    radius: 28;
-}>;
-export function clamp(value: any, min: any, max: any): number;
+export declare function pickWorld(items: readonly (WorldObject & {
+    x: number;
+    y?: number;
+    z: number;
+})[], pose: Pose, x: number, y: number, width: number, height: number, zoom?: number): string | null;

package/src/world-model.mjs

@@ -1,83 +1,112 @@
-import {PerspectiveCamera,Vector3,Raycaster,Vector2,Box3} from 'three'
-import {objectPresentation,spacingPresets,libraryLayout,objectBounds} from './object-presentation.mjs'
+import { PerspectiveCamera, Vector3, Raycaster, Vector2, Box3 } from 'three';
+import { objectPresentation, spacingPresets, libraryLayout, objectBounds } from './object-presentation.mjs';
 // Presentation geometry only. IDs and declared relations are never inferred from position.
-export const worldLimits=Object.freeze({objects:512,relations:512,pixels:1440000,dpr:1.5,fps:30,instances:8192,radius:28})
-export const clamp=(value,min,max)=>Math.max(min,Math.min(max,value))
-export function layoutWorld(objects,relations=[],pattern='ground',spacing='balanced'){
- const distances=spacingPresets[spacing];if(!distances)throw Error('SpatialSpacingInvalid')
- if(!['ground','constellation','garden'].includes(pattern))throw Error('SpatialPatternInvalid')
- if(!Array.isArray(objects)||objects.length>worldLimits.objects||!Array.isArray(relations)||relations.length>worldLimits.relations)throw Error('WorldCapacityExceeded')
- const ids=new Set()
- const items=objects.map((object,index)=>{
-  object={...object,...objectPresentation(object)}
-  if(typeof object.id!=='string'||!object.id||ids.has(object.id))throw Error('WorldIdentityInvalid')
-  ids.add(object.id)
-  if(pattern==='garden'){
-   const actors=objects.filter(o=>o.kind==='character'),actor=object.kind==='character'?actors.findIndex(o=>o.id===object.id):actors.findIndex(o=>o.id===object.anchor)
-   const base={x:actor<0?0:(actor%7-3)*distances.person,z:actor<0?-8:-Math.floor(actor/7)*distances.person*2},plot=object.plot??0
-   if(object.kind==='character')return {...object,...base,y:0}
-   const x=base.x+distances.group+(plot%4)*distances.group,z=base.z-distances.group-Math.floor(plot/4)*distances.group
-   if(object.kind==='group')return {...object,x,y:0,z}
-   const slot=object.member??0,l=libraryLayout
-   return {...object,x:x+(slot%l.columns-(l.columns-1)/2)*l.slotWidth,y:l.baseY+Math.floor(slot/l.columns)*l.rowHeight,z:z+l.frontZ}
-  }
-  if(pattern==='constellation'){
-   const actors=objects.filter(i=>i.kind==='character'),isActor=object.kind==='character',order=isActor?actors.findIndex(o=>o.id===object.id):objects.slice(0,index).filter(i=>i.kind!=='character').length
-   const count=objects.length-actors.length,ring=Math.floor(order/8),angle=(order%8)/Math.min(8,count-ring*8)*Math.PI*2
-   return {...object,x:isActor?(order-(actors.length-1)/2)*3.4:Math.sin(angle)*(5+ring*4),y:isActor?0:2+ring*3+(order%3)*1.2,z:isActor?-1:-8+Math.cos(angle)*(3+ring*2)}
-  }
-  const row=Math.floor(index/7),count=Math.min(7,objects.length-row*7),column=index%7
-  return {...object,x:(column-(count-1)/2)*3.4,z:-row*4.5-1-Math.cos(column)*.4,y:0}
- })
- return {items,relations:relations.filter(edge=>ids.has(edge.from)&&ids.has(edge.to)),...(pattern!=='ground'?{pattern}:{})}
+export const worldLimits = Object.freeze({ objects: 512, relations: 512, pixels: 1440000, dpr: 1.5, fps: 30, instances: 8192, radius: 28 });
+export const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+export function layoutWorld(objects, relations = [], pattern = 'ground', spacing = 'balanced') {
+    if (!Object.hasOwn(spacingPresets, spacing))
+        throw Error('SpatialSpacingInvalid');
+    const distances = spacingPresets[spacing];
+    if (!['ground', 'constellation', 'garden'].includes(pattern))
+        throw Error('SpatialPatternInvalid');
+    if (!Array.isArray(objects) || objects.length > worldLimits.objects || !Array.isArray(relations) || relations.length > worldLimits.relations)
+        throw Error('WorldCapacityExceeded');
+    const ids = new Set();
+    const items = objects.map((object, index) => {
+        const presentation = objectPresentation(object);
+        object = { ...object, ...presentation };
+        if (typeof object.id !== 'string' || !object.id || ids.has(object.id))
+            throw Error('WorldIdentityInvalid');
+        ids.add(object.id);
+        if (pattern === 'garden') {
+            const actors = objects.filter(o => o.kind === 'character'), actor = object.kind === 'character' ? actors.findIndex(o => o.id === object.id) : actors.findIndex(o => o.id === object.anchor);
+            const base = { x: actor < 0 ? 0 : (actor % 7 - 3) * distances.person, z: actor < 0 ? -8 : -Math.floor(actor / 7) * distances.person * 2 }, plot = object.plot ?? 0;
+            if (object.kind === 'character')
+                return { ...object, ...presentation, ...base, y: 0 };
+            const x = base.x + distances.group + (plot % 4) * distances.group, z = base.z - distances.group - Math.floor(plot / 4) * distances.group;
+            if (object.kind === 'group')
+                return { ...object, ...presentation, x, y: 0, z };
+            const slot = object.member ?? 0, l = libraryLayout;
+            return { ...object, ...presentation, x: x + (slot % l.columns - (l.columns - 1) / 2) * l.slotWidth, y: l.baseY + Math.floor(slot / l.columns) * l.rowHeight, z: z + l.frontZ };
+        }
+        if (pattern === 'constellation') {
+            const actors = objects.filter(i => i.kind === 'character'), isActor = object.kind === 'character', order = isActor ? actors.findIndex(o => o.id === object.id) : objects.slice(0, index).filter(i => i.kind !== 'character').length;
+            const count = objects.length - actors.length, ring = Math.floor(order / 8), angle = (order % 8) / Math.min(8, count - ring * 8) * Math.PI * 2;
+            return { ...object, ...presentation, x: isActor ? (order - (actors.length - 1) / 2) * 3.4 : Math.sin(angle) * (5 + ring * 4), y: isActor ? 0 : 2 + ring * 3 + (order % 3) * 1.2, z: isActor ? -1 : -8 + Math.cos(angle) * (3 + ring * 2) };
+        }
+        const row = Math.floor(index / 7), count = Math.min(7, objects.length - row * 7), column = index % 7;
+        return { ...object, ...presentation, x: (column - (count - 1) / 2) * 3.4, z: -row * 4.5 - 1 - Math.cos(column) * .4, y: 0 };
+    });
+    return { items, relations: relations.filter(edge => ids.has(edge.from) && ids.has(edge.to)), ...(pattern !== 'ground' ? { pattern } : {}) };
 }
-export function initialPose(){return {x:0,y:1.85,z:9,yaw:0,pitch:-.035}}
-export function fitPose(items,aspect=1){
- if(!items.length)return {...initialPose(),y:8,z:14,pitch:-.6,focus:{x:0,y:0,z:0}}
- const box=new Box3()
- for(const item of items){box.expandByPoint(new Vector3(item.x-1,item.y??0,item.z-1));box.expandByPoint(new Vector3(item.x+1,(item.y??0)+3,item.z+1))}
- const center=box.getCenter(new Vector3()),radius=box.getSize(new Vector3()).length()/2
- const angle=Math.min(70*Math.PI/360,Math.atan(Math.tan(70*Math.PI/360)*Math.max(.1,aspect)))
- const distance=Math.max(8,radius/Math.sin(angle)*1.45)
- return {x:center.x,y:center.y+distance*.6,z:center.z+distance*.8,yaw:0,pitch:-Math.asin(.6),focus:{x:center.x,y:center.y,z:center.z}}
+export function initialPose() { return { x: 0, y: 1.85, z: 9, yaw: 0, pitch: -.035 }; }
+export function fitPose(items, aspect = 1) {
+    if (!items.length)
+        return { ...initialPose(), y: 8, z: 14, pitch: -.6, focus: { x: 0, y: 0, z: 0 } };
+    const box = new Box3();
+    for (const item of items) {
+        box.expandByPoint(new Vector3(item.x - 1, item.y ?? 0, item.z - 1));
+        box.expandByPoint(new Vector3(item.x + 1, (item.y ?? 0) + 3, item.z + 1));
+    }
+    const center = box.getCenter(new Vector3()), radius = box.getSize(new Vector3()).length() / 2;
+    const angle = Math.min(70 * Math.PI / 360, Math.atan(Math.tan(70 * Math.PI / 360) * Math.max(.1, aspect)));
+    const distance = Math.max(8, radius / Math.sin(angle) * 1.45);
+    return { x: center.x, y: center.y + distance * .6, z: center.z + distance * .8, yaw: 0, pitch: -Math.asin(.6), focus: { x: center.x, y: center.y, z: center.z } };
 }
-export function movePose(pose,forward,side,seconds,vertical=0){
- const length=Math.max(1,Math.hypot(forward,side,vertical)),speed=4.5*Math.min(.05,Math.max(0,seconds))/length
- return {...pose,x:clamp(pose.x+(Math.cos(pose.yaw)*side+Math.sin(pose.yaw)*forward)*speed,-worldLimits.radius,worldLimits.radius),y:clamp(pose.y+vertical*speed,.4,18),z:clamp(pose.z+(Math.sin(pose.yaw)*side-Math.cos(pose.yaw)*forward)*speed,-350,worldLimits.radius)}
+export function movePose(pose, forward, side, seconds, vertical = 0) {
+    const length = Math.max(1, Math.hypot(forward, side, vertical)), speed = 4.5 * Math.min(.05, Math.max(0, seconds)) / length;
+    return { ...pose, x: clamp(pose.x + (Math.cos(pose.yaw) * side + Math.sin(pose.yaw) * forward) * speed, -worldLimits.radius, worldLimits.radius), y: clamp(pose.y + vertical * speed, .4, 18), z: clamp(pose.z + (Math.sin(pose.yaw) * side - Math.cos(pose.yaw) * forward) * speed, -350, worldLimits.radius) };
 }
-export function lookPose(pose,dx,dy){return {...pose,yaw:(pose.yaw+clamp(dx,-150,150)*.004)%(Math.PI*2),pitch:clamp(pose.pitch-clamp(dy,-150,150)*.004,-.9,.9)}}
-export function viewCamera(pose,aspect,zoom=1,camera=new PerspectiveCamera(70,aspect,.08,120)){
- camera.aspect=aspect;camera.far=2000;camera.zoom=clamp(zoom,.65,1.5)
- if(pose.cameraMode==='third-person')camera.position.set(pose.x-Math.sin(pose.yaw)*3,pose.y+1.2,pose.z+Math.cos(pose.yaw)*3)
- else camera.position.set(pose.x,pose.y,pose.z)
- camera.rotation.set(pose.pitch-(pose.cameraMode==='third-person'?.17:0),-pose.yaw,0,'YXZ');camera.updateProjectionMatrix();camera.updateMatrixWorld()
- return camera
+export function lookPose(pose, dx, dy) { return { ...pose, yaw: (pose.yaw + clamp(dx, -150, 150) * .004) % (Math.PI * 2), pitch: clamp(pose.pitch - clamp(dy, -150, 150) * .004, -.9, .9) }; }
+export function viewCamera(pose, aspect, zoom = 1, camera = new PerspectiveCamera(70, aspect, .08, 120)) {
+    camera.aspect = aspect;
+    camera.far = 2000;
+    camera.zoom = clamp(zoom, .65, 1.5);
+    if (pose.cameraMode === 'third-person')
+        camera.position.set(pose.x - Math.sin(pose.yaw) * 3, pose.y + 1.2, pose.z + Math.cos(pose.yaw) * 3);
+    else
+        camera.position.set(pose.x, pose.y, pose.z);
+    camera.rotation.set(pose.pitch - (pose.cameraMode === 'third-person' ? .17 : 0), -pose.yaw, 0, 'YXZ');
+    camera.updateProjectionMatrix();
+    camera.updateMatrixWorld();
+    return camera;
 }
-export function cameraMatrix(pose,aspect,zoom=1){
- const camera=viewCamera(pose,aspect,zoom)
- return camera.projectionMatrix.clone().multiply(camera.matrixWorldInverse).elements
+export function cameraMatrix(pose, aspect, zoom = 1) {
+    const camera = viewCamera(pose, aspect, zoom);
+    return camera.projectionMatrix.clone().multiply(camera.matrixWorldInverse).elements;
 }
-export function screenPoint(matrix,x,y,z,width,height){
- const v=[x,y,z,1],q=[0,0,0,0]
- for(let r=0;r<4;r++)for(let c=0;c<4;c++)q[r]+=matrix[c*4+r]*v[c]
- if(q[3]<=.08)return null
- const nx=q[0]/q[3],ny=q[1]/q[3]
- return {x:(nx*.5+.5)*width,y:(.5-ny*.5)*height,depth:q[3],visible:Math.abs(nx)<.95&&Math.abs(ny)<.88}
+export function screenPoint(matrix, x, y, z, width, height) {
+    const v = [x, y, z, 1], q = [0, 0, 0, 0];
+    for (let r = 0; r < 4; r++)
+        for (let c = 0; c < 4; c++)
+            q[r] += matrix[c * 4 + r] * v[c];
+    if (q[3] <= .08)
+        return null;
+    const nx = q[0] / q[3], ny = q[1] / q[3];
+    return { x: (nx * .5 + .5) * width, y: (.5 - ny * .5) * height, depth: q[3], visible: Math.abs(nx) < .95 && Math.abs(ny) < .88 };
 }
-export function renderSize(width,height,dpr){
- const scale=Math.min(worldLimits.dpr,Math.max(1,dpr),Math.sqrt(worldLimits.pixels/Math.max(1,width*height)))
- return {width:Math.max(1,Math.floor(width*scale)),height:Math.max(1,Math.floor(height*scale))}
+export function renderSize(width, height, dpr) {
+    const scale = Math.min(worldLimits.dpr, Math.max(1, dpr), Math.sqrt(worldLimits.pixels / Math.max(1, width * height)));
+    return { width: Math.max(1, Math.floor(width * scale)), height: Math.max(1, Math.floor(height * scale)) };
 }
-export function pickWorld(items,pose,x,y,width,height,zoom=1){
- const ray=new Raycaster(),camera=viewCamera(pose,width/height,zoom),point=new Vector3(),box=new Box3()
- ray.setFromCamera(new Vector2(2*x/width-1,1-2*y/height),camera)
- let best=null,distance=2000
- for(const item of items){
-  if(item.disabled)continue
-  const y=item.y??0
-  const [width,height,depth]=objectBounds[item.form??objectPresentation(item).form]
-  box.min.set(item.x-width/2,y,item.z-depth/2);box.max.set(item.x+width/2,y+height,item.z+depth/2)
-  if(ray.ray.intersectBox(box,point)){const near=point.distanceTo(camera.position);if(near<distance){best=item.id;distance=near}}
- }
- return best
+export function pickWorld(items, pose, x, y, width, height, zoom = 1) {
+    const ray = new Raycaster(), camera = viewCamera(pose, width / height, zoom), point = new Vector3(), box = new Box3();
+    ray.setFromCamera(new Vector2(2 * x / width - 1, 1 - 2 * y / height), camera);
+    let best = null, distance = 2000;
+    for (const item of items) {
+        if (item.disabled)
+            continue;
+        const y = item.y ?? 0;
+        const [width, height, depth] = objectBounds[item.form ?? objectPresentation(item).form];
+        box.min.set(item.x - width / 2, y, item.z - depth / 2);
+        box.max.set(item.x + width / 2, y + height, item.z + depth / 2);
+        if (ray.ray.intersectBox(box, point)) {
+            const near = point.distanceTo(camera.position);
+            if (near < distance) {
+                best = item.id;
+                distance = near;
+            }
+        }
+    }
+    return best;
 }

package/src/world-projection.d.mts

@@ -0,0 +1,5 @@
+import type { WorldObject, WorldRelation } from './world-types.mjs';
+import type { WorldContext } from './world-context.mjs';
+export declare function filterDirectoryWorld(ctx: WorldContext): void;
+export declare function renderUpdatesWorld(ctx: WorldContext): void;
+export declare function updateWorld(ctx: WorldContext, objects: WorldObject[], relations?: WorldRelation[]): void;

package/src/world-projection.mjs

@@ -0,0 +1,169 @@
+import { layoutWorld } from './world-model.mjs';
+import { worldGeometry } from './world-gpu.mjs';
+import { spatialPattern } from './spatial-patterns.mjs';
+import { objectForms } from './object-presentation.mjs';
+export function filterDirectoryWorld(ctx) { let count = 0; const term = ctx.query.value.trim().toLocaleLowerCase(); for (const row of ctx.directoryNodes.values()) {
+    row.hidden = !(row.textContent ?? '').toLocaleLowerCase().includes(term);
+    if (!row.hidden)
+        count++;
+} ctx.noMatches.hidden = !term || count > 0; }
+export function renderUpdatesWorld(ctx) {
+    const latest = [...ctx.recent.values()].at(-1);
+    ctx.updatesTitle.textContent = latest ? 'Observed changes · ' + ctx.recent.size + ' · ' + latest.title + ' · ' + latest.kind : 'No changes observed in this view';
+    ctx.updateList.replaceChildren();
+    for (const [id, change] of [...ctx.recent].reverse()) {
+        const button = ctx.make('button', '', change.title + ' · ' + change.kind);
+        button.type = 'button';
+        button.dataset.changeId = id;
+        button.disabled = !ctx.sourceObjects.some(item => item.id === id);
+        ctx.updateList.append(button);
+    }
+    for (const [id, node] of ctx.labelNodes)
+        node.dataset.updated = String(ctx.recent.has(id));
+}
+export function updateWorld(ctx, objects, relations = []) {
+    if (ctx.closed)
+        throw Error('WorldDisposed');
+    ctx.engine.update(ctx.workActivity);
+    const nextProjection = spatialPattern(objects, relations, ctx.view), next = layoutWorld(nextProjection.objects, nextProjection.relations, nextProjection.state.pattern, ctx.spacing);
+    // Keep remembered positions for unchanged membership, even if producer ordering changes.
+    if (ctx.placedSpacing === ctx.spacing && (ctx.model.pattern ?? 'ground') === (next.pattern ?? 'ground') && ctx.model.items.length === next.items.length && ctx.model.items.every(item => next.items.some(n => n.id === item.id && n.anchor === item.anchor && n.plot === item.plot && n.member === item.member))) {
+        const previous = new Map(ctx.model.items.map(item => [item.id, item]));
+        for (const item of next.items) {
+            const before = previous.get(item.id);
+            item.x = before.x;
+            item.y = before.y;
+            item.z = before.z;
+        }
+    }
+    ctx.placedSpacing = ctx.spacing;
+    const key = JSON.stringify([next.pattern, next.items.map(i => [i.id, i.kind, i.form, i.needsReview, i.x, i.y, i.z, i.selected, i.disabled, i.memberIds?.length]), next.relations.map(r => [r.from, r.to, r.active])]);
+    const changedGeometry = key !== ctx.geometryKey, nextActors = changedGeometry ? [] : ctx.actorRanges, nextGeometry = changedGeometry ? worldGeometry(next, nextActors) : ctx.geometry;
+    const before = new Map(ctx.sourceObjects.map(item => [item.id, item]));
+    let changed = false;
+    if (before.size) {
+        for (const item of objects) {
+            const previous = before.get(item.id);
+            const kind = !previous ? 'Added to this view' : previous.disabled !== item.disabled ? 'Availability changed' : previous.title !== item.title || previous.summary !== item.summary || previous.changeKey !== item.changeKey ? 'Content changed' : null;
+            if (kind) {
+                ctx.recent.delete(item.id);
+                ctx.recent.set(item.id, { title: item.title ?? item.id, kind });
+                changed = true;
+            }
+        }
+        const ids = new Set(objects.map(item => item.id));
+        for (const item of before.values())
+            if (!ids.has(item.id)) {
+                ctx.recent.delete(item.id);
+                ctx.recent.set(item.id, { title: item.title ?? item.id, kind: 'No longer in this view' });
+                changed = true;
+            }
+        while (ctx.recent.size > 5)
+            ctx.recent.delete(ctx.recent.keys().next().value);
+    }
+    ctx.sourceObjects = objects.map(item => ({ ...item }));
+    ctx.sourceRelations = relations;
+    ctx.projection = nextProjection;
+    ctx.view = ctx.projection.state;
+    if (ctx.conversationId && (changed || !objects.some(i => i.id === ctx.conversationId)))
+        ctx.closeConversation();
+    ctx.model = next;
+    ctx.geometry = nextGeometry;
+    ctx.actorRanges = nextActors;
+    ctx.geometryKey = key;
+    if (!ctx.fittedPopulation && ctx.model.items.length) {
+        ctx.fittedPopulation = true;
+        if (ctx.navigation === 'overview')
+            ctx.needsFit = true;
+    }
+    const ids = new Set(ctx.model.items.map(item => item.id));
+    for (const [id, node] of ctx.labelNodes)
+        if (!ids.has(id)) {
+            node.remove();
+            ctx.labelNodes.delete(id);
+            ctx.directoryNodes.get(id)?.remove();
+            ctx.directoryNodes.delete(id);
+        }
+    ctx.patternSelect.value = ctx.view.pattern;
+    ctx.groupSelect.value = ctx.view.groupBy;
+    ctx.groupSelect.parentElement.hidden = ctx.view.pattern === 'ground' || ctx.view.pattern === 'garden';
+    ctx.patternSelect.parentElement.hidden = ctx.pattern === 'garden';
+    ctx.breadcrumb.hidden = ctx.view.pattern === 'ground' || ctx.view.pattern === 'garden';
+    ctx.back.hidden = !ctx.view.group;
+    ctx.location.textContent = ctx.projection.label + ' · ' + ctx.projection.total + ' objects';
+    ctx.pagination.hidden = ctx.projection.pages === 1;
+    ctx.previous.disabled = ctx.view.page === 0;
+    ctx.nextPage.disabled = ctx.view.page === ctx.projection.pages - 1;
+    ctx.pageCount.textContent = (ctx.view.page + 1) + ' / ' + ctx.projection.pages;
+    ctx.wrap.dataset.pattern = ctx.view.pattern;
+    ctx.wrap.dataset.groupBy = ctx.view.groupBy;
+    ctx.wrap.dataset.group = ctx.view.group ?? '';
+    ctx.wrap.dataset.sourceObjects = String(objects.length);
+    for (const [index, item] of ctx.model.items.entries()) {
+        let b = ctx.labelNodes.get(item.id), row = ctx.directoryNodes.get(item.id);
+        if (!b) {
+            b = ctx.make('button', 'world-name');
+            b.type = 'button';
+            b.dataset.worldId = item.id;
+            b.append(ctx.make('strong', ''), ctx.make('span', ''));
+            ctx.labelNodes.set(item.id, b);
+            row = ctx.make('div', '');
+            row.dataset.directoryId = item.id;
+            const focus = ctx.make('button', ''), open = ctx.make('button', '');
+            focus.type = open.type = 'button';
+            focus.dataset.focus = 'true';
+            row.append(focus, open);
+            ctx.directoryNodes.set(item.id, row);
+        }
+        if (!row)
+            throw Error('WorldDirectoryUnavailable');
+        const review = item.kind === 'character' ? ctx.roleStatus(ctx.workActivity, item.id) : null, state = review?.state ?? null;
+        const detail = item.disabled ? 'Unavailable' : review ? review.label : objectForms[item.form] + ' · ' + (item.summary || 'Inspect information');
+        ctx.setText(b.children[0], item.title);
+        ctx.setText(b.children[1], detail);
+        b.dataset.worldKind = item.kind ?? 'record';
+        b.disabled = Boolean(item.disabled);
+        b.setAttribute('aria-label', item.title + '. ' + detail);
+        b.dataset.position = JSON.stringify([item.x, item.y, item.z]);
+        b.dataset.objectForm = item.form;
+        b.dataset.activity = state ?? '';
+        b.dataset.supportRef = item.supportRef ?? '';
+        b.dataset.selected = String(item.id === ctx.selectedId);
+        b.dataset.marked = String(item.id === ctx.markedId);
+        if (ctx.labels.children[index] !== b)
+            ctx.labels.insertBefore(b, ctx.labels.children[index] ?? null);
+        const [focus, open] = row.querySelectorAll('button');
+        ctx.setText(focus, item.title);
+        focus.setAttribute('aria-label', 'Find ' + item.title);
+        open.disabled = Boolean(item.disabled);
+        const action = item.kind === 'group' ? 'Browse shelf' : ctx.view.pattern === 'garden' && item.kind === 'character' ? 'Talk to' : 'Inspect';
+        ctx.setText(open, action);
+        open.setAttribute('aria-label', action + ' ' + item.title);
+        if (item.kind === 'group')
+            row.dataset.members = JSON.stringify(item.memberIds);
+        else
+            delete row.dataset.members;
+        if (ctx.list.children[index] !== row)
+            ctx.list.insertBefore(row, ctx.list.children[index] ?? null);
+    }
+    ctx.summary.textContent = (ctx.view.pattern === 'garden' ? 'People' : 'In this space') + ' · ' + ctx.model.items.length;
+    ctx.renderMap();
+    ctx.filterDirectory();
+    ctx.renderUpdates();
+    if (ctx.needsFit) {
+        ctx.overview();
+        ctx.needsFit = false;
+    }
+    try {
+        ctx.gpu?.pattern(ctx.view.pattern);
+        if (changedGeometry && ctx.gpu && ctx.geometry) {
+            ctx.gpu.upload(ctx.geometry, ctx.actorRanges);
+            ctx.uploads++;
+        }
+        ctx.gpu?.motionStates(new Map(ctx.model.items.filter(i => i.kind === 'character').map(i => [i.id, ctx.roleStatus(ctx.workActivity, i.id)?.state ?? 'Idle'])));
+        ctx.invalidate();
+    }
+    catch (error) {
+        ctx.fail(error);
+    }
+}

package/src/world-render-loop.d.mts

@@ -0,0 +1,9 @@
+import { tickFrame } from './world-clock.mjs';
+import type { WorldContext } from './world-context.mjs';
+export declare function stopInputWorld(ctx: WorldContext): void;
+export declare function stopFrameWorld(ctx: WorldContext): void;
+export declare function invalidateWorld(ctx: WorldContext): void;
+export declare const tickWorld: typeof tickFrame;
+export declare function drawWorld(ctx: WorldContext): void;
+export declare function failWorld(ctx: WorldContext, error: unknown): void;
+export declare function initializeWorld(ctx: WorldContext): void;

package/src/world-render-loop.mjs

@@ -0,0 +1,110 @@
+import { tickFrame } from './world-clock.mjs';
+import { record } from './world-api.mjs';
+import { cameraMatrix, screenPoint, renderSize, clamp, pickWorld } from './world-model.mjs';
+import { createGpu } from './world-gpu.mjs';
+import { objectBounds } from './object-presentation.mjs';
+export function stopInputWorld(ctx) { ctx.keys?.clear(); ctx.drag = null; if (ctx.canvas && ctx.document?.pointerLockElement === ctx.canvas)
+    ctx.document.exitPointerLock(); }
+export function stopFrameWorld(ctx) { if (typeof ctx.frame === 'number') {
+    ctx.window.cancelAnimationFrame(ctx.frame);
+    ctx.frame = null;
+} if (typeof ctx.motionTimer === 'number') {
+    ctx.window.clearTimeout(ctx.motionTimer);
+    ctx.motionTimer = null;
+} ctx.last = 0; }
+export function invalidateWorld(ctx) { ctx.dirty = true; if (!ctx.closed && ctx.attached && !ctx.paused && !ctx.lost && !ctx.document.hidden && ctx.frame === null)
+    ctx.frame = ctx.window.requestAnimationFrame(ctx.tick); }
+export const tickWorld = tickFrame;
+export function drawWorld(ctx) {
+    if (!ctx.gpu)
+        return;
+    const width = ctx.host.clientWidth, height = ctx.host.clientHeight;
+    if (!width || !height)
+        return;
+    ctx.fitViewport();
+    const size = renderSize(width, height, ctx.window.devicePixelRatio || 1);
+    const matrix = cameraMatrix(ctx.pose, width / height, ctx.zoom);
+    const visibleActors = new Set(ctx.model.items.filter(item => item.kind === 'character').filter(item => { const point = screenPoint(matrix, item.x, item.y + 1.5, item.z, width, height); return point?.visible && point.depth < 150; }).map(item => item.id));
+    if (ctx.window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+        visibleActors.clear();
+    ctx.gpu.draw(ctx.pose, width / height, ctx.zoom, size, ctx.window.performance.now(), visibleActors);
+    ctx.frames++;
+    ctx.positionBubble();
+    ctx.wrap.dataset.animatedNpcs = String(visibleActors.size);
+    if (visibleActors.size && ctx.motionTimer === null && !ctx.paused && !ctx.document.hidden)
+        ctx.motionTimer = ctx.window.setTimeout(() => { ctx.motionTimer = null; ctx.invalidate(); }, 200);
+    ctx.projected = [];
+    for (const item of ctx.model.items) {
+        const point = screenPoint(matrix, item.x, item.y + objectBounds[item.form][1] + .45, item.z, width, height);
+        if (point?.visible && point.depth < 1800)
+            ctx.projected.push({ item, ...point });
+    }
+    ctx.projected.sort((a, b) => a.depth - b.depth);
+    const displayed = [], labelWidth = width < 600 ? 138 : 182;
+    for (const point of ctx.projected) {
+        const x = clamp(point.x, 90, width - 90), y = clamp(point.y, 96, Math.max(96, height - 80));
+        if (displayed.some(p => Math.abs(p.x - x) < labelWidth && Math.abs(p.y - y) < 85))
+            continue;
+        displayed.push({ ...point, x, y });
+        if (displayed.length === 8)
+            break;
+    }
+    const visible = new Set(displayed.map(p => p.item.id));
+    for (const [id, node] of ctx.labelNodes)
+        node.hidden = !visible.has(id);
+    for (const point of displayed) {
+        const node = ctx.labelNodes.get(point.item.id);
+        node.style.left = point.x + 'px';
+        node.style.top = point.y + 'px';
+        node.dataset.distance = point.depth.toFixed(1);
+    }
+    ctx.publishAnchor();
+    ctx.hovered = pickWorld(ctx.model.items, ctx.pose, width / 2, height / 2, width, height, ctx.zoom);
+    const target = ctx.model.items.find(item => item.id === ctx.hovered);
+    ctx.inspect.disabled = !ctx.hovered;
+    ctx.inspect.hidden = ctx.navigation === 'overview';
+    ctx.aim.hidden = ctx.navigation === 'overview';
+    ctx.hint.textContent = ctx.navigation === 'overview' ? (ctx.view.pattern === 'garden' ? `Open people · ${ctx.model.items.filter(item => item.kind === 'character').length}` : `Browse this space · ${ctx.model.items.length}`) : target ? target.title + ' · Inspect' : ctx.model.items.length ? 'Select a person or a group' : 'No information is visible in this view';
+    ctx.hint.hidden = ctx.navigation !== 'overview' || !ctx.model.items.length;
+    ctx.canvas.setAttribute('aria-label', ctx.navigation === 'overview' ? 'Explore your world. Drag to pan. Wheel or pinch to zoom. Select an object to focus. M for Map.' : 'Explore your world. W A S D or arrows to walk. Drag to look. E to interact. M for Map. Q to mark.');
+    for (const [id, node] of ctx.labelNodes)
+        node.dataset.aimed = String(id === ctx.hovered);
+    ctx.wrap.dataset.pose = JSON.stringify(ctx.pose);
+    ctx.wrap.dataset.frames = String(ctx.frames);
+    ctx.wrap.dataset.instances = String(ctx.gpu.count);
+    ctx.wrap.dataset.objects = String(ctx.model.items.length);
+    ctx.wrap.dataset.bufferPixels = String(ctx.canvas.width * ctx.canvas.height);
+    ctx.wrap.dataset.renderer = 'three';
+    ctx.wrap.dataset.renderStats = JSON.stringify(ctx.gpu.stats);
+    ctx.wrap.dataset.cameraMode = ctx.pose.cameraMode ?? 'overview';
+    ctx.wrap.dataset.avatar = ctx.pose.cameraMode === 'third-person' ? 'present' : 'hidden';
+    ctx.wrap.dataset.uploads = String(ctx.uploads);
+    ctx.wrap.dataset.initializations = String(ctx.initializations);
+    ctx.wrap.dataset.navigation = ctx.navigation;
+}
+export function failWorld(ctx, error) { const e = record(error); ctx.stopInput(); ctx.stopFrame(); ctx.status.hidden = false; ctx.status.textContent = (e.code ?? e.message ?? 'WorldRenderingUnavailable') + ' — The 3D view is unavailable. Use “In this space” to inspect the available information.'; ctx.wrap.dataset.gpu = 'unavailable'; }
+export function initializeWorld(ctx) { try {
+    ctx.gpu = createGpu(ctx.canvas);
+    ctx.initializations++;
+    ctx.gpu.pattern(ctx.view.pattern);
+    if (ctx.geometry) {
+        ctx.gpu.upload(ctx.geometry, ctx.actorRanges);
+        ctx.gpu.motionStates(new Map(ctx.model.items.filter(i => i.kind === 'character').map(i => [i.id, ctx.roleStatus(ctx.workActivity, i.id)?.state ?? 'Idle'])));
+        ctx.uploads++;
+    }
+    ctx.lost = false;
+    ctx.status.hidden = true;
+    ctx.wrap.dataset.gpu = 'ready';
+    ctx.invalidate();
+}
+catch (error) {
+    const failed = ctx.gpu;
+    ctx.gpu = null;
+    try {
+        failed?.close();
+    }
+    catch (cleanup) {
+        error = new AggregateError([error, cleanup], 'Graphics initialization and cleanup failed');
+    }
+    ctx.fail(error);
+} }

package/src/world-resources.d.mts

@@ -0,0 +1,34 @@
+interface Clearable {
+    clear(): void;
+}
+interface Closable {
+    close(): void;
+}
+export interface WorldResources {
+    engine?: {
+        close?(): void;
+    };
+    stopInput?: () => void;
+    stopFrame?: () => void;
+    resize?: {
+        disconnect(): void;
+    };
+    controller?: {
+        abort(): void;
+    };
+    orbit?: {
+        dispose(): void;
+    };
+    gpu?: Closable | null;
+    canvas?: Pick<HTMLCanvasElement, 'getContext'>;
+    initializations?: number;
+    labelNodes?: Clearable;
+    directoryNodes?: Clearable;
+    recent?: Clearable;
+    poses?: Clearable;
+    wrap?: {
+        remove(): void;
+    };
+}
+export declare function disposeWorldResources(ctx: WorldResources, gpu?: Closable | null | undefined): void;
+export {};

package/src/world-resources.mjs

@@ -0,0 +1,8 @@
+import { disposeGraphics } from './graphics-disposal.mjs';
+// May also run after partial setup. Every acquired resource gets its own attempt.
+export function disposeWorldResources(ctx, gpu = ctx.gpu) {
+    disposeGraphics([() => ctx.stopInput?.(), () => ctx.stopFrame?.(), () => ctx.resize?.disconnect(), () => ctx.controller?.abort(), () => ctx.engine?.close?.(), () => ctx.orbit?.dispose(), () => gpu?.close(),
+        () => { if ((ctx.initializations ?? 0) > 0)
+            ctx.canvas?.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext(); },
+        () => ctx.labelNodes?.clear(), () => ctx.directoryNodes?.clear(), () => ctx.recent?.clear(), () => ctx.poses?.clear(), () => ctx.wrap?.remove()]);
+}