npm - @bgub/fig-server - Versions diffs - 0.0.1 → 0.1.0-alpha.1 - Mend

@bgub/fig-server 0.0.1 → 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +99 -72
package/dist/escaping-DAot8sFu.js +26 -0
package/dist/escaping-DAot8sFu.js.map +1 -0
package/dist/html-entry.d.ts +7 -0
package/dist/html-entry.js +2 -0
package/dist/index.d.ts +3 -7
package/dist/index.js +671 -395
package/dist/index.js.map +1 -1
package/dist/payload.d.ts +13 -236
package/dist/payload.js +235 -1363
package/dist/payload.js.map +1 -1
package/dist/{shared-CQn6Dje6.js → shared-Bna74_aZ.js} +22 -4
package/dist/shared-Bna74_aZ.js.map +1 -0
package/dist/{types-4X0JT0wt.d.ts → types-CimwEFsf.d.ts} +32 -10
package/package.json +8 -3
package/dist/shared-CQn6Dje6.js.map +0 -1

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @bgub/fig-server
-Fig server renderer.
+Fig server renderer for HTML and Payload component trees.
 ## Installation
@@ -109,18 +109,65 @@ Pass `identifierPrefix` when multiple streaming renders share a document. Fig
 uses it in generated Suspense marker and script identifiers, and it defaults to
 an empty string.
+Streams respect consumer backpressure: once the stream's internal queue holds
+`highWaterMark` encoded bytes (default 65536), completed Suspense content
+waits in segment form and flushes as the consumer reads. Rendering itself
+never pauses, so `shellReady`/`allReady` settle at the same time regardless of
+how fast the stream is consumed.
+## Content Security Policy
+Every script Fig streams is inline: the Suspense reveal runtime, the
+per-boundary reveal ops, and the early event-capture script that opens a
+document `<head>`. Under a CSP that restricts `script-src`, generate a
+per-request nonce, pass it as the `nonce` option, and allow it in the header —
+Fig adds it to every inline script and to emitted `<script>`/`<link>` resource
+tags:
+```ts
+const nonce = crypto.randomUUID();
+const result = renderToDocumentStream(<App />, { nonce });
+return new Response(result.stream, {
+  headers: {
+    "content-type": result.contentType,
+    "content-security-policy": `script-src 'self' 'nonce-${nonce}'`,
+  },
+});
+```
+The nonce is the whole CSP story. Fig intentionally ships no external-runtime
+alternative for nonce-less strict CSP (per-render op scripts also rule out
+static `script-src` hashes), so streamed Suspense requires the nonce. If you
+cannot attach one, use `prerender`: fragment mode emits no scripts at all, and
+document mode emits only the nonce-carrying early event-capture script.
+Framework adapters that add companion markup use the focused HTML helpers:
+```ts
+import {
+  escapeAttribute,
+  escapeScriptJson,
+  escapeScriptText,
+  escapeText,
+} from "@bgub/fig-server/html";
+```
+`escapeScriptText` preserves raw script content while preventing a literal
+`</script>` terminator; `escapeScriptJson` serializes a value and applies the
+same protection.
 ## Data Resources
-Server render requests have their own data-resource store. Reads through
-`@bgub/fig` dedupe by key within the request and fulfilled entries are
+Server render requests have their own data-resource store by default. Reads
+through `@bgub/fig` dedupe by key within the request and fulfilled entries are
 available through `result.getData()`:
 ```tsx
-import { readData } from "@bgub/fig";
-import { serverDataResource } from "@bgub/fig/server";
+import { dataResource, readData } from "@bgub/fig";
 import { renderToStream } from "@bgub/fig-server";
-const userResource = serverDataResource<[string], { name: string }>({
+const userResource = dataResource<[string], { name: string }>({
   key: (id) => ["user", id],
   load: async (id, { signal }) => fetchUser(id, signal),
 });
@@ -136,6 +183,22 @@ await result.allReady;
 const initialData = result.getData();
 ```
+Adapters that run loaders before rendering can create the store themselves.
+The renderer adopts that exact store instead of copying its entries:
+```tsx
+import { createDataStore } from "@bgub/fig";
+import { renderToStream } from "@bgub/fig-server";
+const dataStore = createDataStore();
+await dataStore.ensureData(userResource, "one");
+const result = renderToStream(<Profile id="one" />, { dataStore });
+result.data === dataStore; // true
+```
+One renderer may adopt a store, and that renderer owns its lifetime.
 Pass `initialData` to `createRoot(...)` or `hydrateRoot(...)` on the client to
 hydrate those values by key. Client imports can use a loader-less resource with
 the same key; if no client loader exists, `refreshData(...)` reports
