@almadar/orb-shell-typescript-linux-x64 19.0.3 → 19.2.0

package/templates/almadar-renderers-typescript/test/safelist-entry.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { safelistEntryLine } from '../scripts/lib/safelist-entry.mjs';
+
+describe('G-ORBITAL-SHELL-TYPESCRIPT-034 safelist entry quoting', () => {
+  it('writes a class holding single quotes as a string that evaluates back to the class', () => {
+    const cls = "after:content-['']";
+    const line = safelistEntryLine(cls);
+    expect(new Function(`return [${line}]`)()).toEqual([cls]);
+  });
+
+  it('keeps the single-quoted form for a plain class', () => {
+    expect(safelistEntryLine('bg-primary/10')).toBe("  'bg-primary/10',");
+  });
+});

package/templates/almadar-renderers-typescript/test/ui/agent-chat-feed.test.tsx

@@ -82,4 +82,33 @@ describe('AgentChatFeed', () => {
     feed([]);
     expect(screen.getByText('Ask me anything')).toBeTruthy();
   });
+
+  it('a step whose tool has a declared label shows the label, not the address', () => {
+    render(<AgentChatFeed activities={turn(T0)} working emptyTitle="e" rawLlmPreferenceKey="test-raw" idPrefix="t" toolLabels={[{ tool: 'TaskPersistor.DO_CREATE', label: 'Ustvarjam nalogo' }]} />);
+    const call = screen.getByTestId('agent-activity-tool_call');
+    expect(call.textContent).toContain('Ustvarjam nalogo');
+    expect(call.textContent).not.toContain('TaskPersistor.DO_CREATE');
+    expect(screen.queryByTestId('agent-activity-tool_result')).toBeNull();
+  });
+
+  it('control: a successful step of an unlabelled tool keeps its result row', () => {
+    render(<AgentChatFeed activities={turn(T0)} working emptyTitle="e" rawLlmPreferenceKey="test-raw" idPrefix="t" />);
+    expect(screen.getByTestId('agent-activity-tool_result')).toBeTruthy();
+  });
+
+  it('control: a step whose tool has no declared label shows its address', () => {
+    render(<AgentChatFeed activities={turn(T0)} working emptyTitle="e" rawLlmPreferenceKey="test-raw" idPrefix="t" toolLabels={[{ tool: 'Other.TOOL', label: 'Drugo' }]} />);
+    expect(screen.getByTestId('agent-activity-tool_call').textContent).toContain('TaskPersistor.DO_CREATE');
+  });
+
+  it('edge: a failed step keeps its declared label and its error', () => {
+    const failed: TraceActivity[] = [
+      { type: 'message', role: 'user', content: 'q', timestamp: T0 },
+      { type: 'tool_result', tool: 'Shop.OPEN_PAGE', kind: 'input', success: false, detail: 'net::ERR_NAME_NOT_RESOLVED', resultText: '{}', timestamp: T0 + 1 },
+    ];
+    render(<AgentChatFeed activities={failed} working emptyTitle="e" rawLlmPreferenceKey="test-raw" idPrefix="t" toolLabels={[{ tool: 'Shop.OPEN_PAGE', label: 'Odpiram stran' }]} />);
+    const row = screen.getByTestId('agent-activity-tool_result');
+    expect(row.textContent).toContain('Odpiram stran');
+    expect(row.textContent).toContain('net::ERR_NAME_NOT_RESOLVED');
+  });
 });

package/templates/almadar-renderers-typescript/test/ui/callsite-capture-keeps-state.test.ts

@@ -65,6 +65,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/callsite-capture-server-frame-wins.test.ts

@@ -87,6 +87,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/callsite-capture-walk-through.test.ts

@@ -44,7 +44,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
   return {
     slots: {}, render, clear: vi.fn(), clearBySource: vi.fn(), clearById: vi.fn(), clearAll: vi.fn(),
     subscribe: vi.fn(() => () => undefined), hasContent: vi.fn(() => false), getContent: vi.fn(() => null),
-    getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
+    getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), setDeclaredTraitOrder: vi.fn(), updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
   };
 }
 

