@timber-js/app 0.2.0-alpha.167 → 0.2.0-alpha.168

package/dist/shims/image.d.ts

@@ -31,126 +31,6 @@ export type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
  * props (priority, quality, fill, placeholder, blurDataURL).
  */
 export declare function Image({ priority: _priority, quality: _quality, fill: _fill, placeholder: _placeholder, blurDataURL: _blurDataURL, ...rest }: ImageProps): import("react").DetailedReactHTMLElement<{
-    alt?: string | undefined;
-    crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
-    decoding?: "async" | "auto" | "sync" | undefined;
-    fetchPriority?: "high" | "low" | "auto" | undefined;
-    height?: number | string | undefined;
-    loading?: "eager" | "lazy" | undefined;
-    referrerPolicy?: import("react").HTMLAttributeReferrerPolicy | undefined;
-    sizes?: string | undefined;
-    src?: string | import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_IMG_SRC_TYPES[keyof import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_IMG_SRC_TYPES] | undefined;
-    srcSet?: string | undefined;
-    useMap?: string | undefined;
-    width?: number | string | undefined;
-    defaultChecked?: boolean | undefined;
-    defaultValue?: string | number | readonly string[] | undefined;
-    suppressContentEditableWarning?: boolean | undefined;
-    suppressHydrationWarning?: boolean | undefined;
-    accessKey?: string | undefined;
-    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
-    autoFocus?: boolean | undefined;
-    className?: string | undefined;
-    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
-    contextMenu?: string | undefined;
-    dir?: string | undefined;
-    draggable?: (boolean | "true" | "false") | undefined;
-    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
-    hidden?: boolean | undefined;
-    id?: string | undefined;
-    lang?: string | undefined;
-    nonce?: string | undefined;
-    slot?: string | undefined;
-    spellCheck?: (boolean | "true" | "false") | undefined;
-    style?: import("react").CSSProperties | undefined;
-    tabIndex?: number | undefined;
-    title?: string | undefined;
-    translate?: "yes" | "no" | undefined;
-    radioGroup?: string | undefined;
-    role?: import("react").AriaRole | undefined;
-    about?: string | undefined;
-    content?: string | undefined;
-    datatype?: string | undefined;
-    inlist?: any;
-    prefix?: string | undefined;
-    property?: string | undefined;
-    rel?: string | undefined;
-    resource?: string | undefined;
-    rev?: string | undefined;
-    typeof?: string | undefined;
-    vocab?: string | undefined;
-    autoCorrect?: string | undefined;
-    autoSave?: string | undefined;
-    color?: string | undefined;
-    itemProp?: string | undefined;
-    itemScope?: boolean | undefined;
-    itemType?: string | undefined;
-    itemID?: string | undefined;
-    itemRef?: string | undefined;
-    results?: number | undefined;
-    security?: string | undefined;
-    unselectable?: "on" | "off" | undefined;
-    popover?: "" | "auto" | "manual" | "hint" | undefined;
-    popoverTargetAction?: "toggle" | "show" | "hide" | undefined;
-    popoverTarget?: string | undefined;
-    inert?: boolean | undefined;
-    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
-    is?: string | undefined;
-    exportparts?: string | undefined;
-    part?: string | undefined;
-    "aria-activedescendant"?: string | undefined;
-    "aria-atomic"?: (boolean | "true" | "false") | undefined;
-    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
-    "aria-braillelabel"?: string | undefined;
-    "aria-brailleroledescription"?: string | undefined;
-    "aria-busy"?: (boolean | "true" | "false") | undefined;
-    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-colcount"?: number | undefined;
-    "aria-colindex"?: number | undefined;
-    "aria-colindextext"?: string | undefined;
-    "aria-colspan"?: number | undefined;
-    "aria-controls"?: string | undefined;
-    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined;
-    "aria-describedby"?: string | undefined;
-    "aria-description"?: string | undefined;
-    "aria-details"?: string | undefined;
-    "aria-disabled"?: (boolean | "true" | "false") | undefined;
-    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
-    "aria-errormessage"?: string | undefined;
-    "aria-expanded"?: (boolean | "true" | "false") | undefined;
-    "aria-flowto"?: string | undefined;
-    "aria-grabbed"?: (boolean | "true" | "false") | undefined;
-    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
-    "aria-hidden"?: (boolean | "true" | "false") | undefined;
-    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
-    "aria-keyshortcuts"?: string | undefined;
-    "aria-label"?: string | undefined;
-    "aria-labelledby"?: string | undefined;
-    "aria-level"?: number | undefined;
-    "aria-live"?: "off" | "assertive" | "polite" | undefined;
-    "aria-modal"?: (boolean | "true" | "false") | undefined;
-    "aria-multiline"?: (boolean | "true" | "false") | undefined;
-    "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
-    "aria-orientation"?: "horizontal" | "vertical" | undefined;
-    "aria-owns"?: string | undefined;
-    "aria-placeholder"?: string | undefined;
-    "aria-posinset"?: number | undefined;
-    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-readonly"?: (boolean | "true" | "false") | undefined;
-    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
-    "aria-required"?: (boolean | "true" | "false") | undefined;
-    "aria-roledescription"?: string | undefined;
-    "aria-rowcount"?: number | undefined;
-    "aria-rowindex"?: number | undefined;
-    "aria-rowindextext"?: string | undefined;
-    "aria-rowspan"?: number | undefined;
-    "aria-selected"?: (boolean | "true" | "false") | undefined;
-    "aria-setsize"?: number | undefined;
-    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
-    "aria-valuemax"?: number | undefined;
-    "aria-valuemin"?: number | undefined;
-    "aria-valuenow"?: number | undefined;
-    "aria-valuetext"?: string | undefined;
     children?: import("react").ReactNode | undefined;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
@@ -323,6 +203,126 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     onTransitionRunCapture?: import("react").TransitionEventHandler<HTMLImageElement> | undefined;
     onTransitionStart?: import("react").TransitionEventHandler<HTMLImageElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLImageElement> | undefined;
+    "aria-activedescendant"?: string | undefined;
+    "aria-atomic"?: ("false" | "true" | boolean) | undefined;
+    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
+    "aria-braillelabel"?: string | undefined;
+    "aria-brailleroledescription"?: string | undefined;
+    "aria-busy"?: ("false" | "true" | boolean) | undefined;
+    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
+    "aria-colcount"?: number | undefined;
+    "aria-colindex"?: number | undefined;
+    "aria-colindextext"?: string | undefined;
+    "aria-colspan"?: number | undefined;
+    "aria-controls"?: string | undefined;
+    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined;
+    "aria-describedby"?: string | undefined;
+    "aria-description"?: string | undefined;
+    "aria-details"?: string | undefined;
+    "aria-disabled"?: ("false" | "true" | boolean) | undefined;
+    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
+    "aria-errormessage"?: string | undefined;
+    "aria-expanded"?: ("false" | "true" | boolean) | undefined;
+    "aria-flowto"?: string | undefined;
+    "aria-grabbed"?: ("false" | "true" | boolean) | undefined;
+    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
+    "aria-hidden"?: ("false" | "true" | boolean) | undefined;
+    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
+    "aria-keyshortcuts"?: string | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-level"?: number | undefined;
+    "aria-live"?: "off" | "assertive" | "polite" | undefined;
+    "aria-modal"?: ("false" | "true" | boolean) | undefined;
+    "aria-multiline"?: ("false" | "true" | boolean) | undefined;
+    "aria-multiselectable"?: ("false" | "true" | boolean) | undefined;
+    "aria-orientation"?: "horizontal" | "vertical" | undefined;
+    "aria-owns"?: string | undefined;
+    "aria-placeholder"?: string | undefined;
+    "aria-posinset"?: number | undefined;
+    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
+    "aria-readonly"?: ("false" | "true" | boolean) | undefined;
+    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
+    "aria-required"?: ("false" | "true" | boolean) | undefined;
+    "aria-roledescription"?: string | undefined;
+    "aria-rowcount"?: number | undefined;
+    "aria-rowindex"?: number | undefined;
+    "aria-rowindextext"?: string | undefined;
+    "aria-rowspan"?: number | undefined;
+    "aria-selected"?: ("false" | "true" | boolean) | undefined;
+    "aria-setsize"?: number | undefined;
+    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
+    "aria-valuemax"?: number | undefined;
+    "aria-valuemin"?: number | undefined;
+    "aria-valuenow"?: number | undefined;
+    "aria-valuetext"?: string | undefined;
+    defaultChecked?: boolean | undefined;
+    defaultValue?: string | number | readonly string[] | undefined;
+    suppressContentEditableWarning?: boolean | undefined;
+    suppressHydrationWarning?: boolean | undefined;
+    accessKey?: string | undefined;
+    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
+    autoFocus?: boolean | undefined;
+    className?: string | undefined;
+    contentEditable?: ("false" | "true" | boolean) | "inherit" | "plaintext-only" | undefined;
+    contextMenu?: string | undefined;
+    dir?: string | undefined;
+    draggable?: ("false" | "true" | boolean) | undefined;
+    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
+    hidden?: boolean | undefined;
+    id?: string | undefined;
+    lang?: string | undefined;
+    nonce?: string | undefined;
+    slot?: string | undefined;
+    spellCheck?: ("false" | "true" | boolean) | undefined;
+    style?: import("react").CSSProperties | undefined;
+    tabIndex?: number | undefined;
+    title?: string | undefined;
+    translate?: "yes" | "no" | undefined;
+    radioGroup?: string | undefined;
+    role?: import("react").AriaRole | undefined;
+    about?: string | undefined;
+    content?: string | undefined;
+    datatype?: string | undefined;
+    inlist?: any;
+    prefix?: string | undefined;
+    property?: string | undefined;
+    rel?: string | undefined;
+    resource?: string | undefined;
+    rev?: string | undefined;
+    typeof?: string | undefined;
+    vocab?: string | undefined;
+    autoCorrect?: string | undefined;
+    autoSave?: string | undefined;
+    color?: string | undefined;
+    itemProp?: string | undefined;
+    itemScope?: boolean | undefined;
+    itemType?: string | undefined;
+    itemID?: string | undefined;
+    itemRef?: string | undefined;
+    results?: number | undefined;
+    security?: string | undefined;
+    unselectable?: "on" | "off" | undefined;
+    popover?: "" | "auto" | "manual" | "hint" | undefined;
+    popoverTargetAction?: "toggle" | "show" | "hide" | undefined;
+    popoverTarget?: string | undefined;
+    inert?: boolean | undefined;
+    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
+    is?: string | undefined;
+    exportparts?: string | undefined;
+    part?: string | undefined;
+    alt?: string | undefined;
+    crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
+    decoding?: "async" | "auto" | "sync" | undefined;
+    fetchPriority?: "high" | "low" | "auto" | undefined;
+    height?: number | string | undefined;
+    loading?: "eager" | "lazy" | undefined;
+    referrerPolicy?: import("react").HTMLAttributeReferrerPolicy | undefined;
+    sizes?: string | undefined;
+    src?: string | import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_IMG_SRC_TYPES[keyof import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_IMG_SRC_TYPES] | undefined;
+    srcSet?: string | undefined;
+    useMap?: string | undefined;
+    width?: number | string | undefined;
 }, HTMLElement>;
 export default Image;
 //# sourceMappingURL=image.d.ts.map

