@soederpop/luca 0.1.1 → 0.1.3

package/dist/node/features/helpers.d.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const HelpersStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    discovered: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    registered: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type HelpersState = z.infer<typeof HelpersStateSchema>;
+export declare const HelpersOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    rootDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HelpersOptions = z.infer<typeof HelpersOptionsSchema>;
+export declare const HelpersEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    discovered: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodString>], null>;
+    registered: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodAny], null>;
+}, z.core.$strip>;
+type RegistryType = 'features' | 'clients' | 'servers' | 'commands' | 'endpoints' | 'selectors';
+/**
+ * The Helpers feature is a unified gateway for discovering and registering
+ * project-level helpers from conventional folder locations.
+ *
+ * It scans known folder names (features/, clients/, servers/, commands/, endpoints/, selectors/)
+ * and handles registration differently based on the helper type:
+ *
+ * - Class-based (features, clients, servers): Dynamic import, validate subclass, register
+ * - Config-based (commands, endpoints, selectors): Delegate to existing discovery mechanisms
+ *
+ * @example
+ * ```typescript
+ * const helpers = container.feature('helpers', { enable: true })
+ *
+ * // Discover all helper types
+ * await helpers.discoverAll()
+ *
+ * // Discover a specific type
+ * await helpers.discover('features')
+ *
+ * // Unified view of all available helpers
+ * console.log(helpers.available)
+ * ```
+ */
+export declare class Helpers extends Feature<HelpersState, HelpersOptions> {
+    static shortcut: "features.helpers";
+    static description: string;
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        discovered: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        registered: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        rootDir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        discovered: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodString>], null>;
+        registered: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodAny], null>;
+    }, z.core.$strip>;
+    /** In-flight or completed discovery promises, keyed by registry type */
+    private _discoveryPromises;
+    /** Cached results from completed discoveries */
+    private _discoveryResults;
+    /** In-flight or completed discoverAll promise */
+    private _discoverAllPromise;
+    /**
+     * Returns a mapping from registry type name to its registry singleton, base class, and conventional folder candidates.
+     */
+    private get registryMap();
+    /** The root directory to scan for helper folders. */
+    get rootDir(): string;
+    /**
+     * Whether to use native `import()` for loading project helpers.
+     * True only if `@soederpop/luca` is actually resolvable in `node_modules`.
+     * Warns when `node_modules` exists but the package is missing.
+     */
+    get useNativeImport(): boolean;
+    /** Prevent repeated warnings about missing @soederpop/luca */
+    private _warnedNativeImport;
+    /** Track whether we've seeded the VM with virtual modules */
+    private _vmSeeded;
+    /**
+     * Seeds the VM feature with virtual modules so that project-level files
+     * can `import` / `require('@soederpop/luca')`, `zod`, etc. without
+     * needing them in `node_modules`.
+     *
+     * Called automatically when `useNativeImport` is false.
+     * Can also be called externally (e.g. from the CLI) to pre-seed before discovery.
+     */
+    seedVirtualModules(): void;
+    /**
+     * Returns a unified view of all available helpers across all registries.
+     * Each key is a registry type, each value is the list of helper names in that registry.
+     *
+     * @example
+     * ```typescript
+     * container.helpers.available
+     * // { features: ['fs', 'git', ...], clients: ['rest', 'websocket'], ... }
+     * ```
+     */
+    get available(): Record<string, string[]>;
+    /**
+     * Ensures the fileManager feature is started before using it for discovery.
+     *
+     * @returns The started fileManager instance
+     */
+    private ensureFileManager;
+    /**
+     * Resolves which conventional folder path exists for a given registry type.
+     * Tries each candidate folder in order and returns the first one that exists.
+     *
+     * @param type - The registry type to resolve the folder for
+     * @returns Absolute path to the folder, or null if none exist
+     */
+    private resolveFolderPath;
+    /**
+     * Discover and register project-level helpers of the given type.
+     *
+     * Idempotent: the first caller triggers the actual scan. Subsequent callers
+     * receive the cached results. If discovery is in-flight, callers await the
+     * same promise — no duplicate work.
+     *
+     * @param type - Which type of helpers to discover
+     * @param options - Optional overrides
+     * @param options.directory - Override the directory to scan
+     * @returns Names of helpers that were discovered and registered
+     *
+     * @example
+     * ```typescript
+     * const names = await container.helpers.discover('features')
+     * console.log(names) // ['myCustomFeature']
+     * ```
+     */
+    discover(type: RegistryType, options?: {
+        directory?: string;
+    }): Promise<string[]>;
+    /** Internal: performs the actual discovery work for a single type. */
+    private _doDiscover;
+    /**
+     * Discover all helper types from their conventional folder locations.
+     *
+     * Idempotent: safe to call from multiple places (luca.cli.ts, commands, etc.).
+     * The first caller triggers discovery; all others receive the same results.
+     *
+     * @returns Map of registry type to discovered helper names
+     *
+     * @example
+     * ```typescript
+     * const results = await container.helpers.discoverAll()
+     * // { features: ['myFeature'], clients: [], servers: [], commands: ['deploy'], endpoints: [] }
+     * ```
+     */
+    discoverAll(): Promise<Record<string, string[]>>;
+    /** Internal: performs the actual discoverAll work. */
+    private _doDiscoverAll;
+    /**
+     * Look up a helper class by type and name.
+     *
+     * @param type - The registry type (features, clients, servers, commands, endpoints)
+     * @param name - The helper name within that registry
+     * @returns The helper constructor
+     *
+     * @example
+     * ```typescript
+     * const FsClass = container.helpers.lookup('features', 'fs')
+     * ```
+     */
+    lookup(type: RegistryType, name: string): any;
+    /**
+     * Get the introspection description for a specific helper.
+     *
+     * @param type - The registry type
+     * @param name - The helper name
+     * @returns Markdown description of the helper's interface
+     */
+    describe(type: RegistryType, name: string): string;
+    /**
+     * Load a module either via native `import()` or the VM's virtual module system.
+     * Uses the same `useNativeImport` check as discovery to decide the loading strategy.
+     *
+     * @param absPath - Absolute path to the module file
+     * @param options - Optional settings
+     * @param options.cacheBust - When true, appends a timestamp query to bypass the native import cache (useful for hot reload)
+     * @returns The module's exports
+     */
+    loadModuleExports(absPath: string, options?: {
+        cacheBust?: boolean;
+    }): Promise<Record<string, any>>;
+    /**
+     * Discovers class-based helpers (features, clients, servers) from a directory.
+     * Uses fileManager when available (fast in git repos), falls back to Glob.
+     */
+    private discoverClassBased;
+    /**
+     * Discovers config-based helpers (commands, endpoints) by delegating
+     * to existing discovery mechanisms.
+     */
+    private discoverConfigBased;
+    /**
+     * Discovers commands using the VM's virtual module system.
+     * Mirrors CommandsRegistry.discover() but uses vm.loadModule() instead of import().
+     */
+    private discoverCommandsViaVM;
+    /**
+     * Discovers selectors using the VM's virtual module system.
+     * Mirrors discoverCommandsViaVM but uses selectors registry and Selector base class.
+     */
+    private discoverSelectorsViaVM;
+    /**
+     * Discovers endpoints from a directory, registering them for discoverability.
+     * Actual mounting to an express server is handled separately by ExpressServer.useEndpoints().
+     */
+    private discoverEndpoints;
+    /**
+     * Check if a class is a subclass of a given base class by walking the prototype chain.
+     * Uses identity comparison first, then falls back to name comparison to handle
+     * cross-module boundaries (e.g. compiled binary vs dynamically imported modules
+     * that resolve to separate module instances of the same class).
+     */
+    private isSubclassOf;
+    /**
+     * Convert a kebab-case or snake_case filename to a camelCase registry name.
+     */
+    private fileNameToRegistryName;
+}
+export default Helpers;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/node/features/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/node/features/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAmBvC,eAAO,MAAM,kBAAkB;;;;iBAG7B,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE7D,eAAO,MAAM,oBAAoB;;;;;;iBAE/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEjE,eAAO,MAAM,mBAAmB;;;;;iBAU9B,CAAA;AAEF,KAAK,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAA;AAI/F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,OAAQ,SAAQ,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC;IAChE,OAAgB,QAAQ,EAAG,kBAAkB,CAAS;IACtD,OAAgB,WAAW,SAA0E;IACrG,OAAgB,WAAW;;;;sBAAqB;IAChD,OAAgB,aAAa;;;;;;sBAAuB;IACpD,OAAgB,YAAY;;;;;sBAAsB;IAGlD,wEAAwE;IACxE,OAAO,CAAC,kBAAkB,CAA4C;IACtE,gDAAgD;IAChD,OAAO,CAAC,iBAAiB,CAAmC;IAC5D,iDAAiD;IACjD,OAAO,CAAC,mBAAmB,CAAiD;IAE5E;;OAEG;IACH,OAAO,KAAK,WAAW,GAStB;IAED,qDAAqD;IACrD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;OAIG;IACH,IAAI,eAAe,IAAI,OAAO,CAc7B;IAED,8DAA8D;IAC9D,OAAO,CAAC,mBAAmB,CAAQ;IAEnC,6DAA6D;IAC7D,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;;;;;OAOG;IACH,kBAAkB,IAAI,IAAI;IA4F1B;;;;;;;;;OASG;IACH,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAMxC;IAED;;;;OAIG;YACW,iBAAiB;IAQ/B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;;;;;;;;;;OAiBG;IACG,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA6B3F,sEAAsE;YACxD,WAAW;IA2BzB;;;;;;;;;;;;;OAaG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAStD,sDAAsD;YACxC,cAAc;IAU5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG;IAK7C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAKlD;;;;;;;;OAQG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAYzG;;;OAGG;YACW,kBAAkB;IAyFhC;;;OAGG;YACW,mBAAmB;IAwBjC;;;OAGG;YACW,qBAAqB;IAsEnC;;;OAGG;YACW,sBAAsB;IA2CpC;;;OAGG;YACW,iBAAiB;IAuB/B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAYpB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAK/B;AAED,eAAe,OAAO,CAAA"}

