Real-World Duct UI: Granular State Management in a Word Game

By navilan
Examples Tutorial Real-World Article State Management

Explore how Duct UI powers a multi-board word puzzle with granular observable state management, component refs, and SSG-compatible architecture. A practical example of building interactive games with surgical DOM updates and explicit memory management.

Fourdle

Live Example: Fourdle

Website: https://fourdle.puthir.org/
Source Code: https://github.com/puthirali/fourdle

This word puzzle game showcases Duct UI’s power for building stateful applications with fine-grained reactivity. The game manages multiple simultaneous Wordle-style boards with slot-level state subscriptions, demonstrating advanced patterns for performance optimization and memory management.

Key Patterns Demonstrated

1. Granular Observable State Management

The core introduction is a state service with surgical precision updates—components subscribe to individual slots, not entire boards. This is simply a template to show
how such a service can be constructed. A robust structure can be built upon this
specific model to make event based state management centralized, de-centralized or
federated.

Implementation Highlights:

  • Namespace-based event subscriptions: slot:${boardIndex}:${entryIndex}:${slotIndex}
  • Change detection computes deltas between old and new state
  • Only changed slots/entries/boards emit events
  • Pure function separation for state computations

See it live: Visit fourdle.puthir.org and notice how only the slots you type into update, not the entire board.

Technical approach: The state service computes granular changes and emits targeted events, allowing components to subscribe only to their specific data.

2. Render/Bind Lifecycle Separation

The application strictly separates pure rendering from side effects using Duct’s render/bind pattern.

Architecture Features:

  • Pure Render Functions: Return JSX with no side effects (SSG-compatible)
  • Bind Lifecycle: All subscriptions, DOM manipulation, and cleanup
  • Explicit Cleanup: release() functions prevent memory leaks
  • SSG Constraints: localStorage access only in bind(), never in render()

See it in action: The game pre-renders statically for instant loading, then hydrates with client-side state.

Source code reference: Every component in src/components/ follows this pattern consistently.

3. Component Refs for Parent-Child Communication

The app demonstrates type-safe parent-child communication using Duct’s createRef pattern.

Communication Patterns:

  • Ref Creation: const helpModalRef = createRef<HelpModalLogic>()
  • Logic Exposure: Components expose methods via BindReturn<ComponentLogic>
  • Parent Control: Parents call helpModalRef.current?.open()
  • Type Safety: Full TypeScript support for exposed APIs
// From App.tsx - controlling modals via refs
const helpModalRef = createRef<HelpModalLogic>()

<Header
  on:help-click={() => {
    const modalLogic = helpModalRef.current
    if (modalLogic) {
      modalLogic.open()
    }
  }}
/>
<HelpModal isOpen={false} ref={helpModalRef} />

4. Manual DOM Updates with Event Re-attachment

The interface demonstrates the innerHTML re-rendering pattern with manual event listener management.

Component Integration:

  • Dynamic Content: Using JSX helper functions for re-renderable content
  • Event Re-attachment: Listeners manually re-added after innerHTML updates
  • State in Bind: Component state stored in bind closure, not React state
  • Controlled Updates: Explicit renderTabs() calls, no automatic re-renders

Source reference: SummaryModal.tsx shows complex dynamic tab rendering with event re-attachment.

5. Explicit Memory Management

The application provides clear examples of subscription cleanup and memory leak prevention.

Memory Management Features:

  • Symmetric on()/off() calls for all subscriptions
  • Event listener cleanup in release()
  • Timeout cleanup with stored timeout IDs

Check how every component’s bind() function returns a release() that cleans up all subscriptions.

Architecture Deep Dive

Granular State Change Detection

// From state-service.ts - computing granular changes
function computeChanges(oldState: State, newState: State): GranularChange[] {
  const changes: GranularChange[] = []

  oldState.boards.forEach((oldBoard, boardIndex) => {
    const newBoard = newState.boards[boardIndex]

    // Compare each entry
    oldBoard.board.entries.forEach((oldEntry, entryIndex) => {
      const newEntry = newBoard.board.entries[entryIndex]

      // Compare each slot
      for (let slotIndex = 0; slotIndex < 5; slotIndex++) {
        const oldChar = oldEntry.chars[slotIndex]
        const newChar = newEntry.chars[slotIndex]

        if (oldChar?.char !== newChar?.char || oldChar?.mode !== newChar?.mode) {
          changes.push({
            type: 'slot',
            boardIndex,
            entryIndex,
            slotIndex,
            data: { char: newChar, isCommitted: newEntry.isCommitted }
          })
        }
      }
    })
  })

  return changes
}

Component Subscription Pattern

