@flight-framework/core 0.0.2 → 0.1.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/streaming/adapters/index.d.ts

@@ -0,0 +1,223 @@
+import { StreamingRenderOptions, StreamingRenderResult } from '../index.js';
+
+/**
+ * @flight-framework/core - Multi-Framework Streaming Adapters
+ *
+ * Streaming SSR adapters for React, Vue, Svelte, Solid, and HTMX.
+ * Uses dependency injection pattern for optional framework dependencies.
+ *
+ * Best Practices 2026:
+ * - Dependency injection for optional peer dependencies
+ * - Support both Node.js and Edge runtimes
+ * - Progressive hydration support
+ * - Error boundary integration
+ *
+ * @example
+ * ```typescript
+ * // React adapter with your imports
+ * import { renderToReadableStream } from 'react-dom/server';
+ *
+ * const adapter = createReactStreamAdapter({
+ *     renderToReadableStream,
+ *     bootstrapModules: ['/client.js'],
+ * });
+ * ```
+ */
+
+/**
+ * Framework-specific streaming adapter
+ */
+interface StreamingAdapter<TComponent = unknown> {
+    /** Adapter name */
+    readonly name: string;
+    /** Framework version support */
+    readonly framework: string;
+    /** Runtime support */
+    readonly runtime: 'universal' | 'node' | 'edge';
+    /**
+     * Create a streaming response from a component
+     */
+    stream(component: TComponent, options?: StreamingRenderOptions): Promise<StreamingRenderResult>;
+    /**
+     * Render to static string (for comparison/fallback)
+     */
+    renderToString?(component: TComponent): Promise<string>;
+}
+/**
+ * Common adapter options
+ */
+interface AdapterOptions {
+    /** Enable streaming (default: true) */
+    streaming?: boolean;
+    /** Scripts to bootstrap on client */
+    bootstrapScripts?: string[];
+    /** Modules to bootstrap on client */
+    bootstrapModules?: string[];
+    /** Error handling strategy */
+    onError?: (error: Error) => void;
+    /** Shell ready callback */
+    onShellReady?: () => void;
+    /** All content ready callback */
+    onAllReady?: () => void;
+}
+/**
+ * React streaming adapter options with required dependencies
+ */
+interface ReactAdapterOptions extends AdapterOptions {
+    /** React's renderToReadableStream (for Edge) */
+    renderToReadableStream?: (element: unknown, options?: {
+        bootstrapScripts?: string[];
+        bootstrapModules?: string[];
+        identifierPrefix?: string;
+        signal?: AbortSignal;
+        onError?: (error: unknown) => void;
+    }) => Promise<ReadableStream<Uint8Array> & {
+        allReady: Promise<void>;
+    }>;
+    /** React's renderToString (for static fallback) */
+    renderToString?: (element: unknown) => string;
+    /** Custom identifier prefix */
+    identifierPrefix?: string;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Create a React streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToReadableStream, renderToString } from 'react-dom/server';
+ *
+ * const adapter = createReactStreamAdapter({
+ *     renderToReadableStream,
+ *     renderToString,
+ *     bootstrapModules: ['/client.js'],
+ * });
+ *
+ * const result = await adapter.stream(<App />);
+ * ```
+ */
+declare function createReactStreamAdapter(options: ReactAdapterOptions): StreamingAdapter;
+/**
+ * Vue streaming adapter options
+ */
+interface VueAdapterOptions extends AdapterOptions {
+    /** Vue's renderToWebStream */
+    renderToWebStream?: (app: unknown, context?: Record<string, unknown>) => ReadableStream;
+    /** Vue's renderToString */
+    renderToString?: (app: unknown) => Promise<string>;
+    /** Vue app context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a Vue 3 streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToWebStream, renderToString } from 'vue/server-renderer';
+ *
+ * const adapter = createVueStreamAdapter({
+ *     renderToWebStream,
+ *     renderToString,
+ * });
+ *
+ * const result = await adapter.stream(createSSRApp(App));
+ * ```
+ */
+declare function createVueStreamAdapter(options: VueAdapterOptions): StreamingAdapter;
+/**
+ * Solid streaming adapter options
+ */
+interface SolidAdapterOptions extends AdapterOptions {
+    /** Solid's renderToStream */
+    renderToStream?: (fn: () => unknown, options?: {
+        nonce?: string;
+        onCompleteShell?: () => void;
+        onCompleteAll?: () => void;
+    }) => {
+        pipeTo: (writable: WritableStream) => void;
+    };
+    /** Solid's renderToString */
+    renderToString?: (fn: () => unknown) => string;
+    /** Nonce for CSP */
+    nonce?: string;
+}
+/**
+ * Create a Solid.js streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToStream, renderToString } from 'solid-js/web';
+ *
+ * const adapter = createSolidStreamAdapter({
+ *     renderToStream,
+ *     renderToString,
+ * });
+ *
+ * const result = await adapter.stream(() => <App />);
+ * ```
+ */
+declare function createSolidStreamAdapter(options: SolidAdapterOptions): StreamingAdapter;
+/**
+ * Svelte streaming adapter options
+ */
+interface SvelteAdapterOptions extends AdapterOptions {
+    /** Svelte's render function */
+    render?: (component: unknown, options?: {
+        props?: Record<string, unknown>;
+    }) => {
+        body: string;
+        head?: string;
+    };
+    /** Props for the component */
+    props?: Record<string, unknown>;
+}
+/**
+ * Create a Svelte 5 streaming adapter
+ * Note: Svelte's SSR is primarily string-based, streaming is simulated
+ *
+ * @example
+ * ```typescript
+ * import { render } from 'svelte/server';
+ *
+ * const adapter = createSvelteStreamAdapter({
+ *     render,
+ *     props: { name: 'World' },
+ * });
+ *
+ * const result = await adapter.stream(App);
+ * ```
+ */
+declare function createSvelteStreamAdapter(options: SvelteAdapterOptions): StreamingAdapter;
+/**
+ * HTMX streaming adapter options
+ */
+interface HTMXAdapterOptions extends AdapterOptions {
+    /** Event name for SSE */
+    eventName?: string;
+    /** Retry interval for SSE */
+    retryMs?: number;
+}
+/**
+ * Create an HTMX SSE streaming adapter
+ * Uses Server-Sent Events for progressive updates
+ *
+ * @example
+ * ```typescript
+ * const adapter = createHTMXStreamAdapter({
+ *     eventName: 'update',
+ *     retryMs: 3000,
+ * });
+ *
+ * const result = await adapter.stream(['<div>Part 1</div>', '<div>Part 2</div>']);
+ * ```
+ */
+declare function createHTMXStreamAdapter(options?: HTMXAdapterOptions): StreamingAdapter<string[]>;
+type FrameworkType = 'react' | 'vue' | 'solid' | 'svelte' | 'htmx';
+/**
+ * Create a streaming adapter for any supported framework
+ * Note: For react, vue, solid, svelte you need to pass the required dependencies
+ */
+declare function createStreamAdapter(framework: FrameworkType, options?: AdapterOptions & Record<string, unknown>): StreamingAdapter;
+
+export { type AdapterOptions, type FrameworkType, type HTMXAdapterOptions, type ReactAdapterOptions, type SolidAdapterOptions, type StreamingAdapter, type SvelteAdapterOptions, type VueAdapterOptions, createHTMXStreamAdapter, createReactStreamAdapter, createSolidStreamAdapter, createStreamAdapter, createSvelteStreamAdapter, createVueStreamAdapter };

