heliumts 0.10.2 → 0.11.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 (156) hide show
  1. package/README.md +45 -46
  2. package/dist/bin/helium.js +117 -172
  3. package/dist/bin/helium.js.map +1 -1
  4. package/dist/bin/projectCommands.d.ts +59 -0
  5. package/dist/bin/projectCommands.d.ts.map +1 -0
  6. package/dist/bin/projectCommands.js +103 -0
  7. package/dist/bin/projectCommands.js.map +1 -0
  8. package/dist/bin/publicApi.d.ts +30 -0
  9. package/dist/bin/publicApi.d.ts.map +1 -0
  10. package/dist/bin/publicApi.js +155 -0
  11. package/dist/bin/publicApi.js.map +1 -0
  12. package/dist/client/Router.d.ts.map +1 -1
  13. package/dist/client/Router.js +5 -1
  14. package/dist/client/Router.js.map +1 -1
  15. package/dist/client/callMethod.d.ts +2 -2
  16. package/dist/client/callMethod.d.ts.map +1 -1
  17. package/dist/client/callMethod.js +3 -2
  18. package/dist/client/callMethod.js.map +1 -1
  19. package/dist/client/index.d.ts +3 -1
  20. package/dist/client/index.d.ts.map +1 -1
  21. package/dist/client/index.js +1 -2
  22. package/dist/client/index.js.map +1 -1
  23. package/dist/client/pageModules.d.ts +18 -0
  24. package/dist/client/pageModules.d.ts.map +1 -0
  25. package/dist/client/pageModules.js +3 -0
  26. package/dist/client/pageModules.js.map +1 -0
  27. package/dist/client/routerManifest.d.ts +2 -11
  28. package/dist/client/routerManifest.d.ts.map +1 -1
  29. package/dist/client/routerManifest.js +15 -187
  30. package/dist/client/routerManifest.js.map +1 -1
  31. package/dist/client/types.d.ts +12 -12
  32. package/dist/client/types.d.ts.map +1 -1
  33. package/dist/client/types.js +8 -1
  34. package/dist/client/types.js.map +1 -1
  35. package/dist/client/useCall.d.ts +20 -9
  36. package/dist/client/useCall.d.ts.map +1 -1
  37. package/dist/client/useCall.js +21 -6
  38. package/dist/client/useCall.js.map +1 -1
  39. package/dist/client/useFetch.d.ts +3 -3
  40. package/dist/client/useFetch.d.ts.map +1 -1
  41. package/dist/client/useFetch.js +8 -5
  42. package/dist/client/useFetch.js.map +1 -1
  43. package/dist/client/useStreaming.d.ts +3 -3
  44. package/dist/client/useStreaming.d.ts.map +1 -1
  45. package/dist/client/useStreaming.js +9 -7
  46. package/dist/client/useStreaming.js.map +1 -1
  47. package/dist/internal/index.d.ts +4 -0
  48. package/dist/internal/index.d.ts.map +1 -0
  49. package/dist/internal/index.js +4 -0
  50. package/dist/internal/index.js.map +1 -0
  51. package/dist/runtime/pageRoutes.d.ts +11 -0
  52. package/dist/runtime/pageRoutes.d.ts.map +1 -0
  53. package/dist/runtime/pageRoutes.js +50 -0
  54. package/dist/runtime/pageRoutes.js.map +1 -0
  55. package/dist/server/defineMethod.d.ts +16 -2
  56. package/dist/server/defineMethod.d.ts.map +1 -1
  57. package/dist/server/defineMethod.js +27 -3
  58. package/dist/server/defineMethod.js.map +1 -1
  59. package/dist/server/defineWorker.d.ts.map +1 -1
  60. package/dist/server/defineWorker.js +4 -6
  61. package/dist/server/defineWorker.js.map +1 -1
  62. package/dist/server/devServer.d.ts +2 -1
  63. package/dist/server/devServer.d.ts.map +1 -1
  64. package/dist/server/devServer.js +6 -9
  65. package/dist/server/devServer.js.map +1 -1
  66. package/dist/server/index.d.ts +16 -9
  67. package/dist/server/index.d.ts.map +1 -1
  68. package/dist/server/index.js +9 -12
  69. package/dist/server/index.js.map +1 -1
  70. package/dist/server/prodServer.d.ts +2 -0
  71. package/dist/server/prodServer.d.ts.map +1 -1
  72. package/dist/server/prodServer.js +7 -5
  73. package/dist/server/prodServer.js.map +1 -1
  74. package/dist/server/ssr.d.ts +4 -1
  75. package/dist/server/ssr.d.ts.map +1 -1
  76. package/dist/server/ssr.js +27 -61
  77. package/dist/server/ssr.js.map +1 -1
  78. package/dist/vite/heliumPlugin.d.ts +0 -14
  79. package/dist/vite/heliumPlugin.d.ts.map +1 -1
  80. package/dist/vite/heliumPlugin.js +68 -294
  81. package/dist/vite/heliumPlugin.js.map +1 -1
  82. package/dist/vite/paths.d.ts +0 -2
  83. package/dist/vite/paths.d.ts.map +1 -1
  84. package/dist/vite/paths.js +0 -2
  85. package/dist/vite/paths.js.map +1 -1
  86. package/dist/vite/rpcDiscovery.d.ts +10 -0
  87. package/dist/vite/rpcDiscovery.d.ts.map +1 -0
  88. package/dist/vite/rpcDiscovery.js +237 -0
  89. package/dist/vite/rpcDiscovery.js.map +1 -0
  90. package/dist/vite/rpcModule.d.ts +4 -0
  91. package/dist/vite/rpcModule.d.ts.map +1 -0
  92. package/dist/vite/rpcModule.js +64 -0
  93. package/dist/vite/rpcModule.js.map +1 -0
  94. package/dist/vite/scanner.d.ts +14 -4
  95. package/dist/vite/scanner.d.ts.map +1 -1
  96. package/dist/vite/scanner.js +130 -236
  97. package/dist/vite/scanner.js.map +1 -1
  98. package/dist/vite/serverClientAdapter.d.ts +103 -0
  99. package/dist/vite/serverClientAdapter.d.ts.map +1 -0
  100. package/dist/vite/serverClientAdapter.js +139 -0
  101. package/dist/vite/serverClientAdapter.js.map +1 -0
  102. package/dist/vite/ssg.d.ts +5 -8
  103. package/dist/vite/ssg.d.ts.map +1 -1
  104. package/dist/vite/ssg.js +32 -263
  105. package/dist/vite/ssg.js.map +1 -1
  106. package/dist/vite/virtualServerModule.d.ts +4 -4
  107. package/dist/vite/virtualServerModule.d.ts.map +1 -1
  108. package/dist/vite/virtualServerModule.js +18 -62
  109. package/dist/vite/virtualServerModule.js.map +1 -1
  110. package/docs/agent/api-reference.md +45 -0
  111. package/docs/agent/editable-forms.md +37 -0
  112. package/docs/agent/guide-get.md +13 -0
  113. package/docs/agent/guide-index.md +15 -0
  114. package/docs/agent/http-handlers.md +9 -0
  115. package/docs/agent/imports.md +16 -0
  116. package/docs/agent/index.md +48 -0
  117. package/docs/agent/input-validation.md +9 -0
  118. package/docs/agent/measuring.md +7 -0
  119. package/docs/agent/mutations.md +11 -0
  120. package/docs/agent/operations.md +9 -0
  121. package/docs/agent/query-params.md +28 -0
  122. package/docs/agent/rendering.md +9 -0
  123. package/docs/agent/request-context.md +13 -0
  124. package/docs/agent/routing.md +11 -0
  125. package/docs/agent/scaffold.md +15 -0
  126. package/docs/agent/security.md +9 -0
  127. package/docs/agent/server-files.md +9 -0
  128. package/docs/agent/streaming.md +9 -0
  129. package/docs/agent/validation-page.md +21 -0
  130. package/docs/agent/validation.md +33 -0
  131. package/docs/agent/verify.md +19 -0
  132. package/docs/agent/workflow.md +11 -0
  133. package/docs/agent-guide.md +266 -0
  134. package/docs/agent-start.md +87 -0
  135. package/docs/migration-0.11.md +15 -0
  136. package/package.json +20 -5
  137. package/dist/server/handlerLoader.d.ts +0 -1
  138. package/dist/server/handlerLoader.d.ts.map +0 -1
  139. package/dist/server/handlerLoader.js +0 -2
  140. package/dist/server/handlerLoader.js.map +0 -1
  141. package/dist/server/ipExtractor.d.ts +0 -48
  142. package/dist/server/ipExtractor.d.ts.map +0 -1
  143. package/dist/server/ipExtractor.js +0 -96
  144. package/dist/server/ipExtractor.js.map +0 -1
  145. package/dist/server/requestRouting.d.ts +0 -4
  146. package/dist/server/requestRouting.d.ts.map +0 -1
  147. package/dist/server/requestRouting.js +0 -67
  148. package/dist/server/requestRouting.js.map +0 -1
  149. package/dist/utils/deepEqual.d.ts +0 -1
  150. package/dist/utils/deepEqual.d.ts.map +0 -1
  151. package/dist/utils/deepEqual.js +0 -2
  152. package/dist/utils/deepEqual.js.map +0 -1
  153. package/dist/utils/formatError.d.ts +0 -2
  154. package/dist/utils/formatError.d.ts.map +0 -1
  155. package/dist/utils/formatError.js +0 -18
  156. package/dist/utils/formatError.js.map +0 -1