package/dist/shims/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/shims/image.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC,gBAAgB,CAAC,GAAG;IAC7D,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EACpB,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,KAAK,EACX,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,GAAG,IAAI,EACR,EAAE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAEZ;AAED,eAAe,KAAK,CAAC"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/shims/image.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC,gBAAgB,CAAC,GAAG;IAC7D,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EACpB,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,KAAK,EACX,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,GAAG,IAAI,EACR,EAAE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAEZ;eAEc,KAAK"}

package/docs/api/32-api-cache.mdx

@@ -56,6 +56,101 @@ cache.invalidate({ tag: 'products' });
 cache.invalidate({ key: 'user:abc' });
 ```
 
+## `cache.component(Component, options)`
+
+Wrap an async server component to cache its rendered RSC flight payload. The component renders once and subsequent requests splice the cached output into the live stream.
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+const PostBody = cache.component(
+  async function PostBody() {
+    const post = await getPost();
+    return <article>{post.content}</article>;
+  },
+  { prerender: true }
+);
+```
+
+`prerender` controls **when** the cache is populated. `ttl`/`tags` control **how it refreshes at runtime**. They are orthogonal — every combination is a meaningful tier:
+
+```tsx
+// Static: rendered at build, changes only on redeploy
+const BlogBody = cache.component(Body, { prerender: true });
+
+// Cached: rendered on first request, refreshed by TTL/tags
+const Pricing = cache.component(PricingTable, { ttl: 300, tags: ['pricing'] });
+
+// ISR: rendered at build, refreshable without a redeploy
+const DocsPage = cache.component(DocsBody, { prerender: true, ttl: 3600, tags: ['docs'] });
+```
+
+### `PrebuiltComponentOptions`
+
+| Option                          | Type                                          | Description                                                                                   |
+| ------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `prerender`                     | `boolean`                                     | Populate at build time via `generateStaticSegmentParams`                                      |
+| `ttl`                           | `number`                                      | Runtime freshness window in seconds                                                           |
+| `tags`                          | `string[] \| (props) => string[]`             | Tags for invalidation via `revalidateTag`                                                     |
+| `staleWhileRevalidate`          | `boolean`                                     | Serve stale while a background re-render refreshes                                            |
+| `slots`                         | `string[]`                                    | Prop names whose values are live React elements composed into the cached shell at request time |
+| `fallbackOnMissingSegmentParams`| `boolean`                                     | When `false`, a cache miss throws instead of rendering live (default: `true`)                  |
+
+Only module-scope declarations are transformed at build time:
+
+```ts
+// ✅ Transformed — eligible for prebuilding
+const Shell = cache.component(MyComponent, { prerender: true });
+
+// ❌ Not transformed — renders dynamically with a warning
+export default function Page() {
+  const Cached = cache.component(Inner, { ttl: 60 }); // nested scope
+}
+```
+
+### Tier Rules
+
+| Declaration                  | Enumerated params       | Unenumerated miss                    |
+| ---------------------------- | ----------------------- | ------------------------------------ |
+| `prerender` only             | Built at deploy         | Live render every time, never stored |
+| `ttl`/`tags` only            | —                       | Rendered + stored on first request   |
+| `prerender` + `ttl`/`tags`   | Built at deploy         | Rendered + stored on first request   |
+
+### Slots
+
+Cache a wrapper component's output as a shell with holes for live children:
+
+```tsx
+const Shell = cache.component(ExpensiveWrapper, {
+  ttl: 3600,
+  tags: ['marketing'],
+  slots: ['children'],
+});
+
+// Request time: the shell is served from cache; children render live.
+<Shell theme="dark"><LiveUserFeed /></Shell>
+```
+
+Slot props are excluded from the cache key — two instances with the same data props share one shell entry. Slots are **runtime tier only**: `prerender` is ignored when `slots` is active because the build cannot enumerate children variants.
+
+### Route-Level Sugar
+
+For "this whole route is static," export `prerender` from a page or layout instead of wrapping manually:
+
+```ts title="Fully static route"
+export const prerender = true;
+```
+
+```ts title="Route-level ISR"
+export const prerender = { ttl: 3600, tags: ['docs'] };
+```
+
+This desugars to wrapping the page's default export in `cache.component(...)`. Layout `prerender` cascades to descendant pages unless overridden (most-specific-wins).
+
+### Nesting
+
+When a cached component renders inside another cached component, the outer entry's lifetime wins. The inner's output is baked into the outer's payload as a flat copy — `revalidateTag` on the inner's tags does **not** refresh the embedded copy. The framework warns at capture time when the inner declares a refresh channel the outer cannot honor.
+
 ## `CacheHandler` Interface
 
 Implement this to plug in a custom cache backend.
