@jay-framework/stack-server-runtime 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -4,11 +4,11 @@ import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
 import { WithValidations, JsonSchemaProperty, PluginManifest } from '@jay-framework/compiler-shared';
 export { JsonSchemaProperty } from '@jay-framework/compiler-shared';
-import { Contract, HeadlessContractInfo, ForEachHeadlessInstance, DiscoveredHeadlessInstance } from '@jay-framework/compiler-jay-html';
+import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance, ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
 export { ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
-import { TrackByMap } from '@jay-framework/view-state-merge';
 import { Coordinate } from '@jay-framework/runtime';
+import { TrackByMap } from '@jay-framework/view-state-merge';
 
 interface DevServerPagePart {
     compDefinition: AnyJayStackComponentDefinition;
@@ -45,6 +45,10 @@ interface LoadedPageParts {
     headlessContracts: HeadlessContractInfo[];
     /** Instance-only headless components (no key) for server-side phase orchestration */
     headlessInstanceComponents: HeadlessInstanceComponent[];
+    /** Discovered <jay:xxx> instances from the jay-html (DL#109) */
+    discoveredInstances: DiscoveredHeadlessInstance[];
+    /** Discovered forEach <jay:xxx> instances from the jay-html (DL#109) */
+    forEachInstances: ForEachHeadlessInstance[];
 }
 interface LoadPagePartsOptions {
     /**
@@ -53,21 +57,88 @@ interface LoadPagePartsOptions {
      * Import resolution still uses the original jay-html's directory.
      */
     preRenderedPath?: string;
+    /**
+     * Pre-loaded jay-html content to use instead of reading from disk.
+     * When provided (e.g., from SlowRenderCache with cache tag already stripped),
+     * this content is used directly, avoiding an extra file read.
+     */
+    preRenderedContent?: string;
 }
 declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig, options?: LoadPagePartsOptions): Promise<WithValidations<LoadedPageParts>>;
 
 interface SlowlyChangingPhase {
-    runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
+    runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>, discoveredInstances?: DiscoveredHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], jayHtmlPath?: string): Promise<AnySlowlyRenderResult>;
 }
 declare class DevSlowlyChangingPhase implements SlowlyChangingPhase {
-    private dontCacheSlowly;
-    constructor(dontCacheSlowly: boolean);
-    runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
+    /** Cached loadParams results per route (jayHtmlPath → array of UrlParams[] per part) */
+    private loadParamsCache;
+    runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>, discoveredInstances?: DiscoveredHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], jayHtmlPath?: string): Promise<AnySlowlyRenderResult>;
+    /**
+     * Invalidate the cached loadParams result for a given route.
+     * Called when source files change (page.ts, .jay-contract, .jay-html).
+     */
+    invalidateLoadParamsCache(jayHtmlPath: string): void;
 }
 declare function runLoadParams<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>, services: Services): Promise<void>;
 declare function runSlowlyChangingRender<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>): void;
 
-declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>): Promise<AnyFastRenderResult>;
+/**
+ * Server-side slow render orchestration for headless component instances.
+ *
+ * Given discovered instances (from discoverHeadlessInstances) and their
+ * component definitions, runs slowlyRender for each instance and collects
+ * the results for downstream consumers (pre-render pipeline, direct mode, fast phase).
+ */
+
+/**
+ * Data needed by the fast phase to render headless instances.
+ * Stored in carryForward.__instances so the fast phase can access it
+ * (both in pre-render and cached flows).
+ */
+interface InstancePhaseData {
+    /** Discovered instances with their props and coordinates */
+    discovered: Array<{
+        contractName: string;
+        props: Record<string, string>;
+        coordinate: Coordinate;
+    }>;
+    /** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
+    carryForwards: Record<string, object>;
+    /** ForEach instances that need fast-phase per-item rendering */
+    forEachInstances?: ForEachHeadlessInstance[];
+}
+/**
+ * Result of running slowlyRender for all discovered headless instances.
+ */
+interface InstanceSlowRenderResult {
+    /** Resolved data for each instance (for resolveHeadlessInstances pass 2) */
+    resolvedData: Array<{
+        coordinate: Coordinate;
+        contract: Contract;
+        slowViewState: Record<string, unknown>;
+    }>;
+    /** Per-instance slow ViewState keyed by coordinate (for direct mode merge) */
+    slowViewStates: Record<string, object>;
+    /** Phase data for the fast render phase */
+    instancePhaseData: InstancePhaseData;
+}
+/**
+ * Run slowlyRender for each discovered headless instance.
+ *
+ * Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
+ */
+declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
+/**
+ * Validate that forEach headless instances do not have a slow phase.
+ *
+ * Components with slowlyRender cannot be used inside forEach because
+ * forEach items are only known at request time, after slow rendering completes.
+ *
+ * @returns Array of validation error messages (empty if all valid)
+ */
+declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
+
+declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>, instancePhaseData?: InstancePhaseData, forEachInstances?: ForEachHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], mergedSlowViewState?: object): Promise<AnyFastRenderResult>;
 
 /**
  * Action metadata loaded from .jay-action files.
@@ -497,8 +568,50 @@ interface GenerateClientScriptOptions {
      */
     slowViewState?: object;
 }
+/**
+ * Shared fragments generated by buildScriptFragments().
+ * Used by both generateClientScript() and generateHydrationScript().
+ */
+interface ScriptFragments {
+    partImports: string;
+    compositeParts: string;
+    pluginClientInitImports: string;
+    projectInitImport: string;
+    clientInitExecution: string;
+    automationImport: string;
+    slowViewStateDecl: string;
+}
+/**
+ * Build the shared script fragments used by both client and hydration scripts.
+ */
+declare function buildScriptFragments(parts: DevServerPagePart[], clientInitData: Record<string, Record<string, any>>, projectInit: ProjectClientInitInfo | undefined, pluginInits: PluginClientInitInfo[], options: GenerateClientScriptOptions): ScriptFragments;
+/**
+ * Generate the automation wrapping code.
+ * @param mode - 'client' appends to DOM; 'hydrate' skips appendChild (DOM already present)
+ */
+declare function buildAutomationWrap(options: GenerateClientScriptOptions, mode: 'client' | 'hydrate'): string;
 declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string, trackByMap?: TrackByMap, clientInitData?: Record<string, Record<string, any>>, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions): string;
 
+/**
+ * Invalidate the cached server element module for a jay-html file.
+ * Called when the source file changes (via file watcher).
+ */
+declare function invalidateServerElementCache(jayHtmlPath: string): void;
+/**
+ * Invalidate all cached server element modules.
+ */
+declare function clearServerElementCache(): void;
+/**
+ * Generate a complete SSR HTML page with server-rendered content and hydration script.
+ *
+ * Flow:
+ * 1. Load (or reuse cached) server element module
+ * 2. Execute renderToStream() to produce HTML
+ * 3. Build hydration script (uses ?jay-hydrate query for hydrate target)
+ * 4. Return full HTML page string
+ */
+declare function generateSSRPageHtml(vite: ViteDevServer, jayHtmlContent: string, jayHtmlFilename: string, jayHtmlDir: string, viewState: object, jayHtmlImportPath: string, parts: DevServerPagePart[], carryForward: object, trackByMap: TrackByMap, clientInitData: Record<string, Record<string, any>>, buildFolder: string, projectRoot: string, routeDir: string, tsConfigFilePath?: string, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions): Promise<string>;
+
 /**
  * Service registry for Jay Stack server-side dependency injection.
  *
@@ -668,90 +781,35 @@ declare function getClientInitDataForKey(key: string): Record<string, any>;
  */
 declare function clearClientInitData(): void;
 