package/dist/streaming/adapters/index.js

@@ -0,0 +1,3 @@
+export { createHTMXStreamAdapter, createReactStreamAdapter, createSolidStreamAdapter, createStreamAdapter, createSvelteStreamAdapter, createVueStreamAdapter } from '../../chunk-MQQLYWZZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

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

package/dist/streaming/conditional.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @flight-framework/core - Conditional Streaming
+ *
+ * Smart streaming decisions based on request context.
+ * Bots get full HTML, users get streaming - YOU control the logic.
+ *
+ * Best Practices 2026:
+ * - SEO-friendly: Crawlers receive complete HTML
+ * - Performance: Users get progressive streaming
+ * - Flexibility: Custom conditions for any use case
+ *
+ * @example
+ * ```typescript
+ * import { streamIf } from '@flight-framework/core/streaming';
+ *
+ * const response = await streamIf({
+ *     request,
+ *     condition: (req) => !isBot(req), // YOUR logic
+ *     stream: () => createStreamingSSR({ ... }),
+ *     static: () => renderToString(<App />),
+ * });
+ * ```
+ */
+/**
+ * Condition function to determine if streaming should be used
+ */
+type StreamingCondition = (request: Request) => boolean | Promise<boolean>;
+/**
+ * Built-in condition types
+ */
+type BuiltInCondition = 'always-stream' | 'never-stream' | 'no-bots' | 'fast-network' | 'modern-browser';
+/**
+ * Configuration for conditional streaming
+ */
+interface StreamIfConfig<T = Response> {
+    /** The incoming request */
+    request: Request;
+    /** Condition to check (function or built-in) */
+    condition: StreamingCondition | BuiltInCondition;
+    /** Factory for streaming response */
+    stream: () => Promise<T> | T;
+    /** Factory for static response */
+    static: () => Promise<T> | T;
+    /** Optional: Custom bot patterns */
+    botPatterns?: RegExp[];
+    /** Optional: Force streaming via query param (for testing) */
+    forceStreamParam?: string;
+    /** Optional: Force static via query param (for testing) */
+    forceStaticParam?: string;
+}
+/**
+ * Result of condition evaluation
+ */
+interface StreamingDecision {
+    /** Whether streaming was used */
+    streaming: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** The response */
+    response: Response;
+}
+/**
+ * Default bot patterns for detection
+ */
+declare const DEFAULT_BOT_PATTERNS: RegExp[];
+/**
+ * Check if a request is from a bot/crawler
+ */
+declare function isBot(request: Request, customPatterns?: RegExp[]): boolean;
+/**
+ * Check if request explicitly asks for no streaming
+ */
+declare function prefersNoStream(request: Request): boolean;
+/**
+ * Check if a connection is likely slow (based on headers)
+ */
+declare function isSlowConnection(request: Request): boolean;
+/**
+ * Check if browser supports streaming well
+ */
+declare function supportsStreaming(request: Request): boolean;
+/**
+ * Conditionally use streaming or static rendering based on request context
+ */
+declare function streamIf<T = Response>(config: StreamIfConfig<T>): Promise<{
+    result: T;
+    streaming: boolean;
+    reason: string;
+}>;
+/**
+ * Create a middleware-style conditional streamer
+ */
+declare function createConditionalStreamer<T = Response>(defaultCondition: StreamingCondition | BuiltInCondition, options?: {
+    botPatterns?: RegExp[];
+    forceStreamParam?: string;
+    forceStaticParam?: string;
+}): (config: {
+    request: Request;
+    stream: () => Promise<T> | T;
+    static: () => Promise<T> | T;
+    condition?: StreamingCondition | BuiltInCondition;
+}) => Promise<{
+    result: T;
+    streaming: boolean;
+    reason: string;
+}>;
+/**
+ * Add streaming decision headers to response (for debugging)
+ */
+declare function addStreamingHeaders(response: Response, decision: {
+    streaming: boolean;
+    reason: string;
+}): Response;
+/**
+ * Create a streaming-aware Response with appropriate headers
+ */
+declare function createStreamingResponse(stream: ReadableStream<Uint8Array>, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+    isStreaming?: boolean;
+}): Response;
+/**
+ * Create a static HTML Response
+ */
+declare function createStaticResponse(html: string, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+
+export { type BuiltInCondition, DEFAULT_BOT_PATTERNS, type StreamIfConfig, type StreamingCondition, type StreamingDecision, addStreamingHeaders, createConditionalStreamer, createStaticResponse, createStreamingResponse, isBot, isSlowConnection, prefersNoStream, streamIf, supportsStreaming };

package/dist/streaming/conditional.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BOT_PATTERNS, addStreamingHeaders, createConditionalStreamer, createStaticResponse, createStreamingResponse, isBot, isSlowConnection, prefersNoStream, streamIf, supportsStreaming } from '../chunk-XOIYNY4I.js';
+//# sourceMappingURL=conditional.js.map
+//# sourceMappingURL=conditional.js.map

package/dist/streaming/conditional.js.map

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

package/dist/streaming/index.d.ts

@@ -61,6 +61,14 @@ interface SuspenseBoundaryConfig {
     fallback: string;
     /** Content resolver promise */
     contentPromise: Promise<string>;
+    /**
+     * IDs of boundaries that must resolve before this one.
+     * Enables dependency-aware streaming for complex data relationships.
+     * @example ['user'] - Wait for 'user' boundary before starting
+     */
+    dependsOn?: string[];
+    /** Custom metadata for observability */
+    meta?: Record<string, unknown>;
 }
 /**
  * Create a streaming SSR response using Web Streams API.

package/dist/streaming/index.js

@@ -1,3 +1,3 @@
-export { createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential } from '../chunk-ABNCAPQB.js';
+export { createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential } from '../chunk-6WSPUG5L.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map