@@ -162,10 +225,10 @@ and injects `title()` and `meta()` before `</head>`. With the lower-level
 `renderToStream`, those tags are available through `result.getHead()`
 after `headReady`; they are never emitted into segment HTML. `headReady`
 resolves with the shell and seals the initial document head; `getHead()` keeps
-returning that sealed snapshot afterward. If a new head resource is found
-later, such as behind pending Suspense, Fig reports it through `onAssetError`
-instead of adding it to the already-flushed head, so required shell metadata
-should render before `headReady`.
+returning that sealed snapshot afterward. Metadata discovered later stays staged
+with its Suspense content. When that boundary reveals, Fig replaces the visible
+fallback metadata with the completed branch's title/meta in the same reveal
+operation; failed or abandoned branches never mutate the document head.
 ```ts
 const result = renderToStream(<Page />);
@@ -190,12 +253,11 @@ function Page() {
 }
 ```
-Metadata discovered before `headReady` is injected into the initial document
-head. Metadata discovered after `headReady`, for example inside pending
-Suspense content, is reported through `onAssetError` and is not added to the
-already-flushed shell. Stylesheets discovered for later Suspense segments remain
-stream-safe: Fig emits them near the segment and gates reveal until they load
-unless `{ blocking: "none" }` opts out.
+Metadata for the shell's visible branch is injected into the initial document
+head. Metadata discovered in pending Suspense content is carried by its final
+boundary reveal; partial segment fills do not publish it. Stylesheets discovered
+for later Suspense segments remain stream-safe: Fig emits them near the segment
+and gates reveal until they load unless `{ blocking: "none" }` opts out.
 Stylesheets, preloads, fonts, preconnects, and scripts are body-stream-safe
 resources. Fig hoists them before the HTML segment that depends on them and
@@ -203,13 +265,13 @@ dedupes identical resources. Stylesheets block streamed Suspense reveals by
 default; pass `{ blocking: "none" }` to opt out for non-critical styles.
 Resource duplicates are checked by key and behavior. Identical duplicates dedupe
-silently. Conflicting duplicates throw: for example, the same stylesheet `href`
-with a different `media`, the same `title` key with a different value, or the
-same meta `name` with different `content`. Preloads are keyed by `href` plus
-`as`, so the same URL can be preloaded for distinct targets, but behavior fields
-such as `type`, `crossOrigin`, and `fetchPriority` must match for duplicates.
-Conflict errors include the resource key plus the existing and incoming
-resources.
+silently. Conflicting delivery assets throw: for example, the same stylesheet
+`href` with a different `media`. Title/meta instead use visible-owner claims, so
+a revealed primary branch can replace its fallback and releasing a claim can
+restore the previous value. Preloads are keyed by `href` plus `as`, so the same
+URL can be preloaded for distinct targets, but behavior fields such as `type`,
+`crossorigin`, and `fetchpriority` must match for duplicates. Conflict errors
+include the resource key plus the existing and incoming resources.
 The `assets` option can attach asset resources to component modules without
 wrapping the component tree. It is a string-keyed record intended for
