Unified Positronic Content Architecture - Cache-first State Management

[joelteply]

Summary

This PR introduces the Unified Positronic Content Architecture - a cache-first, event-driven state management system that provides 60fps-capable UI responsiveness.

Key Architectural Changes

EntityCacheService (system/state/EntityCacheService.ts) - NEW

• Single source of truth for ALL entity data
• eventAddedIds tracking (entities from real-time events survive DB refresh)
• Subscribe/notify pattern with microtask batching
• Auto-subscribes to entity events when widgets subscribe

ContentService (system/state/ContentService.ts) - NEW

• Centralized orchestrator for open/switch/close operations
• Recipe awareness (looks up recipe ID for content types)
• Pre-populates EntityCacheService on content open
• Single place for URL updates (no more scattered pushState calls)

RoutingService (system/routing/RoutingService.ts) - ENHANCED

• Cache-first resolution (instant when entities already cached)
• Resolution order: local cache → EntityCache → DB
• Populates EntityCacheService on DB resolution

ChatWidget & EntityScroller - ENHANCED

• ChatWidget populates EntityCacheService when loading messages
• EntityScroller preserves event-added entities during refresh
• Fixed message disappearing on tab switch

Architecture Flow

URL → RoutingService (cache-first) → EntityCacheService
                                            ↓
ContentService (recipe-aware) ← opens → ContentItem
                                            ↓
Widgets (pure views) → subscribe → EntityCacheService
                                            ↑
Events → EntityCacheService (real-time updates)

Benefits

• 60fps capable: Instant cache reads vs DB queries
• No message flickering: Events update cache, cache drives UI
• Consistent state: Single source of truth across all widgets
• Recipe-aware: Content types linked to behavior templates

Test plan

• TypeScript compiles without errors
• Messages persist when switching tabs (eventAddedIds fix)
• URL updates when clicking tabs
• Cache populates on message load
• Full integration test after daemon issues resolved

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces the Unified Positronic Content Architecture, a cache-first state management system designed to achieve 60fps-capable UI responsiveness through event-driven entity caching and centralized content orchestration.

Changes:

• New EntityCacheService - Single source of truth for entity data with event subscription and microtask batching
• New ContentService - Centralized orchestrator for content operations with recipe awareness
• Enhanced RoutingService - Cache-first resolution pattern for instant navigation
• Widget migrations - Multiple widgets converted to ReactiveWidget/ReactiveListWidget patterns with Lit templates
• Event delegation - Memory-efficient message interaction handling via MessageEventDelegator

Reviewed changes

Copilot reviewed 178 out of 327 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
continuum-metrics.css/scss	Auto-generated SCSS compilation output with minified styles
continuum-emoter.css/scss	Auto-generated SCSS compilation output with minified styles
user-list.css/scss	Auto-generated SCSS compilation output with minified styles
room-list-widget.css/scss	Auto-generated SCSS compilation output with minified styles
chat-widget.scss	Auto-generated SCSS compilation output with minified styles
ContinuumMetricsWidget.ts	Complete rewrite using ReactiveWidget with Lit templates, added auto-detect time range
ContinuumEmoterWidget.ts	Added verbose logging helpers and event cleanup tracking
ContentTabsWidget.ts	Migrated to ReactiveWidget with contentState subscription pattern
UserListWidget.ts	Migrated to ReactiveListWidget with filter chips and targeted DOM updates
RoomListWidget.ts	Migrated to ReactiveListWidget with pageState subscription
ChatWidget.ts	Added signal-based state management, event delegation, optimistic updates
InfiniteScrollHelper.ts	Added verbose logging helpers throughout
ChatMessageRenderer.ts	Added verbose logging helper
ChatMessageLoader.ts	Added verbose logging helper
ChatMessageCache.ts	New file - localStorage-based message caching for instant tab switches
BaseMessageRowWidget.ts	Added verbose logging helper
URLCardAdapter.ts	Converted to static action handlers for event delegation
MessageEventDelegator.ts	New file - Single delegated event handler pattern for memory efficiency
universal-demo.html	Added ES module loading with async wait pattern

Files not reviewed (1)

• src/debug/jtag/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Silent catch block ignores all errors during unsubscribe. Consider logging errors in verbose mode to help debug cleanup issues: catch (e) { verbose() && console.warn('Unsubscribe error:', e); }

Suggested change

	try { unsub(); } catch { /* ignore */ }
	try {
	unsub();
	} catch (e) {
	verbose() && console.warn('Unsubscribe error:', e);
	}

[Copilot]

DOM selector uses string interpolation with unescaped personaId. If personaId contains special CSS selector characters (e.g., quotes, brackets), this query could fail or cause injection issues. Consider using CSS.escape() or a data-attribute approach: this.shadowRoot?.querySelector('[data-user-id]')?.filter(el => el.dataset.userId === personaId)

[Copilot]

Repeated verbose logging helper pattern across multiple files (appears in 10+ files). Consider extracting to a shared utility module to ensure consistency and reduce duplication: import { verbose } from '@system/utils/verbose';

Suggested change

	const verbose = () => typeof window !== 'undefined' && (window as any).JTAG_VERBOSE === true;
	import { verbose } from '@system/utils/verbose';

[Copilot]

Temporary ID generation uses timestamp + random string but is cast directly to UUID. This could cause type confusion since it doesn't match UUID format. Consider using a more explicit type like type TempMessageId = string & { __brand: 'temp' } or adding a 'temp-' prefix check in UUID validation.

[Copilot]

The $in operator usage in the filter suggests MongoDB-style queries, but this isn't documented. Add a comment explaining the query syntax expected by the data layer: // Uses MongoDB-style $in operator for batch ID lookup

Suggested change

	collection: UserEntity.collection,
	collection: UserEntity.collection,
	// Uses MongoDB-style $in operator for batch ID lookup

[Copilot]

The .closest('[data-action]') selector will match ANY ancestor with data-action, potentially triggering unintended handlers if nested elements both have data-action attributes. Consider adding a max depth check or container boundary: target.closest('.message-row [data-action]') to scope the search within message boundaries.

[Copilot]

Polling every 50ms for 5 seconds creates 100 timer callbacks. This is inefficient for module loading. Consider using a Promise-based approach with module import: const { jtag } = await import('/dist/index.js') or use a MutationObserver to detect when the global is set.

Suggested change

	<script type="module" src="/dist/index.js"></script>
	<script>
	let jtagSystem = null;
	let activeExample = null;
	let exampleConfig = null;
	// Wait for ES module to load and export jtag
	async function waitForJtag(maxWait = 5000) {
	const start = Date.now();
	while (typeof jtag === 'undefined' && Date.now() - start < maxWait) {
	await new Promise(r => setTimeout(r, 50));
	}
	if (typeof jtag === 'undefined') {
	throw new Error('JTAG module failed to load');
	}
	return jtag;
	}
	// Initialize JTAG system
	async function initializeJTAG() {
	try {
	log('core', '🔌 Waiting for JTAG module...');
	await waitForJtag();
	<script type="module">
	let jtagSystem = null;
	let activeExample = null;
	let exampleConfig = null;
	let jtag = null;
	// Initialize JTAG system
	async function initializeJTAG() {
	try {
	log('core', '🔌 Loading JTAG module...');
	const module = await import('/dist/index.js');
	jtag = module.jtag || module.default;
	if (!jtag) {
	throw new Error('JTAG export not found in module');
	}