@@ -1,16 +1,22 @@
1
1
  import fs from "fs";
2
2
  import path from "path";
3
+ import { fileURLToPath } from "url";
3
4
  import { clearConfigCache, getRpcClientConfig, getRpcConfig, loadConfig } from "../server/config.js";
4
5
  import { attachToDevServer } from "../server/devServer.js";
5
6
  import { injectEnvToProcess, loadEnvFiles } from "../utils/envLoader.js";
6
7
  import { log } from "../utils/logger.js";
7
- import { RESOLVED_VIRTUAL_CLIENT_MODULE_ID, RESOLVED_VIRTUAL_ENTRY_MODULE_ID, RESOLVED_VIRTUAL_SERVER_MANIFEST_ID, SERVER_DIR, VIRTUAL_CLIENT_MODULE_ID, VIRTUAL_ENTRY_MODULE_ID, VIRTUAL_SERVER_MANIFEST_ID, } from "./paths.js";
8
- import { checkRouteCollisions, scanAppShell, scanPageRoutePatterns, scanServerExports, scanSSRPages } from "./scanner.js";
9
- import { generateClientModule, generateEntryModule, generateServerManifest, generateTypeDefinitions } from "./virtualServerModule.js";
8
+ import { RESOLVED_VIRTUAL_ENTRY_MODULE_ID, RESOLVED_VIRTUAL_SERVER_MANIFEST_ID, SERVER_DIR, VIRTUAL_ENTRY_MODULE_ID, VIRTUAL_SERVER_MANIFEST_ID } from "./paths.js";
9
+ import { RPC_MODULE_PATH, writeRpcModule } from "./rpcModule.js";
10
+ import { checkRouteCollisions, scanAppShell, scanPageManifest, scanPageRoutePatterns, scanServerExports, scanSSRPages } from "./scanner.js";
11
+ import { generateServerClientModule, generateServerPrefetchModule, generateServerTransitionsModule } from "./serverClientAdapter.js";
12
+ import { generateEntryModule, generatePageModules, generateServerManifest } from "./virtualServerModule.js";
10
13
  export default function helium() {
11
14
  let root = process.cwd();
15
+ let pageManifest;
16
+ const getPageManifest = () => (pageManifest ?? (pageManifest = scanPageManifest(root)));
17
+ const generateProjectRpc = () => writeRpcModule(root, scanServerExports(root).methods);
12
18
  const serverDir = normalizeToPosix(SERVER_DIR);
13
- const RESOLVED_VIRTUAL_SSR_SERVER_MODULE_ID = "\0heliumts:ssr-server";
19
+ const RESOLVED_PAGE_MODULES_ID = "\0heliumts:page-modules";
14
20
  const RESOLVED_VIRTUAL_SSR_CLIENT_MODULE_ID = "\0heliumts:ssr-client";
15
21
  const RESOLVED_VIRTUAL_SSR_TRANSITIONS_MODULE_ID = "\0heliumts:ssr-transitions";
16
22
  const RESOLVED_VIRTUAL_SSR_PREFETCH_MODULE_ID = "\0heliumts:ssr-prefetch";
@@ -114,6 +120,17 @@ export default function helium() {
114
120
  };
115
121
  },
