@zixcel/dom-renderer 0.10.4 → 0.10.5

package/README.md

@@ -37,3 +37,9 @@ pnpm test
 ## Release provenance
 
 Starting with 0.10.1, releases use GitHub Actions OIDC trusted publishing from `zixcel/projection-runtime` (`publish-npm.yml`), without a stored npm publishing token. The workflow verifies reviewed archive hashes and requires npm provenance metadata. Check the published version on npm and verify registry signatures and provenance with `npm audit signatures` in an installed consumer project. Package runtime behavior and API contracts are unchanged by this release.
+
+## Node.js security baseline
+
+Use a supported Node.js security release for Node-based build, delivery and consumer processes: at least 22.23.4, 24.22.1 or 26.12.1. The renderer runs in the browser and does not bundle Node. Updating an npm library does not update the caller's Node executable. The October 21, 2026 security fixes include TLS, DNS, HTTP and Brotli handling; operator-managed runtimes must be updated independently. GitHub Actions pins select the shell/build runtime, not the GitHub-managed runtime of JavaScript Actions.
+
+Official advisory: https://nodejs.org/en/blog/vulnerability/october-2026-security-releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zixcel/dom-renderer",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Trusted native DOM rendering of PP RenderPlans and Zixcel owner inputs",
@@ -38,10 +38,12 @@
     "dom",
     "data-presentation",
     "rendering",
-    "javascript"
+    "typescript"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:browser": "node test/world-browser.mjs"
+    "test": "node --test --test-concurrency=1 test/*.test.mts",
+    "test:browser": "node test/world-browser.mts",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/emit-dom-declarations.mts",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit"
   }
 }

package/src/book-reader.d.mts

@@ -1 +1,9 @@
-export function bookReader(document: any, item: any, revision: any, close: any, signal: any, previous: any): any;
+import type { RenderPlan } from '@zixcel/projection-client';
+export interface BookPosition {
+    id?: string;
+    revision?: string;
+    page: number;
+}
+type DisplayItem = RenderPlan['regions'][number]['items'][number];
+export declare function bookReader(document: Document, item: DisplayItem, revision: string, close: HTMLElement, signal: AbortSignal, previous: BookPosition | null): HTMLElement;
+export {};

package/src/book-reader.mjs

@@ -1,36 +1,57 @@
 // A world-local inspection view over declared scalar fields. Page position is
 // presentation state only; neither the object nor its evidence is copied.