// From Slot.tsx - subscribing to slot-specific changes
function bind(el: HTMLElement, _eventEmitter: any, props: SlotProps): BindReturn<SlotLogic> {
  const { boardIndex, entryIndex, slotIndex } = props
  const stateService = getStateService()

  // Subscribe to granular slot-specific event
  const eventName = `slot:${boardIndex}:${entryIndex}:${slotIndex}` as any
  const handleSlotChange = (slotData: any) => {
    const keyCap = slotData.char || emptyChar
    const text = keyCap.char.trim() === "" ? "\u00A0" : keyCap.char.toUpperCase()

    // Direct DOM updates
    if (frontFace) frontFace.textContent = text
    if (backFace) backFace.textContent = text

    // Update classes
    el.classList.toggle('flipped', slotData.isCommitted)
    if (backFace) {
      backFace.className = `slot-face slot-back mode-${keyCap.mode}`
    }
  }

  stateService.on(eventName, handleSlotChange)

  return {
    release: () => {
      stateService.off(eventName, handleSlotChange)
    }
  }
}

Technical Stack

  • Framework: Duct UI (SSG with client-side hydration)
  • State Management: Observable pattern with lib0/observable
  • Build Tool: Vite + @duct-ui/cli
  • Styling: Tailwind CSS 4 + DaisyUI
  • Animations: CSS transforms + @formkit/auto-animate
  • Type Safety: TypeScript with strict mode
  • Package Manager: pnpm
  • Deployment: Static site generation

Running Locally

To explore this example locally:

# Clone the repository
git clone https://github.com/puthirali/fourdle.git
cd fourdle

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

Key Takeaways

This real-world example demonstrates:

  1. Granular Subscriptions: Slot-level event subscriptions for surgical DOM updates
  2. Render/Bind Separation: SSG-compatible architecture with clear lifecycle boundaries
  3. Component Refs: Type-safe parent-child communication without prop drilling
  4. Manual Memory Management: Explicit cleanup patterns for subscription lifecycle
  5. Observable Singleton: Centralized state service with granular event emission
  6. Dynamic Re-rendering: innerHTML pattern with event listener re-attachment

Code Examples to Study

Granular State Service

Examine state-service.ts to understand change detection, observable events, and the singleton pattern (495 lines of state management gold).

Render/Bind Pattern

Study Slot.tsx for the canonical example: pure render() function with all side effects in bind().

Component Refs

See App.tsx for how parent components control modals using createRef.

Dynamic Content Re-rendering

Observe SummaryModal.tsx for the innerHTML pattern with manual event re-attachment.

Memory Management

Every component demonstrates proper cleanup—check the release() functions to see subscription cleanup patterns.

Advanced Patterns Highlighted

1. Event Subscription Naming Convention

The app uses a consistent string-based event naming pattern:

// Slot-level: slot:boardIndex:entryIndex:slotIndex
stateService.on(`slot:${boardIndex}:${entryIndex}:${slotIndex}`, handler)

// Entry-level: entry:boardIndex:entryIndex
stateService.on(`entry:${boardIndex}:${entryIndex}`, handler)

// Board-level: board:boardIndex
stateService.on(`board:${boardIndex}`, handler)

// Keycap-level: keycap:character
stateService.on(`keycap:${char}`, handler)

This convention allows components to subscribe to exactly what they need.

2. SSG-Compatible State Access

// ❌ DON'T: This breaks SSG build
function render(props) {
  const savedMode = localStorage.getItem('game-mode')
  return <div>{savedMode}</div>
}

// ✅ DO: Access browser APIs only in bind
function bind(el) {
  const savedMode = localStorage.getItem('game-mode')
  // Use savedMode for client-side initialization
  return { release: () => {} }
}

3. Component Logic Exposure

// From HelpModal.tsx - exposing imperative API
export interface HelpModalLogic {
  open: () => void
  close: () => void
}

function bind(_el: HTMLElement): BindReturn<HelpModalLogic> {
  return {
    open: () => {
      const modalLogic = innerModalRef.current
      if (modalLogic?.show) {
        modalLogic.show()
      }
    },
    close: () => {
      const modalLogic = innerModalRef.current
      if (modalLogic?.hide) {
        modalLogic.hide()
      }
    },
    release: () => {}
  }
}

A High-Performance Game

This project showcases Duct UI’s capability for building interactive applications where performance matters. The granular subscription pattern means typing a letter updates only one slot, not 20+ components.

The combination of observable state, render/bind separation, and explicit memory management creates a responsive user experience that demonstrates production-ready architectural patterns.

Visit fourdle.puthir.org to play the game, and explore the source code to understand the granular state management implementation.

Share Your Duct UI Project!

Building games or interactive applications with Duct UI? We’d love to see your work!

Join the conversation: Share your projects, ask questions, and connect with the Duct UI community in our GitHub Discussions.

Whether you’re building games, data applications, or state-driven interfaces, your examples help demonstrate Duct UI’s architectural capabilities and inspire others.

Start a discussion about your Duct UI project at github.com/navilan/duct-ui/discussions

🔍
🔍
Start typing to search
Find pages, posts, and content across the site
↑↓ navigate↵ selectesc close
Press ⌘K to bring this up