116
122
  resolveId(id, importer, options) {
123
+ if (!options?.ssr && id === "./pageModules.js" && importer && import.meta.url.startsWith("file:")) {
124
+ const importerFile = importer.split("?")[0];
125
+ if (fs.existsSync(importerFile)) {
126
+ const pluginDir = path.dirname(fs.realpathSync(fileURLToPath(import.meta.url)));
127
+ const routerManifest = normalizeToPosix(path.resolve(pluginDir, "../client/routerManifest"));
128
+ const importerPath = normalizeToPosix(fs.realpathSync(importerFile));
129
+ if (importerPath === `${routerManifest}.js` || importerPath === `${routerManifest}.ts`) {
130
+ return RESOLVED_PAGE_MODULES_ID;
131
+ }
132
+ }
133
+ }
117
134
  if (options?.ssr && id === "heliumts/client") {
118
135
  return RESOLVED_VIRTUAL_SSR_CLIENT_MODULE_ID;
119
136
  }
@@ -123,11 +140,8 @@ export default function helium() {
123
140
  if (options?.ssr && id === "heliumts/client/prefetch") {
124
141
  return RESOLVED_VIRTUAL_SSR_PREFETCH_MODULE_ID;
125
142
  }
126
- if (id === VIRTUAL_CLIENT_MODULE_ID) {
127
- if (importer === RESOLVED_VIRTUAL_SSR_SERVER_MODULE_ID || isServerModule(importer, root, serverDir) || /\.server\.[cm]?[jt]sx?(?:\?|$)/.test(importer || "")) {
128
- return null;
129
- }
130
- return options?.ssr ? RESOLVED_VIRTUAL_SSR_SERVER_MODULE_ID : RESOLVED_VIRTUAL_CLIENT_MODULE_ID;
143
+ if (!options?.ssr && id === "heliumts/server") {
144
+ throw new Error("heliumts/server is server-only. Import application RPC references from src/rpc.generated.ts.");
131
145
  }
132
146
  if (id === VIRTUAL_SERVER_MANIFEST_ID) {
133
147
  return RESOLVED_VIRTUAL_SERVER_MANIFEST_ID;
@@ -140,7 +154,7 @@ export default function helium() {
140
154
  },
141
155
  transform(code, id, options) {
142
156
  if (!options?.ssr && isServerModule(id, root, serverDir)) {
143
- throw new Error(`Server-only module cannot be imported by client code: ${id}. Import RPC method stubs from 'heliumts/server' instead.`);
157
+ throw new Error(`Server-only module cannot be imported by client code: ${id}. Import application RPC references from src/rpc.generated.ts instead.`);
144
158
  }
145
159
  // Prevent .server.ts/.server.js sidecar files from being bundled in client code.
146
160
  // These files contain server-only logic (e.g. DB queries) and must never run in the browser.
@@ -149,125 +163,66 @@ export default function helium() {
149
163
  }
150
164
  },
151
165
  load(id) {
152
- if (id === RESOLVED_VIRTUAL_SSR_SERVER_MODULE_ID) {
153
- const { methods } = scanServerExports(root);
154
- return `export * from 'heliumts/server';\n${generateClientModule(methods)}`;
166
+ if (id === RESOLVED_PAGE_MODULES_ID) {
167
+ return generatePageModules(getPageManifest(), root);
155
168
  }
156
169
  if (id === RESOLVED_VIRTUAL_SSR_CLIENT_MODULE_ID) {
157
- return generateSSRClientStubModule();
170
+ return generateServerClientModule("ssr");
158
171
  }
159
172
  if (id === RESOLVED_VIRTUAL_SSR_TRANSITIONS_MODULE_ID) {
160
- return generateSSRTransitionsStubModule();
173
+ return generateServerTransitionsModule("ssr");
161
174
  }
162
175
  if (id === RESOLVED_VIRTUAL_SSR_PREFETCH_MODULE_ID) {
163
- return generateSSRPrefetchStubModule();
164
- }
165
- if (id === RESOLVED_VIRTUAL_CLIENT_MODULE_ID) {
166
- const { methods } = scanServerExports(root);
167
- return generateClientModule(methods);
176
+ return generateServerPrefetchModule();
168
177
  }
169
178
  if (id === RESOLVED_VIRTUAL_SERVER_MANIFEST_ID) {
170
179
  const { methods, httpHandlers, seoMetadata, middleware, workers } = scanServerExports(root);
171
- const pageRoutePatterns = scanPageRoutePatterns(root);
172
- const ssrPages = scanSSRPages(root);
180
+ const pages = getPageManifest();
181
+ const pageRoutePatterns = scanPageRoutePatterns(root, pages);
182
+ const ssrPages = scanSSRPages(root, pages);
173
183
  const appShell = scanAppShell(root);
174
- return generateServerManifest(methods, httpHandlers, seoMetadata, pageRoutePatterns, ssrPages, appShell, middleware, workers);
184
+ return generateServerManifest(methods, httpHandlers, seoMetadata, pageRoutePatterns, ssrPages, appShell, middleware, workers, pages);
175
185
  }
176
186
  if (id === RESOLVED_VIRTUAL_ENTRY_MODULE_ID + ".tsx") {
177
187
  return generateEntryModule(scanAppShell(root));
178
188
  }
179
189
  },
180
190
  buildStart() {
181
- const { methods } = scanServerExports(root);
182
- const dts = generateTypeDefinitions(methods, root);
183
- const typesDir = path.join(root, "src", "types");
184
- const dtsPath = path.join(typesDir, "heliumts-server.d.ts");
185
- // Ensure src/types exists
186
- if (!fs.existsSync(typesDir)) {
187
- fs.mkdirSync(typesDir, { recursive: true });
188
- }
189
- // At build start we always allow writing the canonical set.
190
- // Only skip if content is identical to avoid needless TS invalidation.
191
- if (!fs.existsSync(dtsPath) || fs.readFileSync(dtsPath, "utf-8") !== dts) {
192
- fs.writeFileSync(dtsPath, dts);
193
- touchTsConfig(root);
194
- }
191
+ generateProjectRpc();
195
192
  // Check for route collisions in pages directory
196
- checkRouteCollisions(root);
193
+ pageManifest = undefined;
194
+ checkRouteCollisions(root, getPageManifest());
197
195
  },
198
196
  configureServer(server) {
199
197
  // Vite's SPA fallback runs after static/public assets and preserves request URLs.
200
- /**
201
- * Write type definitions only if content has changed.
202
- * This prevents unnecessary TypeScript recompilation.
203
- *
204
- * When `allowFewer` is false (default) the file will NOT be
205
- * overwritten if the new content has fewer method declarations
206
- * than the existing file — this guards against writing a
207
- * degraded .d.ts while the user's file is only partially saved.
208
- */
209
- const writeTypesIfChanged = (dts, allowFewer = false) => {
210
- const typesDir = path.join(root, "src", "types");
211
- const dtsPath = path.join(typesDir, "heliumts-server.d.ts");
212
- if (!fs.existsSync(typesDir)) {
213
- fs.mkdirSync(typesDir, { recursive: true });
214
- }
215
- // Check if file exists and content is the same
216
- if (fs.existsSync(dtsPath)) {
217
- const existing = fs.readFileSync(dtsPath, "utf-8");
218
- if (existing === dts) {
219
- return false; // No change needed
220
- }
221
- // Guard: don't overwrite with fewer methods unless explicitly allowed
222
- // (e.g. on unlink). This prevents losing types during partial saves.
223
- if (!allowFewer) {
224
- const countExports = (s) => (s.match(/export const \w+:/g) || []).length;
225
- const existingCount = countExports(existing);
226
- const newCount = countExports(dts);
227
- if (newCount < existingCount) {
228
- log("info", `Skipping type generation: found ${newCount} methods, existing has ${existingCount} (likely partial save)`);
229
- return false;
198
+ // Debounce timer for file changes
199
+ let debounceTimer = null;
200
+ const DEBOUNCE_DELAY = 300; // ms — long enough for format-on-save to finish
201
+ const handleServerFileChange = async () => {
202
+ try {
203
+ if (generateProjectRpc()) {
204
+ const generatedFile = normalizeToPosix(path.join(root, RPC_MODULE_PATH));
205
+ for (const environment of [server.environments.client, server.environments.ssr]) {
206
+ const graph = environment?.moduleGraph;
207
+ for (const module of graph?.getModulesByFile(generatedFile) ?? []) {
208
+ graph?.invalidateModule(module);
209
+ }
230
210
  }
231
211
  }
232
212
  }
233
- fs.writeFileSync(dtsPath, dts);
234
- // Touch tsconfig.json to force the TypeScript language server
235
- // to reload the project. Without this, TS may cache stale
236
- // module augmentations and autocomplete won't reflect the
237
- // new methods until a manual restart.
238
- touchTsConfig(root);
239
- return true; // File was written
240
- };
241
- const regenerateTypes = (allowFewer = false) => {
242
- try {
243
- const { methods } = scanServerExports(root);
244
- const dts = generateTypeDefinitions(methods, root);
245
- return writeTypesIfChanged(dts, allowFewer);
246
- }
247
- catch (e) {
248
- log("error", "Failed to regenerate types", e);
249
- return false;
213
+ catch (error) {
214
+ log("error", "Failed to regenerate RPC imports", error);
250
215
  }
251
- };
252
- // Debounce timer for file changes
253
- let debounceTimer = null;
254
- const DEBOUNCE_DELAY = 300; // ms — long enough for format-on-save to finish
255
- const handleServerFileChange = async (allowFewer = false) => {
256
- // Regenerate type definitions
257
- regenerateTypes(allowFewer);
258
216
  // Invalidate the virtual modules so they get regenerated
259
- const clientModule = server.environments.client?.moduleGraph.getModuleById(RESOLVED_VIRTUAL_CLIENT_MODULE_ID);
217
+ pageManifest = undefined;
218
+ const clientPages = server.environments.client?.moduleGraph.getModuleById(RESOLVED_PAGE_MODULES_ID);
260
219
  const serverModule = server.environments.ssr?.moduleGraph.getModuleById(RESOLVED_VIRTUAL_SERVER_MANIFEST_ID);
261
- const ssrRpcModule = server.environments.ssr?.moduleGraph.getModuleById(RESOLVED_VIRTUAL_SSR_SERVER_MODULE_ID);
262
- if (clientModule) {
263
- server.environments.client?.moduleGraph.invalidateModule(clientModule);
220
+ if (clientPages) {
221
+ server.environments.client?.moduleGraph.invalidateModule(clientPages);
264
222
  }
265
223
  if (serverModule) {
266
224
  server.environments.ssr?.moduleGraph.invalidateModule(serverModule);
267
225
  }
268
- if (ssrRpcModule) {
269
- server.environments.ssr?.moduleGraph.invalidateModule(ssrRpcModule);
270
- }
271
226
  // Reload the server manifest and re-register methods
272
227
  try {
273
228
  // Clear config cache to ensure fresh config is loaded
@@ -293,13 +248,13 @@ export default function helium() {
293
248
  registry.setMiddleware(middlewareHandler);
294
249
  httpRouter.setMiddleware(middlewareHandler);
295
250
  }
296
- }, config, workers, ssrPages, appShell);
251
+ }, config, workers, ssrPages, appShell, mod.pageRoutes);
297
252
  }
298
253
  }
299
254
  catch (e) {
300
255
  log("error", "Failed to reload Helium server manifest", e);
301
256
  }
302
- // Trigger HMR for any client code that imports heliumts/server
257
+ // Refresh the browser after the server manifest has reloaded.
303
258
  server.ws.send({
304
259
  type: "full-reload",
305
260
  path: "*",
@@ -315,47 +270,25 @@ export default function helium() {
315
270
  server.watcher.add(configPath);
316
271
  }
317
272
  }
318
- /**
319
- * Debounced handler for server file changes.
320
- * This prevents multiple rapid regenerations during file saves.
321
- * @param allowFewer - pass true when files are deleted, so the
322
- * method count is allowed to decrease.
323
- */
324
- let pendingAllowFewer = false;
325
- const debouncedHandleServerFileChange = (allowFewer = false) => {
326
- // If any event in the batch is an unlink, honour it
327
- if (allowFewer) {
328
- pendingAllowFewer = true;
273
+ const affectsManifest = (file) => {
274
+ const normalized = normalizeToPosix(path.relative(root, file));
275
+ return (normalized.startsWith(`${serverDir}/`) || normalized.startsWith("src/pages/") || /^src\/[Aa]pp\.[jt]sx?$/.test(normalized) || configFiles.includes(normalized));
276
+ };
277
+ const refreshManifest = (file) => {
278
+ if (!affectsManifest(file)) {
279
+ return;
329
280
  }
330
281
  if (debounceTimer) {
331
282
  clearTimeout(debounceTimer);
332
283
  }
333
284
  debounceTimer = setTimeout(() => {
334
285
  debounceTimer = null;
335
- const shouldAllowFewer = pendingAllowFewer;
336
- pendingAllowFewer = false;
337
- handleServerFileChange(shouldAllowFewer);
286
+ void handleServerFileChange();
338
287
  }, DEBOUNCE_DELAY);
339
288
  };
340
- const affectsManifest = (file) => {
341
- const normalized = normalizeToPosix(path.relative(root, file));
342
- return (normalized.startsWith(`${serverDir}/`) || normalized.startsWith("src/pages/") || /^src\/[Aa]pp\.[jt]sx?$/.test(normalized) || configFiles.includes(normalized));
343
- };
344
- server.watcher.on("change", (file) => {
345
- if (affectsManifest(file)) {
346
- debouncedHandleServerFileChange(true);
347
- }
348
- });
349
- server.watcher.on("add", (file) => {
350
- if (affectsManifest(file)) {
351
- debouncedHandleServerFileChange();
352
- }
353
- });
354
- server.watcher.on("unlink", (file) => {
355
- if (affectsManifest(file)) {
356
- debouncedHandleServerFileChange(true);
357
- }
358
- });
289
+ server.watcher.on("change", refreshManifest);
290
+ server.watcher.on("add", refreshManifest);
291
+ server.watcher.on("unlink", refreshManifest);
359
292
  server.httpServer?.once("close", () => {
360
293
  if (debounceTimer) {
361
294
  clearTimeout(debounceTimer);
@@ -381,7 +314,7 @@ export default function helium() {
381
314
  registry.setMiddleware(mod.middlewareHandler);
382
315
  httpRouter.setMiddleware(mod.middlewareHandler);
383
316
  }
384
- }, config, mod.workers || [], mod.ssrPages || [], mod.appShell || null);
317
+ }, config, mod.workers || [], mod.ssrPages || [], mod.appShell || null, mod.pageRoutes);
385
318
  initialized = true;
386
319
  })());
387
320
  return initialization;
@@ -424,140 +357,6 @@ export default function helium() {
424
357
  },
425
358
  };
426
359
  }
427
- function generateSSRClientStubModule() {
428
- return `
429
- import React from 'react';
430
-
431
- export const RouterContext = React.createContext(null);
432
-
433
- function getSSRRouterSnapshot() {
434
- const snapshot = globalThis.__HELIUM_SSR_ROUTER__;
435
- if (!snapshot || typeof snapshot !== 'object') {
436
- return {
437
- path: '/',
438
- params: {},
439
- search: '',
440
- };
441
- }
442
-
443
- return {
444
- path: typeof snapshot.path === 'string' ? snapshot.path : '/',
445
- params: snapshot.params && typeof snapshot.params === 'object' ? snapshot.params : {},
446
- search: typeof snapshot.search === 'string' ? snapshot.search : '',
447
- };
448
- }
449
-
450
- export function useRouter() {
451
- const snapshot = getSSRRouterSnapshot();
452
- return {
453
- path: snapshot.path,
454
- params: snapshot.params,
455
- searchParams: new URLSearchParams(snapshot.search),
456
- push: () => {},
457
- replace: () => {},
458
- on: () => () => {},
459
- status: 200,
460
- isNavigating: false,
461
- isPending: false,
462
- };
463
- }
464
-
465
- export function Link(props) {
466
- const { href = '#', children, prefetch, ...rest } = props || {};
467
- return React.createElement('a', { href, ...rest }, children);
468
- }
469
-
470
- export function Redirect() {
471
- return null;
472
- }
473
-
474
- export function AppRouter() {
475
- return null;
476
- }
477
-
478
- export async function callMethod() {
479
- throw new Error('callMethod is only available in the browser. Load server data with getServerSideProps instead.');
480
- }
481
-
482
- export function useStreaming() {
483
- return {
484
- chunks: [],
485
- text: '',
486
- isStreaming: false,
487
- error: null,
488
- stats: null,
489
- start: async () => {
490
- throw new Error('useStreaming.start is only available in the browser. Load server data with getServerSideProps instead.');
491
- },
492
- cancel: () => {},
493
- reset: () => {},
494
- };
495
- }
496
-
497
- export function useCall() {
498
- return {
499
- call: async () => null,
500
- isCalling: false,
501
- error: null,
502
- };
503
- }
504
-
505
- export function useFetch() {
506
- return {
507
- data: null,
508
- isLoading: false,
509
- error: null,
510
- refetch: async () => undefined,
511
- };
512
- }
513
-
514
- export class RpcError extends Error {}
515
-
516
- export function getPublicEnv() {
517
- return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => key.startsWith('HELIUM_PUBLIC_') && typeof value === 'string'));
518
- }
519
-
520
- export function getPublicEnvValue(key) {
521
- return getPublicEnv()[key];
522
- }
523
-
524
- export function isDevEnvironment() {
525
- return false;
526
- }
527
-
528
- export function isSSR() {
529
- return true;
530
- }
531
- `;
532
- }
533
- function generateSSRTransitionsStubModule() {
534
- return `
535
- import React from 'react';
536
- import { useRouter } from 'heliumts/client';
537
-
538
- export function useDeferredNavigation() {
539
- const { path } = useRouter();
540
- return {
541
- path,
542
- deferredPath: path,
543
- isStale: false,
544
- isPending: false,
545
- isTransitioning: false,
546
- };
547
- }
548
-
549
- export function PageTransition({ children, fallback = null }) {
550
- return React.createElement('div', { style: { opacity: 1, transition: 'opacity 150ms ease' } },
551
- React.createElement(React.Suspense, { fallback }, children));
552
- }
553
- `;
554
- }
555
- function generateSSRPrefetchStubModule() {
556
- return `
557
- export function prefetchRoute() {}
558
- export function clearPrefetchCache() {}
559
- `;
560
- }
561
360
  /**
562
361
  * Convert file path to POSIX format
563
362
  * @internal Exported for testing
@@ -584,29 +383,4 @@ export function isServerModule(importer, root, serverDir) {
584
383
  const normalized = normalizeToPosix(relative);
585
384
  return normalized === serverDir || normalized.startsWith(`${serverDir}/`);
586
385
  }
587
- /**
588
- * Touch the project's tsconfig.json to force the TypeScript language server
589
- * to reload the project and pick up changed module augmentations.
590
- *
591
- * TS language server watches tsconfig.json for changes. When a `.d.ts` file
592
- * with `declare module` augmentations is regenerated, TS doesn't always
593
- * detect the new content — leading to stale autocomplete. By updating
594
- * tsconfig.json's mtime we trigger a full project reload.
595
- *
596
- * The file content is NOT modified; only the filesystem timestamp changes.
597
- *
598
- * @internal Exported for testing
599
- */
600
- export function touchTsConfig(root) {
601
- const tsconfigPath = path.join(root, "tsconfig.json");
602
- try {
603
- if (fs.existsSync(tsconfigPath)) {
604
- const now = new Date();
605
- fs.utimesSync(tsconfigPath, now, now);
606
- }
607
- }
608
- catch {
609
- // Non-critical: if we can't touch the file, TS may just need a manual reload
610
- }
611
- }
612
386
  //# sourceMappingURL=heliumPlugin.js.map