-/**
- * Server-side slow render orchestration for headless component instances.
- *
- * Given discovered instances (from discoverHeadlessInstances) and their
- * component definitions, runs slowlyRender for each instance and collects
- * the results for downstream consumers (pre-render pipeline, direct mode, fast phase).
- */
-
-/**
- * Data needed by the fast phase to render headless instances.
- * Stored in carryForward.__instances so the fast phase can access it
- * (both in pre-render and cached flows).
- */
-interface InstancePhaseData {
-    /** Discovered instances with their props and coordinates */
-    discovered: Array<{
-        contractName: string;
-        props: Record<string, string>;
-        coordinate: Coordinate;
-    }>;
-    /** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
-    carryForwards: Record<string, object>;
-    /** ForEach instances that need fast-phase per-item rendering */
-    forEachInstances?: ForEachHeadlessInstance[];
-}
-/**
- * Result of running slowlyRender for all discovered headless instances.
- */
-interface InstanceSlowRenderResult {
-    /** Resolved data for each instance (for resolveHeadlessInstances pass 2) */
-    resolvedData: Array<{
-        coordinate: Coordinate;
-        contract: Contract;
-        slowViewState: Record<string, unknown>;
-    }>;
-    /** Per-instance slow ViewState keyed by coordinate (for direct mode merge) */
-    slowViewStates: Record<string, object>;
-    /** Phase data for the fast render phase */
-    instancePhaseData: InstancePhaseData;
-}
-/**
- * Run slowlyRender for each discovered headless instance.
- *
- * Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
- */
-declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
-/**
- * Validate that forEach headless instances do not have a slow phase.
- *
- * Components with slowlyRender cannot be used inside forEach because
- * forEach items are only known at request time, after slow rendering completes.
- *
- * @returns Array of validation error messages (empty if all valid)
- */
-declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
-
 /**
  * Cache entry for pre-rendered jay-html
  */
 interface SlowRenderCacheEntry {
     /** Path to the pre-rendered jay-html file on disk */
     preRenderedPath: string;
+    /** Pre-rendered jay-html content with cache metadata tag stripped */
+    preRenderedContent: string;
     /** Slow ViewState that was baked into the jay-html */
     slowViewState: object;
     /** CarryForward data from slow rendering (passed to fast phase) */
     carryForward: object;
-    /** Timestamp when this entry was created */
-    createdAt: number;
     /** Source jay-html path (for debugging) */
     sourcePath: string;
 }
 /**
- * Cache for pre-rendered jay-html files.
+ * Filesystem-based cache for pre-rendered jay-html files.
  *
- * This cache stores jay-html content that has been transformed with slow-phase
- * data baked in. The key insight is that since slow ViewState is embedded directly
- * into the jay-html, we don't need to pass it to the client - only fast and
- * interactive ViewState is sent.
+ * Cache metadata (slowViewState, carryForward) is embedded in the pre-rendered
+ * file as a `<script type="application/jay-cache">` tag. This means:
+ * - Cache survives dev server restart
+ * - The filesystem is the single source of truth
+ * - No in-memory map needed for cache entries
  *
- * Pre-rendered files are written to disk so Vite can pick them up and compile them.
+ * On read, the script tag is extracted and stripped before returning content.
  */
 declare class SlowRenderCache {
-    private cache;
-    private pathToKeys;
+    /** Maps source jay-html path → set of pre-rendered file paths (for invalidation) */
+    private pathToFiles;
     private readonly cacheDir;
     private readonly pagesRoot;
     /**
@@ -760,22 +818,23 @@ declare class SlowRenderCache {
      */
     constructor(cacheDir: string, pagesRoot: string);
     /**
-     * Get a cached pre-rendered jay-html entry
+     * Get a cached pre-rendered jay-html entry by reading from disk.
+     * Returns undefined if the cache file doesn't exist or has no metadata tag.
      */
-    get(jayHtmlPath: string, params: Record<string, string>): SlowRenderCacheEntry | undefined;
+    get(jayHtmlPath: string, params: Record<string, string>): Promise<SlowRenderCacheEntry | undefined>;
     /**
-     * Store a pre-rendered jay-html entry in the cache.
-     * Writes the pre-rendered content to disk and stores metadata in memory.
+     * Store a pre-rendered jay-html entry.
+     * Embeds metadata as a <script> tag and writes to disk.
+     * Returns the full cache entry with stripped content.
      */
-    set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<string>;
+    set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<SlowRenderCacheEntry>;
     /**
      * Check if a pre-rendered entry exists for the given path and params
      */
-    has(jayHtmlPath: string, params: Record<string, string>): boolean;
+    has(jayHtmlPath: string, params: Record<string, string>): Promise<boolean>;
     /**
      * Invalidate all cached entries for a given jay-html source path.
-     * This is called when the source file changes.
-     * Also deletes the cached files from disk.
+     * Deletes cached files from disk.
      */
     invalidate(jayHtmlPath: string): Promise<void>;
     /**
@@ -793,14 +852,23 @@ declare class SlowRenderCache {
      * Clear all cached entries and delete cached files from disk
      */
     clear(): Promise<void>;
-    /**
-     * Get the number of cached entries
-     */
-    get size(): number;
     /**
      * Get all cached jay-html paths (for debugging/monitoring)
      */
     getCachedPaths(): string[];
+    /**
+     * Compute the cache file path for a given jay-html path and params.
+     */
+    private computeCachePath;
+    /**
+     * Track a pre-rendered file path for invalidation.
+     */
+    private trackFile;
+    /**
+     * Scan the cache directory for files matching a route and delete them.
+     * Handles the startup case where pathToFiles is not populated from a previous session.
+     */
+    private scanAndDeleteCacheFiles;
 }
 
 /**
@@ -812,18 +880,6 @@ declare class SlowRenderCache {
  * @see Design Log #80 - Materializing Dynamic Contracts for Agentic Page Generation
  */
 
