> [Agent navigation index](/llms.txt)

# Contentful Rendering

Use rendering adapters when Contentful owns nested, polymorphic page composition. Adapters keep CMS fields at the integration boundary while providing visual components and semantic Markdown from the same entry.

## Create the adapter factory

First [generate the type map](/docs/contentful-typegen.md) from your published models. The examples
assume `hero`, `article`, and `cardList` models; substitute your actual IDs and fields. Create one
browser-safe factory from that map:

`src/contentful-rendering.ts`

```ts
import { createContentfulAdapterFactory } from "brix/contentful/rendering";
import type { Context } from "brix/hono";
import type { ContentTypeMap } from "#/contentful-types.ts";

export const createAdapter = createContentfulAdapterFactory<ContentTypeMap, Context>();

```

The second type argument is the context type passed to adapter loader handlers; it defaults to
`unknown`. Use a narrower type, such as
`Context<{ Bindings: Readonly<CoercedEnvSchema> }>` with the generated environment type, when
handlers read typed `c.env`.

## Write an adapter

Only conventional `*.adapter.ts` and `*.adapter.tsx` modules inspect Contentful `fields` and
`sys`; `brix check` reports entry-field access anywhere else, including `items[0]!.fields`,
`getPage().fields`, `entries.map(({ fields }) => ...)`, and `for (const { fields } of entries)`. Each adapter module exports exactly
one PascalCase runtime value ending in `Adapter`, defined by a direct factory call with an object
literal and a literal `contentType`. Type-only exports are allowed; config spreads and computed keys
are rejected. Components receive ordinary application props.

`src/features/content/hero/Hero.adapter.tsx`

```tsx
import { md } from "brix/markdown";
import { createAdapter } from "#/contentful-rendering.ts";
import { Hero } from "./Hero.tsx";

export const HeroAdapter = createAdapter({
  contentType: "hero",
  markdown: ({ entry }) => md.heading(1, md.text(entry.fields.heading)),
  component: ({ entry, preview }) => (
    <Hero heading={entry.fields.heading} headingAttributes={preview?.getProps("heading")} />
  ),
});

```

`Hero` is an application component that accepts the projected `heading` and optional inspector
attributes. Rendering a `hero` entry through the generated registry now selects this adapter; normal
components do not need to read `entry.fields` themselves.

The `component` callback receives:

- `entry` — the entry, typed from `contentType`;
- `loaded` — `null` for a loaderless adapter, otherwise the loader state described below;
- `props` — extra props declared with `propsOf`;
- `renderEntry` — renders a nested entry through the same registry;
- `preview` — inspector attributes and controls, present only inside
  [Live Preview](/docs/contentful-preview.md);
- `assetsUrl` — the configured assets base URL, empty by default.

Declare extra props a parent passes with `propsOf`. Because the standalone preview renders an entry
without its parent, TypeScript requires `preview.props` fallbacks when any extra prop is required:

`src/features/content/cardList/CardList.adapter.tsx`

```tsx
import { propsOf } from "brix/contentful/rendering";
import { createAdapter } from "#/contentful-rendering.ts";
import { CardList } from "./CardList.tsx";

export const CardListAdapter = createAdapter({
  contentType: "cardList",
  props: propsOf<{ appearance: "light" | "dark" }>(),
  preview: { props: { appearance: "light" } },
  component: ({ entry, props, renderEntry }) => (
    <CardList appearance={props.appearance} heading={entry.fields.heading}>
      {entry.fields.cards.map((card) => renderEntry(card))}
    </CardList>
  ),
});

```

Link resolution turns missing, unpublished, or inaccessible links into `null`, and generated types
include it (for example `Array<ICard | null>`). The component and Markdown `renderEntry` accept
`null` and `undefined` and render nothing for them, so `entry.fields.cards.map(renderEntry)` needs
no filtering. In Markdown, `await renderEntry(null)` resolves to `null`, like a `markdown: false`
child.

Keep top-level adapter imports browser-safe: adapters run in islands too. Browser builds remove
loader handlers, Markdown projections, and their exclusive imports, but retain response schemas.

