@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.
Files changed (3) hide show
  1. package/dist/index.d.ts +243 -93
  2. package/dist/index.js +989 -272
  3. 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
- import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance } from '@jay-framework/compiler-jay-html';
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>): Promise<AnySlowlyRenderResult>;
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
- private dontCacheSlowly;
62
- constructor(dontCacheSlowly: boolean);
63
- runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
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
- declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>): Promise<AnyFastRenderResult>;
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<void>;
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
- * Cache for pre-rendered jay-html files.
800
+ * Filesystem-based cache for pre-rendered jay-html files.
664
801
  *
665
- * This cache stores jay-html content that has been transformed with slow-phase
666
- * data baked in. The key insight is that since slow ViewState is embedded directly
667
- * into the jay-html, we don't need to pass it to the client - only fast and
668
- * interactive ViewState is sent.
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
- * Pre-rendered files are written to disk so Vite can pick them up and compile them.
808
+ * On read, the script tag is extracted and stripped before returning content.
671
809
  */
672
810
  declare class SlowRenderCache {
673
- private cache;
674
- private pathToKeys;
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 in the cache.
688
- * Writes the pre-rendered content to disk and stores metadata in memory.
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<string>;
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
- * This is called when the source file changes.
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
- interface ContractIndexEntry {
736
- plugin: string;
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: Array<{
752
- name: string;
753
- type: 'static' | 'dynamic';
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
- index: ContractsIndex;
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<ContractsIndex>;
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 are guaranteed to be initialized (agent-kit already does this).
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, ActionRegistry, 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, loadPageParts, materializeContracts, onInit, onShutdown, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies };
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 };