@zixcel/dom-renderer 0.10.4 → 0.10.6

package/src/object-presentation.mjs

@@ -1,24 +1,27 @@
 // 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'})
+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]})
+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)}
+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 ? (types[0] === 'string' ? 'text' : types[0] === 'number' ? 'number' : types[0] === 'boolean' ? 'boolean' : 'record') : 'record', needsReview: Boolean(item.unresolved) };
 }

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

@@ -1,20 +1,29 @@
-export function visibleProjection(sources: any, { x, z, radius, limit, marked }?: {
+export interface ProjectionPoint {
+    readonly id: string;
+    readonly x: number;
+    readonly z: number;
+    readonly title?: string;
+    readonly kind?: string;
+}
+export interface NearbyOptions {
     x?: number;
     z?: number;
     radius?: number;
     limit?: number;
-    marked?: any;
-}): {
-    items: any[];
-    markers: any[];
+    marked?: string | null;
+}
+export interface MapOptions {
+    selected?: string | null;
+    marked?: string | null;
+    limit?: number;
+}
+export declare function visibleProjection<T extends ProjectionPoint>(sources: readonly T[], { x, z, radius, limit, marked }?: NearbyOptions): {
+    items: T[];
+    markers: T[];
     total: number;
     omitted: number;
 };
-export function mapProjection(sources: any, { selected, marked, limit }?: {
-    selected?: any;
-    marked?: any;
-    limit?: number;
-}): {
+export declare function mapProjection<T extends ProjectionPoint>(sources: readonly T[], { selected, marked, limit }?: MapOptions): {
     items: {
         id: any;
         title: any;

package/src/open-world-projection.mjs

@@ -1,26 +1,35 @@
 // 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 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}
+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

@@ -1 +1 @@
-export function reconcileChildren(parent: any, children: any): void;
+export declare function reconcileChildren(parent: Node, children: Iterable<Node>): void;

package/src/reconcile.mjs

@@ -1,21 +1,33 @@
 // 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)
+const isElement = (node) => node.nodeType === 1;
+const key = (node, index) => isElement(node)
+    ? [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 (isElement(existing) && isElement(fresh)) {
+                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.parentNode?.removeChild(node);
+    for (let index = 0; index < wanted.length; index++)
+        if (parent.childNodes[index] !== wanted[index])
+            parent.insertBefore(wanted[index], parent.childNodes[index] ?? null);
 }

package/src/scene-items.d.mts

@@ -0,0 +1,9 @@
+import type { RenderItem, RenderPlan } from '@zixcel/projection-client';
+export interface SceneGroup {
+    id: string;
+    role: string;
+    items: readonly RenderItem[];
+}
+export type SceneButton = (label: string, kind: string, id: string, attrs?: Record<string, unknown>) => HTMLButtonElement;
+export declare const reasonOf: (item: RenderItem) => string | undefined;
+export declare function appendSceneItems(document: Document, board: HTMLElement, groups: readonly SceneGroup[], plan: RenderPlan, button: SceneButton): void;

package/src/scene-items.mjs

@@ -0,0 +1,29 @@
+import { element } from './dom-elements.mjs';
+import { symbol } from './symbol.mjs';
+export const reasonOf = (item) => 'reason' in item.content ? item.content.reason : undefined;
+export function appendSceneItems(document, board, groups, plan, button) {
+    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 ?? reasonOf(item) ?? 'Display not configured', 'select', { 'aria-pressed': item.selected }), itemButton('View details', 'inspect', { 'aria-expanded': plan.inspector?.id === item.id, 'aria-haspopup': 'dialog' }));
+            if (reasonOf(item))
+                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', reasonOf(item) ? '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);
+    }
+}

package/src/scene-renderer.d.mts

@@ -0,0 +1,37 @@
+import type { RenderPlan, ActionHandle, Camera } from '@zixcel/projection-client';
+import type { WorldSurface } from './world-api.mjs';
+export interface SceneActor {
+    id: string;
+    title: string;
+    status?: string;
+    preparation?: {
+        label: string;
+    };
+}
+export interface SceneGarden {
+    host: HTMLElement;
+    actors: readonly SceneActor[];
+    activity?: unknown;
+}
+export interface SceneSlots {
+    tools?: HTMLElement;
+    details?: HTMLElement;
+    actions?: HTMLElement;
+    describeUnresolved?: (reason: string) => {
+        label: string;
+        detail: string;
+    };
+}
+export type SceneEvents = (kind: string, value: string | ActionHandle | undefined) => void;
+export declare class SceneRenderer {
+    #private;
+    constructor(root: HTMLElement, onEvent: SceneEvents, slots?: SceneSlots, surface?: WorldSurface | null);
+    render(plan: RenderPlan): void;
+    camera(value: Camera): void;
+    speaker(value: SceneActor | null): void;
+    garden(value: SceneGarden | null): void;
+    activity(value: unknown): void;
+    changeCamera(action: 'in' | 'out' | 'up' | 'down' | 'left' | 'right' | 'reset'): void;
+    close(): void;
+    dispose(): void;
+}

package/src/scene-renderer.mjs

@@ -0,0 +1,170 @@
+import { disposeGraphics } from './graphics-disposal.mjs';
+import { element, fail } from './dom-elements.mjs';
+import { spatialView } from './spatial.mjs';
+import { reasonOf, appendSceneItems } from './scene-items.mjs';
+import { reconcileChildren } from './reconcile.mjs';
+import { createWorldSurface } from './world-surface.mjs';
+import { bookReader } from './book-reader.mjs';
+export class SceneRenderer {
+    #root;
+    #events;
+    #abort = null;
+    #actionHandles = new Map();
+    #spatial = null;
+    #slots;
+    #pose = null;
+    #poseKey = null;
+    #speaker = null;
+    #surface;
+    #ownsSurface;
+    #garden = null;
+    constructor(root, onEvent, slots = {}, surface = null) { this.#root = root; this.#events = onEvent; this.#slots = slots; this.#surface = surface ?? createWorldSurface(); this.#ownsSurface = !surface; }
+    render(plan) {
+        const root = this.#root, document = root.ownerDocument, focused = document.activeElement instanceof document.defaultView.HTMLElement ? document.activeElement.dataset.control : undefined;
+        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');
+        appendSceneItems(document, board, groups, plan, button);
+        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 => reasonOf(item));
+        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 reason = reasonOf(item);
+                if (!reason)
+                    continue;
+                const explanation = this.#slots.describeUnresolved?.(reason) ?? { label: String(reasonOf(item)), 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 inspector = plan.inspector;
+            const chosen = groups.flatMap(r => r.items).find(i => i.id === 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 (!activeViewport || !activeBoard)
+            fail('InvalidRenderPlan');
+        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: 'group' in item.content ? item.content.group : null, semanticRef: 'semanticRef' in item.content ? item.content.semanticRef : null, sourceRefs: item.content.sourceRefs, scalars: (item.display?.fields ?? []).map(f => f.value), unresolved: Boolean(reasonOf(item)), 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((host) => Boolean(host))))
+            host.addEventListener('click', event => {
+                const target = (event.target instanceof document.defaultView.Element ? event.target.closest('button[data-kind]') : null);
+                if (!target || !host.contains(target) || !target.dataset.kind)
+                    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;
+        }
+    }
+    camera(value) { this.#spatial?.apply(value); }
+    speaker(value) { this.#speaker = value; }
+    garden(value) { this.#garden = value; }
+    activity(value) { this.#spatial?.activity(value); }
+    changeCamera(action) { this.#spatial?.change(action); }
+    close() {
+        const spatial = this.#spatial, abort = this.#abort, surface = this.#ownsSurface ? this.#surface : null;
+        this.#spatial = null;
+        this.#abort = null;
+        this.#actionHandles.clear();
+        if (this.#ownsSurface)
+            this.#surface = createWorldSurface();
+        disposeGraphics([() => spatial?.close(), () => abort?.abort(), () => this.#root.replaceChildren(),
+            ...[this.#slots.tools, this.#slots.details, this.#slots.actions].filter((slot) => Boolean(slot)).map(slot => () => slot.replaceChildren()), () => surface?.close()]);
+    }
+    dispose() { this.close(); if (this.#ownsSurface)
+        this.#surface.close(); }
+}

package/src/spatial-patterns.d.mts

@@ -1,29 +1,24 @@
-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;
-    };
+import type { WorldObject, WorldRelation } from './world-types.mjs';
+export interface SpatialState {
+    pattern: string;
+    groupBy: string;
+    group: string | null;
+    page: number;
+}
+export interface SpatialGroup extends WorldObject {
+    kind: 'group';
+    title: string;
+    memberIds: string[];
+}
+export interface SpatialView {
+    objects: WorldObject[];
+    relations: WorldRelation[];
+    groups: SpatialGroup[];
+    state: SpatialState;
     total: number;
     pages: number;
-    label: any;
-};
-export const spatialPatterns: readonly string[][];
-export const spatialGroupings: readonly string[][];
+    label: string;
+}
+export declare const spatialPatterns: readonly string[][];
+export declare const spatialGroupings: readonly string[][];
+export declare function spatialPattern(objects: WorldObject[], relations?: WorldRelation[], options?: Partial<SpatialState>): SpatialView;