## Declare loader responses

An adapter may define a bounded server `loader` for data that is not in the entry itself. Use a
loader object to validate the data intended for the page's recipient:

```tsx
import { z } from "brix/zod";

export const ArticleAdapter = createAdapter({
  contentType: "article",
  loader: {
    response: z.strictObject({
      related: z.array(z.strictObject({ title: z.string(), href: z.string() })),
    }),
    handler: async (entry, c, signal) => {
      const { loadRelatedCards } = await import("./related.server.ts");
      return { related: await loadRelatedCards(entry, c, signal) };
    },
  },
  preview: { data: { related: [] } },
  component: ({ loaded }) => {
    if (loaded.status === "pending") return <p role="status">Loading related cards…</p>;
    if (loaded.status === "error") return <p>Related cards unavailable</p>;
    return <RelatedCards cards={loaded.data.related} />;
  },
});

```

`loadRelatedCards` and `RelatedCards` are application code. The loader object must contain
`response` and an inline async `handler`; spreads, computed keys, and method shorthand are not
supported, nor are function-style loaders. The handler receives `(entry, context, signal)`:
dynamically import server-only code inside it and pass `signal` to downstream requests. Every loader
adapter must also declare `preview.data`, a deterministic fixture used by Live Preview and
Storybook; TypeScript rejects a loader without it. Keep compact card mappings: they describe the
intended response and reduce payload size.

Visual components receive
`{ status: "pending" } | { status: "ok", data: T } | { status: "error", reason: "failed" | "timeout" }`.
Handle all three states in the same `component`; there is no separate `pending` callback. During SSR
Brix awaits the loader before invoking the component, so pending is only a browser state. The
`Loaded<T>` type passed to Markdown has only the two settled states.

Handlers return schema input; `loaded.data` in visual and Markdown callbacks is inferred from schema
output. Brix JSON-normalizes the result before validating it. Invalid or non-serializable data becomes
`{ status: "error", reason: "failed" }`, without rejected data or validation diagnostics in hydration
payloads. Timeouts remain `reason: "timeout"`. Failed results are not retried within the preparation.

Validated JSON input is transported unchanged. For example, `z.string().transform(Number)` sends a
string and gives callbacks a number. SSR reuses parsed results; hydration parses the original input,
not already-transformed output. Schemas and transforms must be synchronous, deterministic, and
browser-safe. `preview.data` and explicit `loadedData` fixtures supply schema input too and pass
through the same validation without calling the handler; treat their result envelopes as immutable
and replace them when data changes.

JSON normalization rejects results larger than 16 MiB of expanded UTF-8 JSON, including repeated
references and escaped strings. This is an output bound, not a new cap on trusted SSR entry-graph
traversal. Serialization checks the loader deadline; parsing and validation check it on return.
Late asynchronous completions are not serialized. Failures never silently truncate content.

**Validation is not redaction or authorization.** Loader results used during island hydration are
browser-visible, so never return credentials or private data the recipient may not see. Use strict
objects at every nested object boundary to reject unexpected fields: plain `z.object` strips unknown
fields only from parsed output, not transported input. Never rely on stripping, preprocessing, or
transforms to conceal secrets. Enforce authorization server-side and configure private caching for
authenticated responses. A schema alone does not enable the client endpoint or grant remote
permission.

## Render polymorphic entries

Vite generates the registry from every discovered adapter module and exposes `renderEntry`:

```tsx
import { renderEntry } from "brix/contentful/rendering/registry";
import type { Entry } from "brix/contentful";

export function ContentPage({ entry }: { entry: Entry<unknown> }) {
  return <main>{renderEntry(entry)}</main>;
}

```

`renderEntry(entry, props?)` selects the adapter by the entry's content type and renders nothing
for a content type without an adapter. Pass an optional transport props record as the second
argument for polymorphic children; directly render a known adapter, such as
`<HeroAdapter entry={entry} />`, when those props should be statically checked.

Brix wraps every server render in the generated registry and loader preparation, so pages and
islands need no provider. Outside the generated registry, for example in a component test or a
library that ships its own adapters, build the registry yourself:

```tsx
import type { Entry } from "brix/contentful";
import {
  ContentfulRenderingProvider,
  contentfulEntryKey,
  createContentfulRegistry,
  renderContentfulEntry,
  type Loaded,
} from "brix/contentful/rendering";
import { ArticleAdapter } from "./Article.adapter.tsx";
import { HeroAdapter } from "./Hero.adapter.tsx";

const registry = createContentfulRegistry([HeroAdapter, ArticleAdapter]);

export function RenderedArticle({ entry }: { entry: Entry<unknown> }) {
  const loadedData = new Map<string, Loaded<unknown>>([
    [contentfulEntryKey(entry), { status: "ok", data: { related: [] } }],
  ]);
  return (
    <ContentfulRenderingProvider registry={registry} loadedData={loadedData}>
      {renderContentfulEntry(entry, registry)}
    </ContentfulRenderingProvider>
  );
}

```

`createContentfulRegistry` rejects duplicate content types. `ContentfulRenderingProvider` requires
`registry`; its optional props are `loadedData`, `clientLoading` (a resource from
`createContentfulLoadingResource`), and `assetsUrl`. `loadedData` is a `ReadonlyMap` of loader
results keyed by `contentfulEntryKey(entry)`, which joins space, environment, locale (`*` for
wildcard-locale reads), content type, and entry ID with `:`. Values are schema input in a
`Loaded` envelope. `renderContentfulEntry(entry, registry, props?)` renders without an enclosing
provider too, but loader adapters then fail unless their data is prepared. Inside a provider with a
different registry, such as the generated one during SSR, it keeps the provider's data, loading, and
preview state but resolves the entry and its nested `renderEntry` calls through the explicit
registry. Server and browser renders therefore select the same adapters. `isContentfulAdapter`
recognizes adapter values.

Explicit `loadedData` wins per entry; absent keys fall back to SSR preparation or the browser
resource. In the browser it overrides the scoped resource for the current generation without
fetching or replacing the resource's shared values. A supplied dictionary belongs to the resource
generation that first observed it: session reset or failed session discovery invalidates it, even
after remount, so it cannot restore stale private data. Supply new authorized data through the
resource's `reset({ scope, permissions, loadedData })`, not by remounting the old provider.

### SSR preparation and hydration

During HTML SSR, Brix starts and awaits a loader when rendering reaches its adapter, before invoking
the consumer component. Nested adapters reached through the supplied `renderEntry`, including those
selected from loader results, work the same way. Brix does not scan raw page props or loader-result
graphs for entries that are merely carried but never rendered.

Preparation is request-local, deduplicated, bounded, cancellable, and deadline-limited. Each page
request:

- runs at most eight loaders concurrently;
- observes at most 10,000 adapter renders and nests adapters at most 32 levels deep;
- allows one loader round per nesting level;
- shares one five-second deadline.

Traversal overflow fails the render; loader timeouts become `Loaded` errors.

Hydration retains results consumed by client-executed adapters plus already-prepared results
reachable from emitted island props and client-owned adapter inputs and parsed results. Selection
never runs a loader. This scan has no node or depth limit: it is linear in the island props that the
page already serializes, so large charts or tables in islands do not fail the render. Brix skips it
when no adapter declares a loader. This conservative closure preserves reuse for an adapter first mounted after
a click; it does not predict which interactions will happen.

Available results are those observed when an adapter renders. Unused entries in a server-only
provider's `loadedData` dictionary are not automatically exported, even if an island receives the
matching entry in its props. A later mount needs retained observed data, a provider/prepared data
reconstructed in the browser, or authorized client loading.

Server-only adapters, including visible and hidden JSX slots, do not automatically publish their
complete loader results. Slots attach their prepared HTML; independent islands inside slots retain
their own required results. Effective explicit-provider successes and failures are included;
conflicting values for one entry key within one hydration payload fail explicitly during SSR. Page
and fragment resources remain isolated. Loaderless adapter inputs still contribute reachable children.

