@flight-framework/core 0.0.3 → 0.2.0

package/dist/islands/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @flight-framework/core - Islands Architecture
+ *
+ * Selective hydration with fine-grained control over when and how
+ * components become interactive. Framework-agnostic islands primitives.
+ *
+ * Best Practices 2026:
+ * - Minimal JavaScript: Only hydrate what needs interactivity
+ * - Lazy hydration: Load JS when actually needed
+ * - Progressive enhancement: Works without JS
+ * - Performance: Reduce main thread work
+ *
+ * @example
+ * ```typescript
+ * import { defineIsland, renderIsland, hydrateIslands } from '@flight-framework/core/islands';
+ *
+ * // Server: Define an interactive island
+ * const Counter = defineIsland({
+ *     id: 'counter',
+ *     component: CounterComponent,
+ *     hydrate: 'visible', // Only hydrate when scrolled into view
+ * });
+ *
+ * // Server: Render to HTML with island markers
+ * const html = await renderIsland(Counter, { initial: 0 });
+ *
+ * // Client: Hydrate all islands on the page
+ * hydrateIslands();
+ * ```
+ */
+/**
+ * When to hydrate the island
+ */
+type HydrationTrigger = 'load' | 'idle' | 'visible' | 'interaction' | 'media' | 'never' | CustomHydrationTrigger;
+/**
+ * Custom hydration trigger function
+ */
+interface CustomHydrationTrigger {
+    type: 'custom';
+    /** Name for debugging */
+    name: string;
+    /** Function that returns a promise resolving when hydration should occur */
+    when: (element: HTMLElement) => Promise<void>;
+}
+/**
+ * Island configuration
+ */
+interface IslandConfig<P = Record<string, unknown>> {
+    /** Unique identifier for this island type */
+    id: string;
+    /** The component to render (framework-specific) */
+    component: unknown;
+    /** When to hydrate on client */
+    hydrate: HydrationTrigger;
+    /** Default props */
+    defaultProps?: P;
+    /** Media query for 'media' trigger */
+    mediaQuery?: string;
+    /** Path to client-side component bundle */
+    clientEntry?: string;
+    /** Fallback HTML while not hydrated (optional override) */
+    fallback?: string;
+    /** Loading priority hint */
+    priority?: 'high' | 'low';
+}
+/**
+ * Island instance with props
+ */
+interface Island<P = Record<string, unknown>> {
+    /** Island configuration */
+    config: IslandConfig<P>;
+    /** Instance props */
+    props: P;
+    /** Unique instance ID (for multiple instances of same island type) */
+    instanceId: string;
+}
+/**
+ * Rendered island HTML with metadata
+ */
+interface RenderedIsland {
+    /** The HTML string */
+    html: string;
+    /** Island ID */
+    id: string;
+    /** Instance ID */
+    instanceId: string;
+    /** Serialized props for hydration */
+    propsScript: string;
+    /** CSS if any */
+    css?: string;
+}
+/**
+ * Island registry for client-side hydration
+ */
+interface IslandRegistry {
+    /** Register a component for an island ID */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /** Get registered loader */
+    get(id: string): (() => Promise<unknown>) | undefined;
+    /** Check if island is registered */
+    has(id: string): boolean;
+}
+/**
+ * Client-side hydration options
+ */
+interface HydrateOptions {
+    /** Root element to scan for islands */
+    root?: HTMLElement;
+    /** Custom island registry */
+    registry?: IslandRegistry;
+    /** Callback when an island is hydrated */
+    onHydrate?: (id: string, instanceId: string, duration: number) => void;
+    /** Callback on hydration error */
+    onError?: (id: string, error: Error) => void;
+}
+/**
+ * Define an island component
+ */
+declare function defineIsland<P = Record<string, unknown>>(config: IslandConfig<P>): (props?: P) => Island<P>;
+/**
+ * UI framework adapter for island rendering
+ */
+interface IslandRenderAdapter {
+    /** Framework name */
+    name: string;
+    /** Render component to HTML */
+    renderToString(component: unknown, props: Record<string, unknown>): Promise<string>;
+    /** Get CSS if any */
+    getCSS?(component: unknown): string;
+}
+/**
+ * Set the global island render adapter
+ */
+declare function setIslandAdapter(adapter: IslandRenderAdapter): void;
+/**
+ * Render an island to HTML with hydration markers
+ */
+declare function renderIsland<P extends Record<string, unknown>>(island: Island<P>, adapter?: IslandRenderAdapter): Promise<RenderedIsland>;
+/**
+ * Render multiple islands and collect their outputs
+ */
+declare function renderIslands<P extends Record<string, unknown>>(islands: Island<P>[], adapter?: IslandRenderAdapter): Promise<{
+    html: string;
+    propsScripts: string;
+    css: string;
+}>;
+/**
+ * Create an island registry for client-side hydration
+ */
+declare function createIslandRegistry(): IslandRegistry;
+/**
+ * Register an island component for client-side hydration
+ */
+declare function registerIsland(id: string, loader: () => Promise<unknown>): void;
+/**
+ * Client-side hydration bootstrapper
+ * Call this in your client entry point
+ */
+declare function hydrateIslands(options?: HydrateOptions): void;
+/**
+ * Create a React island render adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToString } from 'react-dom/server';
+ * import { createElement } from 'react';
+ *
+ * const reactAdapter = createReactIslandAdapter({
+ *     renderToString,
+ *     createElement,
+ * });
+ * ```
+ */
+declare function createReactIslandAdapter(deps: {
+    renderToString: (element: unknown) => string;
+    createElement: (type: unknown, props?: unknown) => unknown;
+}): IslandRenderAdapter;
+/**
+ * Create a Preact island render adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToString } from 'preact-render-to-string';
+ * import { h } from 'preact';
+ *
+ * const preactAdapter = createPreactIslandAdapter({
+ *     renderToString,
+ *     h,
+ * });
+ * ```
+ */
+declare function createPreactIslandAdapter(deps: {
+    renderToString: (element: unknown) => string;
+    h: (type: unknown, props?: unknown) => unknown;
+}): IslandRenderAdapter;
+/**
+ * Create a Vue island render adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToString, createSSRApp } from 'vue/server-renderer';
+ *
+ * const vueAdapter = createVueIslandAdapter({
+ *     renderToString,
+ *     createSSRApp,
+ * });
+ * ```
+ */
+declare function createVueIslandAdapter(deps: {
+    renderToString: (app: unknown) => Promise<string>;
+    createSSRApp: (component: unknown, props?: unknown) => unknown;
+}): IslandRenderAdapter;
+/**
+ * Create a Solid island render adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToString } from 'solid-js/web';
+ *
+ * const solidAdapter = createSolidIslandAdapter({
+ *     renderToString,
+ * });
+ * ```
+ */
+declare function createSolidIslandAdapter(deps: {
+    renderToString: (fn: () => unknown) => string;
+}): IslandRenderAdapter;
+/**
+ * Register the flight-island custom element
+ * This provides additional functionality like slot support
+ */
+declare function registerFlightIslandElement(): void;
+
+export { type CustomHydrationTrigger, type HydrateOptions, type HydrationTrigger, type Island, type IslandConfig, type IslandRegistry, type IslandRenderAdapter, type RenderedIsland, createIslandRegistry, createPreactIslandAdapter, createReactIslandAdapter, createSolidIslandAdapter, createVueIslandAdapter, defineIsland, hydrateIslands, registerFlightIslandElement, registerIsland, renderIsland, renderIslands, setIslandAdapter };