@@ -228,59 +290,24 @@ renderToStream(<Page />, {
 Manifest assets use the same registry, destination rules, dedupe checks, and
 Suspense reveal gating as explicit `assets(...)` wrappers.
-## Payload (server components)
+## Payload components
 ```ts
-import {
-  createPayloadResponse,
-  decodePayloadValue,
-  encodePayloadValue,
-  fetchPayload,
-  jsonPayloadCodec,
-  PAYLOAD_BOUNDARY_HEADER,
-  renderToPayloadStream,
-  PayloadBoundary,
-  PayloadFetchError,
-  type PayloadCodec,
-} from "@bgub/fig-server/payload";
-```
-`renderToPayloadStream(node, options?)` renders a server-component payload. The
-result exposes `abort(reason?)`, and `options.signal` also cancels the render;
-both paths reject `allReady`. The default `jsonPayloadCodec` writes one
-readable JSON row per newline and identifies itself with
-`text/x-fig-payload; codec=json; charset=utf-8`. Pass a custom `PayloadCodec`
-to both `renderToPayloadStream(node, { codec })` and
-`createPayloadResponse({ codec })` when both ends should use a different byte
-encoding. Codec ids are implementation ids, not stable public wire formats.
-Pass `refreshBoundary` to render a targeted boundary refresh:
-```tsx
-renderToPayloadStream(<FeedItems />, { refreshBoundary: "feed" });
+import { renderToPayloadStream } from "@bgub/fig-server/payload";
 ```
-The rendered node must be the replacement content for that boundary. Do not
-include a nested `<PayloadBoundary id="feed">` wrapper in the refresh payload.
-`createPayloadResponse()` decodes streamed rows on the client, and
-`fetchPayload(response, input, options?)` fetches and processes a payload. Pass
-`refreshBoundary` to `fetchPayload` to request and apply a boundary refresh.
-`fetchPayload` sends the response codec in `Accept` and checks the response
-`codec=` content-type parameter before decoding. Server integrations can read
-the exported `PAYLOAD_BOUNDARY_HEADER` constant for targeted refresh requests.
-Non-2xx responses reject with `PayloadFetchError`, which exposes `status` and
-`response` and cancels the response body before throwing.
-Decoded client references require `loadClientReference` or a matching
-`resolveClientReference` before render; metadata-only decodes can still inspect
-rows without configuring a loader.
-`encodePayloadValue` / `decodePayloadValue` are low-level helpers for payload
-integrations that need the same data-value fidelity as payload data rows:
-`undefined`, `Date`, `Map`, `Set`, `BigInt`, non-finite numbers, `-0`, and
-global `Symbol.for` symbols round-trip. Shared references and cycles across
-arrays, plain objects, `Map`, and `Set` also round-trip; functions, class
-instances, and non-global symbols are rejected.
+`renderToPayloadStream(node, options?)` renders a component tree to Payload. The
+result exposes `stream`, `contentType`, and `allReady`; cancellation is
+signal-only — aborting `options.signal` (or cancelling the stream) cancels the
+render and rejects `allReady`. Pass the stream and content type directly to a `Response`. Browser
+code decodes it with `decodePayloadStream` from `@bgub/fig/payload`, normally
+through fig-dom's `createPayloadComponent`. Rows, codecs, value encoding, and
+framework document transports are internal implementation details.
+The public options cover error sanitization (`onError`), bundler-provided
+Payload component assets (`componentAssets`), manifest-provided client assets
+(`clientReferenceAssets`), data-store partitioning, byte backpressure
+(`highWaterMark`), and cancellation (`signal`).
 The server renderer supports function components, fragments, context providers,
 `useState` initial values, `useSyncExternalStore` server snapshots, no-op server

package/dist/escaping-DAot8sFu.js ADDED Viewed

@@ -0,0 +1,26 @@
+//#region src/escaping.ts
+function escapeText(value) {
+	return value.replace(/[&<>]/g, (character) => {
+		if (character === "&") return "&amp;";
+		if (character === "<") return "&lt;";
+		return "&gt;";
+	});
+}
+function escapeAttribute(value) {
+	return value.replace(/[&"<>]/g, (character) => {
+		if (character === "&") return "&amp;";
+		if (character === "\"") return "&quot;";
+		if (character === "<") return "&lt;";
+		return "&gt;";
+	});
+}
+function escapeScriptText(value) {
+	return value.replaceAll("<", "\\u003C").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+function escapeScriptJson(value) {
+	return escapeScriptText(JSON.stringify(value));
+}
+//#endregion
+export { escapeText as i, escapeScriptJson as n, escapeScriptText as r, escapeAttribute as t };
+//# sourceMappingURL=escaping-DAot8sFu.js.map

package/dist/escaping-DAot8sFu.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"escaping-DAot8sFu.js","names":[],"sources":["../src/escaping.ts"],"sourcesContent":["export function escapeText(value: string): string {\n return value.replace(/[&<>]/g, (character) => {\n if (character === \"&\") return \"&\";\n if (character === \"<\") return \"<\";\n return \">\";\n });\n}\n\nexport function escapeAttribute(value: string): string {\n return value.replace(/[&\"<>]/g, (character) => {\n if (character === \"&\") return \"&\";\n if (character === '\"') return \""\";\n if (character === \"<\") return \"<\";\n return \">\";\n });\n}\n\n// Script elements are raw-text elements: HTML entities are not decoded in\n// their contents, so escape only characters that can terminate the element\n// or executable source.\nexport function escapeScriptText(value: string): string {\n return value\n .replaceAll(\"<\", \"\\\\u003C\")\n .replaceAll(\"\\u2028\", \"\\\\u2028\")\n .replaceAll(\"\\u2029\", \"\\\\u2029\");\n}\n\nexport function escapeScriptJson(value: unknown): string {\n return escapeScriptText(JSON.stringify(value));\n}\n"],"mappings":";AAAA,SAAgB,WAAW,OAAuB;CAChD,OAAO,MAAM,QAAQ,WAAW,cAAc;EAC5C,IAAI,cAAc,KAAK,OAAO;EAC9B,IAAI,cAAc,KAAK,OAAO;EAC9B,OAAO;CACT,CAAC;AACH;AAEA,SAAgB,gBAAgB,OAAuB;CACrD,OAAO,MAAM,QAAQ,YAAY,cAAc;EAC7C,IAAI,cAAc,KAAK,OAAO;EAC9B,IAAI,cAAc,MAAK,OAAO;EAC9B,IAAI,cAAc,KAAK,OAAO;EAC9B,OAAO;CACT,CAAC;AACH;AAKA,SAAgB,iBAAiB,OAAuB;CACtD,OAAO,MACJ,WAAW,KAAK,SAAS,CAAC,CAC1B,WAAW,UAAU,SAAS,CAAC,CAC/B,WAAW,UAAU,SAAS;AACnC;AAEA,SAAgB,iBAAiB,OAAwB;CACvD,OAAO,iBAAiB,KAAK,UAAU,KAAK,CAAC;AAC/C"}

package/dist/html-entry.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+//#region src/escaping.d.ts
+declare function escapeText(value: string): string;
+declare function escapeAttribute(value: string): string;
+declare function escapeScriptText(value: string): string;
+declare function escapeScriptJson(value: unknown): string;
+//#endregion
+export { escapeAttribute, escapeScriptJson, escapeScriptText, escapeText };

package/dist/html-entry.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { i as escapeText, n as escapeScriptJson, r as escapeScriptText, t as escapeAttribute } from "./escaping-DAot8sFu.js";
2	+ export { escapeAttribute, escapeScriptJson, escapeScriptText, escapeText };

package/dist/index.d.ts CHANGED Viewed

@@ -1,9 +1,5 @@
-import { a as ServerErrorPayload, c as ServerPrerenderResult, d as RenderTreeKind, f as RenderTreeNode, i as ServerErrorInfo, l as ServerRenderOptions, n as ServerAssetErrorInfo, o as ServerFragmentRenderResult, p as createRenderTreeCollector, r as ServerDocumentRenderResult, s as ServerPrerenderOptions, t as ServerAssetDestination, u as RenderTreeCollector } from "./types-4X0JT0wt.js";
-import { FigNode, Props } from "@bgub/fig";
-//#region src/html.d.ts
-declare function escapeText(value: string): string;
-declare function escapeAttribute(value: string): string;
-//#endregion
+import { a as ServerPreloadHeaderOptions, c as ServerPrerenderResult, d as RenderTreeKind, f as RenderTreeNode, i as ServerFragmentRenderResult, l as ServerRenderOptions, n as ServerErrorInfo, o as ServerPreloadHeaderResource, p as createRenderTreeCollector, r as ServerErrorPayload, s as ServerPrerenderOptions, t as ServerDocumentRenderResult, u as RenderTreeCollector } from "./types-CimwEFsf.js";
+import { FigNode } from "@bgub/fig";
 //#region src/index.d.ts
 declare function renderToStream(node: FigNode, options?: ServerRenderOptions): ServerFragmentRenderResult;
 declare function renderToDocumentStream(node: FigNode, options?: ServerRenderOptions): ServerDocumentRenderResult;
@@ -24,4 +20,4 @@ declare function renderToDocumentHtml(node: FigNode, options?: ServerRenderOptio
  */
 declare function prerender(node: FigNode, options?: ServerPrerenderOptions): Promise<ServerPrerenderResult>;
 //#endregion
-export { type RenderTreeCollector, type RenderTreeKind, type RenderTreeNode, type ServerAssetDestination, type ServerAssetErrorInfo, type ServerDocumentRenderResult, type ServerErrorInfo, type ServerErrorPayload, type ServerFragmentRenderResult, type ServerPrerenderOptions, type ServerPrerenderResult, type ServerRenderOptions, createRenderTreeCollector, escapeAttribute, escapeText, prerender, renderToDocumentHtml, renderToDocumentStream, renderToHtml, renderToStream };
+export { type RenderTreeCollector, type RenderTreeKind, type RenderTreeNode, type ServerDocumentRenderResult, type ServerErrorInfo, type ServerErrorPayload, type ServerFragmentRenderResult, type ServerPreloadHeaderOptions, type ServerPreloadHeaderResource, type ServerPrerenderOptions, type ServerPrerenderResult, type ServerRenderOptions, createRenderTreeCollector, prerender, renderToDocumentHtml, renderToDocumentStream, renderToHtml, renderToStream };