An adapter first introduced by browser interaction has no loader result unless that entry was
prepared during SSR and retained as client-reachable data. Without the opt-in loading policy below,
it fails clearly before its consumer component runs, naming the entry and the three ways to supply
data. Loaderless adapters receive `null`; prepared failures remain typed loaded results.

## Authorize client-introduced adapters

Loaders can run in the browser through the framework-owned `POST /_/contentful/load` endpoint. This
is opt-in: add `createContentfulClientLoadingIntegration` from the server-only
`brix/contentful/server` subpath to `defineBrixServer(brix, { integrations })`.

During loading, a subscribed component receives `loaded.status === "pending"`, then the settled
result. Declare hooks before conditional returns. Brix preserves the component identity across
pending and settled states, including Preview refresh. Keep shared controls in a stable subtree
when their DOM state should also survive; changing your returned element type can still replace
that DOM node. No loading hook, token, or per-adapter cache is needed.

### Configure the loading policy

The integration accepts static options or an async request-scoped factory, evaluated lazily once
for render-time scope classification or loading/Preview. Keep that factory limited to
configuration; establish sessions in `middleware`, which runs after token verification on loading
endpoints. This middleware does not run for page issuance. The page rendering permissions must
establish the same session before `scope` and `authorize` run, using its own page middleware or
application-global session setup. The generated Contentful registry is required. Configure every
policy explicitly; page middleware is not inherited by endpoints:

`src/brix.server.ts`

```ts
import { createContentfulClientLoadingIntegration } from "brix/contentful/server";

export const brixServer = defineBrixServer(brix, {
  env,
  integrations: [
    createContentfulClientLoadingIntegration({
      audience: "site",
      generation: "v1",
      signingKey: "current",
      keys: permissionKeys,
      middleware: [identifySession],
      scope: (c) => resolveLoadingScope(c),
      authorize: (c, operation) => authorizeLoader(c, operation),
      resolve: (c, { identity, scope }, signal) =>
        resolveCanonicalEntry(c, identity, scope, signal),
    }),
  ],
});

```

`permissionKeys`, session middleware, and the three policy functions are application-owned server
code, not Brix defaults:

- `audience`, `generation`, and `signingKey` — nonempty labels of at most 256 characters without
  `:`. Changing `generation` revokes earlier permissions.
- `keys` — a record of Web Crypto `CryptoKey` values: HMAC SHA-256, at least 256 bits, with
  verification usage, plus signing usage on the `signingKey` entry. Import stable secret key
  material from server bindings; never generate a new key on each request or deployment.
- `middleware` — required, possibly empty; runs on the loading endpoints after token verification.
- `scope(c)` — the current session's scope.
- `authorize(c, operation)` — approves each phase; return false to deny.
- `resolve(c, { identity, scope }, signal)` — returns the current authorized canonical entry or
  `null`.
- `maxResponseBytes` — expanded loader JSON limit; default 1 MiB, positive integer up to 16 MiB.
- `maxUpstreamAttempts` — shared upstream attempt budget; default 64, positive safe integer.

TypeScript cannot infer the server's request context inside the nested factory call, so callback
parameters default to Hono's untyped `Context`. Annotate them, for example
`createContentfulClientLoadingIntegration(async (c: ServerContext) => policy)` with
`type ServerContext = Context<{ Bindings: Readonly<CoercedEnvSchema> }>`, when the callbacks read
typed `c.env`. Adapter loader handlers are typed by the factory instead:
`createContentfulAdapterFactory<ContentTypeMap, TContext>()` passes `TContext` as the handler's
second argument.

For example, reuse the session helper on each page that issues private grants:

```ts
import { createPageRoute } from "#brix/server";

export const articlePageRoute = createPageRoute(articlePageContract, {
  middleware: [identifySession],
  component: ArticlePage,
  load: loadArticlePage,
});

```

`articlePageContract`, `ArticlePage`, `loadArticlePage`, and `identifySession` are application code.
Application-global session middleware is another option, but it runs before endpoint token checks;
make repeated session setup request-memoized/idempotent if it is also registered on the endpoint.
Brix does not run loading-endpoint middleware on unrelated pages. Cache classification runs at the
render boundary even when a conditional island is absent or the page has no islands: private/Preview
scope marks HTML `private, no-store`, while public scope leaves the application's cache policy intact.