package/dist/islands/index.js

@@ -0,0 +1,3 @@
+export { createIslandRegistry, createPreactIslandAdapter, createReactIslandAdapter, createSolidIslandAdapter, createVueIslandAdapter, defineIsland, hydrateIslands, registerFlightIslandElement, registerIsland, renderIsland, renderIslands, setIslandAdapter } from '../chunk-WFAWAHJH.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/islands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/rsc/adapters/index.d.ts

@@ -0,0 +1,8 @@
+export { ReactConsumerOptions, ReactServerComponent, createReactAdapter, createReactConsumer, markAsClientComponent } from './react.js';
+export { VueConsumerOptions, VueDependencies, VueServerComponent, createVueAdapter, createVueConsumer, markAsVueClientComponent } from './vue.js';
+export { SolidConsumerOptions, SolidDependencies, SolidServerComponent, createSolidAdapter, createSolidConsumer, isServer as isSolidServer, markAsSolidClientComponent } from './solid.js';
+export { PreactConsumerOptions, PreactDependencies, PreactServerComponent, createPreactAdapter, createPreactConsumer, markAsPreactClientComponent, lazy as preactLazy } from './preact.js';
+export { ElementTypeInfo, UIAdapter } from '../renderer.js';
+import 'react';
+import '../context.js';
+import '../payload.js';

