next-live 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,580 @@
+import { ComponentType, ReactElement, ReactNode, ElementType, Component, ErrorInfo, Context } from 'react';
+import * as sucrase from 'sucrase';
+
+/**
+ * A value registered under an import specifier.
+ *
+ * The idiomatic value is a real module namespace - `import * as ui from
+ * 'my-ui-kit'` - but any object, function, or primitive works. See
+ * {@link normalizeModule} for how each shape maps onto `default` and named
+ * imports.
+ */
+type ModuleValue = unknown;
+/**
+ * A lazily-loaded module, awaited before user code is evaluated.
+ *
+ * Receives the specifier that was imported. Exact-match entries can ignore it;
+ * prefix entries (a key ending in `/`) need it, since one loader serves the
+ * whole subtree.
+ */
+type ModuleLoader = (specifier: string) => ModuleValue | Promise<ModuleValue>;
+/**
+ * Maps import specifiers to values:
+ *
+ * ```ts
+ * { 'react': React, '@app/ui': ui, '@app/store': { useAppStore } }
+ * ```
+ */
+interface ModuleRegistry {
+    [specifier: string]: ModuleValue | ModuleLoader;
+}
+/**
+ * Free variables injected directly into the snippet's scope, the way
+ * `react-live` does it. Prefer `modules` + real `import` statements; this
+ * exists for compatibility and for values that read better unqualified.
+ */
+interface LiveScope {
+    [identifier: string]: unknown;
+}
+/** A module record shaped so Sucrase's interop helpers become no-ops. */
+interface NormalizedModule {
+    readonly __esModule: true;
+    readonly default: unknown;
+    readonly [name: string]: unknown;
+}
+/** What the snippet ultimately produced. */
+type LiveRenderable = {
+    kind: 'component';
+    component: ComponentType<Record<string, unknown>>;
+} | {
+    kind: 'element';
+    element: ReactElement;
+};
+/** How the renderable was found - surfaced in error messages. */
+type ExtractionSource = 'render()' | 'export default' | 'module.exports' | 'named export' | 'declaration';
+interface TranspileOptions {
+    /**
+     * Logical filename. Drives the `sourceURL` so stack frames and DevTools
+     * agree on one name. Use a stable per-app identity, e.g. `app-42.tsx`.
+     */
+    filePath?: string;
+    /** `false` selects `react/jsx-dev-runtime`, giving richer component stacks. */
+    production?: boolean;
+    jsxRuntime?: 'automatic' | 'classic';
+    jsxImportSource?: string;
+}
+interface TransformResult {
+    code: string;
+    /** Lines inserted above the user's line 1. Added back during error mapping. */
+    linePrefixOffset: number;
+    /** True when the snippet was compiled as a bare expression. */
+    expression: boolean;
+}
+/**
+ * Replaces the built-in Sucrase pass - for server-precompiled output, or a
+ * different transpiler entirely.
+ */
+type TransformFn = (source: string, options: Required<TranspileOptions>) => TransformResult | Promise<TransformResult>;
+interface CompileOptions extends TranspileOptions {
+    modules?: ModuleRegistry;
+    scope?: LiveScope;
+    transform?: TransformFn;
+    /**
+     * Resolve `pkg/Sub` against a registered `pkg` by walking the remaining
+     * segments as property accesses. Correct for barrel-shaped packages, wrong
+     * for those whose subpaths are not re-exported - so it is opt-in rather than
+     * a silent guess. Default false.
+     */
+    resolveSubpaths?: boolean;
+    /** Aborts a compile whose result is no longer wanted. */
+    signal?: AbortSignal;
+}
+interface CompileResult {
+    renderable: LiveRenderable;
+    via: ExtractionSource;
+    /** The transpiled JavaScript, for debugging and for the server cache. */
+    code: string;
+    /** Every module specifier the snippet imported, sorted. */
+    imports: readonly string[];
+}
+interface CompileModuleResult {
+    /** Everything the snippet exported. */
+    exports: Record<string, unknown>;
+    /** The transpiled JavaScript. */
+    code: string;
+    /** Every module specifier the snippet imported, sorted. */
+    imports: readonly string[];
+}
+interface CompileSuccessInfo {
+    compileId: number;
+    imports: readonly string[];
+    via?: ExtractionSource;
+    durationMs: number;
+}
+interface UseLiveRunnerOptions extends CompileOptions {
+    code: string;
+    /**
+     * Called when the code is edited from inside, by `<LiveEditor>`, or via
+     * `setCode`. Not called when the `code` prop changes from outside, which
+     * would otherwise echo your own updates back at you.
+     *
+     * This is what a control panel needs to persist an author's edits.
+     */
+    onCodeChange?: (code: string) => void;
+    /** Called after every successful compile. Not called on failure or abort. */
+    onCompileSuccess?: (info: CompileSuccessInfo) => void;
+    /** Milliseconds to wait after a change before recompiling. Default 150. */
+    debounce?: number;
+    /**
+     * Keep the last working component mounted when a recompile fails, instead
+     * of blanking the preview on every half-typed keystroke. Default true.
+     */
+    keepLastGood?: boolean;
+    /** Renders per second before the loop breaker trips. Default 1000. */
+    maxRendersPerSecond?: number;
+}
+interface LiveRunnerState {
+    code: string;
+    setCode: (code: string) => void;
+    /** Null until the first successful compile - including during SSR. */
+    Component: ComponentType<Record<string, unknown>> | null;
+    element: ReactElement | null;
+    error: Error | null;
+    isCompiling: boolean;
+    /** Changes on every successful compile; use as a remount `key`. */
+    compileId: number;
+}
+interface LiveContextValue extends LiveRunnerState {
+    /** Props forwarded into the rendered component. */
+    props: Record<string, unknown>;
+    language: string;
+    /** Called by the error boundary when rendering the snippet throws. */
+    reportRuntimeError: (error: Error) => void;
+    fallback: ReactNode;
+}
+
+interface LiveProviderProps extends Omit<UseLiveRunnerOptions, 'code'> {
+    /**
+     * The snippet to run. Treated as controlled: when it changes - because a new
+     * app was fetched from an API, say, the preview follows.
+     */
+    code: string;
+    /** Props forwarded into the rendered component. Passed by reference. */
+    props?: Record<string, unknown>;
+    /** Language hint for `<LiveEditor>` highlighting. Default 'tsx'. */
+    language?: string;
+    /** Notified on every compile and runtime error. */
+    onError?: (error: Error) => void;
+    /** Rendered by `<LivePreview>` until the first compile finishes. */
+    fallback?: ReactNode;
+    children?: ReactNode;
+}
+/**
+ * Provides a compiled snippet to `<LiveEditor>`, `<LivePreview>`, and
+ * `<LiveError>`.
+ *
+ * Safe to render from a Server Component: nothing is compiled during the
+ * server pass, and the first client render matches the server output exactly.
+ */
+declare function LiveProvider(props: LiveProviderProps): ReactNode;
+
+interface LivePreviewProps {
+    /** Element to wrap the preview in. Default 'div'. */
+    as?: ElementType;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * Props handed to the compiled component, merged over the provider's.
+     * Passed by reference, so live objects - a map view, a store, the active
+     * user, arrive intact rather than serialized.
+     */
+    props?: Record<string, unknown>;
+    /** Shown until the first compile finishes. Overrides the provider's. */
+    fallback?: ReactNode;
+}
+/**
+ * Renders the compiled component.
+ *
+ * Until the first compile lands this renders `fallback` - on the server and on
+ * the client's first pass alike, which is precisely why hydration cannot
+ * mismatch. Give it a skeleton of roughly the right size to avoid layout shift.
+ */
+declare function LivePreview(props: LivePreviewProps): ReactNode;
+
+interface LiveErrorProps {
+    as?: ElementType;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Replaces the default rendering entirely. */
+    children?: (error: Error) => ReactNode;
+}
+/**
+ * Displays the current compile or runtime error, and renders nothing when the
+ * snippet is healthy.
+ */
+declare function LiveError$1(props: LiveErrorProps): ReactNode;
+
+interface LiveErrorBoundaryProps {
+    children: ReactNode;
+    onError: (error: Error) => void;
+    /**
+     * Changing this resets the boundary. Wire it to the compile id so fixing a
+     * broken snippet recovers on its own, with no manual retry.
+     */
+    resetKey: unknown;
+    fallback?: ReactNode;
+}
+interface State {
+    error: Error | null;
+    resetKey: unknown;
+    /** True after resetKey changes — allows one render attempt before falling back again. */
+    recovering: boolean;
+}
+/**
+ * Contains failures in evaluated code so a bad snippet cannot take down the
+ * host application.
+ *
+ * React recovers from an error by client-rendering the whole nearest boundary,
+ * so this one is kept as tight around the preview as possible - anything else
+ * on the page is unaffected.
+ */
+declare class LiveErrorBoundary extends Component<LiveErrorBoundaryProps, State> {
+    private mounted;
+    constructor(props: LiveErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<State>;
+    static getDerivedStateFromProps(props: LiveErrorBoundaryProps, state: State): Partial<State> | null;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(_prevProps: LiveErrorBoundaryProps, prevState: State): void;
+    componentWillUnmount(): void;
+    render(): ReactNode;
+}
+
+/**
+ * The headless engine behind `<LiveProvider>` - compiles a snippet and hands
+ * back a component, for hosts building their own UI.
+ *
+ * Compilation never runs during render or on the server. The first client
+ * render produces exactly what the server produced (no component, no error),
+ * so there is nothing for React to find mismatched during hydration; the
+ * compile starts afterwards, in an effect.
+ *
+ * For snippets that are not components, use {@link useLiveModule}.
+ */
+declare function useLiveRunner(options: UseLiveRunnerOptions): LiveRunnerState;
+
+interface UseLiveModuleOptions extends Omit<UseLiveRunnerOptions, 'maxRendersPerSecond'> {
+}
+interface LiveModuleState<T extends Record<string, unknown> = Record<string, unknown>> {
+    code: string;
+    setCode: (code: string) => void;
+    /** Everything the snippet exported. Null until the first successful run. */
+    exports: T | null;
+    /** Shorthand for `exports?.default`. */
+    value: unknown;
+    error: Error | null;
+    isCompiling: boolean;
+    /** Increments on every successful run. */
+    compileId: number;
+}
+/**
+ * Runs a snippet and returns its exports, without requiring a React component.
+ *
+ * Use it for stored code that is not UI - a validator, a data transformer, a
+ * calculated field, a config builder:
+ *
+ * ```ts
+ * const { exports } = useLiveModule({ code: rule.source, modules });
+ * const isValid = exports?.validate?.(input);
+ * ```
+ *
+ * Shares its scheduling with `useLiveRunner`, so the SSR, debounce, and
+ * keep-last-good behaviour is identical: nothing runs during the server pass,
+ * and a failed recompile leaves the previous exports in place.
+ *
+ * The same caveat applies as everywhere else in this library, the snippet runs
+ * with your page's full authority, so its author must be someone you trust.
+ */
+declare function useLiveModule<T extends Record<string, unknown> = Record<string, unknown>>(options: UseLiveModuleOptions): LiveModuleState<T>;
+
+/**
+ * Reads the surrounding `<LiveProvider>`. Use it to build custom editors,
+ * toolbars, or status indicators that stay in sync with the preview.
+ */
+declare function useLiveContext(): LiveContextValue;
+
+declare const LiveContext: Context<LiveContextValue | null>;
+
+/** Base class for every error next-live raises. */
+declare class LiveError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The snippet could not be parsed or transpiled. */
+declare class LiveCompileError extends LiveError {
+    readonly line: number | undefined;
+    readonly column: number | undefined;
+    constructor(message: string, position?: {
+        line?: number;
+        column?: number;
+    }, cause?: unknown);
+}
+/** The snippet threw while being evaluated or rendered. */
+declare class LiveRuntimeError extends LiveError {
+}
+/** A render loop was detected and stopped. */
+declare class RenderLoopError extends LiveRuntimeError {
+}
+/** `import` referenced a specifier that is not in the registry. */
+declare class ModuleNotFoundError extends LiveError {
+    readonly specifier: string;
+    readonly available: readonly string[];
+    constructor(specifier: string, available: readonly string[]);
+}
+/** The snippet compiled and ran but produced nothing renderable. */
+declare class NoComponentError extends LiveError {
+}
+/** Sucrase could not be loaded (usually a chunk-load failure). */
+declare class TranspilerLoadError extends LiveError {
+    constructor(cause: unknown);
+}
+
+interface CompileInput extends CompileOptions {
+    code: string;
+    /** Reports each render of the compiled component to the loop breaker. */
+    onRender?: () => void;
+}
+/**
+ * Compiles and evaluates a snippet, returning something renderable.
+ *
+ * The stages run in a fixed order for one reason: Sucrase emits synchronous
+ * `require()` calls, so every module - including any registered as an async
+ * loader, must be resolved *before* evaluation begins.
+ */
+declare function compile(input: CompileInput): Promise<CompileResult>;
+/**
+ * Compiles and runs a snippet, returning its exports rather than a component.
+ *
+ * Use this for stored code that is not UI, a validator, a data transformer, a
+ * calculated field. {@link compile} is the right call when you need something
+ * to render; this one makes no such demand and will happily return
+ * `{ validate, schema }`.
+ */
+declare function compileModule(input: CompileInput): Promise<CompileModuleResult>;
+
+type SucraseModule = typeof sucrase;
+/**
+ * Starts fetching the transpiler chunk ahead of time. Worth calling on idle or
+ * on route prefetch so the first compile is not gated on a network round trip.
+ */
+declare function preloadTranspiler(): void;
+/** Replaces the loaded transpiler. Intended for tests and custom backends. */
+declare function setTranspiler(module: SucraseModule | null): void;
+/**
+ * Transpiles a snippet to CommonJS that `new Function` can evaluate.
+ *
+ * Three authoring styles are supported, resolved without ever asking the user
+ * which one they used:
+ *
+ * 1. A real module - `export default function App() {}`.
+ * 2. A bare expression, `<div/>` or `() => <div/>`.
+ * 3. Bare statements with no export, `function App() {}`, or `render(<App/>)`.
+ *
+ * Styles 1 and 3 are compiled as-is; the component is recovered after
+ * evaluation (see `evaluate.ts`). Style 2 is not a valid module body on its
+ * own, so it is wrapped in `export default (...)`.
+ */
+declare function transpile(source: string, options?: TranspileOptions, transform?: TransformFn): Promise<TransformResult>;
+/**
+ * Wraps an already-compiled result as a `transform` function, so the client
+ * skips loading Sucrase entirely:
+ *
+ * ```tsx
+ * <LiveProvider code={source} transform={precompiledTransform(compiled)} />
+ * ```
+ *
+ * Lives here rather than next-live/server on purpose. It is a pure closure over
+ * a value and needs no transpiler - but importing it from the server entry
+ * would pull Sucrase statically into the page bundle, which is the exact cost
+ * precompiling exists to avoid.
+ */
+declare function precompiledTransform(result: TransformResult): () => TransformResult;
+
+/**
+ * Modules every snippet can import without the host registering anything.
+ *
+ * The two JSX runtimes are not optional: with `jsxRuntime: 'automatic'`
+ * Sucrase compiles every JSX element into a `react/jsx-runtime` (or
+ * `react/jsx-dev-runtime`) call, so without these entries *every* snippet
+ * fails on its first tag.
+ *
+ * These are static imports so evaluated code shares the host's single React
+ * instance - hooks and context work across the boundary, which is the whole
+ * point of evaluating in the host realm. Host `modules` merge over these, so
+ * a React shim can still be substituted.
+ *
+ * `react-dom` is deliberately absent: snippets rarely need it, and a host that
+ * does can register it explicitly.
+ */
+declare const builtinModules: ModuleRegistry;
+
+/**
+ * Wraps a function so the registry treats it as a lazy loader instead of as
+ * the module value. Without this a registered component function would be
+ * indistinguishable from a loader.
+ *
+ * ```ts
+ * { 'heavy-chart': defineLoader(() => import('heavy-chart')) }
+ * ```
+ */
+declare function defineLoader(load: ModuleLoader): ModuleLoader;
+/**
+ * Builds an explicit module record, for the shape that cannot be inferred.
+ *
+ * {@link normalizeModule} unwraps any registered object that has its own
+ * `default` key, because that is almost always a module wrapper. When it is
+ * not - a config object that happens to contain the word `default`, say so:
+ *
+ * ```ts
+ * { './theme': defineModule({ default: { default: 'dark', light: '#fff' } }) }
+ * // import theme from './theme'  →  the whole object
+ * ```
+ *
+ * `default` and `exports.default` address the same slot, because ESM makes no
+ * distinction between a default export and a named export called `default`.
+ * A top-level `default` wins if both are given.
+ */
+declare function defineModule(shape: {
+    default?: unknown;
+    exports?: Record<string, unknown>;
+}): NormalizedModule;
+/**
+ * Converts a registered value into a record Sucrase's interop helpers accept.
+ *
+ * The trick that makes this total: both helpers Sucrase emits are identity
+ * functions when the required value carries `__esModule === true` -
+ * `_interopRequireDefault` is literally `obj && obj.__esModule ? obj : {default: obj}`.
+ * By always returning such a record we neutralise both helpers, so this
+ * function becomes the single source of truth for what `default` and each
+ * named import resolve to.
+ *
+ * Named exports are exposed as *getters* over the original value rather than
+ * copied. That preserves ES module live bindings, and - more importantly in
+ * practice, avoids eagerly invoking the lazy namespace getters that packages
+ * like icon sets and large UI barrels use, which a naive spread would trigger
+ * on every single compile.
+ */
+declare function normalizeModule(value: ModuleValue): NormalizedModule;
+/** The resolved, synchronously-readable module table handed to a snippet. */
+interface ResolvedModules {
+    get(specifier: string): NormalizedModule | undefined;
+    readonly keys: readonly string[];
+}
+interface ResolveOptions {
+    registry: ModuleRegistry;
+    /** Specifiers found in the compiled output. */
+    specifiers: Iterable<string>;
+    /**
+     * Resolve `@scope/pkg/Sub` against a registered `@scope/pkg` by walking the
+     * remaining segments as property accesses. Correct for barrel-shaped
+     * packages, wrong for those whose subpaths are not re-exported - so it is
+     * opt-in rather than a silent guess. Default false.
+     */
+    resolveSubpaths?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Resolves every specifier a snippet needs *before* evaluation, because
+ * Sucrase emits synchronous `require()` calls that cannot await anything.
+ */
+declare function resolveModules(options: ResolveOptions): Promise<ResolvedModules>;
+/**
+ * The synchronous `require` shim handed to compiled snippets. Sucrase emits
+ * `var _react = require('react')` at module top level, so this must never
+ * return a promise.
+ */
+declare function createRequire(resolved: ResolvedModules): (specifier: string) => NormalizedModule;
+
+/**
+ * Merges registry groups into one, later groups winning.
+ *
+ * A large SDK surface is best kept as several small files - one per domain -
+ * rather than a single object that grows without bound. This composes them.
+ *
+ * ```ts
+ * export const liveModules = createRegistry(vendorModules, storeModules, uiModules);
+ * ```
+ *
+ * A key defined by two groups is almost always a mistake rather than an
+ * intentional override, and it fails silently otherwise, so it warns in
+ * development.
+ */
+declare function createRegistry(...groups: ModuleRegistry[]): ModuleRegistry;
+/** The lazy shape `import.meta.glob()` returns: path → thunk. */
+type GlobResult = Record<string, () => Promise<unknown>>;
+/**
+ * Builds a registry from a directory of files, so the registry stops needing
+ * hand-maintenance as the codebase grows.
+ *
+ * Pass the *result* of `import.meta.glob` - the call has to stay in your own
+ * code, because bundlers resolve the pattern statically at the call site.
+ * (`import.meta.glob` requires Turbopack; under webpack, build an equivalent
+ * `{ path: () => import(path) }` object yourself.)
+ *
+ * ```ts
+ * export const storeModules = registryFromGlob(
+ *   import.meta.glob('../stores/*.ts'),
+ *   (path) => `@app/store/${path.split('/').pop()!.replace(/\.tsx?$/, '')}`,
+ * );
+ * // → { '@app/store/cart': <loader>, '@app/store/user': <loader>, … }
+ * ```
+ *
+ * Every entry is a loader, so none of these files is fetched until a snippet
+ * imports it.
+ *
+ * @param glob       Result of `import.meta.glob(pattern)`, left lazy.
+ * @param toSpecifier Maps a file path to the specifier snippet authors write.
+ *   Return `null` to leave a file out of the registry.
+ */
+declare function registryFromGlob(glob: GlobResult, toSpecifier: (path: string) => string | null): ModuleRegistry;
+
+interface RenderBudgetOptions {
+    /** Renders allowed inside one window before the breaker trips. Default 1000. */
+    maxRenders?: number;
+    /** Length of the rolling window in milliseconds. Default 1000. */
+    windowMs?: number;
+}
+/**
+ * A circuit breaker for runaway re-renders.
+ *
+ * This is the one class of hang that *can* be caught in the host realm. A
+ * synchronous `while (true)` blocks the main thread and nothing - no timer, no
+ * AbortController, will ever run again. But the common real failure in
+ * authored code is not that: it is `setState` during render, or an effect with
+ * a bad dependency array, which React executes as a rapid *sequence* of
+ * renders. Between them the breaker gets to run, so it can stop the loop.
+ *
+ * The throw happens during render so the nearest error boundary catches it and
+ * the host application stays alive.
+ */
+declare function createRenderBudget(options?: RenderBudgetOptions): () => void;
+
+interface PositionedError extends Error {
+    line?: number;
+    column?: number;
+}
+/**
+ * Reads a 1-based line/column from a compile or runtime error, if present.
+ *
+ * Accepts a nullish value and returns null for it. The state this is meant to
+ * be fed from - `LiveRunnerState.error` and `LiveContextValue.error` - is
+ * `Error | null`, so `errorPosition(error)` is the natural thing to write in a
+ * custom editor. TypeScript rejects that, but a JavaScript host would have hit
+ * a TypeError instead of the "no position" answer the name promises.
+ */
+declare function errorPosition(error: Error | null | undefined): {
+    line: number;
+    column?: number;
+} | null;
+
+export { type CompileInput, type CompileModuleResult, type CompileOptions, type CompileResult, type CompileSuccessInfo, type ExtractionSource, type GlobResult, LiveCompileError, LiveContext, type LiveContextValue, LiveError$1 as LiveError, LiveError as LiveErrorBase, LiveErrorBoundary, type LiveErrorBoundaryProps, type LiveErrorProps, type LiveModuleState, LivePreview, type LivePreviewProps, LiveProvider, type LiveProviderProps, type LiveRenderable, type LiveRunnerState, LiveRuntimeError, type LiveScope, type ModuleLoader, ModuleNotFoundError, type ModuleRegistry, type ModuleValue, NoComponentError, type NormalizedModule, type PositionedError, type RenderBudgetOptions, RenderLoopError, type TransformFn, type TransformResult, type TranspileOptions, TranspilerLoadError, type UseLiveModuleOptions, type UseLiveRunnerOptions, builtinModules, compile, compileModule, createRegistry, createRenderBudget, createRequire, defineLoader, defineModule, errorPosition, normalizeModule, precompiledTransform, preloadTranspiler, registryFromGlob, resolveModules, setTranspiler, transpile, useLiveContext, useLiveModule, useLiveRunner };