### Identities, scopes, and authorization

The identity contains `space`, `environment`, `locale`, `contentType`, and `entryId`. Entries read
with `locale: "*"` have no `sys.locale`; their identity locale is `"*"`, so `resolve` should read
them again with `locale: "*"`. A scope is
`{ mode: "public", tenant }` or `{ mode: "private" | "preview", tenant, principal, expires }`.
`expires` is an absolute Unix timestamp in milliseconds, in the next 24 hours. Scope strings are
nonempty, at most 256 characters, and cannot contain `:`. Match the current session and tenant on
every request.

`authorize` receives `phase`, `identity`, `scope`, and an optional `entry`. Approve `resolve` before
any CMS read, and `load` before executing a handler. `issue` separately approves browser-visible
candidates for signing; seeing an entry must not implicitly authorize a more privileged loader
response. The `issue` entry is a candidate, not proof of canonical content; the `load` entry has
been resolved by the server. `resolve` must never accept editor or browser snapshots as canonical
data. A denied phase returns 403, and a `null` or mismatched resolved entry returns 404. The browser
resource settles a 404 as that entry's `{ status: "error", reason: "failed" }` result. Sibling
adapters keep their data, because a deleted or unpublished entry is content state, not a session
change.

The request sends only a signed permission. Handlers receive the new API request context, not the
original page parameters. Use `getContentfulLoadingContext(c)` from `brix/contentful/server` for the
verified identity and scope, and choose the correct locale, tenant, credentials, and data-cache
partition. On loading endpoints this context is available to middleware and `scope` after signature
verification. Use its mode to select public/private/Preview policy, but derive the current principal
and tenant from the authenticated session; returning the token's scope unchanged is not session
validation. On the real-loader Preview page route, middleware and the `scope` callback both run
before any verified identity exists, so the context is `undefined` in both; select Preview policy
from the request path instead.
During initial Preview SSR, after the root is resolved, this is the shared preview-root identity, not
each concurrent child; use the handler's entry argument for that child's identity. Do not authorize loaders that
still depend on page-only context. Handlers must be read operations.

### Grants and browser resources

Brix signs distinct eligible entries in actually emitted island props and prepared loader results;
it does not run their loaders speculatively. Successful remote results can grant same-space,
same-environment, same-locale children after policy approval. Only entries whose adapter declares a
loader become candidates. Issuance fails explicitly beyond 256 distinct candidates or 256 KiB of
permissions instead of emitting partial state; this also applies to page grants. Endpoint grant
collection over loader results and saved Preview graphs also fails beyond 10,000 visited objects or
depth 32. Page grant collection shares the unbounded hydration scan of emitted props. Only the serialized data view contributes grants. Entries fabricated in browser code
or fetched through unrelated APIs receive no implicit permission. Permission candidates are
authorized separately: an unopened entry can receive a grant without loading, and a prepared result
can hydrate even when remote reloading is denied.

Committed mounts share requests within the page/fragment resource, with four concurrent requests.
Unmounting the last subscriber cancels work. Settled successes and failures are reused without
automatic retries. Transport failures and unavailable (404) entries become generic `Loaded` failures
for that entry. Missing, revoked, or unauthorized permissions (401, 403, 409) produce a
reload-required diagnostic and discard stale resource data.
Subscribed descendants can remain pending while current-generation grant discovery or authorized
loader requests can supply their grants. They load only when granted; if that work finishes without
granting them (including parent failure), missing permission becomes terminal rather than pending
forever. Initial missing-grant errors wait through committed subscription discovery, allowing a
child to mount before its granting parent in the same tree. Abandoned renders start no requests;
genuine settled loader failures remain cached rather than being retried when new grants arrive.

