@typstream/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ikram Hasan
+
+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,84 @@
-# Temporary Holding Version
+# @typstream/react
 
-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.
+React bindings for typstream: render Typst streamed from an LLM, live. A thin layer over `@typstream/dom`'s `mountTypstream`. Most apps import the `typstream` package instead, which is this with html-compat and the math font set up.
+
+```tsx
+import { Typstream } from "@typstream/react";
+
+<Typstream source={text} isStreaming={status === "streaming"} animated caret />;
+```
+
+## `<Typstream>`
+
+The document is `source`, its whole text so far (streamdown-style), or `stream`, an `AsyncIterable<string>` of chunks (create it once, e.g. in `useMemo`: a new stream starts the document over). Instances given the same stream share one reader, so StrictMode's remount loses no chunk.
+
+| Prop | Default | |
+|---|---|---|
+| `source` / `stream` | | The document. |
+| `isStreaming` | `false` | More `source` is coming. When it turns false the document is finished: compiled strictly (final mode), without the caret. Turning true again starts over (a regenerated answer). Ignored with `stream`, which finishes when it ends. |
+| `target` | `"html"` | `"html"` (semantic HTML + MathML) or `"paged"` (SVG pages). Switching keeps the document; the old output stays until the new target's first compile. |
+| `layout`, `pageHeight` | `"fixed"`, `"a4"` | Paged only. `"fit-width"` scales the pages to the element's width; `"reflow"` lays them out that wide (and `pageHeight` sets their height). |
+| `preamble` | | Typst evaluated before the document, after the plugins' and the template's. |
+| `template` | | Name of a template from the plugins' `templates`: its preamble and default `inputs`. |
+| `inputs` | | `sys.inputs`, e.g. `{ showAnswers: "true" }` to recompile with answers instead of re-prompting. |
+| `files` | | Files the document reads (images, data). |
+| `heal` | | `@typstream/heal` options (lint settings, fences). |
+| `schedule` | | Compile pacing (`minInterval`, `maxInterval`). |
+| `plugins`, `stylesheets` | | Plugins' engine files and preambles, heal handlers, templates and sanitizer allowances; extra CSS for the HTML target. |
+| `animated`, `caret` | `false` | Word fade-in (`true` or `AnimateOptions`) and a caret, while streaming (HTML target). |
+| `theme` | `"auto"` | HTML target: `"light"`, `"dark"`, or the page's `color-scheme`. |
+| `linkTarget`, `textLayer` | `"_blank"`, `true` | External links' `target`; paged text layer (selection, find). |
+| `lazy` | `true` | Open and compile only near the viewport, or while streaming. |
+| `engine` | shared | An `Engine` from `createEngine()`. Default: one engine worker for the page, shared by every instance. |
+| `mathFont` | | URL of New Computer Modern Math, registered as a web font for MathML. |
+| `onStatusChange`, `onDiagnostics` | | `idle` / `compiling` / `stale` / `error` / `done`; diagnostics in `source` coordinates. |
+| `onRendered`, `onFallback`, `onWatchdog` | | Telemetry, `@typstream/core`'s event shapes: a render with its compile's timings, heal time and patches, fixes and fallback level; output that fell back (with the input and healed source); a compile the watchdog stopped. |
+| `className`, `style`, `id`, `ref` | | The host element; `ref` receives a `TypstreamHandle`. |
+
+`islands` (beta) maps island names to components: a plugin's markers become interactive components rendered through portals over their Typst fallback (`@typstream/mindmap/react`'s `mindmapIslands`).
+
+Engine options (an adapter, fonts, packages for every document) aren't props: create an `Engine` with them and pass it as `engine`.
+
+## `TypstreamProvider`
+
+App-wide settings for every `<Typstream>` below it: the same props except the document and `onStatusChange`. Lists (`plugins`, `stylesheets`) add up, records (`inputs`, `files`) merge, telemetry hooks (`onRendered`, `onFallback`, `onWatchdog`, `onDiagnostics`) are all called, outer ones first, and anything else an instance sets wins. One provider can wire every document to an analytics sink (`examples/nextjs-ai-sdk/app/telemetry.tsx`). Without an `engine`, the provider keeps the page's shared engine alive while it is mounted, so the worker survives answers coming and going.
+
+```tsx
+<TypstreamProvider plugins={[edu]} theme="dark" heal={{ lint: { "currency-dollar": "warn" } }}>
+  <App />
+</TypstreamProvider>
+```
+
+## `useTypstream()`
+
+```tsx
+const t = useTypstream();
+<Typstream ref={t.ref} source={text} isStreaming />;
+t.status; // "idle" until the document opens
+t.diagnostics; t.healedSource; t.openFrames; // e.g. "writing a table…"
+t.document; // the EngineDocument, once it has opened
+await t.exportPdf(); // Uint8Array, at the document's own page size (also on the ref's TypstreamHandle)
+await t.exportPdf({ inputs: { showAnswers: "true" } }); // inputs for this export only, over the props'
+await t.exportHtml({ title: "Quiz" }); // a standalone HTML file, with the component's plugins' CSS and theme
+t.exportSource(); // the healed Typst the exports compile
+```
+
+React refs don't announce when they're set, so the hook hands out a callback ref rather than reading yours. The exports
+open a lazy document that hasn't opened yet, and reject (`exportSource()` throws) while no `<Typstream>` is mounted.
+
+## Behaviour
+
+- **One worker, many documents.** Instances without an `engine` share one; it is created on first use and terminated a second after the last instance (or provider) unmounts. Compiles run one at a time across documents.
+- **Only visible or streaming documents compile.** A document opens when its element comes within one screen of the viewport, or as soon as it streams; offscreen, finished ones apply prop changes when they scroll back.
+- **StrictMode-safe.** The mount follows the component's lifetime; StrictMode's second mount opens a fresh document and the first is disposed. Unmounting disposes the document.
+- **Server rendering.** The component renders an empty `<div>` on the server and starts in the browser. The bundle is marked `"use client"`.
+
+## Tests
+
+- `pnpm test`: configuration merging and the shared engine's lifetime, in Node.
+- `pnpm test:browser`: `<Typstream>` with React Testing Library against the real engine worker in Chromium, Firefox and WebKit (`BROWSERS=chromium` runs one).
+- `pnpm size`: ≤ 35.3 KB gzipped with `@typstream/dom` (React and the engine external).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { IslandProps, Diagnostic } from '@typstream/core';
+export { AppliedFix, CompileReport, CompiledEvent, DocumentEvent, FallbackEvent, FallbackLevel, IslandProps, RenderedEvent, WatchdogEvent } from '@typstream/core';
+import { TypstreamOptions, TypstreamExportOptions, TypstreamHtmlExportOptions } from '@typstream/dom';
+export { StandaloneHtmlOptions, TypstFont, TypstreamExportOptions, TypstreamHtmlExportOptions } from '@typstream/dom';
+import { Engine, EngineDocument, DocumentState, DocumentStatus } from '@typstream/engine';
+export { DocumentState, DocumentStatus, Engine } from '@typstream/engine';
+import * as react from 'react';
+import { ComponentType, ReactNode, Ref, CSSProperties } from 'react';
+
+/**
+ * A React component for an island: it renders into an element positioned
+ * over the marker's fallback, which shows until the component renders
+ * something (while its code loads, say); paint your own background. @beta
+ */
+type IslandComponent<Data = any> = ComponentType<IslandProps<Data>>;
+/** Island components by name, as plugins name them in their `islands` facet. @beta */
+type IslandComponents = Readonly<Record<string, IslandComponent>>;
+
+/**
+ * Callbacks for logging and telemetry. The library sends nothing itself; the
+ * app decides what to collect (render latency, heal patches, fixer hits,
+ * fallbacks as candidate test cases, watchdog strikes).
+ * @public
+ */
+type TelemetryHooks = Pick<TypstreamOptions, "onRendered" | "onFallback" | "onWatchdog" | "onDiagnostics">;
+
+/**
+ * Settings that make sense for every document of an app. Everything except
+ * `engine`, `resolveImage`, `islands` and plugins' functions is serializable, so it can
+ * be stored per organization or per user.
+ * @public
+ */
+interface TypstreamDefaults extends Pick<TypstreamOptions, "target" | "layout" | "pageHeight" | "preamble" | "template" | "inputs" | "files" | "resolveImage" | "heal" | "schedule" | "plugins" | "stylesheets" | "animated" | "caret" | "theme" | "fonts" | "linkTarget" | "textLayer" | "renderer" | "lazy">, TelemetryHooks {
+    /**
+     * The engine every `<Typstream>` below compiles with, unless it is given its
+     * own. Default: one engine worker for the page, shared by all instances.
+     */
+    engine?: Engine;
+    /**
+     * URL of the math font for MathML (HTML target), registered as a web font
+     * when a document first renders. The engine's copy is in
+     * `@typstream/engine-wasm/fonts`; the `typstream` package sets it for you.
+     */
+    mathFont?: string | URL;
+    /**
+     * Interactive components by island name (PLAN §8.4), e.g. `@typstream/mindmap/react`'s
+     * `{ mindmap: MindMapIsland }`: a marker becomes an island when a plugin
+     * declares its name and a component is given for it. Providers' and the
+     * component's merge, the inner one winning by name. @beta
+     */
+    islands?: IslandComponents;
+}
+/** Props of {@link TypstreamProvider}. @public */
+interface TypstreamProviderProps extends TypstreamDefaults {
+    /** The app, or the part of it these settings apply to. */
+    children?: ReactNode;
+}
+/**
+ * App-wide settings for the `<Typstream>`s below it. Nested providers merge:
+ * the inner one's settings win. Without an `engine`, it keeps the page's
+ * default engine alive while it is mounted, so the worker survives documents
+ * coming and going (a chat switching conversations).
+ * @public
+ */
+declare const TypstreamProvider: ({ children, ...defaults }: TypstreamProviderProps) => react.JSX.Element;
+
+/**
+ * Props of {@link Typstream}: the document (`source` or `stream`), how to
+ * compile and show it, and callbacks. Unset settings come from the nearest
+ * {@link TypstreamProvider}, then the defaults.
+ * @public
+ */
+interface TypstreamProps extends TypstreamDefaults, Pick<TypstreamOptions, "source" | "stream" | "isStreaming" | "streamingRange" | "onStatusChange"> {
+    /** Receives the instance's {@link TypstreamHandle}, e.g. `useTypstream().ref`. */
+    ref?: Ref<TypstreamHandle>;
+    /** Of the element the document renders into. */
+    className?: string;
+    /** Of the element the document renders into. */
+    style?: CSSProperties;
+    /** Of the element the document renders into. */
+    id?: string;
+}
+/**
+ * A `<Typstream>` instance, for reading its document from outside (see
+ * {@link useTypstream}). The same object for the component's lifetime.
+ * @public
+ */
+interface TypstreamHandle {
+    /** The element the document renders into, while mounted. */
+    readonly element: HTMLElement | null;
+    /** The engine document, once it has opened (documents open lazily, near the viewport). */
+    readonly document: EngineDocument | null;
+    /** The document's state; `null` before it opens. */
+    getState(): DocumentState | null;
+    /** Calls `listener` whenever `getState()` or `document` changes. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Exports the document as PDF (#18), compiled by the engine that renders the
+     * preview. It compiles with the template's inputs, the `inputs` prop and
+     * `options.inputs` (a teacher's copy: `{ showAnswers: "true" }`), but not a
+     * `layout="reflow"` preview's page size, so it prints at the document's
+     * own size. Opens a lazy document that hasn't opened yet. Rejects with the
+     * engine's `ExportError`, or an `Error` when the component isn't mounted.
+     */
+    exportPdf(options?: TypstreamExportOptions): Promise<Uint8Array>;
+    /**
+     * Exports the document as an HTML file that opens on its own, laid out as
+     * the pages (see `standalonePages` in `@typstream/dom`; `pages: false` for
+     * `standaloneHtml`'s reading layout), with the component's plugins,
+     * `stylesheets`, `theme` and Typst fonts. `options` add to or override them
+     * (a `mathFont`, a `title`). Otherwise as {@link TypstreamHandle.exportPdf},
+     * `options.inputs` included.
+     */
+    exportHtml(options?: TypstreamHtmlExportOptions): Promise<string>;
+    /**
+     * Exports the document as an editable DOCX file that Word lays out as the PDF (#131). Otherwise as
+     * {@link TypstreamHandle.exportPdf}, `options.inputs` included. @beta
+     */
+    exportDocx(options?: TypstreamExportOptions): Promise<Uint8Array>;
+    /**
+     * The source the exports compile: the healed input, as a `.typ` file would
+     * hold it. Opens a lazy document that hasn't opened yet. Throws when the
+     * component isn't mounted.
+     */
+    exportSource(): string;
+}
+/**
+ * Renders a streaming Typst document: pass the text so far as `source` while
+ * `isStreaming`, or a `stream` of chunks. Heals each prefix, compiles it in the
+ * engine's worker and shows HTML (default) or pages, keeping the last good
+ * output while a prefix doesn't compile.
+ *
+ * @example
+ * ```tsx
+ * <Typstream source={part.text} isStreaming={status === "streaming"} animated caret />
+ * ```
+ * @public
+ */
+declare const Typstream: ({ ref, className, style, id, ...props }: TypstreamProps) => react.JSX.Element;
+
+/** What {@link useTypstream} returns. @public */
+interface TypstreamInfo {
+    /** Pass to `<Typstream ref>`. Stable. */
+    ref: (handle: TypstreamHandle | null) => void;
+    /** The instance, once mounted. */
+    handle: TypstreamHandle | null;
+    /** The document's whole state; `null` until it opens. */
+    state: DocumentState | null;
+    /** `idle` until the document opens. */
+    status: DocumentStatus;
+    /** Diagnostics of the latest compile, in `source` coordinates. */
+    diagnostics: readonly Diagnostic[];
+    /** The healed source the engine compiles (empty until the document opens). */
+    healedSource: string;
+    /** Constructs still open at the end of the input, innermost first. */
+    openFrames: DocumentState["heal"]["openFrames"];
+    /**
+     * The engine document. For exports, prefer `exportPdf()` and friends: the
+     * document's own exports use its inputs, which include a reflow preview's
+     * page size.
+     */
+    document: EngineDocument | null;
+    /**
+     * Exports the document as PDF, at its own page size (a reflow preview's
+     * width left out), with the template's inputs, the `inputs` prop and
+     * `options.inputs`. Opens a lazy document that hasn't opened yet. Rejects
+     * with the engine's `ExportError`, or an `Error` when no `<Typstream>` is
+     * mounted. See {@link TypstreamHandle.exportPdf}.
+     */
+    exportPdf(options?: TypstreamExportOptions): Promise<Uint8Array>;
+    /** Exports the document as an editable DOCX file. See {@link TypstreamHandle.exportDocx}. @beta */
+    exportDocx(options?: TypstreamExportOptions): Promise<Uint8Array>;
+    /**
+     * Exports the document as an HTML file that opens on its own, with the
+     * component's plugins, `stylesheets` and `theme`; `options` add to or
+     * override them. See {@link TypstreamHandle.exportHtml}.
+     */
+    exportHtml(options?: TypstreamHtmlExportOptions): Promise<string>;
+    /** The healed source the exports compile. Throws when no `<Typstream>` is mounted. */
+    exportSource(): string;
+}
+/**
+ * Reads a `<Typstream>`'s document: status, diagnostics, healed source; and
+ * exports it (`exportPdf()`, `exportHtml()`, `exportSource()`, as on
+ * {@link TypstreamHandle}).
+ *
+ * @example
+ * ```tsx
+ * const t = useTypstream();
+ * return (
+ *   <>
+ *     <Typstream ref={t.ref} source={text} isStreaming />
+ *     {t.status === "stale" ? <p>Showing the last good render…</p> : null}
+ *     <button onClick={async () => save(await t.exportPdf())}>Download PDF</button>
+ *   </>
+ * );
+ * ```
+ * @public
+ */
+declare const useTypstream: () => TypstreamInfo;
+
+export { type IslandComponent, type IslandComponents, type TelemetryHooks, Typstream, type TypstreamDefaults, type TypstreamHandle, type TypstreamInfo, type TypstreamProps, TypstreamProvider, type TypstreamProviderProps, useTypstream };