@@ -100,15 +195,19 @@ interface RedisClient {
   srem(key: string, ...members: string[]): Promise<unknown>;
   smembers(key: string): Promise<string[]>;
   ttl(key: string): Promise<number>;
+  execMulti?(ops: RedisWriteOp[]): Promise<void>; // optional MULTI/EXEC
 }
 ```
 
 `expireNX` and `expireGT` map to Redis 7.0's `EXPIRE key seconds NX|GT` subcommands. `NX` sets the TTL only if none exists, `GT` extends only if greater. Both are used internally for atomic tag set TTL management. Separate methods ensure adapters cannot silently drop the mode. Requires **Redis 7.0+**.
 
+`execMulti` is optional. When provided, `set()` executes tag-index writes and the data write atomically via `MULTI/EXEC`, preventing concurrent `invalidate({tag})` calls from interleaving. When absent, writes are sequential (correct but with a narrow self-healing race window).
+
 This is deliberately not the native shape of any client library — ioredis, node-redis, and @upstash/redis disagree on TTL argument shapes and method casing, and a contract that pattern-matches one client lets another silently write keys with no expiry. Wrap your client with one of these adapters:
 
 ```ts title="ioredis"
 import { RedisCacheHandler } from '@timber-js/app/cache';
+import type { RedisWriteOp } from '@timber-js/app/cache';
 import Redis from 'ioredis';
 
 const redis = new Redis(process.env.REDIS_URL!);