package/dist/rsc/adapters/index.js

@@ -0,0 +1,7 @@
+import '../../chunk-Y22AMGTM.js';
+export { createPreactAdapter, createPreactConsumer, markAsPreactClientComponent, lazy as preactLazy } from '../../chunk-Q62ZQ6FM.js';
+export { createReactAdapter, createReactConsumer, markAsClientComponent } from '../../chunk-PSJPMEQK.js';
+export { createVueAdapter, createVueConsumer, markAsVueClientComponent } from '../../chunk-BJIMTO2I.js';
+export { createSolidAdapter, createSolidConsumer, isServer as isSolidServer, markAsSolidClientComponent } from '../../chunk-6CD5FIYI.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/rsc/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/rsc/adapters/preact.d.ts

@@ -0,0 +1,97 @@
+import { ServerContext } from '../context.js';
+import { FlightElement, FlightChunk } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Minimal Preact VNode interface
+ */
+interface PreactVNode {
+    type: unknown;
+    props: Record<string, unknown>;
+    key: string | number | null;
+    ref: unknown;
+    __?: unknown;
+    __k?: unknown[];
+    __b?: number;
+    __e?: unknown;
+    __c?: unknown;
+}
+/**
+ * Preact dependencies (user provides these)
+ */
+interface PreactDependencies {
+    /** preact module */
+    preact: {
+        h: (type: unknown, props?: unknown, ...children: unknown[]) => PreactVNode;
+        Fragment?: unknown;
+        Component?: unknown;
+        isValidElement?: (value: unknown) => boolean;
+        cloneElement?: (vnode: PreactVNode, props?: unknown) => PreactVNode;
+    };
+    /** preact-render-to-string module (optional - for SSR) */
+    renderToString?: (vnode: PreactVNode) => string;
+    /** preact/hooks module (optional) */
+    hooks?: {
+        useState: <T>(initial: T) => [T, (v: T) => void];
+        useEffect: (fn: () => void | (() => void), deps?: unknown[]) => void;
+        useMemo: <T>(fn: () => T, deps: unknown[]) => T;
+    };
+}
+/**
+ * Create Preact UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createPreactAdapter } from '@flight-framework/core/rsc/adapters/preact';
+ * import * as preact from 'preact';
+ * import renderToString from 'preact-render-to-string';
+ *
+ * const adapter = createPreactAdapter({
+ *   preact,
+ *   renderToString,
+ * });
+ *
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createPreactAdapter(deps?: PreactDependencies): UIAdapter;
+/**
+ * Options for Preact consumer
+ */
+interface PreactConsumerOptions {
+    /** Registry of client components */
+    registry?: Map<string, () => Promise<unknown>>;
+}
+/**
+ * Create a Preact client-side consumer for Flight payloads
+ */
+declare function createPreactConsumer(deps: PreactDependencies, options?: PreactConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to Preact VNodes
+     */
+    toPreactElement(element: FlightElement): unknown;
+    /**
+     * Hydrate Flight payload into DOM
+     */
+    hydrate(chunks: FlightChunk[], container: Element, hydrateFn?: (vnode: unknown, container: Element) => void): void;
+};
+/**
+ * Type helper for Preact Server Component
+ */
+type PreactServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<PreactVNode> | PreactVNode;
+/**
+ * Mark a Preact component as a client component
+ */
+declare function markAsPreactClientComponent<T extends (...args: unknown[]) => unknown>(component: T, moduleId: string, exportName?: string): T;
+/**
+ * Create a lazy-loading component for Preact
+ */
+declare function lazy<T extends (...args: unknown[]) => unknown>(loader: () => Promise<{
+    default: T;
+}>): T;
+
+export { type PreactConsumerOptions, type PreactDependencies, type PreactServerComponent, createPreactAdapter, createPreactConsumer, lazy, markAsPreactClientComponent };

package/dist/rsc/adapters/preact.js

@@ -0,0 +1,3 @@
+export { createPreactAdapter, createPreactConsumer, lazy, markAsPreactClientComponent } from '../../chunk-Q62ZQ6FM.js';
+//# sourceMappingURL=preact.js.map
+//# sourceMappingURL=preact.js.map