package/dist/index.js

@@ -0,0 +1,287 @@
+"use client";
+
+// src/context.tsx
+import { createContext, useContext, useEffect } from "react";
+
+// src/engine.ts
+import { createEngine, engineWorker } from "@typstream/engine";
+var RELEASE_DELAY = 1e3;
+var factory = () => createEngine({ spawn: engineWorker(), clientInfo: { name: "@typstream/react" } });
+var engine = null;
+var users = 0;
+var timer;
+var acquireEngine = () => {
+  clearTimeout(timer);
+  users++;
+  engine ??= factory();
+  return engine;
+};
+var releaseEngine = () => {
+  users = Math.max(0, users - 1);
+  if (users > 0) return;
+  clearTimeout(timer);
+  timer = setTimeout(() => {
+    if (users > 0) return;
+    engine?.dispose();
+    engine = null;
+  }, RELEASE_DELAY);
+};
+
+// src/telemetry.ts
+var HOOKS = ["onRendered", "onFallback", "onWatchdog", "onDiagnostics"];
+var mergeHooks = (outer, inner) => {
+  const merged = {};
+  for (const name of HOOKS) {
+    const a = outer[name];
+    const b = inner[name];
+    const both = (...args) => {
+      a?.(...args);
+      b?.(...args);
+    };
+    const hook = a && b ? both : a ?? b;
+    if (hook) merged[name] = hook;
+  }
+  return merged;
+};
+
+// src/context.tsx
+import { jsx } from "react/jsx-runtime";
+var Context = createContext({});
+var useTypstreamDefaults = () => useContext(Context);
+var TypstreamProvider = ({ children, ...defaults }) => {
+  const outer = useContext(Context);
+  const own = defaults.engine;
+  useEffect(() => {
+    if (own) return;
+    acquireEngine();
+    return releaseEngine;
+  }, [own]);
+  return /* @__PURE__ */ jsx(Context, { value: mergeDefaults(outer, defaults), children });
+};
+var dedupePlugins = (plugins) => {
+  if (!plugins || plugins.length < 2) return plugins;
+  const byKey = new Map(plugins.map((p) => [p.key, p]));
+  return byKey.size === plugins.length ? plugins : [...byKey.values()];
+};
+var concat = (a, b) => a && b ? [...a, ...b] : b ?? a;
+var assign = (a, b) => a && b ? { ...a, ...b } : b ?? a;
+var mergeDefaults = (outer, inner) => {
+  const merged = { ...outer };
+  for (const [k, v] of Object.entries(inner)) if (v !== void 0) merged[k] = v;
+  const plugins = dedupePlugins(concat(outer.plugins, inner.plugins));
+  const stylesheets = concat(outer.stylesheets, inner.stylesheets);
+  const inputs = assign(outer.inputs, inner.inputs);
+  const files = assign(outer.files, inner.files);
+  const islands = assign(outer.islands, inner.islands);
+  return {
+    ...merged,
+    ...plugins ? { plugins } : {},
+    ...stylesheets ? { stylesheets: [...new Set(stylesheets)] } : {},
+    ...inputs ? { inputs } : {},
+    ...files ? { files } : {},
+    ...islands ? { islands } : {},
+    ...mergeHooks(outer, inner)
+  };
+};
+
+// src/Typstream.tsx
+import {
+  mountTypstream,
+  registerMathFont
+} from "@typstream/dom";
+import {
+  useEffect as useEffect2,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+
+// src/islands.tsx
+import { Component, Suspense } from "react";
+import { createPortal } from "react-dom";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var createIslandStore = () => {
+  let entries = [];
+  let ids = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const set = (next) => {
+    entries = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    get: () => entries,
+    /** dom renderers for `names` that record their islands here. */
+    renderers(names) {
+      const render = (host, props) => {
+        const id = ids++;
+        set([...entries, { id, host, props }]);
+        return {
+          update: (next) => set(entries.map((e) => e.id === id ? { ...e, props: next } : e)),
+          destroy: () => set(entries.filter((e) => e.id !== id))
+        };
+      };
+      return Object.fromEntries(names.map((name) => [name, render]));
+    }
+  };
+};
+var IslandBoundary = class extends Component {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error) {
+    globalThis.reportError?.(error);
+  }
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+};
+var islandPortals = (entries, components) => entries.map(({ id, host, props }) => {
+  const Island = components && Object.hasOwn(components, props.name) ? components[props.name] : void 0;
+  if (!Island) return null;
+  return createPortal(
+    /* @__PURE__ */ jsx2(IslandBoundary, { children: /* @__PURE__ */ jsx2(Suspense, { fallback: null, children: /* @__PURE__ */ jsx2(Island, { ...props }) }) }),
+    host,
+    String(id)
+  );
+});
+
+// src/Typstream.tsx
+import { Fragment, jsx as jsx3, jsxs } from "react/jsx-runtime";
+var createHandle = () => {
+  let mounted = null;
+  let stop = () => {
+  };
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+  const mount = () => {
+    if (!mounted) throw new Error("<Typstream> isn't mounted");
+    return mounted;
+  };
+  const handle = {
+    get element() {
+      return mounted?.element ?? null;
+    },
+    get document() {
+      return mounted?.document ?? null;
+    },
+    getState: () => mounted?.getState() ?? null,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    exportPdf: async (options) => mount().exportPdf(options),
+    exportHtml: async (options) => mount().exportHtml(options),
+    exportDocx: async (options) => mount().exportDocx(options),
+    exportSource: () => mount().exportSource()
+  };
+  const attach = (next) => {
+    stop();
+    mounted = next;
+    stop = next ? next.subscribe(notify) : () => {
+    };
+    notify();
+  };
+  return { handle, attach };
+};
+var registered = /* @__PURE__ */ new Set();
+var useMathFont = (url) => {
+  useEffect2(() => {
+    if (!url || registered.has(String(url))) return;
+    registered.add(String(url));
+    registerMathFont(url).catch((error) => {
+      registered.delete(String(url));
+      globalThis.reportError?.(error);
+    });
+  }, [url]);
+};
+var Typstream = ({ ref, className, style, id, ...props }) => {
+  const { engine: explicit, mathFont, islands: components, ...rest } = mergeDefaults(useTypstreamDefaults(), props);
+  const [store] = useState(createIslandStore);
+  const names = Object.keys(components ?? {}).sort().join("\n");
+  const islands = useMemo(() => names ? store.renderers(names.split("\n")) : void 0, [store, names]);
+  const entries = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const options = islands ? { ...rest, islands } : rest;
+  const element = useRef(null);
+  const mounted = useRef(null);
+  const [{ handle, attach }] = useState(createHandle);
+  useImperativeHandle(ref, () => handle, [handle]);
+  useMathFont(mathFont);
+  const latest = useRef(options);
+  latest.current = options;
+  useEffect2(() => {
+    const el = element.current;
+    if (!el) return;
+    const engine2 = explicit ?? acquireEngine();
+    const view = mountTypstream(el, { ...latest.current, engine: engine2 });
+    mounted.current = { view, engine: engine2 };
+    attach(view);
+    return () => {
+      attach(null);
+      mounted.current = null;
+      view.destroy();
+      if (!explicit) releaseEngine();
+    };
+  }, [explicit, attach]);
+  useEffect2(() => {
+    const m = mounted.current;
+    if (m) m.view.update({ ...options, engine: m.engine });
+  });
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx3(
+      "div",
+      {
+        ref: element,
+        className: className ? `typstream-host ${className}` : "typstream-host",
+        style,
+        id
+      }
+    ),
+    islandPortals(entries, components)
+  ] });
+};
+
+// src/useTypstream.ts
+import { useCallback, useMemo as useMemo2, useState as useState2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+var EMPTY = [];
+var noSubscription = () => () => {
+};
+var useTypstream = () => {
+  const [handle, setHandle] = useState2(null);
+  const subscribe = useCallback((listener) => handle?.subscribe(listener) ?? noSubscription(), [handle]);
+  const read = () => handle?.getState() ?? null;
+  const state = useSyncExternalStore2(subscribe, read, () => null);
+  const document = handle?.document ?? null;
+  return useMemo2(() => {
+    const { exportPdf, exportDocx, exportHtml, exportSource } = handle ?? createHandle().handle;
+    return {
+      ref: setHandle,
+      handle,
+      state,
+      status: state?.status ?? "idle",
+      diagnostics: state?.diagnostics ?? EMPTY,
+      healedSource: state?.heal.source ?? "",
+      openFrames: state?.heal.openFrames ?? EMPTY,
+      document,
+      exportPdf,
+      exportDocx,
+      exportHtml,
+      exportSource
+    };
+  }, [handle, state, document]);
+};
+export {
+  Typstream,
+  TypstreamProvider,
+  useTypstream
+};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@typstream/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React bindings for typstream: <Typstream>, useTypstream() and TypstreamProvider, for Typst streamed from an LLM.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ikramhasan/typstream.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://typstream.vercel.app/docs/reference/react",
+  "bugs": "https://github.com/ikramhasan/typstream/issues",
+  "keywords": [
+    "typst",
+    "streaming",
+    "llm",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@typstream/core": "0.1.0",
+    "@typstream/dom": "0.1.0",
+    "@typstream/engine": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@typstream/corpus": "0.0.0",
+    "@typstream/html-compat": "0.1.0",
+    "@vitest/browser-playwright": "4.1.12",
+    "playwright": "^1.64.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --project node",
+    "test:browser": "vitest run --project browser",
+    "size": "node scripts/size.mjs",
+    "check-types": "tsc -p tsconfig.json",
+    "check:api": "api-extractor run",
+    "api:update": "api-extractor run --local",
+    "check:package": "publint --strict --pack npm && attw --pack . --profile esm-only"
+  }
 }