@@ -122,6 +221,19 @@ const handler = new RedisCacheHandler({
   srem: (k, ...m) => redis.srem(k, ...m),
   smembers: (k) => redis.smembers(k),
   ttl: (k) => redis.ttl(k),
+  execMulti: async (ops) => {
+    const p = redis.multi();
+    for (const op of ops) {
+      switch (op.op) {
+        case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+        case 'sadd': p.sadd(op.key, ...op.members); break;
+        case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+        case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+        case 'del': p.del(op.key); break;
+      }
+    }
+    await p.exec();
+  },
 });
 ```
 

package/docs/api/34-api-config.mdx

@@ -17,8 +17,6 @@ interface TimberUserConfig {
   buildDir?: string;
   clientJavascript?: boolean | ClientJavascriptConfig;
   adapter?: TimberPlatformAdapter;
-  cacheHandler?: CacheHandler;
-  cdnPurge?: CdnPurgeHandler;
   serverTiming?: 'detailed' | 'total' | false;
   allowedOrigins?: string[];
   csrf?: boolean;
@@ -27,9 +25,6 @@ interface TimberUserConfig {
     uploadBodySize?: string;
     maxFields?: number;
   };
-  actions?: {
-    runMiddleware?: boolean;
-  };
   forms?: {
     stripSensitiveFields?: boolean | readonly string[];
   };
@@ -119,13 +114,6 @@ adapter: cloudflare();
 adapter: nitro({ preset: 'node-server' });
 ```
 