Applications changing private sessions without navigation must replace the provider resource or
call its `reset({ scope, permissions, loadedData })` with the new authorized payload; reset clears
old prepared and fetched results and ignores old replies. Pass an application-created resource from
`createContentfulLoadingResource({ scope, permissions, loadedData?, transport? })` as the provider's
`clientLoading` to own resets or to supply a server-free fixture transport.

### Endpoint limits

All endpoint responses are `no-store`; requests must be same-origin `application/json` POSTs. The
effective server request URL must retain the public HTTPS origin behind a TLS proxy. Brix does not
trust forwarded headers to bypass this check. On Node (`brix start`) and generated Lambda, set
`BRIX_PUBLIC_ORIGIN` to the public HTTPS origin; see [Node and Lambda deployment](/docs/deployment-node-aws.md).

- Request bodies are limited to 10 KiB of consumed bytes, independently of `Content-Length`.
- Resolution, authorization, and loader work inside the endpoint handler share a five-second
  monotonic deadline; the browser timeout is ten seconds. Exceeding the deadline produces a timeout.
- `maxResponseBytes` bounds expanded loader JSON and `maxUpstreamAttempts` bounds the shared upstream
  budget; exceeding either fails the load. Permissions retain their separate 256 KiB limit.

Configuration, body reading, and application middleware are outside the handler deadline: bound
their I/O and enforce a host-level request timeout. Aborting cannot forcibly stop application code
that ignores its signal. Grant collection checks cancellation before and after asynchronous
authorization/signing so it starts no further grant work after cancellation.

### Share the request budget with native clients

Native clients opt into the shared budget with `request: getContentfulLoadingContext(c)?.request`.
Use the same object for every client in canonical resolution and handler execution. Create these
clients lazily inside resolution/loading, not session middleware: middleware has the verified identity
but precedes execution-budget setup. Select source credentials and cache partitions from verified
identity/scope, and pass the verified locale to each query. Initial Preview SSR and ordinary page
loaders can instead use `request: { signal }` with the supplied loader/resolver signal.

Retries count as attempts; the native default is three attempts. Set
`retry: { maxAttempts: 1, on: [] }` when retries are inappropriate. Cache hits and same-request flight
joiners consume no additional attempts. Flights do not cross request budgets, but stored values
still share through normal cache/source identity. Raw fetches and other clients must pass the scope
signal and call its `onAttempt?.()` before each HTTP attempt or they bypass the budget.

No JavaScript timer can preempt synchronous application code, getters, `toJSON`, or schema callbacks;
overruns are detected when control returns. Upstream response sizes and noncooperative I/O still need
host limits. Prefer compact projections and explicit pagination to loading every card or fanning out
over every tag; budget rejection is not a substitute for application query design. Add aggregate
rate limits at your host: concurrency limits do not prevent bearer-token replay across requests or
instances. Reuse native data caching inside read handlers with the correct partition.

### Permission lifetime

Public permissions deliberately have no time expiry, so cached and SSG HTML can remain usable.
They are bearer permissions, not encrypted data. Keep old verification keys for the supported HTML
and open-page lifetime. Removing keys or changing the compatibility generation revokes old grants:
coordinate cache invalidation/rebuilds and reload open clients. Keep schemas and handlers compatible
with older browser bundles within a generation. Permission does not freeze content: deleted,
unpublished, or newly unauthorized entries can become unavailable. Private/preview HTML must remain
`private, no-store` through every edge and proxy. Static hosting still needs the same-origin runtime
endpoint; cross-origin transport is not supported.

## Add semantic Markdown

An adapter's `markdown` callback runs on the server and returns safe nodes from `brix/markdown`,
synchronously or as a promise, not a string or complete document. It receives the typed `entry`,
readonly extra `props`, the settled `loaded` result (or `null` without a loader), and an awaitable
`renderEntry`. Await child results before passing them to synchronous builders:

```ts
markdown: async ({ entry, renderEntry }) => {
  const children = await Promise.all(entry.fields.children.map((child) => renderEntry(child)));
  return md.fragment(...children.filter((child) => child !== null));
},

```

Use `markdown: false` only for intentionally visual-only nested content; it produces a `null`
nested result. Omitting a projection for an entry that Markdown reaches fails with its content type
and identity, and a root marked `false` fails rather than returning an empty page. Neither omitted
nor unsupported projections start a loader.