package/dist/rsc/adapters/preact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"preact.js"}

package/dist/rsc/adapters/react.d.ts

@@ -0,0 +1,82 @@
+import * as react from 'react';
+import { ServerContext } from '../context.js';
+import { FlightElement, FlightChunk } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Create React UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createReactAdapter } from '@flight-framework/core/rsc/adapters/react';
+ * import { renderToString } from 'react-dom/server';
+ * import * as React from 'react';
+ *
+ * const adapter = createReactAdapter({
+ *   React,
+ *   renderToString,
+ * });
+ *
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createReactAdapter(deps?: {
+    /** React module (optional - for SSR) */
+    React?: {
+        isValidElement: (value: unknown) => boolean;
+        Children: {
+            toArray: (children: unknown) => unknown[];
+        };
+        Fragment: symbol;
+        Suspense: unknown;
+    };
+    /** renderToString function (optional - for SSR fallbacks) */
+    renderToString?: (element: unknown) => string;
+}): UIAdapter;
+/**
+ * Opciones para el consumer de React
+ */
+interface ReactConsumerOptions {
+    /** Registry de client components */
+    registry?: Map<string, () => Promise<unknown>>;
+    /** Callback when hydration completes */
+    onHydrate?: (id: string) => void;
+}
+/**
+ * Create a React client-side consumer for Flight payloads
+ *
+ * This reconstructs React elements from Flight chunks on the client.
+ */
+declare function createReactConsumer(deps: {
+    React: {
+        createElement: (type: unknown, props?: unknown, ...children: unknown[]) => unknown;
+        Suspense: unknown;
+        Fragment: unknown;
+        lazy: (factory: () => Promise<{
+            default: unknown;
+        }>) => unknown;
+    };
+}, options?: ReactConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to React elements
+     */
+    toReactElement(element: FlightElement): unknown;
+    /**
+     * Process Flight chunks and build React tree
+     */
+    processChunks(chunks: FlightChunk[]): unknown;
+};
+/**
+ * Type helper for React Server Component
+ */
+type ReactServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<ReturnType<typeof react.createElement>> | ReturnType<typeof react.createElement>;
+/**
+ * Mark a component as a client component (for use without bundler transform)
+ */
+declare function markAsClientComponent<T extends (...args: unknown[]) => unknown>(component: T, moduleId: string, exportName?: string): T;
+
+export { type ReactConsumerOptions, type ReactServerComponent, createReactAdapter, createReactConsumer, markAsClientComponent };

package/dist/rsc/adapters/react.js

@@ -0,0 +1,3 @@
+export { createReactAdapter, createReactConsumer, markAsClientComponent } from '../../chunk-PSJPMEQK.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/rsc/adapters/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.js"}

package/dist/rsc/adapters/solid.d.ts

@@ -0,0 +1,84 @@
+import { ServerContext } from '../context.js';
+import { FlightElement, FlightChunk } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Solid dependencies (user provides these)
+ */
+interface SolidDependencies {
+    /** solid-js module */
+    solid: {
+        createSignal: <T>(value: T) => [() => T, (v: T) => void];
+        createMemo: <T>(fn: () => T) => () => T;
+        createEffect: (fn: () => void) => void;
+        children: (fn: () => unknown) => () => unknown[];
+        splitProps: <T extends object, K extends keyof T>(props: T, ...keys: K[][]) => [Pick<T, K>, Omit<T, K>][];
+        For?: unknown;
+        Show?: unknown;
+        Switch?: unknown;
+        Match?: unknown;
+        Suspense?: unknown;
+        ErrorBoundary?: unknown;
+    };
+    /** solid-js/web module */
+    web: {
+        render?: (code: () => unknown, element: Element) => () => void;
+        hydrate?: (code: () => unknown, element: Element) => () => void;
+        renderToString?: (code: () => unknown) => string;
+        renderToStringAsync?: (code: () => unknown) => Promise<string>;
+        isServer?: boolean;
+        Dynamic?: unknown;
+    };
+}
+/**
+ * Create Solid.js UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createSolidAdapter } from '@flight-framework/core/rsc/adapters/solid';
+ * import * as solid from 'solid-js';
+ * import * as web from 'solid-js/web';
+ *
+ * const adapter = createSolidAdapter({ solid, web });
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createSolidAdapter(deps?: SolidDependencies): UIAdapter;
+/**
+ * Options for Solid consumer
+ */
+interface SolidConsumerOptions {
+    /** Registry of client components */
+    registry?: Map<string, () => Promise<unknown>>;
+}
+/**
+ * Create a Solid client-side consumer for Flight payloads
+ */
+declare function createSolidConsumer(deps: SolidDependencies, options?: SolidConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to Solid JSX
+     */
+    toSolidElement(element: FlightElement): unknown;
+    /**
+     * Hydrate Flight payload into DOM
+     */
+    hydrate(chunks: FlightChunk[], container: Element): (() => void) | undefined;
+};
+/**
+ * Type helper for Solid Server Component
+ */
+type SolidServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<unknown> | unknown;
+/**
+ * Mark a Solid component as a client component
+ */
+declare function markAsSolidClientComponent<T extends object>(component: T, moduleId: string, exportName?: string): T;
+/**
+ * Check if running on server (Solid isServer helper)
+ */
+declare function isServer(deps?: SolidDependencies): boolean;
+
+export { type SolidConsumerOptions, type SolidDependencies, type SolidServerComponent, createSolidAdapter, createSolidConsumer, isServer, markAsSolidClientComponent };