-### `cacheHandler`
-
-- **Type:** `CacheHandler`
-- **Default:** `MemoryCacheHandler`
-
-Cache backend for `timber.cache()`. See [Cache API](/docs/api-cache).
-
 ### `serverTiming`
 
 - **Type:** `'detailed' | 'total' | false`
@@ -159,13 +147,6 @@ limits: {
 }
 ```
 
-### `actions.runMiddleware`
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-Run `middleware.ts` on server action requests before dispatching. Keeps authentication, rate limiting, and other cross-cutting checks applied uniformly to page renders, route handlers, and server actions. Set to `false` only if your middleware would corrupt action submissions (e.g. it rewrites POST bodies) — you then own placing those checks inside every action.
-
 ### `forms.stripSensitiveFields`
 
 - **Type:** `boolean | string[]`
@@ -191,13 +172,6 @@ Two files claiming the same convention in one directory (e.g. `page.tsx` + `page
 
 Enable timber debug logging in production builds. When `true`, timber's own diagnostics (dev warnings, verbose logging) are active even in production mode. React stays in production mode — only timber's logs are affected. Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
 
-### `cdnPurge`
-
-- **Type:** `CdnPurgeHandler`
-- **Default:** none
-
-CDN purge handler called on `revalidateTag` / `cache.invalidate` to purge CDN-cached responses.
-
 ### `slowRequestMs`
 
 - **Type:** `number`

