@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/docs/learn/07-typed-routes.mdx

@@ -0,0 +1,132 @@
+---
+title: 'Typed Routes'
+description: 'Build-time route types — <Link> validates href, params are inferred from the file tree.'
+slug: 'typed-routes'
+---
+
+# Typed Routes
+
+timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree. Segment params are inferred from directory names. Search params are typed when you define them.
+
+## How It Works
+
+When you run `timber dev` or `timber build`, the framework scans your `app/` directory and generates a route map in `.timber/routes.d.ts`:
+
+```ts
+// .timber/routes.d.ts (generated, gitignored)
+export interface TimberSegmentParams {
+  '/': {};
+  '/products/[id]': { id: number };
+  '/blog/[...slug]': { slug: string[] };
+}
+```
+
+Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
+
+## Typed `<Link>`
+
+`<Link>` validates `href` against the route map. Invalid routes are caught at build time:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>           // ✓ known route
+<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
+```
+
+For dynamic routes, pass `segmentParams`:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/products/[id]" segmentParams={{ id: 42 }}>
+  Product
+</Link>
+// → <a href="/products/42">Product</a>
+```
+
+Or use an interpolated href directly:
+
+```tsx
+<Link href={`/products/${id}`}>Product</Link>
+```
+
+Both forms are type-safe. With the pattern form (`/products/[id]`), `segmentParams` is required and typed. With the interpolated form, `segmentParams` is forbidden.
+
+## Typed Segment Params
+
+Each route directory gets a generated `$segment` module. Import `SEGMENT_PATH` for type-safe param access:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id is typed from your schema codec (e.g., number for codec.integer)
+}
+```
+
+Without `SEGMENT_PATH`, params are untyped — all optional strings.
+
+### tsconfig.json
+
+Add `rootDirs` so TypeScript can resolve `$segment` imports:
+
+```jsonc
+{
+  "compilerOptions": {
+    "rootDirs": [".", ".timber/types"]
+  }
+}
+```
+
+## Typed Search Params
+
+Define search params with `defineSearchParams()` in any module and import it — there is no convention file. Search params are then fully typed throughout the stack:
+
+```ts title="app/products/search-params.ts"
+import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params';
+import { parseAsInteger, parseAsStringEnum } from 'nuqs';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: withDefault(parseAsInteger, 1),
+  q: withUrlKey(z.string().nullable().default(null), 'search'),
+  category: z.string().nullable().default(null),
+  sort: withDefault(parseAsStringEnum(['price-asc', 'price-desc', 'newest']), 'newest'),
+});
+```
+
+```tsx title="app/products/page.tsx"
+import { searchParams } from './search-params';
+
+export default async function ProductsPage() {
+  const { page, q, category, sort } = await searchParams.get();
+  // page: number, q: string | null, category: string | null, sort: 'price-asc' | ...
+}
+```
+
+Pass them to `<Link>` by building them from the definition. `buildSearchParams` type-checks the values and applies the definition's codecs and URL-key aliases:
+
+```tsx
+import { searchParams } from './search-params';
+
+<Link
+  href="/products/[id]"
+  segmentParams={{ id }}
+  searchParams={searchParams.buildSearchParams({ sort: 'newest', q: 'boots' })}
+/>
+// → /products/42?sort=newest&search=boots   (q is aliased to search)
+```
+
+A plain object also works as an untyped escape hatch for one-off params with no definition — but it skips codecs and aliases, so do not use it for keys a definition owns.
+
+See [Typed Params](/docs/typed-params) for the full search params API.
+
+## Codegen
+
+Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
+
+For the full type definitions and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).

package/docs/learn/08-streaming.mdx

@@ -0,0 +1,146 @@
+---
+title: 'Streaming'
+description: 'Suspense placement, deferSuspenseFor, and the layout footgun.'
+slug: 'streaming'
+---
+
+# Streaming
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.string,
+  },
+});
+```
+
+Streaming lets the server send HTML to the browser in chunks as it becomes ready. timber uses streaming selectively — the shell is sent as a complete block, and only `<Suspense>` boundaries stream in afterward.
+
+## The Shell vs. Suspense Boundaries
+
+timber divides your page into two phases:
+
+**The shell** (before the [flush point](/docs/the-flush-point)):
+- Layouts, navigation, page structure
+- Primary content that defines the page
+- Determines the HTTP status code
+
+**Suspense boundaries** (after the flush):
+- Secondary content wrapped in `<Suspense>`
+- Streams in progressively as data resolves
+- Cannot affect the status code
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { Suspense } from 'react';
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function ReviewsSkeleton(): React.ReactElement;
+declare function ProductReviews(props: { productId: string }): React.ReactElement;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404); // Real HTTP 404
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={product.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+The product loads before the flush — if it doesn't exist, the server sends a real 404. Reviews stream in later.
+
+## Choosing What to Stream
+
+**Don't stream** (keep in the shell):
+- Content that defines the page — the product, the article, the user profile
+- Content that might produce a 404 or redirect
+- Content that should be visible without JavaScript
+
+**Do stream** (wrap in `<Suspense>`):
+- Recommendations, related items, activity feeds
+- Analytics widgets, personalization
+- Anything slow that isn't essential to the page's identity
+
+The rule: if missing content means the page shouldn't exist, don't stream it.
+
+## No `loading.tsx`
+
+There is no `loading.tsx` convention. timber does not insert Suspense boundaries for you. If you want a loading state, you place `<Suspense>` explicitly. This keeps you in control of what streams and what blocks.
+
+## The Layout Suspense Footgun
+
+Wrapping `children` in `<Suspense>` inside a layout surrenders HTTP correctness for every page in that subtree:
+
+```tsx
+// ⚠️ Don't do this
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <Shell>
+      <Suspense fallback={<Skeleton />}>{children}</Suspense>
+    </Shell>
+  );
+}
+```
+
+The framework warns in dev mode when this is detected. For navigation loading states, use `usePendingNavigation()` instead.
+
+## `deferSuspenseFor`
+
+Sometimes Suspense content resolves fast enough that you'd rather wait for it than show a fallback. `deferSuspenseFor` holds the SSR stream for a specified duration:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { Suspense } from 'react';
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function ProductHeader(props: { product: { name: string } }): React.ReactElement;
+declare function ReviewsSkeleton(): React.ReactElement;
+declare function ProductReviews(props: { productId: string }): React.ReactElement;
+
+export const deferSuspenseFor = 200; // milliseconds
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404);
+
+  return (
+    <div>
+      <ProductHeader product={product} />
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={product.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+If reviews resolve within 200ms, they render inline — no fallback shown. If they take longer, the fallback flushes and reviews stream in when ready.
+
+## Signal Promotion
+
+When `deny()` or `redirect()` fires inside a `<Suspense>` boundary:
+
+**Before the flush** — the signal is promoted to pre-flush semantics. The framework sends the correct HTTP status code and renders the appropriate status file.
+
+**After the flush** — the status code is already committed. The signal triggers an error boundary in the client, and timber adds `<meta name="robots" content="noindex">`.
+
+`deferSuspenseFor` extends the window where signals can be promoted.
+
+**The rule:** don't rely on Suspense-wrapped content to control the status code. If content must drive the status code, fetch it outside `<Suspense>`. Signal promotion is a safety net, not a guarantee.
+
+## Early Hints (103)
+
+Before the flush, timber sends 103 Early Hints with CSS, fonts, and JS URLs. These fire at route-match time — before middleware runs — based on the build manifest. The browser starts fetching resources while the server is still working.

package/docs/learn/09-caching.mdx

@@ -0,0 +1,252 @@
+---
+title: 'Caching'
+description: 'Explicit caching with timber.cache — TTL, tags, staleWhileRevalidate, and pluggable backends.'
+slug: 'caching'
+---
+
+# Caching
+
+timber.js does not cache anything by default. No patched `fetch`, no implicit data cache. If you want caching, you ask for it explicitly.
+
+## timber.cache vs React.cache
+
+This is the number one confusion point. They are different things:
+
+|                     | `timber.cache`              | `React.cache`        |
+| ------------------- | --------------------------- | -------------------- |
+| Scope               | Cross-request (persistent)  | Single request       |
+| TTL/tags            | Yes                         | No                   |
+| Works in middleware  | Yes                         | No                   |
+| Use case            | Database queries, API calls | Request-scoped dedup |
+
+`React.cache` deduplicates within a single request — if three components call `getUser(id)`, only one database query runs. `timber.cache` persists across requests with TTL — the same query serves cached results for 60 seconds.
+
+```tsx title="lib/data.ts"
+import { cache } from 'react';
+import { cache as timberCache } from '@timber-js/app/cache';
+
+declare const db: {
+  users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
+  products: { findPopular(): Promise<{ id: string; name: string }[]> };
+};
+
+// Deduplicates within one request
+export const getUser = cache(async (id: string) => {
+  return db.users.findUnique({ where: { id } });
+});
+
+// Caches across requests for 60 seconds
+export const getPopularProducts = timberCache.data(
+  async () => {
+    return db.products.findPopular();
+  },
+  { ttl: 60, tags: ['products'] }
+);
+```
+
+## `cache.data()` Options
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+declare const db: {
+  users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
+};
+
+const getUser = cache.data(
+  async (userId: string) => {
+    return db.users.findUnique({ where: { id: userId } });
+  },
+  {
+    ttl: 60,                                   // Cache for 60 seconds
+    key: (userId) => `user:${userId}`,         // Explicit cache key (optional)
+    staleWhileRevalidate: true,                // Serve stale while refetching
+    tags: (userId) => [`user:${userId}`],      // For tag-based invalidation
+  }
+);
+```
+
+`tags` accepts a static array (`['products']`) or a function that receives the same arguments as the wrapped function.
+
+## Cache Keys
+
+Without an explicit `key`, the cache key is derived from the call site plus a deterministic serialization of the arguments.
+
+### Content-Derived Cache Identities
+
+The call-site identity is content-based — derived from the source code of the `cache.data()` call, not its position in the file. This means:
+
+- **Unchanged code = cache survives deploys.** If you redeploy without changing a cached function, its entries remain valid on persistent handlers like Redis or KV.
+- **Changed code = automatic invalidation.** Editing the wrapped function or its options changes the cache identity, which invalidates old entries without manual cache busting.
+
+This works for namespace imports, re-exports, and other patterns where the call site isn't trivially traceable. For callsites that can't be statically traced, a deterministic source-hash runtime fallback ensures cache identities never collide across instances.
+
+Object key order doesn't matter — `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same key. `Date`, `URL`, and anything with a `toJSON()` method serialize the way `JSON.stringify` would; `Map` and `Set` are serialized by their entries.
+
+Arguments that can't be serialized faithfully — functions, symbols, or class instances whose data lives behind getters with no `toJSON()` — throw a `TypeError` instead of silently colliding. If you hit this, pass an explicit `key`:
+
+```ts
+cache.data(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
+```
+
+## Invalidation
+
+Invalidate by tag:
+
+```ts
+import { revalidateTag } from '@timber-js/app/server';
+
+// In a server action after updating a product:
+revalidateTag('products');
+revalidateTag(`user:${userId}`);
+```
+
+Invalidation wins races against in-flight cached functions: if a cached function is mid-execution when you invalidate one of its tags (the usual mutation flow — update the database, then `revalidateTag`), its result is not written back to the cache, and callers arriving after the invalidation re-execute instead of joining the superseded execution. This guard is per-process; with a shared handler (Redis/KV), an invalidation from a *different* instance can still race a concurrent write on this one.
+
+## `staleWhileRevalidate`
+
+When enabled, expired entries are served immediately while a background refetch runs:
+
+- **0–60s:** Fresh. Served from cache.
+- **60s+:** Stale. Served immediately, background refetch starts.
+- **Next request after refetch:** Gets fresh data.
+
+On serverless platforms (Cloudflare Workers, Lambda), the background refetch is automatically registered with the platform's `waitUntil` so it completes even after the response is sent. If the refetch fails, the stale entry continues to be served and the error is logged.
+
+## Singleflight
+
+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.cache.ts`:
+
+```ts title="timber.cache.ts"
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+export default new MemoryCacheHandler();
+```
+
+Implement the `CacheHandler` interface for Redis, Cloudflare KV, or any other backend. See the [Cache API Reference](/docs/api-cache).
+
+import SlowStaticComponent from '@/ui/SlowStaticComponent';
+
+<SlowStaticComponent />

package/docs/learn/10-middleware.mdx

@@ -0,0 +1,157 @@
+---
+title: 'Middleware'
+description: 'proxy.ts for global concerns, middleware.ts for per-segment logic.'
+slug: 'middleware'
+---
+
+# Middleware
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[userId]': codec.string,
+  },
+});
+```
+
+timber.js has two middleware layers: `proxy.ts` for global concerns and `middleware.ts` for per-segment logic.
+
+## Middleware vs Access
+
+Before diving in, the first question: should this be middleware or `access.ts`?
+
+|               | `middleware.ts`                        | `access.ts`                       |
+| ------------- | -------------------------------------- | --------------------------------- |
+| Runs          | Before rendering                       | Inside React tree                 |
+| Purpose       | Headers, redirects, cache warming      | Auth, data gating                 |
+| `React.cache` | Not available                          | Active — shares scope with layout |
+| Slots         | N/A                                    | Graceful degradation              |
+
+Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it has `React.cache` and supports slot degradation.
+
+## `proxy.ts` — Global Middleware
+
+`app/proxy.ts` runs on every request before route matching:
+
+```ts title="app/proxy.ts"
+export default [
+  cors({ origins: ['https://example.com'] }),
+  rateLimit({ requests: 100, window: '1m' }),
+  securityHeaders(),
+];
+```
+
+```ts title="app/proxy.ts"
+export default async function proxy(req: Request, next: () => Promise<Response>) {
+  const start = performance.now();
+  const res = await next();
+  console.log(`${req.method} ${req.url} — ${performance.now() - start}ms`);
+  return res;
+}
+```
+
+`proxy.ts` has `next()` — it can wrap the entire request lifecycle. This is where you observe and modify responses.
+
+## `middleware.ts` — Per-Segment Middleware
+
+`middleware.ts` files run after route matching, before rendering. They're scoped to their route segment.
+
+```ts title="app/dashboard/middleware.ts"
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getSession(req: Request): Promise<{ userId: string } | null>;
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+}
+```
+
+**Key differences from proxy.ts:** Middleware does not have `next()`. It's a gate — it either short-circuits (redirect, deny, return a Response) or passes through silently. It cannot observe or modify the render result.
+
+**Key difference from Next.js:** Next.js has a single global `middleware.ts`. timber lets you place `middleware.ts` at any route segment.
+
+## Middleware Context
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req;              // The incoming Request
+  ctx.segmentParams;    // Route params (already coerced by schema.ts)
+  ctx.headers;          // Response headers (writable)
+  ctx.requestHeaders;   // Request headers (injectable)
+}
+```
+
+Middleware can inject request headers that components read later:
+
+```ts title="app/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function detectLocale(req: Request): string;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const locale = detectLocale(ctx.req);
+  ctx.requestHeaders.set('x-locale', locale);
+}
+```
+
+```tsx title="app/page.tsx"
+import { getHeaders } from '@timber-js/app/server';
+
+declare function Content(props: { locale: string | null }): React.ReactElement;
+
+export default async function Page() {
+  const locale = (getHeaders()).get('x-locale');
+  return <Content locale={locale} />;
+}
+```
+
+## Execution Order
+
+For a request to `/dashboard/settings`:
+
+1. `proxy.ts` (global)
+2. `app/middleware.ts` (root, if exists)
+3. `app/dashboard/middleware.ts` (segment)
+4. `app/dashboard/settings/middleware.ts` (segment)
+5. `access.ts` checks (inside React tree)
+6. Render
+
+## Cache Warming
+
+Use middleware to fire off data fetches before rendering starts:
+
+```ts title="app/users/[userId]/middleware.ts" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getUser(userId: string): Promise<{ id: string; name: string }>;
+declare function getUserPosts(userId: string): Promise<{ id: string; title: string }[]>;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  await Promise.all([
+    getUser(userId),
+    getUserPosts(userId),
+  ]);
+}
+```
+
+```tsx title="app/users/[userId]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+
+export default async function UserPage() {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  const user = await getUser(userId);       // cache hit
+  const posts = await getUserPosts(userId); // cache hit
+  return <Profile user={user} posts={posts} />;
+}
+```
+
+Without cache warming, these fetches waterfall. With middleware, both fire in parallel before rendering begins.
+