-interface ContractIndexEntry {
-    plugin: string;
-    name: string;
-    type: 'static' | 'dynamic';
-    path: string;
-    metadata?: Record<string, unknown>;
-}
-interface ContractsIndex {
-    materialized_at: string;
-    jay_stack_version: string;
-    contracts: ContractIndexEntry[];
-}
 /** Action metadata entry in plugins-index.yaml */
 interface ActionIndexEntry {
     name: string;
@@ -831,20 +887,22 @@ interface ActionIndexEntry {
     /** Path to the .jay-action file (relative to project root) */
     path: string;
 }
+/** Contract entry within a plugin in plugins-index.yaml */
+interface PluginContractEntry {
+    name: string;
+    type: 'static' | 'dynamic';
+    path: string;
+    metadata?: Record<string, unknown>;
+}
 /** Entry for plugins-index.yaml (Design Log #85) */
 interface PluginsIndexEntry {
     name: string;
     path: string;
-    contracts: Array<{
-        name: string;
-        type: 'static' | 'dynamic';
-        path: string;
-    }>;
+    contracts: PluginContractEntry[];
     /** Actions with .jay-action metadata (exposed to AI agents) */
     actions?: ActionIndexEntry[];
 }
 interface PluginsIndex {
-    materialized_at: string;
     jay_stack_version: string;
     plugins: PluginsIndexEntry[];
 }
@@ -859,7 +917,7 @@ interface MaterializeContractsOptions {
     viteServer?: ViteSSRLoader;
 }
 interface MaterializeResult {
-    index: ContractsIndex;
+    pluginsIndex: PluginsIndex;
     staticCount: number;
     dynamicCount: number;
     outputDir: string;
@@ -874,7 +932,7 @@ declare function materializeContracts(options: MaterializeContractsOptions, serv
 /**
  * Lists contracts without writing files (for --list mode)
  */
-declare function listContracts(options: MaterializeContractsOptions): Promise<ContractsIndex>;
+declare function listContracts(options: MaterializeContractsOptions): Promise<PluginsIndex>;
 
 /**
  * Plugin Scanner
@@ -1077,4 +1135,4 @@ declare function executePluginReferences(plugin: PluginWithReferences, options:
     verbose?: boolean;
 }): Promise<PluginReferencesResult>;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContractIndexEntry, type ContractsIndex, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, listContracts, loadActionMetadata, loadPageParts, materializeContracts, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies, validateForEachInstances };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginContractEntry, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, type ScriptFragments, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, buildAutomationWrap, buildScriptFragments, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServerElementCache, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, generateSSRPageHtml, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies, validateForEachInstances };