package/templates/almadar-renderers-typescript/test/ui/callsite-child-deferred-mount.test.ts

@@ -57,7 +57,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
   return {
     slots: {}, render, clear: vi.fn(), clearBySource: vi.fn(), clearById: vi.fn(), clearAll: vi.fn(),
     subscribe: vi.fn(() => () => undefined), hasContent: vi.fn(() => false), getContent: vi.fn(() => null),
-    getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
+    getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), setDeclaredTraitOrder: vi.fn(), updateTraitContent: vi.fn((traitName: string, content: object) => render({ ...content, sourceTrait: traitName })),
   };
 }
 

package/templates/almadar-renderers-typescript/test/ui/chat-bar-focus-request.test.tsx

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+/**
+ * A focus request with text puts it in the input for the user to edit; a new id
+ * puts the next text; the same id re-rendered leaves what the user typed alone.
+ */
+import React from 'react';
+import { afterEach, describe, it, expect } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { ChatBar } from '../../src/components/core/organisms/ChatBar';
+
+afterEach(cleanup);
+
+function textarea(): HTMLTextAreaElement {
+  const el = screen.getByRole('textbox');
+  if (!(el instanceof HTMLTextAreaElement)) throw new Error('chat input is not a textarea');
+  return el;
+}
+
+describe('ChatBar focus request', () => {
+  it('fills the input with the requested text and focuses it', () => {
+    render(<ChatBar sendEvent="ASK" focusRequest={{ id: 1, text: 'Preveri dostopnost https://' }} />);
+    expect(textarea().value).toBe('Preveri dostopnost https://');
+    expect(document.activeElement).toBe(textarea());
+  });
+
+  it('a new id replaces the input with the new text', () => {
+    const { rerender } = render(<ChatBar sendEvent="ASK" focusRequest={{ id: 1, text: 'first' }} />);
+    rerender(<ChatBar sendEvent="ASK" focusRequest={{ id: 2, text: 'second' }} />);
+    expect(textarea().value).toBe('second');
+  });
+
+  it('edge: the same request re-rendered keeps what the user typed', () => {
+    const { rerender } = render(<ChatBar sendEvent="ASK" focusRequest={{ id: 1, text: 'template' }} />);
+    fireEvent.change(textarea(), { target: { value: 'template edited' } });
+    rerender(<ChatBar sendEvent="ASK" focusRequest={{ id: 1, text: 'template' }} />);
+    expect(textarea().value).toBe('template edited');
+  });
+
+  it('control: a request without text focuses and leaves the input as it is', () => {
+    const { rerender } = render(<ChatBar sendEvent="ASK" />);
+    fireEvent.change(textarea(), { target: { value: 'typed' } });
+    rerender(<ChatBar sendEvent="ASK" focusRequest={{ id: 1, placeholder: 'Ask about it' }} />);
+    expect(textarea().value).toBe('typed');
+  });
+});

package/templates/almadar-renderers-typescript/test/ui/dialog-focus-no-scroll.test.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import { useDialogBehavior } from '../../src/core/hooks/useDialogBehavior';
+
+function Dialog({ open }: { open: boolean }): React.ReactElement | null {
+  const ref = React.useRef<HTMLDivElement>(null);
+  useDialogBehavior({ open, containerRef: ref, onEscape: () => {} });
+  return open ? <div ref={ref} role="dialog"><button>inside</button></div> : <div ref={ref} />;
+}
+
+describe('a dialog moves focus without scrolling the page behind it', () => {
+  it('handing focus back to the opener on close does not scroll', () => {
+    const opener = document.createElement('button');
+    document.body.appendChild(opener);
+    opener.focus();
+    const spy = vi.spyOn(opener, 'focus');
+    const { rerender } = render(<Dialog open />);
+    rerender(<Dialog open={false} />);
+    expect(spy).toHaveBeenCalledWith({ preventScroll: true });
+    opener.remove();
+  });
+
+  it('control: focus does return to the opener', () => {
+    const opener = document.createElement('button');
+    document.body.appendChild(opener);
+    opener.focus();
+    const { rerender } = render(<Dialog open />);
+    rerender(<Dialog open={false} />);
+    expect(document.activeElement).toBe(opener);
+    opener.remove();
+  });
+});

