Dinou Architecture & Runtime Engine

2.1. The React 19 Dual Condition Conflict

React 19 imposes a strict module-resolution constraint: Server Components must be imported under the "react-server" export condition (which disables client-only hooks such as useState and useEffect, as well as react-dom/server). Conversely, SSR rendering requires client conditions ("browser" or react-dom/server.edge).

Importing both engines within the same unisolated module graph throws a fatal runtime panic:

Earlier meta-frameworks circumvented this in Node.js by spawning an external child process via child_process.fork(). However, this introduced process serialization latency, doubled server memory consumption, and made deployment to Edge runtimes (Cloudflare Workers, Deno Deploy) impossible because Edge V8 isolates do not support spawning OS processes.

2.2. The 3-Pass Compilation Model (Pass A, Pass B, Pass C)

Dinou v7 resolves this conflict Ahead-of-Time (AOT) through an isolated, in-memory 3-pass compilation pipeline:

2.3. In-Memory Dev Server & SWC Disk-Mirror

During development, Dinou v7 stores all generated chunks, manifests, sourcemaps, and CSS in a global in-memory buffer:

3.1. 100% State Preservation & Zero Remounts

Horizontal segmentation guarantees that layout components never unmount or re-execute during client-side navigation between sibling routes:

• Active media playback: Audio and video players embedded in the layout continue playing seamlessly with 0 interruption.
• Form & filter states: Sidebar filters, search queries, and collapsible menus retain their exact state.
• Scroll position: Layout-level containers maintain their scroll coordinates across page transitions.

3.2. layout_functions for Independent Layout ISR

Layouts can declare their own independent caching, validation, and metadata lifecycle using layout_functions.ts (or named exports in layout.tsx):

// src/dashboard/layout_functions.ts
// ⚡ Cache the layout shell for 1 hour independently of child pages:
export const revalidate = 3600;

// Assign tags for granular invalidation:
export const tags = ["dashboard-shell", "user-nav"];

export async function validateParams(params) {
  // Validate route parameters before evaluating layout
  return true;
}

This separation means that a child page with live SSR (revalidate = 0) can be rendered inside a layout shell that is cached statically or regenerated every hour.

5.1. Micro-ISR of Server Components & SWR

Wrap expensive Server Components in a cache slot. Stale content is served instantly while an asynchronous background task (via waitUntil) evaluates the component and updates the cache in the active StorageAdapter:

// src/analytics/page.tsx
import { DinouCacheSlot } from "dinou/server";

export default function AnalyticsPage() {
  return (
    <div className="dashboard-grid">
      <h1>Live Analytics</h1>
      
      {/* Caches this heavy Server Component for 60 seconds */}
      <DinouCacheSlot id="metrics-widget" tag="metrics-tag" revalidate={60}>
        <ExpensiveMetricsGraph />
      </DinouCacheSlot>
    </div>
  );
}

5.2. In-Place Client Live Refresh (refreshSlot)

Every <DinouCacheSlot> is automatically wrapped in a DinouCacheSlotBoundary. Client Components can programmatically re-render a single slot in place by calling refreshSlot(id) from "dinou" without triggering a full page reload:

"use client";
import { refreshSlot } from "dinou";

export function LiveRefreshButton() {
  return (
    <button 
      onClick={() => refreshSlot("metrics-widget")}
      className="btn-refresh"
    >
      Refresh Metrics Only
    </button>
  );
}

When refreshSlot("metrics-widget") fires, the client requests /____rsc_slot____/metrics-widget directly from the server and reconciles only that DOM subtree.

6.1. Static Prelude (0ms TTFB) & Streaming Dynamic Holes

// src/dashboard/page.tsx
import { Suspense } from "react";
import { getContext } from "dinou";

async function UserFeed() {
  const ctx = getContext();
  const user = ctx?.req?.cookies?.user || "Guest";
  const data = await fetchFeedForUser(user);
  return <FeedList items={data} />;
}

export default function DashboardPage() {
  return (
    <div>
      {/* 🚀 Static Shell: Sent at 0ms TTFB */}
      <header><h1>Dashboard</h1></header>

      {/* ⚡ Dynamic Hole: Streamed and replaced on the fly */}
      <Suspense fallback={<div className="skeleton">Loading feed...</div>}>
        <UserFeed />
      </Suspense>
    </div>
  );
}

6.2. Configuration Hierarchy (Global, Layout, Page)

7.1. Elimination of HTML Double-Wrapping in Error SSR

When a route crashed during Server-Side Rendering, earlier implementations checked whether the root JSX was an <html> element. When an application layout was applied, the root was the layout function, prompting the server to blindly inject an emergency <html><body> shell outside the layout. This produced nested <html> tags, triggering fatal hydration mismatches in React 19.

Dinou v7 tracks layoutApplied in getErrorJSX. When an application layout is present, error JSX is injected directly into the layout's active content area. The document structure remains valid HTML, and interactive navigation elements (sidebars, headers) remain fully operational.

7.2. Handling SuspenseException with use()

In React 19, reading pending promises inside component bodies with use(errorPromise) intentionally throws an internal suspension signal (SuspenseException). If executed inside an eager JavaScript try / catch block, the catch intercepted this signal as if it were a fatal runtime crash, preventing custom error.tsx components from ever rendering.

Dinou v7 decouples SlotErrorRenderer from eager try / catch blocks and wraps it in a native React <Suspense fallback={null}> boundary. Once the error chunk resolves, React smoothly renders your custom error.tsx component with its error and reset props.

7.3. Two-Level Error Boundaries with Clean Navigation Reset

Earlier frameworks reset error boundaries on navigation by mutating <ErrorBoundary key={pathname}>. However, mutating key indiscriminately destroys and remounts the DOM on every healthy navigation, wiping form inputs and scroll positions.

Dinou v7 implements a Two-Level Error Boundary Architecture in dinou/core/slot.js:

┌────────────────────────────────────────────────────────┐
│  SlotErrorBoundary (Level 1 - State-Preserving Reset)  │
│  - Healthy navigation: Key unchanged, state intact.    │
│  - On error: Listens to resetKey & resets state.       │
│  ┌──────────────────────────────────────────────────┐  │
│  │  InnerErrorBoundary (Level 2 - Error Guard)      │  │
│  │  - Guards against bugs inside custom error.tsx   │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │  <Suspense fallback={null}>                │  │  │
│  │  │    <SlotErrorRenderer /> (use(errorPromise)│  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────┘

• Level 1 (SlotErrorBoundary): Preserves DOM and state on healthy navigations. Only when hasError === true does componentDidUpdate check the compound navigation key (resetKey: ${route}::${navCount}) to reset the error state cleanly.
• Level 2 (InnerErrorBoundary): Fail-safe guard that catches bugs or unhandled exceptions inside the developer's custom error.tsx component, safely displaying DefaultDevError and preventing a white screen of death.