package/docs/learn/09-caching.mdx

@@ -117,16 +117,132 @@ On serverless platforms (Cloudflare Workers, Lambda), the background refetch is
 
 When multiple concurrent requests miss the cache for the same key, only one executes the underlying function. The rest wait for the result. The result is written to the cache exactly once, by the execution that ran the function. This is built in — no opt-in needed.
 
+## Caching Components
+
+`cache.data` caches a function's return value. `cache.component` caches a component's **rendered output** — the RSC flight payload — so re-renders skip the entire component tree:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { cache } from '@timber-js/app/cache';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const PostBody = cache.component(
+  async function PostBody() {
+    const { slug } = getSegmentParams();
+    const post = await getPost(slug);
+    return <article><h1>{post.title}</h1><PostContent content={post.content} /></article>;
+  },
+  { prerender: true }
+);
+
+export async function generateStaticSegmentParams() {
+  return allPosts.map((p) => ({ slug: p.slug }));
+}
+
+export default async function BlogPost() {
+  return <PostBody />;
+}
+```
+
+The same API gives you three tiers of freshness, controlled by two options:
+
+### Static (build-time only)
+
+Rendered at build for each set of params from `generateStaticSegmentParams`. Changes only on redeploy. Request context (`getCookieJar()`, `getHeaders()`) is a build error.
+
+```tsx
+const BlogBody = cache.component(Body, { prerender: true });
+```
+
+### Cached (runtime only)
+
+Rendered on first request, stored with a TTL. Invalidatable by tag. May read request context (with a warning — be careful not to leak per-user data into a shared cache).
+
+```tsx
+const Pricing = cache.component(PricingTable, {
+  ttl: 300,
+  tags: ['pricing'],
+  staleWhileRevalidate: true,
+});
+```
+
+### ISR (build-seeded, runtime-refreshable)
+
+Rendered at build, but refreshable via `revalidateTag` without a redeploy. Unenumerated params fill in on first request.
+
+```tsx
+const DocsPage = cache.component(DocsBody, {
+  prerender: true,
+  ttl: 3600,
+  tags: ['docs'],
+});
+```
+
+### Mixing Tiers on One Page
+
+A page can combine all three — a dynamic shell with cached islands:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { getCookieJar } from '@timber-js/app/server';
+
+export default async function BlogPost() {
+  const user = await getUser(getCookieJar());
+  return (
+    <>
+      <Nav user={user} />           {/* dynamic — personalized */}
+      <PostBody />                   {/* prerendered — from build artifact */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments />                 {/* dynamic — streams per-request */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+### Route-Level Shorthand
+
+For fully static routes, export `prerender` instead of wrapping the component manually:
+
+```ts title="app/about/page.tsx"
+export const prerender = true;
+```
+
+This desugars to `cache.component(...)` around the page's default export. For dynamic routes (`[slug]`), pair it with `generateStaticSegmentParams` so the build knows which params to prerender:
+
+```ts title="app/docs/[slug]/page.tsx"
+export const prerender = { ttl: 3600, tags: ['docs'] };
+
+export async function generateStaticSegmentParams() {
+  return allDocs.map((d) => ({ slug: d.slug }));
+}
+```
+
+Layout `prerender` cascades to descendant pages unless a closer layout or page overrides it.
+
+### Slots: Dynamic Children Through a Cached Shell
+
+When the expensive part is a wrapper (nav, sidebar, layout chrome) but its children are dynamic, use `slots` to cache the shell with holes for live content:
+
+```tsx
+const Shell = cache.component(ExpensiveWrapper, {
+  ttl: 3600,
+  tags: ['marketing'],
+  slots: ['children'],
+});
+
+// The shell serves from cache; children render live per request.
+<Shell theme="dark"><LiveUserFeed /></Shell>
+```
+
+Slot props are excluded from the cache key. Slots are runtime tier only — `prerender` is ignored when `slots` is active.
+
 ## Cache Handlers
 
-The default handler is in-memory. Configure a different backend in `timber.config.ts`:
+The default handler is in-memory. Configure a different backend in `timber.cache.ts`:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { MemoryCacheHandler } from '@timber-js/app/cache';
 
-export default {
-  cacheHandler: new MemoryCacheHandler(),
-};
+export default new MemoryCacheHandler();
 ```
 
 Implement the `CacheHandler` interface for Redis, Cloudflare KV, or any other backend. See the [Cache API Reference](/docs/api-cache).