package/templates/almadar-renderers-typescript/test/ui/drawing-surfaces.literal-ban.test.ts

@@ -17,12 +17,6 @@ const HEX = /['"`]#[0-9a-fA-F]{3,8}\b/;
 /** Engine fallbacks still carrying literals (G-UI-066). Remove an entry when its file is clean. */
 const EXEMPT = new Set([
   'components/game/atoms/MiniMap.tsx',
-  'lib/drawable/three/Lighting3D.tsx',
-  'lib/drawable/three/Scene3D.tsx',
-  'lib/drawable/three/mesh3d.tsx',
-  'lib/drawable/three/DrawMesh3D.tsx',
-  'lib/drawable/three/ModelLoader.tsx',
-  'lib/drawable/three/hooks/useThree.ts',
   'lib/webPainter2d.ts',
 ]);
 
@@ -48,7 +42,7 @@ const drawingFiles = SCAN_DIRS.flatMap((d) => walk(path.join(ROOT, d)))
 describe('drawing surfaces carry no hardcoded colors', () => {
   it('finds the drawing surfaces it guards', () => {
     const rels = drawingFiles.map((f) => f.rel);
-    for (const known of ['components/learning/atoms/LearningCanvas.tsx', 'components/core/molecules/GraphCanvas.tsx', 'components/game/molecules/Canvas2D.tsx', 'lib/drawable/three/Canvas3DHost.tsx']) {
+    for (const known of ['components/core/molecules/GraphCanvas.tsx', 'components/game/molecules/Canvas2D.tsx']) {
       expect(rels).toContain(known);
     }
   });

package/templates/almadar-renderers-typescript/test/ui/game-keyboard-routing.test.ts

@@ -88,6 +88,7 @@ function stubSlots(): UISlotManager {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/kernel-engine.test.tsx

@@ -254,7 +254,7 @@ describeKernel('useTraitStateMachine on the kernel engine', () => {
     return {
       slots: {}, render: vi.fn(() => 'id'), clear: vi.fn(), clearBySource: vi.fn(), clearById: vi.fn(), clearAll: vi.fn(),
       subscribe: vi.fn(() => () => undefined), hasContent: vi.fn(() => false), getContent: vi.fn(() => null),
-      getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), updateTraitContent: vi.fn(() => 'id'),
+      getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), setDeclaredTraitOrder: vi.fn(), updateTraitContent: vi.fn(() => 'id'),
     };
   }
 

package/templates/almadar-renderers-typescript/test/ui/listen-source-routing.test.ts

@@ -81,6 +81,7 @@ function stubSlots(): UISlotManager {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/mount-lifecycle-once.test.ts

@@ -49,6 +49,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/multi-source-slot-scope.test.ts

@@ -85,4 +85,33 @@ describe('multi-source slot aggregation — trait attribution', () => {
     expect(children[0]._sourceTrait).toBeUndefined();
     expect(children[1]._sourceTrait).toBe('RealTrait');
   });
+
+  it('G-ORBITAL-SHELL-TYPESCRIPT-040: stacks by the declared trait order, not write timing', () => {
+    const { result } = renderHook(() => useUISlotManager());
+
+    act(() => {
+      result.current.setDeclaredTraitOrder(['PicksHeader', 'PicksList']);
+      result.current.render({ target: 'main', pattern: 'data-grid', sourceTrait: 'PicksList' });
+      result.current.render({ target: 'main', pattern: 'stat-display', sourceTrait: 'PicksHeader' });
+    });
+
+    const stackProps = result.current.slots['main']?.props;
+    if (typeof stackProps === 'string' || stackProps === undefined) throw new Error(`expected object props, got ${typeof stackProps}`);
+    expect(childrenOf(stackProps).map((c) => c._sourceTrait)).toEqual(['PicksHeader', 'PicksList']);
+  });
+
+  it('G-ORBITAL-SHELL-TYPESCRIPT-040 control: an undeclared writer follows the declared ones in write order', () => {
+    const { result } = renderHook(() => useUISlotManager());
+
+    act(() => {
+      result.current.render({ target: 'main', pattern: 'data-grid', sourceTrait: 'Stray' });
+      result.current.render({ target: 'main', pattern: 'stat-display', sourceTrait: 'B' });
+      result.current.render({ target: 'main', pattern: 'stat-display', sourceTrait: 'A' });
+      result.current.setDeclaredTraitOrder(['A', 'B']);
+    });
+
+    const stackProps = result.current.slots['main']?.props;
+    if (typeof stackProps === 'string' || stackProps === undefined) throw new Error(`expected object props, got ${typeof stackProps}`);
+    expect(childrenOf(stackProps).map((c) => c._sourceTrait)).toEqual(['A', 'B', 'Stray']);
+  });
 });

package/templates/almadar-renderers-typescript/test/ui/off-page-trait-effects.test.ts

@@ -40,6 +40,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn>; update
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/reconcile-slot-content.test.ts

@@ -82,11 +82,28 @@ describe('reconcileSlotProps', () => {
         expect(reconcileSlotProps(prev, diff).equal).toBe(false);
     });
 
-    it('React elements and functions compare by identity only', () => {
-        const el = React.createElement('div');
+    it('a React element rebuilt with the same type, key, ref and props is equal and keeps the previous element', () => {
+        const prev = React.createElement('div', { key: 'k', title: 'a' }, React.createElement('span', null, 'x'));
+        const next = React.createElement('div', { key: 'k', title: 'a' }, React.createElement('span', null, 'x'));
+        const result = reconcileSlotProps({ c: prev }, { c: next });
+        expect(result.equal).toBe(true);
+        expect((result.value as { c: SlotPropValue }).c).toBe(prev);
+    });
+
+    it('control: a rebuilt element with another type, key, prop or callback is not equal', () => {
+        const base = (): React.ReactElement => React.createElement('div', { key: 'k', title: 'a' });
+        expect(reconcileSlotProps({ c: base() }, { c: React.createElement('section', { key: 'k', title: 'a' }) }).equal).toBe(false);
+        expect(reconcileSlotProps({ c: base() }, { c: React.createElement('div', { key: 'j', title: 'a' }) }).equal).toBe(false);
+        expect(reconcileSlotProps({ c: base() }, { c: React.createElement('div', { key: 'k', title: 'b' }) }).equal).toBe(false);
+        const onClick = (): void => undefined;
+        expect(reconcileSlotProps(
+            { c: React.createElement('button', { onClick }) },
+            { c: React.createElement('button', { onClick: (): void => undefined }) },
+        ).equal).toBe(false);
+    });
+
+    it('functions compare by identity only', () => {
         const fn = (): void => undefined;
-        expect(reconcileSlotProps({ c: el }, { c: el }).equal).toBe(true);
-        expect(reconcileSlotProps({ c: el }, { c: React.createElement('div') }).equal).toBe(false);
         expect(reconcileSlotProps({ f: fn as SlotPropValue }, { f: fn as SlotPropValue }).equal).toBe(true);
         expect(reconcileSlotProps({ f: fn as SlotPropValue }, { f: ((): void => undefined) as SlotPropValue }).equal).toBe(false);
     });

package/templates/almadar-renderers-typescript/test/ui/server-push-paints.test.ts

@@ -59,6 +59,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/slot-flush-embedded-portal.test.ts

@@ -27,6 +27,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn>; update
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/slot-flush-host-ask.test.ts

@@ -22,6 +22,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/slot-flush-identity.test.tsx

@@ -85,3 +85,75 @@ describe('useUISlots flush sink — structural sharing', () => {
         expect(result.current.slots['main']?.pattern).toBe('stack');
     });
 });
+
+describe('useUISlots embedded trait content — structural sharing', () => {
+    it('an all-equal re-write of an embedded trait notifies no subscriber', () => {
+        const { result } = renderHook(() => useUISlotManager());
+        let notified = 0;
+        act(() => {
+            result.current.subscribeTrait('Child', () => { notified += 1; });
+            result.current.updateTraitContent('Child', { pattern: 'stack', props: descriptor('a'), slot: 'main', priority: 0 });
+        });
+        const first = result.current.getTraitContent('Child');
+        expect(notified).toBe(1);
+        act(() => {
+            result.current.updateTraitContent('Child', { pattern: 'stack', props: descriptor('a'), slot: 'main', priority: 0 });
+        });
+        expect(notified).toBe(1);
+        expect(result.current.getTraitContent('Child')).toBe(first);
+    });
+
+    it('control: a changed embedded write notifies with the new content', () => {
+        const { result } = renderHook(() => useUISlotManager());
+        let notified = 0;
+        act(() => {
+            result.current.subscribeTrait('Child', () => { notified += 1; });
+            result.current.updateTraitContent('Child', { pattern: 'stack', props: descriptor('a'), slot: 'main', priority: 0 });
+            result.current.updateTraitContent('Child', { pattern: 'stack', props: descriptor('b'), slot: 'main', priority: 0 });
+        });
+        expect(notified).toBe(2);
+        const props = result.current.getTraitContent('Child')?.props;
+        if (typeof props === 'string' || props === undefined) throw new Error(`expected object props, got ${typeof props}`);
+        expect((props.children as ReadonlyArray<{ note: string }>)[0].note).toBe('b');
+    });
+});
+
+describe('useUISlots flush sink — an identical write schedules nothing', () => {
+    it('re-writing the same content does not re-render the slot manager', () => {
+        let renders = 0;
+        const { result } = renderHook(() => { renders += 1; return useUISlotManager(); });
+        act(() => {
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+        });
+        const settled = renders;
+        act(() => {
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+        });
+        expect(renders).toBe(settled);
+    });
+
+    it('control: A, then B, then A again ends on A', () => {
+        const { result } = renderHook(() => useUISlotManager());
+        act(() => {
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('b') });
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+        });
+        const props = result.current.slots['main']?.props;
+        if (typeof props === 'string' || props === undefined) throw new Error(`expected object props, got ${typeof props}`);
+        expect((props.children as ReadonlyArray<{ note: string }>)[0].note).toBe('a');
+    });
+
+    it('control: the same content written after its source was cleared is shown again', () => {
+        const { result } = renderHook(() => useUISlotManager());
+        act(() => {
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+        });
+        act(() => { result.current.clearBySource('main', 'World'); });
+        expect(result.current.slots['main']).toBeNull();
+        act(() => {
+            result.current.render({ target: 'main', pattern: 'game-shell', sourceTrait: 'World', props: descriptor('a') });
+        });
+        expect(result.current.slots['main']?.pattern).toBe('game-shell');
+    });
+});

package/templates/almadar-renderers-typescript/test/ui/slot-flush-render-provenance.test.ts

@@ -24,6 +24,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn>; update
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/slot-flush-rows-changed.test.tsx

@@ -14,7 +14,7 @@ import type { RowSetResolver } from '../../src/lib/row-set-resolver';
 const slots: UISlotManager = {
   slots: {}, render: vi.fn(() => 'id'), clear: vi.fn(), clearBySource: vi.fn(), clearById: vi.fn(), clearAll: vi.fn(),
   subscribe: vi.fn(() => () => undefined), hasContent: vi.fn(() => false), getContent: vi.fn(() => null),
-  getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), updateTraitContent: vi.fn(() => 'id'),
+  getTraitContent: vi.fn(() => null), subscribeTrait: vi.fn(() => () => undefined), setDeclaredTraitOrder: vi.fn(), updateTraitContent: vi.fn(() => 'id'),
 };
 const table: JsonObject = { type: 'data-list', entity: { [ROW_SET_MARKER]: true, ref: { entityType: 'Task', ids: ['t1'], total: 1, query: {} } } };
 const effect = (repaint?: 'rows-changed'): ClientEffectByTrait => ({ traitName: 'Board', effect: ['render-ui', 'main', table], ...(repaint !== undefined ? { repaint } : {}) });

