@jay-framework/stack-server-runtime 0.12.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +243 -93
- package/dist/index.js +989 -272
- package/package.json +13 -12
package/dist/index.d.ts
CHANGED
|
@@ -2,11 +2,13 @@ import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlPa
|
|
|
2
2
|
import { JayComponentCore } from '@jay-framework/component';
|
|
3
3
|
import { ViteDevServer } from 'vite';
|
|
4
4
|
import { JayRoute } from '@jay-framework/stack-route-scanner';
|
|
5
|
-
import { WithValidations, PluginManifest } from '@jay-framework/compiler-shared';
|
|
6
|
-
|
|
5
|
+
import { WithValidations, JsonSchemaProperty, PluginManifest } from '@jay-framework/compiler-shared';
|
|
6
|
+
export { JsonSchemaProperty } from '@jay-framework/compiler-shared';
|
|
7
|
+
import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance, ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
|
|
8
|
+
export { ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
|
|
7
9
|
import { JayRollupConfig } from '@jay-framework/rollup-plugin';
|
|
8
|
-
import { TrackByMap } from '@jay-framework/view-state-merge';
|
|
9
10
|
import { Coordinate } from '@jay-framework/runtime';
|
|
11
|
+
import { TrackByMap } from '@jay-framework/view-state-merge';
|
|
10
12
|
|
|
11
13
|
interface DevServerPagePart {
|
|
12
14
|
compDefinition: AnyJayStackComponentDefinition;
|
|
@@ -43,6 +45,10 @@ interface LoadedPageParts {
|
|
|
43
45
|
headlessContracts: HeadlessContractInfo[];
|
|
44
46
|
/** Instance-only headless components (no key) for server-side phase orchestration */
|
|
45
47
|
headlessInstanceComponents: HeadlessInstanceComponent[];
|
|
48
|
+
/** Discovered <jay:xxx> instances from the jay-html (DL#109) */
|
|
49
|
+
discoveredInstances: DiscoveredHeadlessInstance[];
|
|
50
|
+
/** Discovered forEach <jay:xxx> instances from the jay-html (DL#109) */
|
|
51
|
+
forEachInstances: ForEachHeadlessInstance[];
|
|
46
52
|
}
|
|
47
53
|
interface LoadPagePartsOptions {
|
|
48
54
|
/**
|
|
@@ -51,21 +57,132 @@ interface LoadPagePartsOptions {
|
|
|
51
57
|
* Import resolution still uses the original jay-html's directory.
|
|
52
58
|
*/
|
|
53
59
|
preRenderedPath?: string;
|
|
60
|
+
/**
|
|
61
|
+
* Pre-loaded jay-html content to use instead of reading from disk.
|
|
62
|
+
* When provided (e.g., from SlowRenderCache with cache tag already stripped),
|
|
63
|
+
* this content is used directly, avoiding an extra file read.
|
|
64
|
+
*/
|
|
65
|
+
preRenderedContent?: string;
|
|
54
66
|
}
|
|
55
67
|
declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig, options?: LoadPagePartsOptions): Promise<WithValidations<LoadedPageParts>>;
|
|
56
68
|
|
|
57
69
|
interface SlowlyChangingPhase {
|
|
58
|
-
runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart
|
|
70
|
+
runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>, discoveredInstances?: DiscoveredHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], jayHtmlPath?: string): Promise<AnySlowlyRenderResult>;
|
|
59
71
|
}
|
|
60
72
|
declare class DevSlowlyChangingPhase implements SlowlyChangingPhase {
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart
|
|
73
|
+
/** Cached loadParams results per route (jayHtmlPath → array of UrlParams[] per part) */
|
|
74
|
+
private loadParamsCache;
|
|
75
|
+
runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>, discoveredInstances?: DiscoveredHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], jayHtmlPath?: string): Promise<AnySlowlyRenderResult>;
|
|
76
|
+
/**
|
|
77
|
+
* Invalidate the cached loadParams result for a given route.
|
|
78
|
+
* Called when source files change (page.ts, .jay-contract, .jay-html).
|
|
79
|
+
*/
|
|
80
|
+
invalidateLoadParamsCache(jayHtmlPath: string): void;
|
|
64
81
|
}
|
|
65
82
|
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>;
|
|
66
83
|
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;
|
|
67
84
|
|
|
68
|
-
|
|
85
|
+
/**
|
|
86
|
+
* Server-side slow render orchestration for headless component instances.
|
|
87
|
+
*
|
|
88
|
+
* Given discovered instances (from discoverHeadlessInstances) and their
|
|
89
|
+
* component definitions, runs slowlyRender for each instance and collects
|
|
90
|
+
* the results for downstream consumers (pre-render pipeline, direct mode, fast phase).
|
|
91
|
+
*/
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Data needed by the fast phase to render headless instances.
|
|
95
|
+
* Stored in carryForward.__instances so the fast phase can access it
|
|
96
|
+
* (both in pre-render and cached flows).
|
|
97
|
+
*/
|
|
98
|
+
interface InstancePhaseData {
|
|
99
|
+
/** Discovered instances with their props and coordinates */
|
|
100
|
+
discovered: Array<{
|
|
101
|
+
contractName: string;
|
|
102
|
+
props: Record<string, string>;
|
|
103
|
+
coordinate: Coordinate;
|
|
104
|
+
}>;
|
|
105
|
+
/** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
|
|
106
|
+
carryForwards: Record<string, object>;
|
|
107
|
+
/** ForEach instances that need fast-phase per-item rendering */
|
|
108
|
+
forEachInstances?: ForEachHeadlessInstance[];
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Result of running slowlyRender for all discovered headless instances.
|
|
112
|
+
*/
|
|
113
|
+
interface InstanceSlowRenderResult {
|
|
114
|
+
/** Resolved data for each instance (for resolveHeadlessInstances pass 2) */
|
|
115
|
+
resolvedData: Array<{
|
|
116
|
+
coordinate: Coordinate;
|
|
117
|
+
contract: Contract;
|
|
118
|
+
slowViewState: Record<string, unknown>;
|
|
119
|
+
}>;
|
|
120
|
+
/** Per-instance slow ViewState keyed by coordinate (for direct mode merge) */
|
|
121
|
+
slowViewStates: Record<string, object>;
|
|
122
|
+
/** Phase data for the fast render phase */
|
|
123
|
+
instancePhaseData: InstancePhaseData;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Run slowlyRender for each discovered headless instance.
|
|
127
|
+
*
|
|
128
|
+
* Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
|
|
129
|
+
*/
|
|
130
|
+
declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
|
|
131
|
+
/**
|
|
132
|
+
* Validate that forEach headless instances do not have a slow phase.
|
|
133
|
+
*
|
|
134
|
+
* Components with slowlyRender cannot be used inside forEach because
|
|
135
|
+
* forEach items are only known at request time, after slow rendering completes.
|
|
136
|
+
*
|
|
137
|
+
* @returns Array of validation error messages (empty if all valid)
|
|
138
|
+
*/
|
|
139
|
+
declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
|
|
140
|
+
|
|
141
|
+
declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>, instancePhaseData?: InstancePhaseData, forEachInstances?: ForEachHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], mergedSlowViewState?: object): Promise<AnyFastRenderResult>;
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Action metadata loaded from .jay-action files.
|
|
145
|
+
*
|
|
146
|
+
* Uses the compiler's parseAction to parse .jay-action YAML into JayType,
|
|
147
|
+
* then converts JayType → JSON Schema for consumers (AI agent tool builders).
|
|
148
|
+
*
|
|
149
|
+
* Actions without .jay-action files are not exposed to AI agents.
|
|
150
|
+
*/
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Input schema for an action (JSON Schema object type).
|
|
154
|
+
*/
|
|
155
|
+
interface ActionSchema {
|
|
156
|
+
type: 'object';
|
|
157
|
+
properties: Record<string, JsonSchemaProperty>;
|
|
158
|
+
required?: string[];
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* Metadata loaded from a .jay-action file.
|
|
162
|
+
*/
|
|
163
|
+
interface ActionMetadata {
|
|
164
|
+
/** Action name (must match the export name in plugin code) */
|
|
165
|
+
name: string;
|
|
166
|
+
/** Human-readable description of what the action does */
|
|
167
|
+
description: string;
|
|
168
|
+
/** JSON Schema for the action's input parameters */
|
|
169
|
+
inputSchema: ActionSchema;
|
|
170
|
+
/** JSON Schema for the action's output (optional) */
|
|
171
|
+
outputSchema?: JsonSchemaProperty;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Parses a .jay-action YAML string into ActionMetadata.
|
|
175
|
+
* Uses the compiler's parseAction to produce JayType, then converts to JSON Schema.
|
|
176
|
+
*/
|
|
177
|
+
declare function parseActionMetadata(yamlContent: string, fileName: string): ActionMetadata | null;
|
|
178
|
+
/**
|
|
179
|
+
* Loads action metadata from a .jay-action file on disk.
|
|
180
|
+
*/
|
|
181
|
+
declare function loadActionMetadata(filePath: string): ActionMetadata | null;
|
|
182
|
+
/**
|
|
183
|
+
* Resolves the absolute path of a .jay-action file relative to a plugin directory.
|
|
184
|
+
*/
|
|
185
|
+
declare function resolveActionMetadataPath(actionPath: string, pluginDir: string): string;
|
|
69
186
|
|
|
70
187
|
/**
|
|
71
188
|
* Action registry for Jay Stack server-side action handling.
|
|
@@ -88,6 +205,9 @@ interface RegisteredAction {
|
|
|
88
205
|
services: any[];
|
|
89
206
|
/** The handler function */
|
|
90
207
|
handler: (input: any, ...services: any[]) => Promise<any>;
|
|
208
|
+
/** Optional metadata from .jay-action file (description, input/output schemas).
|
|
209
|
+
* Actions with metadata are exposed to AI agents; those without are not. */
|
|
210
|
+
metadata?: ActionMetadata;
|
|
91
211
|
}
|
|
92
212
|
/**
|
|
93
213
|
* Result of executing an action.
|
|
@@ -153,6 +273,24 @@ declare class ActionRegistry {
|
|
|
153
273
|
* @returns Array of registered action names
|
|
154
274
|
*/
|
|
155
275
|
getNames(): string[];
|
|
276
|
+
/**
|
|
277
|
+
* Attaches metadata from a .jay-action file to a registered action.
|
|
278
|
+
* Called during action discovery when a plugin declares action metadata.
|
|
279
|
+
*
|
|
280
|
+
* @param actionName - The action name
|
|
281
|
+
* @param metadata - Parsed ActionMetadata from .jay-action file
|
|
282
|
+
*/
|
|
283
|
+
setMetadata(actionName: string, metadata: ActionMetadata): void;
|
|
284
|
+
/**
|
|
285
|
+
* Gets all registered actions that have .jay-action metadata.
|
|
286
|
+
* These are the actions that should be exposed to AI agents.
|
|
287
|
+
*
|
|
288
|
+
* @returns Array of { actionName, metadata } for actions with metadata
|
|
289
|
+
*/
|
|
290
|
+
getActionsWithMetadata(): Array<{
|
|
291
|
+
actionName: string;
|
|
292
|
+
metadata: ActionMetadata;
|
|
293
|
+
}>;
|
|
156
294
|
/**
|
|
157
295
|
* Clears all registered actions.
|
|
158
296
|
*/
|
|
@@ -346,6 +484,8 @@ interface PluginWithInit {
|
|
|
346
484
|
initExport: string;
|
|
347
485
|
/** Dependencies from package.json (for ordering) */
|
|
348
486
|
dependencies: string[];
|
|
487
|
+
/** When true, plugin is loaded on every page regardless of usage in jay-html */
|
|
488
|
+
global: boolean;
|
|
349
489
|
}
|
|
350
490
|
/**
|
|
351
491
|
* Options for plugin init discovery.
|
|
@@ -383,7 +523,7 @@ declare function sortPluginsByDependencies(plugins: PluginWithInit[]): PluginWit
|
|
|
383
523
|
* @param viteServer - Vite server for SSR module loading (optional)
|
|
384
524
|
* @param verbose - Whether to log progress
|
|
385
525
|
*/
|
|
386
|
-
declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<
|
|
526
|
+
declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<Map<string, Error>>;
|
|
387
527
|
/**
|
|
388
528
|
* Information needed to generate client init script for a plugin.
|
|
389
529
|
*/
|
|
@@ -428,8 +568,50 @@ interface GenerateClientScriptOptions {
|
|
|
428
568
|
*/
|
|
429
569
|
slowViewState?: object;
|
|
430
570
|
}
|
|
571
|
+
/**
|
|
572
|
+
* Shared fragments generated by buildScriptFragments().
|
|
573
|
+
* Used by both generateClientScript() and generateHydrationScript().
|
|
574
|
+
*/
|
|
575
|
+
interface ScriptFragments {
|
|
576
|
+
partImports: string;
|
|
577
|
+
compositeParts: string;
|
|
578
|
+
pluginClientInitImports: string;
|
|
579
|
+
projectInitImport: string;
|
|
580
|
+
clientInitExecution: string;
|
|
581
|
+
automationImport: string;
|
|
582
|
+
slowViewStateDecl: string;
|
|
583
|
+
}
|
|
584
|
+
/**
|
|
585
|
+
* Build the shared script fragments used by both client and hydration scripts.
|
|
586
|
+
*/
|
|
587
|
+
declare function buildScriptFragments(parts: DevServerPagePart[], clientInitData: Record<string, Record<string, any>>, projectInit: ProjectClientInitInfo | undefined, pluginInits: PluginClientInitInfo[], options: GenerateClientScriptOptions): ScriptFragments;
|
|
588
|
+
/**
|
|
589
|
+
* Generate the automation wrapping code.
|
|
590
|
+
* @param mode - 'client' appends to DOM; 'hydrate' skips appendChild (DOM already present)
|
|
591
|
+
*/
|
|
592
|
+
declare function buildAutomationWrap(options: GenerateClientScriptOptions, mode: 'client' | 'hydrate'): string;
|
|
431
593
|
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;
|
|
432
594
|
|
|
595
|
+
/**
|
|
596
|
+
* Invalidate the cached server element module for a jay-html file.
|
|
597
|
+
* Called when the source file changes (via file watcher).
|
|
598
|
+
*/
|
|
599
|
+
declare function invalidateServerElementCache(jayHtmlPath: string): void;
|
|
600
|
+
/**
|
|
601
|
+
* Invalidate all cached server element modules.
|
|
602
|
+
*/
|
|
603
|
+
declare function clearServerElementCache(): void;
|
|
604
|
+
/**
|
|
605
|
+
* Generate a complete SSR HTML page with server-rendered content and hydration script.
|
|
606
|
+
*
|
|
607
|
+
* Flow:
|
|
608
|
+
* 1. Load (or reuse cached) server element module
|
|
609
|
+
* 2. Execute renderToStream() to produce HTML
|
|
610
|
+
* 3. Build hydration script (uses ?jay-hydrate query for hydrate target)
|
|
611
|
+
* 4. Return full HTML page string
|
|
612
|
+
*/
|
|
613
|
+
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>;
|
|
614
|
+
|
|
433
615
|
/**
|
|
434
616
|
* Service registry for Jay Stack server-side dependency injection.
|
|
435
617
|
*
|
|
@@ -599,79 +781,35 @@ declare function getClientInitDataForKey(key: string): Record<string, any>;
|
|
|
599
781
|
*/
|
|
600
782
|
declare function clearClientInitData(): void;
|
|
601
783
|
|
|
602
|
-
/**
|
|
603
|
-
* Server-side slow render orchestration for headless component instances.
|
|
604
|
-
*
|
|
605
|
-
* Given discovered instances (from discoverHeadlessInstances) and their
|
|
606
|
-
* component definitions, runs slowlyRender for each instance and collects
|
|
607
|
-
* the results for downstream consumers (pre-render pipeline, direct mode, fast phase).
|
|
608
|
-
*/
|
|
609
|
-
|
|
610
|
-
/**
|
|
611
|
-
* Data needed by the fast phase to render headless instances.
|
|
612
|
-
* Stored in carryForward.__instances so the fast phase can access it
|
|
613
|
-
* (both in pre-render and cached flows).
|
|
614
|
-
*/
|
|
615
|
-
interface InstancePhaseData {
|
|
616
|
-
/** Discovered instances with their props and coordinates */
|
|
617
|
-
discovered: Array<{
|
|
618
|
-
contractName: string;
|
|
619
|
-
props: Record<string, string>;
|
|
620
|
-
coordinate: Coordinate;
|
|
621
|
-
}>;
|
|
622
|
-
/** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
|
|
623
|
-
carryForwards: Record<string, object>;
|
|
624
|
-
}
|
|
625
|
-
/**
|
|
626
|
-
* Result of running slowlyRender for all discovered headless instances.
|
|
627
|
-
*/
|
|
628
|
-
interface InstanceSlowRenderResult {
|
|
629
|
-
/** Resolved data for each instance (for resolveHeadlessInstances pass 2) */
|
|
630
|
-
resolvedData: Array<{
|
|
631
|
-
coordinate: Coordinate;
|
|
632
|
-
contract: Contract;
|
|
633
|
-
slowViewState: Record<string, unknown>;
|
|
634
|
-
}>;
|
|
635
|
-
/** Per-instance slow ViewState keyed by coordinate (for direct mode merge) */
|
|
636
|
-
slowViewStates: Record<string, object>;
|
|
637
|
-
/** Phase data for the fast render phase */
|
|
638
|
-
instancePhaseData: InstancePhaseData;
|
|
639
|
-
}
|
|
640
|
-
/**
|
|
641
|
-
* Run slowlyRender for each discovered headless instance.
|
|
642
|
-
*
|
|
643
|
-
* Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
|
|
644
|
-
*/
|
|
645
|
-
declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
|
|
646
|
-
|
|
647
784
|
/**
|
|
648
785
|
* Cache entry for pre-rendered jay-html
|
|
649
786
|
*/
|
|
650
787
|
interface SlowRenderCacheEntry {
|
|
651
788
|
/** Path to the pre-rendered jay-html file on disk */
|
|
652
789
|
preRenderedPath: string;
|
|
790
|
+
/** Pre-rendered jay-html content with cache metadata tag stripped */
|
|
791
|
+
preRenderedContent: string;
|
|
653
792
|
/** Slow ViewState that was baked into the jay-html */
|
|
654
793
|
slowViewState: object;
|
|
655
794
|
/** CarryForward data from slow rendering (passed to fast phase) */
|
|
656
795
|
carryForward: object;
|
|
657
|
-
/** Timestamp when this entry was created */
|
|
658
|
-
createdAt: number;
|
|
659
796
|
/** Source jay-html path (for debugging) */
|
|
660
797
|
sourcePath: string;
|
|
661
798
|
}
|
|
662
799
|
/**
|
|
663
|
-
*
|
|
800
|
+
* Filesystem-based cache for pre-rendered jay-html files.
|
|
664
801
|
*
|
|
665
|
-
*
|
|
666
|
-
*
|
|
667
|
-
*
|
|
668
|
-
*
|
|
802
|
+
* Cache metadata (slowViewState, carryForward) is embedded in the pre-rendered
|
|
803
|
+
* file as a `<script type="application/jay-cache">` tag. This means:
|
|
804
|
+
* - Cache survives dev server restart
|
|
805
|
+
* - The filesystem is the single source of truth
|
|
806
|
+
* - No in-memory map needed for cache entries
|
|
669
807
|
*
|
|
670
|
-
*
|
|
808
|
+
* On read, the script tag is extracted and stripped before returning content.
|
|
671
809
|
*/
|
|
672
810
|
declare class SlowRenderCache {
|
|
673
|
-
|
|
674
|
-
private
|
|
811
|
+
/** Maps source jay-html path → set of pre-rendered file paths (for invalidation) */
|
|
812
|
+
private pathToFiles;
|
|
675
813
|
private readonly cacheDir;
|
|
676
814
|
private readonly pagesRoot;
|
|
677
815
|
/**
|
|
@@ -680,22 +818,23 @@ declare class SlowRenderCache {
|
|
|
680
818
|
*/
|
|
681
819
|
constructor(cacheDir: string, pagesRoot: string);
|
|
682
820
|
/**
|
|
683
|
-
* Get a cached pre-rendered jay-html entry
|
|
821
|
+
* Get a cached pre-rendered jay-html entry by reading from disk.
|
|
822
|
+
* Returns undefined if the cache file doesn't exist or has no metadata tag.
|
|
684
823
|
*/
|
|
685
|
-
get(jayHtmlPath: string, params: Record<string, string>): SlowRenderCacheEntry | undefined
|
|
824
|
+
get(jayHtmlPath: string, params: Record<string, string>): Promise<SlowRenderCacheEntry | undefined>;
|
|
686
825
|
/**
|
|
687
|
-
* Store a pre-rendered jay-html entry
|
|
688
|
-
*
|
|
826
|
+
* Store a pre-rendered jay-html entry.
|
|
827
|
+
* Embeds metadata as a <script> tag and writes to disk.
|
|
828
|
+
* Returns the full cache entry with stripped content.
|
|
689
829
|
*/
|
|
690
|
-
set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<
|
|
830
|
+
set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<SlowRenderCacheEntry>;
|
|
691
831
|
/**
|
|
692
832
|
* Check if a pre-rendered entry exists for the given path and params
|
|
693
833
|
*/
|
|
694
|
-
has(jayHtmlPath: string, params: Record<string, string>): boolean
|
|
834
|
+
has(jayHtmlPath: string, params: Record<string, string>): Promise<boolean>;
|
|
695
835
|
/**
|
|
696
836
|
* Invalidate all cached entries for a given jay-html source path.
|
|
697
|
-
*
|
|
698
|
-
* Also deletes the cached files from disk.
|
|
837
|
+
* Deletes cached files from disk.
|
|
699
838
|
*/
|
|
700
839
|
invalidate(jayHtmlPath: string): Promise<void>;
|
|
701
840
|
/**
|
|
@@ -713,14 +852,23 @@ declare class SlowRenderCache {
|
|
|
713
852
|
* Clear all cached entries and delete cached files from disk
|
|
714
853
|
*/
|
|
715
854
|
clear(): Promise<void>;
|
|
716
|
-
/**
|
|
717
|
-
* Get the number of cached entries
|
|
718
|
-
*/
|
|
719
|
-
get size(): number;
|
|
720
855
|
/**
|
|
721
856
|
* Get all cached jay-html paths (for debugging/monitoring)
|
|
722
857
|
*/
|
|
723
858
|
getCachedPaths(): string[];
|
|
859
|
+
/**
|
|
860
|
+
* Compute the cache file path for a given jay-html path and params.
|
|
861
|
+
*/
|
|
862
|
+
private computeCachePath;
|
|
863
|
+
/**
|
|
864
|
+
* Track a pre-rendered file path for invalidation.
|
|
865
|
+
*/
|
|
866
|
+
private trackFile;
|
|
867
|
+
/**
|
|
868
|
+
* Scan the cache directory for files matching a route and delete them.
|
|
869
|
+
* Handles the startup case where pathToFiles is not populated from a previous session.
|
|
870
|
+
*/
|
|
871
|
+
private scanAndDeleteCacheFiles;
|
|
724
872
|
}
|
|
725
873
|
|
|
726
874
|
/**
|
|
@@ -732,30 +880,29 @@ declare class SlowRenderCache {
|
|
|
732
880
|
* @see Design Log #80 - Materializing Dynamic Contracts for Agentic Page Generation
|
|
733
881
|
*/
|
|
734
882
|
|
|
735
|
-
|
|
736
|
-
|
|
883
|
+
/** Action metadata entry in plugins-index.yaml */
|
|
884
|
+
interface ActionIndexEntry {
|
|
885
|
+
name: string;
|
|
886
|
+
description: string;
|
|
887
|
+
/** Path to the .jay-action file (relative to project root) */
|
|
888
|
+
path: string;
|
|
889
|
+
}
|
|
890
|
+
/** Contract entry within a plugin in plugins-index.yaml */
|
|
891
|
+
interface PluginContractEntry {
|
|
737
892
|
name: string;
|
|
738
893
|
type: 'static' | 'dynamic';
|
|
739
894
|
path: string;
|
|
740
895
|
metadata?: Record<string, unknown>;
|
|
741
896
|
}
|
|
742
|
-
interface ContractsIndex {
|
|
743
|
-
materialized_at: string;
|
|
744
|
-
jay_stack_version: string;
|
|
745
|
-
contracts: ContractIndexEntry[];
|
|
746
|
-
}
|
|
747
897
|
/** Entry for plugins-index.yaml (Design Log #85) */
|
|
748
898
|
interface PluginsIndexEntry {
|
|
749
899
|
name: string;
|
|
750
900
|
path: string;
|
|
751
|
-
contracts:
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
path: string;
|
|
755
|
-
}>;
|
|
901
|
+
contracts: PluginContractEntry[];
|
|
902
|
+
/** Actions with .jay-action metadata (exposed to AI agents) */
|
|
903
|
+
actions?: ActionIndexEntry[];
|
|
756
904
|
}
|
|
757
905
|
interface PluginsIndex {
|
|
758
|
-
materialized_at: string;
|
|
759
906
|
jay_stack_version: string;
|
|
760
907
|
plugins: PluginsIndexEntry[];
|
|
761
908
|
}
|
|
@@ -770,7 +917,7 @@ interface MaterializeContractsOptions {
|
|
|
770
917
|
viteServer?: ViteSSRLoader;
|
|
771
918
|
}
|
|
772
919
|
interface MaterializeResult {
|
|
773
|
-
|
|
920
|
+
pluginsIndex: PluginsIndex;
|
|
774
921
|
staticCount: number;
|
|
775
922
|
dynamicCount: number;
|
|
776
923
|
outputDir: string;
|
|
@@ -785,7 +932,7 @@ declare function materializeContracts(options: MaterializeContractsOptions, serv
|
|
|
785
932
|
/**
|
|
786
933
|
* Lists contracts without writing files (for --list mode)
|
|
787
934
|
*/
|
|
788
|
-
declare function listContracts(options: MaterializeContractsOptions): Promise<
|
|
935
|
+
declare function listContracts(options: MaterializeContractsOptions): Promise<PluginsIndex>;
|
|
789
936
|
|
|
790
937
|
/**
|
|
791
938
|
* Plugin Scanner
|
|
@@ -887,7 +1034,7 @@ interface PluginSetupResult {
|
|
|
887
1034
|
type PluginSetupHandler = (context: PluginSetupContext) => Promise<PluginSetupResult>;
|
|
888
1035
|
/**
|
|
889
1036
|
* Context passed to a plugin's references handler.
|
|
890
|
-
* Services
|
|
1037
|
+
* Services may or may not be initialized — check initError if your handler needs them.
|
|
891
1038
|
*/
|
|
892
1039
|
interface PluginReferencesContext {
|
|
893
1040
|
/** Plugin name (from plugin.yaml) */
|
|
@@ -898,6 +1045,8 @@ interface PluginReferencesContext {
|
|
|
898
1045
|
referencesDir: string;
|
|
899
1046
|
/** Registered services */
|
|
900
1047
|
services: Map<symbol, unknown>;
|
|
1048
|
+
/** Present if this plugin's server init failed */
|
|
1049
|
+
initError?: Error;
|
|
901
1050
|
/** Whether --force flag was passed */
|
|
902
1051
|
force: boolean;
|
|
903
1052
|
}
|
|
@@ -981,8 +1130,9 @@ declare function executePluginSetup(plugin: PluginWithSetup, options: {
|
|
|
981
1130
|
declare function executePluginReferences(plugin: PluginWithReferences, options: {
|
|
982
1131
|
projectRoot: string;
|
|
983
1132
|
force: boolean;
|
|
1133
|
+
initError?: Error;
|
|
984
1134
|
viteServer?: ViteSSRLoader;
|
|
985
1135
|
verbose?: boolean;
|
|
986
1136
|
}): Promise<PluginReferencesResult>;
|
|
987
1137
|
|
|
988
|
-
export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult,
|
|
1138
|
+
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 };
|