package/dist/node/features/ink.d.ts

@@ -0,0 +1,332 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const InkStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mounted: z.ZodBoolean;
+}, z.core.$loose>;
+type InkState = z.infer<typeof InkStateSchema>;
+export declare const InkOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    maxFps: z.ZodOptional<z.ZodNumber>;
+    patchConsole: z.ZodOptional<z.ZodBoolean>;
+    incrementalRendering: z.ZodOptional<z.ZodBoolean>;
+    concurrent: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type InkOptions = z.infer<typeof InkOptionsSchema>;
+export declare const InkEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    mounted: z.ZodTuple<[], null>;
+    unmounted: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+/**
+ * Ink Feature — React-powered Terminal UI via Ink
+ *
+ * Exposes the Ink library (React for CLIs) through the container so any
+ * feature, script, or application can build rich terminal user interfaces
+ * using React components rendered directly in the terminal.
+ *
+ * This feature is intentionally a thin pass-through. It re-exports all of
+ * Ink's components, hooks, and the render function, plus a few convenience
+ * methods for mounting / unmounting apps. The actual UI composition is left
+ * entirely to the consumer — the feature just makes Ink available.
+ *
+ * **What you get:**
+ * - `ink.render(element)` — mount a React element to the terminal
+ * - `ink.components` — { Box, Text, Static, Transform, Newline, Spacer }
+ * - `ink.hooks` — { useInput, useApp, useStdin, useStdout, useStderr, useFocus, useFocusManager }
+ * - `ink.React` — the React module itself (createElement, useState, etc.)
+ * - `ink.unmount()` — tear down the currently mounted app
+ * - `ink.waitUntilExit()` — await the mounted app's exit
+ *
+ * **Quick start:**
+ * ```tsx
+ * const ink = container.feature('ink', { enable: true })
+ * const { Box, Text } = ink.components
+ * const { React } = ink
+ *
+ * ink.render(
+ *   React.createElement(Box, { flexDirection: 'column' },
+ *     React.createElement(Text, { color: 'green' }, 'hello from ink'),
+ *     React.createElement(Text, { dimColor: true }, 'powered by luca'),
+ *   )
+ * )
+ *
+ * await ink.waitUntilExit()
+ * ```
+ *
+ * Or if you're in a .tsx file:
+ * ```tsx
+ * import React from 'react'
+ * const ink = container.feature('ink', { enable: true })
+ * const { Box, Text } = ink.components
+ *
+ * ink.render(
+ *   <Box flexDirection="column">
+ *     <Text color="green">hello from ink</Text>
+ *     <Text dimColor>powered by luca</Text>
+ *   </Box>
+ * )
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class Ink extends Feature<InkState, InkOptions> {
+    static shortcut: "features.ink";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        mounted: z.ZodBoolean;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        maxFps: z.ZodOptional<z.ZodNumber>;
+        patchConsole: z.ZodOptional<z.ZodBoolean>;
+        incrementalRendering: z.ZodOptional<z.ZodBoolean>;
+        concurrent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        mounted: z.ZodTuple<[], null>;
+        unmounted: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    private _instance;
+    private _inkModule;
+    private _reactModule;
+    private _blocks;
+    get initialState(): InkState;
+    /**
+     * The raw ink module. Lazy-loaded on first access.
+     */
+    private _getInk;
+    /**
+     * The raw react module. Lazy-loaded on first access.
+     */
+    private _getReact;
+    /**
+     * The React module (createElement, useState, useEffect, etc.)
+     *
+     * Exposed so consumers don't need a separate react import.
+     * Lazy-loaded — first access triggers the import.
+     */
+    get React(): typeof import('react');
+    /**
+     * Pre-load ink + react modules so the sync getters work.
+     * Called automatically by render(), but you can call it early.
+     *
+     * @returns This Ink feature instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const ink = container.feature('ink', { enable: true })
+     * await ink.loadModules()
+     * // Now sync getters like ink.React, ink.components, ink.hooks work
+     * const { Box, Text } = ink.components
+     * ```
+     */
+    loadModules(): Promise<this>;
+    /**
+     * All Ink components as a single object for destructuring.
+     *
+     * ```ts
+     * const { Box, Text, Static, Spacer } = ink.components
+     * ```
+     */
+    get components(): {
+        Box: typeof import('ink').Box;
+        Text: typeof import('ink').Text;
+        Static: typeof import('ink').Static;
+        Transform: typeof import('ink').Transform;
+        Newline: typeof import('ink').Newline;
+        Spacer: typeof import('ink').Spacer;
+    };
+    /**
+     * All Ink hooks as a single object for destructuring.
+     *
+     * ```ts
+     * const { useInput, useApp, useFocus } = ink.hooks
+     * ```
+     */
+    get hooks(): {
+        useInput: typeof import('ink').useInput;
+        useApp: typeof import('ink').useApp;
+        useStdin: typeof import('ink').useStdin;
+        useStdout: typeof import('ink').useStdout;
+        useStderr: typeof import('ink').useStderr;
+        useFocus: typeof import('ink').useFocus;
+        useFocusManager: typeof import('ink').useFocusManager;
+        useCursor: typeof import('ink').useCursor;
+    };
+    /**
+     * The Ink measureElement utility.
+     */
+    get measureElement(): typeof import('ink').measureElement;
+    /**
+     * Mount a React element to the terminal.
+     *
+     * Wraps `ink.render()` — automatically loads modules if needed,
+     * tracks the instance for unmount / waitUntilExit, and updates state.
+     *
+     * @param node - A React element (JSX or React.createElement)
+     * @param options - Ink render options (stdout, stdin, debug, etc.)
+     * @returns The Ink instance with rerender, unmount, waitUntilExit, clear
+     */
+    render(node: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Re-render the currently mounted app with a new root element.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * const ink = container.feature('ink', { enable: true })
+     * const { React } = await ink.loadModules()
+     * const { Text } = ink.components
+     *
+     * await ink.render(React.createElement(Text, null, 'Hello'))
+     * ink.rerender(React.createElement(Text, null, 'Updated!'))
+     * ```
+     */
+    rerender(node: any): void;
+    /**
+     * Unmount the currently mounted Ink app.
+     *
+     * Tears down the React tree rendered in the terminal and resets state.
+     * Safe to call when no app is mounted (no-op).
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * const ink = container.feature('ink', { enable: true })
+     * await ink.render(myElement)
+     * // ... later
+     * ink.unmount()
+     * console.log(ink.isMounted) // false
+     * ```
+     */
+    unmount(): void;
+    /**
+     * Returns a promise that resolves when the mounted app exits.
+     *
+     * Useful for keeping a script alive while the terminal UI is active.
+     *
+     * @returns Promise that resolves when the Ink app exits
+     * @throws {Error} When no app is currently mounted
+     *
+     * @example
+     * ```typescript
+     * const ink = container.feature('ink', { enable: true })
+     * await ink.render(myElement)
+     * await ink.waitUntilExit()
+     * console.log('App exited')
+     * ```
+     */
+    waitUntilExit(): Promise<void>;
+    /**
+     * Clear the terminal output of the mounted app.
+     *
+     * Erases all Ink-rendered content from the terminal. Safe to call
+     * when no app is mounted (no-op).
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * const ink = container.feature('ink', { enable: true })
+     * await ink.render(myElement)
+     * // ... later, wipe the screen
+     * ink.clear()
+     * ```
+     */
+    clear(): void;
+    /**
+     * Whether an ink app is currently mounted.
+     */
+    get isMounted(): boolean;
+    /**
+     * The raw ink render instance if you need low-level access.
+     */
+    get instance(): any | null;
+    /**
+     * Register a named React function component as a renderable block.
+     *
+     * @param name - Unique block name
+     * @param component - A React function component
+     * @returns This Ink feature instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * ink.registerBlock('Greeting', ({ name }) =>
+     *   React.createElement(Text, { color: 'green' }, `Hello ${name}!`)
+     * )
+     * ```
+     */
+    registerBlock(name: string, component: Function): this;
+    /**
+     * Render a registered block by name with optional props.
+     *
+     * Looks up the component, creates a React element, renders it via ink,
+     * then immediately unmounts so the static output stays on screen while
+     * freeing the React tree.
+     *
+     * @param name - The registered block name
+     * @param data - Props to pass to the component
+     *
+     * @example
+     * ```typescript
+     * await ink.renderBlock('Greeting', { name: 'Jon' })
+     * ```
+     */
+    renderBlock(name: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Render a registered block that needs to stay mounted for async work.
+     *
+     * The component receives a `done` prop — a callback it must invoke when
+     * it has finished rendering its final output. The React tree stays alive
+     * until `done()` is called or the timeout expires.
+     *
+     * @param name - The registered block name
+     * @param data - Props to pass to the component (a `done` prop is added automatically)
+     * @param options - `timeout` in ms before force-unmounting (default 30 000)
+     *
+     * @example
+     * ```tsx
+     * // In a ## Blocks section:
+     * function AsyncChart({ url, done }) {
+     *   const [rows, setRows] = React.useState(null)
+     *   React.useEffect(() => {
+     *     fetch(url).then(r => r.json()).then(data => {
+     *       setRows(data)
+     *       done()
+     *     })
+     *   }, [])
+     *   if (!rows) return <Text dimColor>Loading...</Text>
+     *   return <Box><Text>{JSON.stringify(rows)}</Text></Box>
+     * }
+     *
+     * // In a code block:
+     * await renderAsync('AsyncChart', { url: 'https://api.example.com/data' })
+     * ```
+     */
+    renderBlockAsync(name: string, data?: Record<string, any>, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * List all registered block names.
+     */
+    get blocks(): string[];
+}
+export default Ink;
+declare module '../../feature' {
+    interface AvailableFeatures {
+        ink: typeof Ink;
+    }
+}
+//# sourceMappingURL=ink.d.ts.map

package/dist/node/features/ink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ink.d.ts","sourceRoot":"","sources":["../../../src/node/features/ink.ts"],"names":[],"mappings":"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"}