Represent the root in a page route whose contract declares `representations: ["markdown"]`, and add
the single document wrapper there:

```ts
import { markdownEntry } from "brix/contentful/rendering/registry";
import { md } from "brix/markdown";
import { createPageRoute } from "#brix/server";

export const articlePageRoute = createPageRoute(articlePageContract, {
  component: ArticlePage,
  load: async (c, { params }) => ({ entry: await getArticle(c, params.slug) }),
  markdown: async (c, { entry }) => md.document({ body: await markdownEntry(entry, c) }),
});

```

In this page-route excerpt, `articlePageContract`, `ArticlePage`, and `getArticle` are application
code. `getArticle` must return the adapter-backed entry in the explicit `entry` load prop. The
Markdown representation then produces one complete document from the same content tree.
`markdownEntry` is available only in server code.

Markdown loads only the entries explicitly requested by the projection. Unused fields, props,
loader results, and Rich Text hyperlinks do not start loaders. Repeated entries share one handler
execution, but each projection runs once with its own props; path-local cycles are omitted without
confusing shared parallel children for cycles. Calling `renderEntry` requests work even if its
promise is discarded, so always await or return it.

`markdownEntry(entry, c, options)` accepts:

- `props` — props for the root adapter;
- `signal` — the request signal by default;
- `timeoutMs` — the loader session deadline, 5000 by default;
- `concurrency` — concurrent loader handlers, 8 by default;
- `maxProjectionDepth` — 32 by default;
- `maxProjectionNodes` — 10000 by default.

Only handlers occupy concurrency slots, so concurrency one supports nested composition. The deadline
spans the whole loader session and stops new handlers after expiry or cancellation. Failures remain
settled loaded states for truthful fallback content. Keep external I/O inside `loader.handler`:
arbitrary asynchronous projection promises and CPU work are not preempted by the loader deadline.
Apply host request limits.

Configured private/Preview scopes force `private, no-store` for HTML and both negotiated and durable
Contentful Markdown, even without islands. This is cache classification, not page authorization or
automatic data-cache partitioning. New smaller payloads do not revoke grants or erase data from
already cached HTML; deployment key/generation and cache-invalidation requirements remain unchanged.

## Project Contentful Rich Text

Keep visual Rich Text rendering in your application component. For agent-readable output, project the structured document directly rather than converting rendered HTML:

```tsx
import { projectContentfulRichText } from "brix/contentful/rendering/markdown";

export const ArticleAdapter = createAdapter({
  contentType: "article",
  markdown: ({ entry, renderEntry }) =>
    projectContentfulRichText(entry.fields.body, { renderEntry }),
  component: ({ entry }) => <Article body={entry.fields.body} />,
});

```

Import projection helpers from `brix/contentful/rendering/markdown` and use them only inside
`markdown`; browser adapter builds remove them. The projector returns a promise of content and
awaits embedded entries while preserving order. It supports paragraphs, headings, lists,
blockquotes, separators, GFM tables, text marks, safe hyperlinks, assets, and embedded entries.
Embedded entries use the adapter registry. Supply `getEntryUrl(entry)` for entry hyperlinks; when
it is omitted or returns `null`, readable labels remain but Brix invents no destination.

Content degrades rather than failing when editors publish something Markdown cannot express safely:

- A hyperlink, entry hyperlink, or asset URL that Brix Markdown rejects (a disallowed scheme, a protocol-relative URL, credentials, a non-absolute HTTP URL, or an invalid host or encoding) keeps its label without a link.
- Link resolution replaces missing, unpublished, or inaccessible targets with `null`. Hyperlinks to them keep their labels; embedded entries and assets with `null` targets are omitted.
- Underline, superscript, and subscript have no portable Markdown form, so their text is kept without presentation.

Unknown node types and marks, unsupported placements, malformed targets, raw unresolved `Link` objects (resolve links before projecting), malformed tables, and documents deeper than 64 levels or larger than 10,000 nodes still fail explicitly.