package/dist/rsc/adapters/solid.js

@@ -0,0 +1,3 @@
+export { createSolidAdapter, createSolidConsumer, isServer, markAsSolidClientComponent } from '../../chunk-6CD5FIYI.js';
+//# sourceMappingURL=solid.js.map
+//# sourceMappingURL=solid.js.map

package/dist/rsc/adapters/solid.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"solid.js"}

package/dist/rsc/adapters/vue.d.ts

@@ -0,0 +1,80 @@
+import { ServerContext } from '../context.js';
+import { FlightElement } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Minimal Vue VNode interface
+ */
+interface VueVNode {
+    __v_isVNode?: boolean;
+    type: unknown;
+    props: Record<string, unknown> | null;
+    children: unknown;
+    key: string | number | null;
+    component?: unknown;
+    shapeFlag?: number;
+}
+/**
+ * Vue dependencies (user provides these)
+ */
+interface VueDependencies {
+    /** Vue module */
+    Vue: {
+        h: (type: unknown, props?: unknown, children?: unknown) => VueVNode;
+        isVNode: (value: unknown) => boolean;
+        createSSRApp?: (rootComponent: unknown) => unknown;
+        Fragment?: symbol;
+        Suspense?: unknown;
+        Text?: symbol;
+    };
+    /** renderToString from vue/server-renderer (optional - for SSR) */
+    renderToString?: (app: unknown) => Promise<string>;
+}
+/**
+ * Create Vue UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createVueAdapter } from '@flight-framework/core/rsc/adapters/vue';
+ * import * as Vue from 'vue';
+ * import { renderToString } from 'vue/server-renderer';
+ *
+ * const adapter = createVueAdapter({
+ *   Vue,
+ *   renderToString,
+ * });
+ *
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createVueAdapter(deps?: VueDependencies): UIAdapter;
+/**
+ * Options for Vue consumer
+ */
+interface VueConsumerOptions {
+    /** Registry of client components */
+    registry?: Map<string, () => Promise<unknown>>;
+}
+/**
+ * Create a Vue client-side consumer for Flight payloads
+ */
+declare function createVueConsumer(deps: VueDependencies, options?: VueConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to Vue VNodes
+     */
+    toVueElement(element: FlightElement): unknown;
+};
+/**
+ * Type helper for Vue Server Component
+ */
+type VueServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<VueVNode> | VueVNode;
+/**
+ * Mark a Vue component as a client component
+ */
+declare function markAsVueClientComponent<T extends object>(component: T, moduleId: string, exportName?: string): T;
+
+export { type VueConsumerOptions, type VueDependencies, type VueServerComponent, createVueAdapter, createVueConsumer, markAsVueClientComponent };

package/dist/rsc/adapters/vue.js

@@ -0,0 +1,3 @@
+export { createVueAdapter, createVueConsumer, markAsVueClientComponent } from '../../chunk-BJIMTO2I.js';
+//# sourceMappingURL=vue.js.map
+//# sourceMappingURL=vue.js.map

package/dist/rsc/adapters/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"vue.js"}