@jasy/react 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Heuberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/logo.png" width="120" alt="jasy">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@jasy/react</h1>
+
+<p align="center">
+  <b>Author PDFs as React components - and render them right in the browser.</b>
+</p>
+
+A thin React renderer over the [`@jasy/pdf`](https://npmx.dev/@jasy/pdf) engine. You write a component
+tree, you get a real PDF: no headless browser, no server round-trip, no Java.
+
+```tsx
+import { Document, Page, Row, Text, Table, TableRow, TableCell, renderToPdf } from "@jasy/react";
+
+function Invoice({ items }: { items: { desc: string; amount: string }[] }) {
+  return (
+    <Document size={11}>
+      <Page size="A4" gap={16} footer={<Text size={9}>Acme GmbH · Berlin</Text>}>
+        <Row justify="between">
+          <Text size={22} bold color="#0a2348">
+            Acme GmbH
+          </Text>
+          <Text size={22} bold color="#1450aa">
+            INVOICE
+          </Text>
+        </Row>
+        <Table columns={["1fr", 120]} cellBorder="#e2e8f0" cellPadding={8}>
+          <TableRow header>
+            <TableCell>Description</TableCell>
+            <TableCell>Amount (EUR)</TableCell>
+          </TableRow>
+          {items.map((item) => (
+            <TableRow key={item.desc}>
+              <TableCell>{item.desc}</TableCell>
+              <TableCell>{item.amount}</TableCell>
+            </TableRow>
+          ))}
+        </Table>
+      </Page>
+    </Document>
+  );
+}
+
+const items = [
+  { desc: "Design work", amount: "1,200.00" },
+  { desc: "Development", amount: "3,400.00" },
+];
+const bytes = await renderToPdf(<Invoice items={items} />); // in the browser or in Node
+```
+
+## Why
+
+- **Runs in the browser.** `renderToPdf` produces the PDF bytes client-side. No `/api/render`, no Node
+  on the request path. The same call works in Node.
+- **Real layout, real pagination.** `Row`/`Column` flex, wrapping, `%` sizes, a table whose header row
+  repeats on every page, newspaper columns. Not a drawing API you hand absolute coordinates.
+- **React, all of it.** Hooks, context, lists with `key`, your own components. A component that
+  throws fails the render with that error.
+- **Typed by the engine.** Every prop type IS the engine's option type, so a new engine option is a
+  typed prop the day it ships, and a wrong value goes red in your editor.
+- **The same bytes.** A document in JSX renders byte-for-byte like the same document written with the
+  `@jasy/pdf` functions. The test suite holds every component to that.
+
+## Install
+
+```bash
+pnpm add @jasy/react @jasy/pdf react
+```
+
+React 19.
+
+## Components
+
+| Group      | Components                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------ |
+| Structure  | `Document` · `Page` · `PageBreak` · `KeepTogether` · `DefaultTextStyle` · `PageBuilder`                |
+| Layout     | `Column` · `Row` · `Box` · `Padding` · `Expanded` · `Spacer` · `Positioned` · `Rotated` · `RotatedBox` |
+| Text       | `Text` · `Paragraph` · `Span` · `PageNumber` · `PageCount` · `SubPageNumber` · `SubPageCount`          |
+| Content    | `Image` · `Svg` · `Canvas` · `Divider` · `Table` · `TableRow` · `TableCell`                            |
+| Flow       | `Flow` · `Region` · `ColumnBreak` · `SplitView`                                                        |
+| Navigation | `Link` · `Anchor` · `Bookmark`                                                                         |
+| Forms      | `TextField` · `Checkbox` · `RadioGroup` · `Dropdown` · `ListBox` · `PushButton` · `SignatureField`     |
+
+The props are the options of the matching `@jasy/pdf` function, documented at [jasy.dev](https://jasy.dev).
+Where React has its own way, it is used:
+
+- **Text is children.** `<Text bold>Total: {sum}</Text>`, and `<Span>` styles part of a line.
+- **A form field's label is its children.** `<Checkbox name="agree">I agree</Checkbox>`.
+- **Repeating areas are props.** `<Page header={<Logo />} footer={<PageNumber />}>`: laid out once and
+  repeated on every page the content flows onto, with the space they need reserved.
+- **What depends on the page is a function child**, built for every page it lands on:
+  `<PageBuilder>{({ pageNumber, pageCount }) => <Text>Page {pageNumber} of {pageCount}</Text>}</PageBuilder>`.
+- **A Flow's page is a render prop**, rendered in place, so hooks and context work in it:
+
+```tsx
+<Flow
+  page={({ index }) => (
+    <Row gap={14}>
+      <Expanded>
+        <Region />
+      </Expanded>
+      <Region width={index === 0 ? 150 : 100} />
+    </Row>
+  )}
+>
+  {paragraphs.map((p) => (
+    <Text key={p}>{p}</Text>
+  ))}
+</Flow>
+```
+
+## Fonts and images
+
+Both load as bytes, so the same code runs in the browser and in Node:
+
+```tsx
+<Document fonts={{ GreatVibes: fontBytes }}>
+  <Page>
+    <Text font="GreatVibes" size={44}>
+      Jasy Atelier
+    </Text>
+    <Image src={photoBytes} width={84} height={84} fit="cover" radius={42} />
+  </Page>
+</Document>
+```
+
+## API
+
+- `renderToPdf(element, options?) => Promise<Uint8Array>` - the PDF bytes. Browser or Node.
+- `renderToPdfString(element, options?) => Promise<string>` - the raw PDF string.
+- `options` are the `@jasy/pdf` `RenderOptions`, e.g. `{ encrypt: { userPassword: "secret" } }` for
+  AES-256, `{ accessible: true }` for a tagged PDF, `onDiagnostic` for what the engine has to say.
+- `toDocumentDescriptor(element)` - the engine descriptor of the document, a plain object. Before
+  posting it as JSON, encode font and image bytes yourself (JSON has no `Uint8Array`) and decode them on
+  the other side. Functions do not survive JSON at all, so a document with a `Canvas`, a `Flow` or a
+  `PageBuilder` goes through `renderToPdf`.
+
+## Try it
+
+```bash
+git clone https://github.com/jasy-pdf/jasy && cd jasy && pnpm install && pnpm run build
+pnpm --filter @jasy/react play
+```
+
+The playground renders twelve documents in the browser, side by side with their source: an invoice
+that grows across pages, a newspaper, layout, typography, drawing, fonts, form fields, encryption.
+
+---
+
+Part of [Jasy](https://jasy.dev) - a declarative, dependency-light PDF toolkit in pure TypeScript.
+MIT, by Florian Heuberger.

package/dist/components.d.ts

@@ -0,0 +1,170 @@
+import { type ReactNode } from "react";
+import type { BoxOptions, CanvasOptions, CanvasPaint, CheckboxOptions, ChoiceOptionInput, DividerOptions, DocumentOptions, DropdownOptions, ExpandedOptions, FlowOptions, FlowPage, FontSource, ImageOptions, ImageSource, Insets, ListBoxOptions, PageNumberOptions, PageInfo, PageOptions, PositionedInsets, PushButtonOptions, RadioChoice, RadioGroupOptions, RegionOptions, SignatureFieldOptions, SplitViewOptions, StackOptions, SvgOptions, SvgSource, TableOptions, TextDefaults, TextFieldOptions, TextOptions, TextStyle } from "@jasy/pdf";
+type WithChildren = {
+    children?: ReactNode;
+};
+/** Text a field draws as its label: `<Checkbox name="agree">I agree</Checkbox>`. */
+type LabelText = string | number | Array<string | number>;
+export type DocumentProps = DocumentOptions & WithChildren & {
+    /** Fonts by family name: a file path (Node), the file's bytes, a URL or a family of styles. */
+    fonts?: Record<string, FontSource>;
+};
+export type PageProps = Omit<PageOptions, "header" | "footer"> & WithChildren & {
+    /** Laid out at the top of every physical page the content flows onto. */
+    header?: ReactNode;
+    /** Laid out at the bottom of every physical page the content flows onto. */
+    footer?: ReactNode;
+};
+export type StackProps = StackOptions & WithChildren;
+export type BoxProps = BoxOptions & WithChildren;
+export type PaddingProps = WithChildren & {
+    insets?: Insets;
+};
+export type ExpandedProps = ExpandedOptions & WithChildren;
+export type SpacerProps = {
+    flex?: number;
+};
+export type DividerProps = DividerOptions;
+export type ImageProps = ImageOptions & {
+    src: ImageSource;
+};
+export type SvgProps = SvgOptions & {
+    src: SvgSource;
+};
+export type CanvasProps = CanvasOptions & {
+    paint: CanvasPaint;
+};
+export type TextProps = TextOptions & WithChildren;
+export type SpanProps = TextStyle & WithChildren;
+export type TableProps = Omit<TableOptions, "header"> & WithChildren;
+export type TableRowProps = WithChildren & {
+    /** Repeat this row at the top of every page the table flows onto. */
+    header?: boolean;
+};
+export type FlowProps = Omit<FlowOptions, "template"> & WithChildren & {
+    /** One page of the Flow, per page: the `Region`s in it are where the content goes. */
+    page: (info: FlowPage) => ReactNode;
+};
+export type RegionProps = RegionOptions;
+export type SplitViewProps = SplitViewOptions & WithChildren;
+export type PositionedProps = PositionedInsets & WithChildren;
+export type DefaultTextStyleProps = TextDefaults & WithChildren;
+/** Exactly one target: `href` opens a URL, `to` jumps to an `Anchor` of that name. */
+export type LinkProps = WithChildren & ({
+    href: string;
+    to?: never;
+} | {
+    to: string;
+    href?: never;
+});
+export type AnchorProps = WithChildren & {
+    name: string;
+};
+export type BookmarkProps = WithChildren & {
+    title: string;
+    level?: number;
+};
+export type RotatedProps = WithChildren & {
+    angle: number;
+};
+export type RotatedBoxProps = WithChildren & {
+    turns: number;
+};
+export type PageNumberProps = PageNumberOptions;
+export type PageBuilderProps = {
+    /** What to show, built from the page it lands on. */
+    children: (info: PageInfo) => ReactNode;
+};
+export type TextFieldProps = TextFieldOptions;
+export type CheckboxProps = CheckboxOptions & {
+    children?: LabelText;
+};
+export type RadioGroupProps = RadioGroupOptions & {
+    /** The choices: `["S", "M"]`, or `{ value, label }` when the label differs. */
+    options: Array<string | RadioChoice>;
+};
+export type DropdownProps = DropdownOptions & {
+    options: ChoiceOptionInput[];
+};
+export type ListBoxProps = ListBoxOptions & {
+    options: ChoiceOptionInput[];
+};
+export type PushButtonProps = Omit<PushButtonOptions, "label"> & {
+    label?: string;
+    children?: LabelText;
+};
+export type SignatureFieldProps = SignatureFieldOptions & {
+    children?: LabelText;
+};
+export declare const Document: (props: DocumentProps) => ReactNode;
+/** A page template; `header` and `footer` repeat on every physical page the content flows onto. */
+export declare function Page({ header, footer, children, ...props }: PageProps): ReactNode;
+export declare const Column: (props: StackProps) => ReactNode;
+export declare const Row: (props: StackProps) => ReactNode;
+export declare const Box: (props: BoxProps) => ReactNode;
+export declare const Padding: (props: PaddingProps) => ReactNode;
+export declare const Expanded: (props: ExpandedProps) => ReactNode;
+export declare const Spacer: (props: SpacerProps) => ReactNode;
+export declare const PageBreak: (props: object) => ReactNode;
+/** Keeps its children on one page (CSS `break-inside: avoid`); also a `keepTogether` prop on stacks. */
+export declare const KeepTogether: (props: WithChildren) => ReactNode;
+export declare const Divider: (props: DividerOptions) => ReactNode;
+export declare const Image: (props: ImageProps) => ReactNode;
+export declare const Svg: (props: SvgProps) => ReactNode;
+export declare const Canvas: (props: CanvasProps) => ReactNode;
+export declare const Text: (props: TextProps) => ReactNode;
+export declare const Paragraph: (props: TextProps) => ReactNode;
+export declare const Span: (props: SpanProps) => ReactNode;
+export declare const Table: (props: TableProps) => ReactNode;
+export declare const TableRow: (props: TableRowProps) => ReactNode;
+export declare const TableCell: (props: WithChildren) => ReactNode;
+export declare const Region: (props: RegionOptions) => ReactNode;
+export declare const ColumnBreak: (props: object) => ReactNode;
+export declare const SplitView: (props: SplitViewProps) => ReactNode;
+export declare const Positioned: (props: PositionedProps) => ReactNode;
+export declare const DefaultTextStyle: (props: DefaultTextStyleProps) => ReactNode;
+export declare const Link: (props: LinkProps) => ReactNode;
+export declare const Anchor: (props: AnchorProps) => ReactNode;
+export declare const Bookmark: (props: BookmarkProps) => ReactNode;
+export declare const Rotated: (props: RotatedProps) => ReactNode;
+export declare const RotatedBox: (props: RotatedBoxProps) => ReactNode;
+export declare const PageNumber: (props: PageNumberOptions) => ReactNode;
+export declare const PageCount: (props: PageNumberOptions) => ReactNode;
+/** The page number within its `Page` (a section of the document), as text. */
+export declare const SubPageNumber: (props: PageNumberOptions) => ReactNode;
+/** How many pages its `Page` (a section of the document) produced, as text. */
+export declare const SubPageCount: (props: PageNumberOptions) => ReactNode;
+export declare const TextField: (props: TextFieldOptions) => ReactNode;
+export declare const Checkbox: {
+    ({ children, label, ...props }: CheckboxProps): import("react").ReactElement<Omit<CheckboxProps, "children" | "label"> & {
+        label: string | undefined;
+    }, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const RadioGroup: (props: RadioGroupProps) => ReactNode;
+export declare const Dropdown: (props: DropdownProps) => ReactNode;
+export declare const ListBox: (props: ListBoxProps) => ReactNode;
+export declare const PushButton: {
+    ({ children, label, ...props }: PushButtonProps): import("react").ReactElement<Omit<PushButtonProps, "children" | "label"> & {
+        label: string | undefined;
+    }, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const SignatureField: {
+    ({ children, label, ...props }: SignatureFieldProps): import("react").ReactElement<Omit<SignatureFieldProps, "children" | "label"> & {
+        label: string | undefined;
+    }, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+/**
+ * Content flowing through the `Region`s of `page`: the first Region full, then the next, then the next
+ * page. `page` is rendered for every page while the engine lays the document out.
+ */
+export declare function Flow({ page, children, ...props }: FlowProps): ReactNode;
+/**
+ * Content built from the page it lands on: `{({ pageNumber, pageCount }) => ...}` as its child. Place
+ * it anywhere - a header, a footer, the body, a table cell. What it builds is placed whole on its page;
+ * build nothing (`null`) to show it on some pages only.
+ */
+export declare function PageBuilder({ children }: PageBuilderProps): ReactNode;
+export {};

package/dist/components.js

@@ -0,0 +1,104 @@
+import { createElement as h, useContext, useRef, useState } from "react";
+import { childDescriptors, flushNow, RenderSinkContext } from "./renderer.js";
+/** A component that leaves one host node of `type` with its props and children. */
+function host(type, name) {
+    const component = ({ children, ...props }) => h(type, props, children);
+    component.displayName = name;
+    return component;
+}
+/** A field whose children are its label: forwarded as the `label` prop the engine draws. */
+function labelled(type, name) {
+    const component = ({ children, label, ...props }) => {
+        const text = [children ?? []].flat().join("").trim();
+        return h(type, { ...props, label: text || label });
+    };
+    component.displayName = name;
+    return component;
+}
+export const Document = host("document", "Document");
+/** A page template; `header` and `footer` repeat on every physical page the content flows onto. */
+export function Page({ header, footer, children, ...props }) {
+    return h("page", props, header != null && h("page-header", null, header), footer != null && h("page-footer", null, footer), children);
+}
+export const Column = host("column", "Column");
+export const Row = host("row", "Row");
+export const Box = host("box", "Box");
+export const Padding = host("padding", "Padding");
+export const Expanded = host("expanded", "Expanded");
+export const Spacer = host("spacer", "Spacer");
+export const PageBreak = host("page-break", "PageBreak");
+/** Keeps its children on one page (CSS `break-inside: avoid`); also a `keepTogether` prop on stacks. */
+export const KeepTogether = host("keep-together", "KeepTogether");
+export const Divider = host("divider", "Divider");
+export const Image = host("image", "Image");
+export const Svg = host("svg", "Svg");
+export const Canvas = host("canvas", "Canvas");
+export const Text = host("text", "Text");
+export const Paragraph = host("paragraph", "Paragraph");
+export const Span = host("span", "Span");
+export const Table = host("table", "Table");
+export const TableRow = host("table-row", "TableRow");
+export const TableCell = host("table-cell", "TableCell");
+export const Region = host("region", "Region");
+export const ColumnBreak = host("column-break", "ColumnBreak");
+export const SplitView = host("split-view", "SplitView");
+export const Positioned = host("positioned", "Positioned");
+export const DefaultTextStyle = host("default-text-style", "DefaultTextStyle");
+export const Link = host("link", "Link");
+export const Anchor = host("anchor", "Anchor");
+export const Bookmark = host("bookmark", "Bookmark");
+export const Rotated = host("rotated", "Rotated");
+export const RotatedBox = host("rotated-box", "RotatedBox");
+export const PageNumber = host("page-number", "PageNumber");
+export const PageCount = host("page-count", "PageCount");
+/** The page number within its `Page` (a section of the document), as text. */
+export const SubPageNumber = host("sub-page-number", "SubPageNumber");
+/** How many pages its `Page` (a section of the document) produced, as text. */
+export const SubPageCount = host("sub-page-count", "SubPageCount");
+export const TextField = host("text-field", "TextField");
+export const Checkbox = labelled("checkbox", "Checkbox");
+export const RadioGroup = host("radio-group", "RadioGroup");
+export const Dropdown = host("dropdown", "Dropdown");
+export const ListBox = host("list-box", "ListBox");
+export const PushButton = labelled("push-button", "PushButton");
+export const SignatureField = labelled("signature-field", "SignatureField");
+/**
+ * Renders `render(info)` in place, in the tree, whenever the engine asks during layout - so hooks and
+ * context work in it as anywhere else. Each request carries the `render` of the render that made it, so
+ * a callback the engine kept from an earlier page still draws what that page rendered.
+ */
+function useRenderedOnRequest(component, render) {
+    const [asked, setAsked] = useState();
+    const self = useRef(null);
+    const sink = useContext(RenderSinkContext);
+    const request = (info) => {
+        if (!self.current || !sink) {
+            throw new Error(`@jasy/react: a <${component}> renders while the PDF is laid out - render the document ` +
+                "with renderToPdf, which keeps it mounted until then.");
+        }
+        flushNow(() => setAsked({ info, render }));
+        if (sink.failure)
+            throw sink.failure;
+        const marker = self.current.children.find((c) => c.type === "rendered-on-request");
+        return marker ? childDescriptors(marker) : [];
+    };
+    const rendered = asked && h("rendered-on-request", null, asked.render(asked.info));
+    return { ref: self, request, rendered };
+}
+/**
+ * Content flowing through the `Region`s of `page`: the first Region full, then the next, then the next
+ * page. `page` is rendered for every page while the engine lays the document out.
+ */
+export function Flow({ page, children, ...props }) {
+    const { ref, request, rendered } = useRenderedOnRequest("Flow", page);
+    return h("flow", { ...props, page: request, ref }, rendered, children);
+}
+/**
+ * Content built from the page it lands on: `{({ pageNumber, pageCount }) => ...}` as its child. Place
+ * it anywhere - a header, a footer, the body, a table cell. What it builds is placed whole on its page;
+ * build nothing (`null`) to show it on some pages only.
+ */
+export function PageBuilder({ children }) {
+    const { ref, request, rendered } = useRenderedOnRequest("PageBuilder", children);
+    return h("page-builder", { build: request, ref }, rendered);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import { type Descriptor, type RenderOptions } from "@jasy/pdf";
+export * from "./components.js";
+/** Render an element whose root is a `<Document>` to PDF bytes - browser or Node. */
+export declare function renderToPdf(element: ReactNode, options?: RenderOptions): Promise<Uint8Array<ArrayBuffer>>;
+/** Render an element to the raw PDF string - browser or Node. */
+export declare function renderToPdfString(element: ReactNode, options?: RenderOptions): Promise<string>;
+/**
+ * The engine descriptor for an element's `<Document>`, a plain object. As JSON it loses what JSON cannot
+ * hold: bytes (encode fonts and images yourself) and functions - a `Canvas`'s paint, and a `Flow` or
+ * `PageBuilder`, which render during the PDF render. Those documents go through `renderToPdf`.
+ */
+export declare function toDocumentDescriptor(element: ReactNode): Descriptor;

package/dist/index.js

@@ -0,0 +1,31 @@
+import { buildDocument, renderPdf, renderToBytes, } from "@jasy/pdf";
+import { mountDocument } from "./renderer.js";
+export * from "./components.js";
+/** Mounted until the PDF is done: a `Flow` renders its page while the engine lays the pages out. */
+async function rendered(element, render) {
+    const { descriptor, unmount } = mountDocument(element);
+    try {
+        return await render(buildDocument(descriptor));
+    }
+    finally {
+        unmount();
+    }
+}
+/** Render an element whose root is a `<Document>` to PDF bytes - browser or Node. */
+export function renderToPdf(element, options) {
+    return rendered(element, (doc) => renderToBytes(doc, options));
+}
+/** Render an element to the raw PDF string - browser or Node. */
+export function renderToPdfString(element, options) {
+    return rendered(element, (doc) => renderPdf(doc, options));
+}
+/**
+ * The engine descriptor for an element's `<Document>`, a plain object. As JSON it loses what JSON cannot
+ * hold: bytes (encode fonts and images yourself) and functions - a `Canvas`'s paint, and a `Flow` or
+ * `PageBuilder`, which render during the PDF render. Those documents go through `renderToPdf`.
+ */
+export function toDocumentDescriptor(element) {
+    const { descriptor, unmount } = mountDocument(element);
+    unmount();
+    return descriptor;
+}

package/dist/renderer.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import type { Descriptor, DescriptorChild } from "@jasy/pdf";
+/**
+ * A host node in our tree. It is shaped like a `Descriptor` already: the reconciler builds this tree,
+ * and it maps 1:1 onto the engine's descriptor seam. Text nodes carry `text`; `parent` is bookkeeping
+ * the reconciler needs (insert/remove), stripped on the way out.
+ */
+export interface JNode {
+    type: string;
+    props: Record<string, any>;
+    children: JNode[];
+    text?: string;
+    parent: JNode | null;
+}
+/** Where a render reports an error thrown in the tree - also while a `Flow` re-renders its page. */
+export interface RenderSink {
+    failure?: unknown;
+}
+export declare const RenderSinkContext: import("react").Context<RenderSink | null>;
+/**
+ * A node's children as descriptors - also what a `Flow` reads its rendered page from. `Total: {sum}` is
+ * two text nodes in React; merged back into one string they measure and kern as the one run they are.
+ */
+export declare function childDescriptors(n: JNode): DescriptorChild[];
+/**
+ * Mounts an element and returns the engine descriptor for its `<Document>` root, with the tree still
+ * mounted: a `Flow` renders its `page` for every page while the engine lays the document out.
+ */
+export declare function mountDocument(element: ReactNode): {
+    descriptor: Descriptor;
+    unmount: () => void;
+};
+/** Synchronously apply a state update made outside React's render, so its result can be read back. */
+export declare function flushNow(update: () => void): void;

package/dist/renderer.js

@@ -0,0 +1,162 @@
+import Reconciler from "react-reconciler";
+import { DefaultEventPriority, LegacyRoot } from "react-reconciler/constants.js";
+import { createContext, createElement } from "react";
+const node = (type, props = {}) => ({
+    type,
+    props,
+    children: [],
+    parent: null,
+});
+// `children` and `ref` are React's, not props the engine reads - the tree carries the children.
+function ownProps({ children: _children, ref: _ref, ...rest }) {
+    return rest;
+}
+function insert(parent, child, before) {
+    detach(child);
+    child.parent = parent;
+    const i = before ? parent.children.indexOf(before) : -1;
+    if (i >= 0)
+        parent.children.splice(i, 0, child);
+    else
+        parent.children.push(child);
+}
+function detach(child) {
+    const siblings = child.parent?.children;
+    const i = siblings?.indexOf(child) ?? -1;
+    if (siblings && i >= 0)
+        siblings.splice(i, 1);
+    child.parent = null;
+}
+let updatePriority = DefaultEventPriority;
+// The host config, as react-reconciler 0.31 (React 19) calls it - see react-reconciler.d.ts.
+const hostConfig = {
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    isPrimaryRenderer: false,
+    noTimeout: -1,
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    supportsMicrotasks: true,
+    scheduleMicrotask: queueMicrotask,
+    createInstance: (type, props) => node(type, ownProps(props)),
+    createTextInstance: (text) => Object.assign(node("#text"), { text }),
+    appendInitialChild: insert,
+    appendChild: insert,
+    appendChildToContainer: insert,
+    insertBefore: insert,
+    insertInContainerBefore: insert,
+    removeChild: (_parent, child) => detach(child),
+    removeChildFromContainer: (_parent, child) => detach(child),
+    clearContainer: (container) => {
+        container.children = [];
+    },
+    commitUpdate: (n, _type, _prev, next) => {
+        n.props = ownProps(next);
+    },
+    commitTextUpdate: (n, _prev, next) => {
+        n.text = next;
+    },
+    finalizeInitialChildren: () => false,
+    shouldSetTextContent: () => false,
+    getRootHostContext: () => ({}),
+    getChildHostContext: (parent) => parent,
+    getPublicInstance: (n) => n,
+    prepareForCommit: () => null,
+    resetAfterCommit: () => { },
+    preparePortalMount: () => { },
+    detachDeletedInstance: () => { },
+    hideInstance: () => { },
+    unhideInstance: () => { },
+    hideTextInstance: () => { },
+    unhideTextInstance: () => { },
+    // Scheduling: a PDF is rendered in one synchronous pass, there are no events to prioritize.
+    getCurrentEventPriority: () => DefaultEventPriority,
+    getCurrentUpdatePriority: () => updatePriority,
+    setCurrentUpdatePriority: (p) => {
+        updatePriority = p;
+    },
+    resolveUpdatePriority: () => updatePriority,
+    resolveEventType: () => null,
+    resolveEventTimeStamp: () => -1.1,
+    shouldAttemptEagerTransition: () => false,
+    trackSchedulerEvent: () => { },
+    requestPostPaintCallback: () => { },
+    getInstanceFromNode: () => null,
+    beforeActiveInstanceBlur: () => { },
+    afterActiveInstanceBlur: () => { },
+    prepareScopeUpdate: () => { },
+    getInstanceFromScope: () => null,
+    maySuspendCommit: () => false,
+    preloadInstance: () => true,
+    startSuspendingCommit: () => { },
+    suspendInstance: () => { },
+    waitForCommitToBeReady: () => null,
+    NotPendingTransition: null,
+    HostTransitionContext: createContext(null),
+    resetFormInstance: () => { },
+};
+const reconciler = Reconciler(hostConfig);
+export const RenderSinkContext = createContext(null);
+// Text and Paragraph read their children as text, so whitespace there is content (`{" "}` between two
+// spans). Everywhere else a whitespace-only string would become an empty Text with a stray `gap`.
+const TEXT_PARENTS = new Set(["text", "paragraph", "span"]);
+/** Strip our tree down to the engine's descriptor: adjacent strings merge, empty ones are dropped. */
+function toDescriptor(n) {
+    if (n.type === "#text")
+        return n.text ?? "";
+    return { type: n.type, props: n.props, children: childDescriptors(n) };
+}
+/**
+ * A node's children as descriptors - also what a `Flow` reads its rendered page from. `Total: {sum}` is
+ * two text nodes in React; merged back into one string they measure and kern as the one run they are.
+ */
+export function childDescriptors(n) {
+    const out = [];
+    for (const c of n.children) {
+        const d = toDescriptor(c);
+        const last = out[out.length - 1];
+        if (typeof d === "string" && typeof last === "string")
+            out[out.length - 1] = last + d;
+        else
+            out.push(d);
+    }
+    return TEXT_PARENTS.has(n.type)
+        ? out.filter((d) => d !== "")
+        : out.filter((d) => typeof d !== "string" || d.trim() !== "");
+}
+/**
+ * Mounts an element and returns the engine descriptor for its `<Document>` root, with the tree still
+ * mounted: a `Flow` renders its `page` for every page while the engine lays the document out.
+ */
+export function mountDocument(element) {
+    const container = node("#root");
+    const sink = {};
+    // An error no boundary caught fails the render; one a boundary caught is the author's to handle.
+    const fail = (error) => {
+        sink.failure ?? (sink.failure = error);
+    };
+    const report = (error) => console.error(error);
+    const root = reconciler.createContainer(container, LegacyRoot, null, false, null, "", fail, report, report, null);
+    const unmount = () => {
+        reconciler.updateContainerSync(null, root, null, null);
+        reconciler.flushSyncWork();
+    };
+    reconciler.updateContainerSync(createElement(RenderSinkContext.Provider, { value: sink }, element), root, null, null);
+    reconciler.flushSyncWork();
+    if (sink.failure) {
+        unmount();
+        throw sink.failure;
+    }
+    const doc = container.children.find((c) => c.type === "document");
+    if (!doc) {
+        unmount();
+        throw new Error("@jasy/react: the element must render a <Document>.");
+    }
+    return { descriptor: toDescriptor(doc), unmount };
+}
+/** Synchronously apply a state update made outside React's render, so its result can be read back. */
+export function flushNow(update) {
+    reconciler.flushSyncFromReconciler(update);
+    reconciler.flushSyncWork();
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@jasy/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta.1",
+  "description": "Author PDFs as React components - a thin React renderer over @jasy/pdf.",
+  "keywords": [
+    "declarative",
+    "invoice",
+    "jasy",
+    "pdf",
+    "pdf-generation",
+    "react",
+    "renderer"
+  ],
+  "license": "MIT",
+  "author": "Florian Heuberger",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "react-reconciler": "^0.31.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^5.6.0",
+    "vite": "^6.3.4",
+    "@jasy/pdf": "1.0.0-beta.5"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@jasy/pdf": "^1.0.0-beta.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "play": "vite playground --open",
+    "test": "vitest run"
+  }
 }