-import {symbol} from './symbol.mjs'
-export function bookReader(document,item,revision,close,signal,previous){
- const make=(tag,text,className)=>{const node=document.createElement(tag);if(text!==undefined)node.textContent=text;if(className)node.className=className;return node}
- const root=make('article',undefined,'entity-inspector game-book'),header=make('header'),title=make('h2',item.display?.title??'Display not configured')
- root.dataset.bookId=item.id;root.dataset.bookRevision=revision
- root.setAttribute('aria-label','Inspect '+title.textContent)
- const heading=make('div',undefined,'game-book-heading');heading.append(make('small','INSPECT'),title)
- if(item.display?.summary)heading.append(make('p',item.display.summary))
- header.append(heading,close)
- const object=make('div',undefined,'game-book-object');object.setAttribute('aria-hidden','true');object.append(symbol(document,'book'))
- const pageView=make('section',undefined,'game-book-page'),body=make('div',undefined,'game-book-body'),footer=make('nav'),counter=make('output')
- pageView.setAttribute('aria-live','polite');body.append(object,pageView)
- footer.setAttribute('aria-label','Book pages')
- const fields=item.display?.fields??[],pages=Math.max(1,Math.ceil(fields.length/2))
- let page=previous?.id===item.id&&previous.revision===revision&&Number.isInteger(previous.page)?Math.max(0,Math.min(pages-1,previous.page)):0
- const button=(text,delta)=>{const node=make('button',text);node.type='button';node.addEventListener('click',()=>{page=Math.max(0,Math.min(pages-1,page+delta));draw()},{signal});return node}
- const back=button('Previous pages',-1),next=button('Next pages',1);footer.append(back,counter,next);root.append(header,body,footer)
- function draw(){
-  root.dataset.bookPage=String(page);pageView.setAttribute('aria-label','Page '+(page+1)+' of '+pages)
-  const list=make('dl',undefined,'object-fields')
-  for(const field of fields.slice(page*2,page*2+2))list.append(make('dt',field.label),make('dd',field.value===null?'Not set':String(field.value)))
-  pageView.replaceChildren(make('small','PAGE '+String(page+1).padStart(2,'0')+' / '+String(pages).padStart(2,'0')),list)
-  if(!list.children.length)pageView.append(make('p','No display fields have been declared.'))
-  const focused=document.activeElement,refocus=focused===back&&page===0?next:focused===next&&page===pages-1?back:null
-  counter.textContent=(page+1)+' / '+pages;back.disabled=page===0;next.disabled=page===pages-1;refocus?.focus({preventScroll:true})
- }
- document.addEventListener('keydown',event=>{
-  if(!['ArrowLeft','ArrowRight'].includes(event.key)||event.altKey||event.ctrlKey||event.metaKey)return
-  const panel=root.closest('.frame-panel'),focused=document.activeElement
-  if(!panel?.contains(focused)||focused?.matches('input,select,textarea,[contenteditable]'))return
-  event.preventDefault();page=Math.max(0,Math.min(pages-1,page+(event.key==='ArrowRight'?1:-1)));draw()
- },{signal})
- draw();return root
+import { symbol } from './symbol.mjs';
+export function bookReader(document, item, revision, close, signal, previous) {
+    const make = (tag, text, className) => { const node = document.createElement(tag); if (text !== undefined)
+        node.textContent = text; if (className)
+        node.className = className; return node; };
+    const root = make('article', undefined, 'entity-inspector game-book'), header = make('header'), title = make('h2', item.display?.title ?? 'Display not configured');
+    root.dataset.bookId = item.id;
+    root.dataset.bookRevision = revision;
+    root.setAttribute('aria-label', 'Inspect ' + title.textContent);
+    const heading = make('div', undefined, 'game-book-heading');
+    heading.append(make('small', 'INSPECT'), title);
+    if (item.display?.summary)
+        heading.append(make('p', item.display.summary));
+    header.append(heading, close);
+    const object = make('div', undefined, 'game-book-object');
+    object.setAttribute('aria-hidden', 'true');
+    object.append(symbol(document, 'book'));
+    const pageView = make('section', undefined, 'game-book-page'), body = make('div', undefined, 'game-book-body'), footer = make('nav'), counter = make('output');
+    pageView.setAttribute('aria-live', 'polite');
+    body.append(object, pageView);
+    footer.setAttribute('aria-label', 'Book pages');
+    const fields = item.display?.fields ?? [], pages = Math.max(1, Math.ceil(fields.length / 2));
+    let page = previous?.id === item.id && previous.revision === revision && Number.isInteger(previous.page) ? Math.max(0, Math.min(pages - 1, previous.page)) : 0;
+    const button = (text, delta) => { const node = make('button', text); node.type = 'button'; node.addEventListener('click', () => { page = Math.max(0, Math.min(pages - 1, page + delta)); draw(); }, { signal }); return node; };
+    const back = button('Previous pages', -1), next = button('Next pages', 1);
+    footer.append(back, counter, next);
+    root.append(header, body, footer);
+    function draw() {
+        root.dataset.bookPage = String(page);
+        pageView.setAttribute('aria-label', 'Page ' + (page + 1) + ' of ' + pages);
+        const list = make('dl', undefined, 'object-fields');
+        for (const field of fields.slice(page * 2, page * 2 + 2))
+            list.append(make('dt', field.label), make('dd', field.value === null ? 'Not set' : String(field.value)));
+        pageView.replaceChildren(make('small', 'PAGE ' + String(page + 1).padStart(2, '0') + ' / ' + String(pages).padStart(2, '0')), list);
+        if (!list.children.length)
+            pageView.append(make('p', 'No display fields have been declared.'));
+        const focused = document.activeElement, refocus = focused === back && page === 0 ? next : focused === next && page === pages - 1 ? back : null;
+        counter.textContent = (page + 1) + ' / ' + pages;
+        back.disabled = page === 0;
+        next.disabled = page === pages - 1;
+        refocus?.focus({ preventScroll: true });
+    }
+    document.addEventListener('keydown', event => {
+        if (!['ArrowLeft', 'ArrowRight'].includes(event.key) || event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const panel = root.closest('.frame-panel'), focused = document.activeElement;
+        if (!panel?.contains(focused) || focused?.matches('input,select,textarea,[contenteditable]'))
+            return;
+        event.preventDefault();
+        page = Math.max(0, Math.min(pages - 1, page + (event.key === 'ArrowRight' ? 1 : -1)));
+        draw();
+    }, { signal });
+    draw();
+    return root;
 }

package/src/dom-elements.d.mts

@@ -0,0 +1,11 @@
+export declare const renderBounds: Readonly<{
+    nodes: 8192;
+    depth: 20;
+    textBytes: 524288;
+}>;
+export declare function fail(code: string): never;
+export declare function element<K extends keyof HTMLElementTagNameMap>(document: Document, tag: K, text?: unknown, attrs?: Record<string, unknown>): HTMLElementTagNameMap[K];
+export declare function valueView(document: Document, value: unknown, budget?: {
+    nodes: number;
+    bytes: number;
+}): HTMLElement;

package/src/dom-elements.mjs

@@ -0,0 +1,48 @@
+// Trusted DOM primitives: external values are rendered as text, never HTML.
+export const renderBounds = Object.freeze({ nodes: 8192, depth: 20, textBytes: 524288 });
+export function fail(code) { throw Object.assign(Error(code), { code }); }
+export function element(document, tag, text = null, attrs = {}) {
+    const node = document.createElement(tag);
+    if (text !== null)
+        node.textContent = String(text);
+    for (const [key, value] of Object.entries(attrs))
+        if (value !== null)
+            node.setAttribute(key, String(value));
+    return node;
+}
+export function valueView(document, value, budget = { nodes: 0, bytes: 0 }) {
+    function walk(value, depth) {
+        if (++budget.nodes > renderBounds.nodes || depth > renderBounds.depth)
+            fail('RenderLimitExceeded');
+        if (value === null || typeof value !== 'object') {
+            if (typeof value === 'string' && value.length > renderBounds.textBytes)
+                fail('RenderLimitExceeded');
+            const text = JSON.stringify(value);
+            if (typeof text !== 'string')
+                fail('InvalidRenderValue');
+            budget.bytes += new TextEncoder().encode(text).length;
+            if (budget.bytes > renderBounds.textBytes)
+                fail('RenderLimitExceeded');
+            return element(document, 'span', text, { 'data-projection-scalar': text });
+        }
+        if (Object.keys(value).length > 4096)
+            fail('RenderLimitExceeded');
+        if (!Object.keys(value).length)
+            return element(document, 'span', Array.isArray(value) ? '[]' : '{}', { 'data-empty-value': Array.isArray(value) ? 'array' : 'object' });
+        const list = element(document, Array.isArray(value) ? 'ol' : 'dl');
+        for (const [key, child] of Object.entries(value)) {
+            if (Array.isArray(value)) {
+                const item = element(document, 'li');
+                item.append(walk(child, depth + 1));
+                list.append(item);
+            }
+            else {
+                const name = element(document, 'dt', key), item = element(document, 'dd');
+                item.append(walk(child, depth + 1));
+                list.append(name, item);
+            }
+        }
+        return list;
+    }
+    return walk(value, 0);
+}

package/src/frame-layout.d.mts

@@ -1,8 +1,14 @@
-export function frameLayout(width: any, height: any, kind: any, anchor?: any): {
+export interface AnchorBounds {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export declare function frameLayout(width: number, height: number, kind: string, anchor?: AnchorBounds | null): {
     mode: string;
     world: {
-        width: any;
-        height: any;
+        width: number;
+        height: number;
     };
     panel: {
         x: number;

package/src/frame-layout.mjs

@@ -1,25 +1,25 @@
 // Pure presentation policy: never resize the world or refit its camera for a panel.
 // The exact object's projected bounds determine an adjacent, bounded bubble.
-export function frameLayout(width,height,kind,anchor=null){
- const gap=12,left=8,top=56,right=width-8,bottom=height-64
- const clamp=(v,min,max)=>Math.max(min,Math.min(max,v))
- const w=Math.min(kind==='actions'?320:['details','structure'].includes(kind)?640:432,right-left)
- const h=Math.min(kind==='actions'?360:kind==='details'?height*.6:480,bottom-top)
- let panel={x:right-w,y:top,width:w,height:h},mode='overlay'
- if(anchor){
-  const areas=[
-   {side:'right',x:Math.max(left,anchor.right+gap),y:top,right,bottom},
-   {side:'left',x:left,y:top,right:Math.min(right,anchor.left-gap),bottom},
-   {side:'above',x:left,y:top,right,bottom:Math.min(bottom,anchor.top-gap)},
-   {side:'below',x:left,y:Math.max(top,anchor.bottom+gap),right,bottom}
-  ].map(a=>({...a,width:Math.min(w,Math.max(0,a.right-a.x)),height:Math.min(h,Math.max(0,a.bottom-a.y))}))
-  const best=areas.filter(a=>a.width>=Math.min(240,w)&&a.height>=80).sort((a,b)=>b.width*b.height-a.width*a.height)[0]
-  if(best){
-   const vertical=['above','below'].includes(best.side)
-   panel={x:vertical?clamp((anchor.left+anchor.right-best.width)/2,best.x,best.right-best.width):best.side==='left'?best.right-best.width:best.x,
-    y:vertical?(best.side==='above'?best.bottom-best.height:best.y):clamp(anchor.top,best.y,best.bottom-best.height),width:best.width,height:best.height}
-   mode=best.side
-  }
- }
- return {mode,world:{width,height},panel}
+export function frameLayout(width, height, kind, anchor = null) {
+    const gap = 12, left = 8, top = 56, right = width - 8, bottom = height - 64;
+    const clamp = (v, min, max) => Math.max(min, Math.min(max, v));
+    const w = Math.min(kind === 'actions' ? 320 : ['details', 'structure'].includes(kind) ? 640 : 432, right - left);
+    const h = Math.min(kind === 'actions' ? 360 : kind === 'details' ? height * .6 : 480, bottom - top);
+    let panel = { x: right - w, y: top, width: w, height: h }, mode = 'overlay';
+    if (anchor) {
+        const areas = [
+            { side: 'right', x: Math.max(left, anchor.right + gap), y: top, right, bottom },
+            { side: 'left', x: left, y: top, right: Math.min(right, anchor.left - gap), bottom },
+            { side: 'above', x: left, y: top, right, bottom: Math.min(bottom, anchor.top - gap) },
+            { side: 'below', x: left, y: Math.max(top, anchor.bottom + gap), right, bottom }
+        ].map(a => ({ ...a, width: Math.min(w, Math.max(0, a.right - a.x)), height: Math.min(h, Math.max(0, a.bottom - a.y)) }));
+        const best = areas.filter(a => a.width >= Math.min(240, w) && a.height >= 80).sort((a, b) => b.width * b.height - a.width * a.height)[0];
+        if (best) {
+            const vertical = ['above', 'below'].includes(best.side);
+            panel = { x: vertical ? clamp((anchor.left + anchor.right - best.width) / 2, best.x, best.right - best.width) : best.side === 'left' ? best.right - best.width : best.x,
+                y: vertical ? (best.side === 'above' ? best.bottom - best.height : best.y) : clamp(anchor.top, best.y, best.bottom - best.height), width: best.width, height: best.height };
+            mode = best.side;
+        }
+    }
+    return { mode, world: { width, height }, panel };
 }

package/src/frame.d.mts

@@ -1,13 +1,25 @@
-export function windowFrame(root: any, { stage, title, state, panels }: {
-    stage: any;
-    title: any;
-    state: any;
-    panels: any;
-}): {
-    open: (id: any, objectId?: any) => void;
+export interface FramePanel {
+    id: string;
+    label: string;
+    symbol: string;
+    nodes?: readonly Node[];
+    activate?: () => void;
+    dock?: boolean;
+}
+export interface FrameOptions {
+    stage: Node;
+    title: Node;
+    state: HTMLElement;
+    panels: FramePanel[];
+}
+export declare function windowFrame(root: HTMLElement, { stage, title, state, panels }: FrameOptions): {
+    open: (id: string, objectId?: string | null) => void;
     close: (restoreFocus?: boolean) => void;
-    speaker(value: any): void;
-    label(id: any, value: any): void;
-    notify(count: any): void;
+    speaker(value: {
+        id: string;
+        title?: string;
+    } | null): void;
+    label(id: string, value: string): void;
+    notify(count: number): void;
     dispose(): void;
 };

package/src/frame.mjs

@@ -1,47 +1,95 @@
+import { eventDetail, record } from './world-api.mjs';
 // Presentation-only window frame: one active panel, stable content and bounded listeners.
-import {symbol} from './symbol.mjs'
-import {frameLayout} from './frame-layout.mjs'
-export function windowFrame(root,{stage,title,state,panels}){
- const document=root.ownerDocument,abort=new AbortController(),buttons=new Map(),bodies=new Map()
- const make=(tag,attrs={})=>{const node=document.createElement(tag);for(const [k,v]of Object.entries(attrs))node.setAttribute(k,v);return node}
- const dock=make('nav',{class:'frame-dock','aria-label':'Window tools'}),bar=make('header',{class:'frame-bar'})
- const panel=make('aside',{class:'frame-panel',role:'dialog','aria-modal':'false',tabindex:'-1'}),head=make('header'),heading=make('h2'),closeButton=make('button',{type:'button','aria-label':'Close panel',title:'Close panel'})
- closeButton.textContent='×';head.append(heading,closeButton);panel.append(head);panel.hidden=true
- let active=null,speaker=null,target=null,anchor=null
- const requestAnchor=()=>root.dispatchEvent(new document.defaultView.CustomEvent('world-anchor-request',{detail:{id:target}}))
- const position=()=>{
-  if(!active){delete root.dataset.panelLayout;return}
-  const layout=frameLayout(root.clientWidth,root.clientHeight,active,anchor),rect=layout.panel
-  root.dataset.panelLayout=layout.mode
-  panel.dataset.anchorId=target??''
-  if(anchor)panel.dataset.anchorBounds=JSON.stringify(anchor);else delete panel.dataset.anchorBounds
-  Object.assign(panel.style,{left:rect.x+'px',top:rect.y+'px',right:'auto',bottom:'auto',width:rect.width+'px',height:rect.height+'px',maxHeight:rect.height+'px'})
- }
- const describe=()=>{const talking=Boolean(speaker&&active==='actions');panel.dataset.book=String(active==='details');panel.dataset.conversation=String(talking);if(talking)heading.textContent=speaker.title;position()}
- root.addEventListener('world-anchor',event=>{if(event.detail.id!==target)return;anchor=event.detail.bounds;position()},{signal:abort.signal})
- const resize=new root.ownerDocument.defaultView.ResizeObserver(()=>{requestAnchor();position()});resize.observe(root)
- function close(restoreFocus=true){const previous=active;active=null;target=null;anchor=null;requestAnchor();panel.hidden=true;delete root.dataset.panel;position();for(const b of buttons.values())b.setAttribute('aria-expanded','false');if(restoreFocus)(buttons.get(previous)?.isConnected?buttons.get(previous):dock.querySelector('button'))?.focus({preventScroll:true})}
- function open(id,objectId=null){if(!bodies.has(id))return;active=id;target=objectId??(id==='actions'?speaker?.id:null);anchor=null;panel.hidden=false;heading.textContent=panels.find(p=>p.id===id).label;panel.setAttribute('aria-label',heading.textContent)
-  for(const [key,body]of bodies)body.hidden=key!==id
-  for(const [key,button]of buttons)button.setAttribute('aria-expanded',String(key===id))
-  root.dataset.panel=id
-  root.dispatchEvent(new document.defaultView.CustomEvent('frame-panel-open'))
-  describe()
-  requestAnchor()
-  panel.focus({preventScroll:true})
- }
- for(const item of panels){
-  if(item.activate){
-   const button=make('button',{type:'button','aria-label':item.label,title:item.label,'data-panel':item.id})
-   button.append(symbol(document,item.symbol),Object.assign(document.createElement('span'),{textContent:item.label}))
-   button.addEventListener('click',()=>{close();item.activate()},{signal:abort.signal});dock.append(button);continue
-  }
-  const id='panel-'+crypto.randomUUID(),button=make('button',{type:'button','aria-label':item.label,title:item.label,'aria-expanded':'false','aria-controls':id,'data-panel':item.id})
-  button.append(symbol(document,item.symbol),Object.assign(document.createElement('span'),{textContent:item.label}));button.addEventListener('click',()=>active===item.id?close():open(item.id),{signal:abort.signal})
-  const body=make('section',{id,class:'frame-panel-body'});body.hidden=true;body.append(...item.nodes);panel.append(body);if(item.dock!==false)dock.append(button);buttons.set(item.id,button);bodies.set(item.id,body)
- }
- closeButton.addEventListener('click',close,{signal:abort.signal})
- document.addEventListener('keydown',event=>{if(event.key==='Escape'&&active!==null){event.preventDefault();close()}},{signal:abort.signal})
- bar.append(title,state);root.replaceChildren(stage,bar,dock,panel)
- return {open,close,speaker(value){speaker=value;describe()},label(id,value){const item=panels.find(p=>p.id===id),button=buttons.get(id);if(!item||!button)return;item.label=value;button.setAttribute('aria-label',value);button.title=value;button.querySelector('span:last-child').textContent=value;if(active===id){heading.textContent=value;panel.setAttribute('aria-label',value)}},notify(count){state.setAttribute('data-attention',String(count>0));state.title=count?count+' notifications':'Connection status'},dispose(){resize.disconnect();abort.abort();buttons.clear();bodies.clear();root.replaceChildren()}}
+import { symbol } from './symbol.mjs';
+import { frameLayout } from './frame-layout.mjs';
+export function windowFrame(root, { stage, title, state, panels }) {
+    const document = root.ownerDocument, browser = document.defaultView;
+    if (!browser)
+        throw Error('FrameDocumentUnavailable');
+    const window = browser, abort = new AbortController(), buttons = new Map(), bodies = new Map();
+    const make = (tag, attrs = {}) => { const node = document.createElement(tag); for (const [k, v] of Object.entries(attrs))
+        node.setAttribute(k, v); return node; };
+    const dock = make('nav', { class: 'frame-dock', 'aria-label': 'Window tools' }), bar = make('header', { class: 'frame-bar' });
+    const panel = make('aside', { class: 'frame-panel', role: 'dialog', 'aria-modal': 'false', tabindex: '-1' }), head = make('header'), heading = make('h2'), closeButton = make('button', { type: 'button', 'aria-label': 'Close panel', title: 'Close panel' });
+    closeButton.textContent = '×';
+    head.append(heading, closeButton);
+    panel.append(head);
+    panel.hidden = true;
+    let active = null, speaker = null, target = null, anchor = null;
+    const requestAnchor = () => root.dispatchEvent(new window.CustomEvent('world-anchor-request', { detail: { id: target } }));
+    const position = () => {
+        if (!active) {
+            delete root.dataset.panelLayout;
+            return;
+        }
+        const layout = frameLayout(root.clientWidth, root.clientHeight, active, anchor), rect = layout.panel;
+        root.dataset.panelLayout = layout.mode;
+        panel.dataset.anchorId = target ?? '';
+        if (anchor)
+            panel.dataset.anchorBounds = JSON.stringify(anchor);
+        else
+            delete panel.dataset.anchorBounds;
+        Object.assign(panel.style, { left: rect.x + 'px', top: rect.y + 'px', right: 'auto', bottom: 'auto', width: rect.width + 'px', height: rect.height + 'px', maxHeight: rect.height + 'px' });
+    };
+    const describe = () => { const talking = Boolean(speaker && active === 'actions'); panel.dataset.book = String(active === 'details'); panel.dataset.conversation = String(talking); if (talking && speaker)
+        heading.textContent = speaker.title ?? 'Information'; position(); };
+    root.addEventListener('world-anchor', event => { const detail = eventDetail(event); if (detail.id !== target)
+        return; const b = record(detail.bounds); anchor = ['left', 'right', 'top', 'bottom'].every(k => typeof b[k] === 'number' && Number.isFinite(b[k])) ? { left: Number(b.left), right: Number(b.right), top: Number(b.top), bottom: Number(b.bottom) } : null; position(); }, { signal: abort.signal });
+    const resize = new window.ResizeObserver(() => { requestAnchor(); position(); });
+    resize.observe(root);
+    function close(restoreFocus = true) { const previous = active ? buttons.get(active) : undefined; active = null; target = null; anchor = null; requestAnchor(); panel.hidden = true; delete root.dataset.panel; position(); for (const b of buttons.values())
+        b.setAttribute('aria-expanded', 'false'); if (restoreFocus)
+        (previous?.isConnected ? previous : dock.querySelector('button'))?.focus({ preventScroll: true }); }
+    function open(id, objectId = null) {
+        if (!bodies.has(id))
+            return;
+        active = id;
+        target = objectId ?? (id === 'actions' ? speaker?.id ?? null : null);
+        anchor = null;
+        panel.hidden = false;
+        heading.textContent = panels.find(p => p.id === id)?.label ?? '';
+        panel.setAttribute('aria-label', heading.textContent);
+        for (const [key, body] of bodies)
+            body.hidden = key !== id;
+        for (const [key, button] of buttons)
+            button.setAttribute('aria-expanded', String(key === id));
+        root.dataset.panel = id;
+        root.dispatchEvent(new window.CustomEvent('frame-panel-open'));
+        describe();
+        requestAnchor();
+        panel.focus({ preventScroll: true });
+    }
+    for (const item of panels) {
+        if (item.activate) {
+            const button = make('button', { type: 'button', 'aria-label': item.label, title: item.label, 'data-panel': item.id });
+            button.append(symbol(document, item.symbol), Object.assign(document.createElement('span'), { textContent: item.label }));
+            button.addEventListener('click', () => { close(); item.activate?.(); }, { signal: abort.signal });
+            dock.append(button);
+            continue;
+        }
+        const id = 'panel-' + crypto.randomUUID(), button = make('button', { type: 'button', 'aria-label': item.label, title: item.label, 'aria-expanded': 'false', 'aria-controls': id, 'data-panel': item.id });
+        button.append(symbol(document, item.symbol), Object.assign(document.createElement('span'), { textContent: item.label }));
+        button.addEventListener('click', () => active === item.id ? close() : open(item.id), { signal: abort.signal });
+        const body = make('section', { id, class: 'frame-panel-body' });
+        body.hidden = true;
+        body.append(...item.nodes ?? []);
+        panel.append(body);
+        if (item.dock !== false)
+            dock.append(button);
+        buttons.set(item.id, button);
+        bodies.set(item.id, body);
+    }
+    closeButton.addEventListener('click', () => close(), { signal: abort.signal });
+    document.addEventListener('keydown', event => { if (event.key === 'Escape' && active !== null) {
+        event.preventDefault();
+        close();
+    } }, { signal: abort.signal });
+    bar.append(title, state);
+    root.replaceChildren(stage, bar, dock, panel);
+    return { open, close, speaker(value) { speaker = value; describe(); }, label(id, value) { const item = panels.find(p => p.id === id), button = buttons.get(id); if (!item || !button)
+            return; item.label = value; button.setAttribute('aria-label', value); button.title = value; const label = button.querySelector('span:last-child'); if (label)
+            label.textContent = value; if (active === id) {
+            heading.textContent = value;
+            panel.setAttribute('aria-label', value);
+        } }, notify(count) { state.setAttribute('data-attention', String(count > 0)); state.title = count ? count + ' notifications' : 'Connection status'; }, dispose() { resize.disconnect(); abort.abort(); buttons.clear(); bodies.clear(); root.replaceChildren(); } };
 }

package/src/geometry-policy.d.mts

@@ -0,0 +1,3 @@
+import type { ActorRange } from './world-types.mjs';
+/** Validate the complete upload before allocating or updating GPU state. */
+export declare function admitGeometry(data: Float32Array, ranges: readonly ActorRange[]): void;

package/src/geometry-policy.mjs

@@ -0,0 +1,17 @@
+import { worldLimits } from './world-model.mjs';
+/** Validate the complete upload before allocating or updating GPU state. */
+export function admitGeometry(data, ranges) {
+    const fail = () => { throw Error('WorldGeometryLimitExceeded'); };
+    if (!(data instanceof Float32Array) || data.length % 9 || data.length / 9 >= worldLimits.instances || ranges.length > worldLimits.objects)
+        fail();
+    for (const value of data)
+        if (!Number.isFinite(value))
+            fail();
+    const ids = new Set(), count = data.length / 9;
+    for (const range of ranges) {
+        if (!range || typeof range.id !== 'string' || !range.id || range.id.length > 512 || ids.has(range.id) ||
+            !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || range.end > count)
+            fail();
+        ids.add(range.id);
+    }
+}

package/src/graph-documents.d.mts

@@ -0,0 +1,48 @@
+import type { InspectionOverview } from './inspection-overview.mjs';
+export interface GraphDocument {
+    id: string;
+    label: string;
+    value: unknown;
+    source?: {
+        method?: string;
+        semanticRevision?: string;
+        memoryRevision?: string;
+        truncated?: boolean;
+        roleRef?: {
+            id?: string;
+            revision?: string;
+            digest_sha256?: string;
+        };
+    };
+}
+export interface GraphNode {
+    id: string;
+    label: string;
+    path: string;
+    level: number;
+    value: unknown;
+    document: GraphDocument;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    label: string;
+}
+export interface GraphView {
+    roles: readonly {
+        id: string;
+    }[];
+    selected?: string | null;
+    documents: GraphDocument[];
+    overview: InspectionOverview | null;
+}
+export declare function graphDocuments(documents: GraphDocument[], { component, query, depth, maximum }?: {
+    component?: string | undefined;
+    depth?: number | undefined;
+    maximum?: number | undefined;
+    query?: string | undefined;
+}): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    truncated: boolean;
+};

package/src/graph-documents.mjs

@@ -0,0 +1,40 @@
+// Hatter 2026: bounded document-containment graph. No meaning inference or writes.
+export function graphDocuments(documents, { component = '', query = '', depth = 3, maximum = 256 } = {}) {
+    if (!Array.isArray(documents) || documents.length > 32 || !Number.isInteger(depth) || depth < 1 || depth > 6 || !Number.isSafeInteger(maximum) || maximum < 1 || maximum > 256)
+        throw Error('GraphInputInvalid');
+    const nodes = [], edges = [];
+    let truncated = false;
+    const add = (value, label, path, level, parent, document) => {
+        if (nodes.length >= maximum) {
+            truncated = true;
+            return;
+        }
+        const id = document.id + ':' + path, node = { id, label, path, level, value, document };
+        nodes.push(node);
+        if (parent)
+            edges.push({ from: parent, to: id, label });
+        if (value && typeof value === 'object') {
+            const entries = Object.entries(value);
+            if (level >= depth) {
+                if (entries.length)
+                    truncated = true;
+                return;
+            }
+            for (const [key, child] of entries) {
+                if (nodes.length >= maximum) {
+                    truncated = true;
+                    break;
+                }
+                add(child, key, path + '/' + key.replaceAll('~', '~0').replaceAll('/', '~1'), level + 1, id, document);
+            }
+        }
+    };
+    for (const doc of documents)
+        if (!component || doc.id === component)
+            add(doc.value, doc.label, '', 0, null, doc);
+    if (query) {
+        const matches = new Set(nodes.filter(n => (n.label + ' ' + n.path + ' ' + (n.value === null || typeof n.value !== 'object' ? String(n.value) : '')).toLowerCase().includes(query.toLowerCase())).map(n => n.id));
+        return { nodes: nodes.filter(n => matches.has(n.id)), edges: edges.filter(e => matches.has(e.from) && matches.has(e.to)), truncated };
+    }
+    return { nodes, edges, truncated };
+}

package/src/graphics-disposal.d.mts

@@ -0,0 +1,2 @@
+/** Drain each independently owned resource; preserve falsy failures too. */
+export declare function disposeGraphics(operations: readonly (() => void)[]): void;

package/src/graphics-disposal.mjs

@@ -0,0 +1,14 @@
+/** Drain each independently owned resource; preserve falsy failures too. */
+export function disposeGraphics(operations) {
+    const failures = [];
+    for (const operation of operations) {
+        try {
+            operation();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, 'Graphics cleanup failed');
+}