package/docs/learn/12-client-navigation.mdx

@@ -108,7 +108,13 @@ export function NavItem({ href, children }: { href: string; children: React.Reac
 
 ## Segment Cache
 
-The client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+Opt-in via `clientSegmentCache: true` in `timber.config.ts`. When enabled, the client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+
+```ts title="timber.config.ts"
+export default {
+  clientSegmentCache: true,
+};
+```
 
 ```
 /dashboard/settings → /dashboard/team
@@ -121,6 +127,8 @@ The client maintains a mirror of the server's segment tree. On navigation, only
 
 Sync layouts stay cached while mounted. Async layouts always re-render. Pages always re-render. Client component state in shared layouts is preserved — counters, form inputs, scroll positions survive navigation.
 
+When disabled (the default), every client navigation gets a full RSC payload from the server. This is simpler and avoids edge cases with stale cached layouts, at the cost of slightly larger payloads on navigation.
+
 Back/forward navigation replays cached RSC payloads instantly — no server roundtrip.
 
 ## Scroll Restoration

package/docs/learn/13-configuration.mdx

@@ -81,16 +81,15 @@ export default {
 
 ## Cache Handler
 
-```ts title="timber.config.ts"
+Cache handler configuration lives in a separate `timber.cache.ts` file (not `timber.config.ts`). This keeps runtime cache instances separate from build-time config, preventing build dependencies from leaking into the server bundle.
+
+```ts title="timber.cache.ts"
 import { MemoryCacheHandler } from '@timber-js/app/cache';
 
-export default {
-  output: 'server',
-  cacheHandler: new MemoryCacheHandler(),
-};
+export default new MemoryCacheHandler();
 ```
 
-The default is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
+The default export is the `CacheHandler` instance. Export `cdnPurge` as a named export for CDN purge handlers. The default handler is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
 
 ## `clientJavascript`
 
@@ -129,8 +128,6 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 | `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
 | `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
 | `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
-| `cacheHandler`      | `CacheHandler`              | `MemoryCacheHandler`         | Cache backend                            |
-| `cdnPurge`          | `CdnPurgeHandler`           | —                            | CDN purge on revalidation                |
 | `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
 | `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
 | `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
@@ -148,6 +145,7 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 | `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
 | `reactCompiler`     | `boolean \| object`         | `false`                      | React Compiler auto-memoization          |
 | `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
+| `clientSegmentCache`| `boolean`                   | `false`                      | Opt-in client segment cache for partial nav |
 | `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
 
 For the full type definition, see the [Config API Reference](/docs/api-config).