package/templates/almadar-renderers-typescript/test/ui/slot-flush-sexpr-props.test.ts

@@ -23,6 +23,7 @@ function stubSlots(): UISlotManager & { render: ReturnType<typeof vi.fn> } {
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/trait-binding-slot-cleanup.test.ts

@@ -141,6 +141,7 @@ function stubSlots(): UISlotManager & { clearBySource: Mock<UISlotManager['clear
     getContent: vi.fn(() => null),
     getTraitContent: vi.fn(() => null),
     subscribeTrait: vi.fn(() => () => undefined),
+    setDeclaredTraitOrder: vi.fn(),
     updateTraitContent: vi.fn(() => 'id'),
   };
 }

package/templates/almadar-renderers-typescript/test/ui/ui-slots-manager-settles.test.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { describe, it, expect } from 'vitest';
+import { act, render, renderHook } from '@testing-library/react';
+import { UISlotProvider, useUISlots } from '../../src/providers/UISlotContext';
+import { useUISlotManager } from '../../src/hooks/useUISlots';
+
+const LOOP_CAP = 30;
+
+function renderDeclaring(order: () => readonly string[]): { declares: () => number } {
+  let declares = 0;
+  const Host = (): null => {
+    const slots = useUISlots();
+    React.useEffect(() => {
+      if (declares >= LOOP_CAP) return;
+      declares += 1;
+      slots.setDeclaredTraitOrder(order());
+    }, [slots]);
+    return null;
+  };
+  render(<UISlotProvider><Host /></UISlotProvider>);
+  return { declares: () => declares };
+}
+
+describe('the UI slot manager settles', () => {
+  it('a host declaring the same trait order from an effect keyed on the manager settles after the one real change', async () => {
+    const { declares } = renderDeclaring(() => ['First', 'Second']);
+    await act(async () => { await new Promise((resolve) => setTimeout(resolve, 20)); });
+    expect(declares()).toBe(2);
+  });
+
+  it('edge: an order array rebuilt each time with the same names is the same order', () => {
+    const { result } = renderHook(() => useUISlotManager());
+    const before = result.current;
+    act(() => result.current.setDeclaredTraitOrder(['First', 'Second']));
+    const declared = result.current;
+    expect(declared).not.toBe(before);
+    act(() => result.current.setDeclaredTraitOrder(['First', 'Second']));
+    expect(result.current).toBe(declared);
+  });
+
+  it('control: a changed order is taken and reorders what the slot shows', () => {
+    const { result } = renderHook(() => useUISlotManager());
+    act(() => {
+      result.current.render({ target: 'main', pattern: 'typography', props: { content: 'b' }, sourceTrait: 'Second' });
+      result.current.render({ target: 'main', pattern: 'typography', props: { content: 'a' }, sourceTrait: 'First' });
+    });
+    act(() => result.current.setDeclaredTraitOrder(['First', 'Second']));
+    const firstOrder = JSON.stringify(result.current.slots.main);
+    act(() => result.current.setDeclaredTraitOrder(['Second', 'First']));
+    expect(JSON.stringify(result.current.slots.main)).not.toBe(firstOrder);
+  });
+
+  it('the manager keeps its identity across a re-render that changed nothing', () => {
+    const { result, rerender } = renderHook(() => useUISlotManager());
+    const before = result.current;
+    rerender();
+    expect(result.current).toBe(before);
+  });
+
+  it('control: the manager changes identity when a slot paints, so its readers see it', () => {
+    const { result } = renderHook(() => useUISlotManager());
+    const before = result.current;
+    act(() => {
+      result.current.render({ target: 'main', pattern: 'typography', props: { content: 'x' }, sourceTrait: 'Painter' });
+    });
+    expect(result.current).not.toBe(before);
+    expect(result.current.slots.main).not.toBeNull();
+  });
+});

package/templates/almadar-renderers-typescript/tsup.config.ts

@@ -17,7 +17,6 @@ const ESM_ENTRIES = {
   'renderer/index': 'src/renderer/index.ts',
   'runtime/index': 'src/preview/index.ts',
   'lib/index': 'src/lib/index.ts',
-  'three/index': 'src/lib/drawable/three/index.ts',
   'avl/index': 'src/avl/index.ts',
   'storage/browser/index': 'src/storage/browser/index.ts',
   'auth/browser/index': 'src/auth/browser/index.ts',

package/templates/almadar-renderers-typescript/vitest.config.ts

@@ -1,8 +1,5 @@
-import { createRequire } from 'node:module';
 import { defineConfig } from 'vitest/config';
 
-const THREE_ENTRY = createRequire(import.meta.url).resolve('three');
-
 const RENDER_KERNEL_SETUP = ['./vitest.setup.ts', './test/ui/helpers/kernel-evaluator.setup.ts', './test/ui/helpers/kernel-engine-default.setup.ts'];
 
 export default defineConfig({
@@ -23,15 +20,12 @@ export default defineConfig({
           include: ['src/core/**/__tests__/*.test.{ts,tsx}'],
           environment: 'jsdom',
           globals: true,
-          setupFiles: ['./vitest.setup.ts'],
+          setupFiles: ['./vitest.setup.ts', './test/ui/helpers/kernel-evaluator.setup.ts'],
         },
       },
       {
-        // r3f is bundled into the transform so its `three` is the one the components import (one instance, one Color class).
-        resolve: { dedupe: ['three'], alias: [{ find: /^three$/, replacement: THREE_ENTRY }] },
         // Every circuit runs on the kernel: the setup supplies the test kernel where a host would pass its loader.
         test: {
-          server: { deps: { inline: [/@react-three\/fiber/] } },
           name: 'render',
           include: ['test/ui/**/*.test.{ts,tsx}', 'src/**/__tests__/**/*.test.{ts,tsx}'],
           exclude: [

package/templates/almadar-shell/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+**/node_modules
+**/dist
+.git
+.env

package/templates/almadar-shell/.env.example

@@ -0,0 +1,45 @@
+# ── Server ────────────────────────────────────────────────────────────────
+PORT=3030
+NODE_ENV=production
+# Comma-separated allowlist of browser origins permitted to call the API.
+CORS_ORIGIN=http://localhost:5173,http://localhost:5174
+
+# ── Auth: who @user is ────────────────────────────────────────────────────
+# Every request is identified by its verified ID token, or is anonymous; the
+# app's own guards decide what an anonymous visitor may do.
+# AUTH_PROVIDER=firebase        # firebase (default) | oidc
+# firebase: Firebase Auth / Identity Platform, verified with the project below.
+# oidc (Auth0, Okta, Keycloak, Cognito, Clerk…): tokens verified against the issuer's keys.
+# OIDC_ISSUER_URL=https://your-tenant.example.com/
+# OIDC_AUDIENCE=your-api-identifier
+
+# ── Firebase project (auth verification) ──
+# FIREBASE_PROJECT_ID=
+# FIREBASE_CLIENT_EMAIL=
+# FIREBASE_PRIVATE_KEY=
+# or: FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
+
+# ── Database ──────────────────────────────────────────────────────────────
+# The row store is declared by the app (`store:` with a std driver); no variable selects it.
+# USE_MOCK_DATA=true            # LOCAL DEV ONLY: integrations answer mock data
+
+# ── Local dev on the Firebase emulators (never in production) ─────────────
+# Personas are the app's [identity] rows signed in as Auth-emulator users.
+# FIREBASE_PROJECT_ID=demo-almadar
+# FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
+# FIRESTORE_EMULATOR_HOST=127.0.0.1:8080
+#
+# The server refuses to start with NODE_ENV=production when the auth config is
+# incomplete, an emulator host is set, or USE_MOCK_DATA=true.
+
+# ── Client (packages/client/.env) ─────────────────────────────────────────
+# VITE_API_URL=http://localhost:3030
+# VITE_APP_FIREBASE_API_KEY=
+# VITE_APP_FIREBASE_PROJECT_ID=
+# VITE_APP_FIREBASE_AUTH_DOMAIN=
+# dev: VITE_FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099 with VITE_APP_FIREBASE_API_KEY=emulator
+#      and VITE_APP_FIREBASE_PROJECT_ID=demo-almadar
+
+# ── Integration keys ──────────────────────────────────────────────────────
+# Listed per service in SECRETS.md; a production server refuses to start
+# without the required key of any service the app calls.