gemi 0.51.1 → 0.53.0

package/dist/support/Service.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Base for the application's own long-lived singletons — an API client, a
+ * billing gateway, a search index. A subclass declares a `static token`, holds
+ * its settings as ordinary fields, and is listed in `services` on the Kernel;
+ * the kernel constructs it once and awaits its `boot()` before the first
+ * request is served.
+ *
+ * ### Why the settings are fields and not a config slice
+ *
+ * `app/config/*.ts` exists because you do not own the class. `MailManager` and
+ * `AuthManager` ship with the framework, so a config slice is the only place
+ * you can reach in and change them. You *do* own a `Service` subclass, so there
+ * is nothing to reach in from the outside for — a field is a real declaration
+ * the compiler checks, where a config slice is a string key and a cast over
+ * `Repository.get`, which returns `any`. Use `.with()` to override at the
+ * wiring site or in a test.
+ *
+ * ### Why `boot()` is async and the constructor is not
+ *
+ * `Container.make` is synchronous, so a lazily-constructed service could never
+ * await anything. Construction therefore does no I/O — it runs during the
+ * kernel's synchronous phase, which is what makes an instance available to a
+ * provider's `boot()` — and everything that needs to await happens in `boot()`,
+ * during the asynchronous phase. The cost is that every listed service is
+ * constructed and booted on every application boot, including in a worker
+ * thread and in every test that boots a kernel. Keep `boot()` cheap: validate
+ * settings there, and open connections lazily inside the methods that need
+ * them.
+ */
+export declare abstract class Service {
+    /**
+     * The container key. Required, and a string literal rather than the class's
+     * implicit `.name`, for the same reason every other service in the framework
+     * carries one — see the note on `ServiceToken`. Minification renames the
+     * class; it cannot rename a string.
+     */
+    static token: string;
+    /**
+     * Awaited once during kernel boot, in `services` order. A service whose
+     * `boot()` needs another service must be listed after it.
+     */
+    boot(): Promise<void>;
+    /**
+     * The booted singleton for the current application.
+     *
+     * Written as a constructor default so a controller reads as an ordinary
+     * class and stays constructible by hand:
+     *
+     *   class FooController extends Controller {
+     *     constructor(private billing = Billing.inject()) {
+     *       super();
+     *     }
+     *   }
+     *
+     * The default is evaluated when the controller is constructed — per request,
+     * inside the kernel's async context — so this resolves against the
+     * Application handling that request, and a test that passes its own instance
+     * never evaluates it at all.
+     */
+    static inject<T>(this: (abstract new (...args: any[]) => T) & {
+        token: string;
+        name: string;
+    }): T;
+    /**
+     * A configured instance: constructs the service and assigns over its fields.
+     * Typed against the subclass, which a constructor parameter on this base
+     * class could not be — there is no `Partial<this>` in a constructor
+     * signature.
+     *
+     *   services = [Billing.with({ apiKey: process.env.STAGING_KEY })];
+     *   const billing = Billing.with({ apiKey: "test" }); // in a test
+     *
+     * A key whose value is `undefined` is skipped rather than assigned. The first
+     * line above is the reason: `process.env.STAGING_KEY` is `undefined` in every
+     * environment that does not set it, and `Object.assign` would copy that over
+     * the field's declared default — so the service would boot holding
+     * `undefined` where it had a perfectly good fallback. An absent value is not
+     * an override; write `null` if you mean to clear a field.
+     */
+    static with<T extends Service>(this: new () => T, overrides: Partial<T>): T;
+}
+/**
+ * A `Service` subclass, as the Kernel's `services` array accepts it. The array
+ * also takes instances, which is what `.with()` returns.
+ */
+export type ServiceConstructor = (new () => Service) & {
+    token: string;
+    name: string;
+};
+//# sourceMappingURL=Service.d.ts.map

package/dist/support/Service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Service.d.ts","sourceRoot":"","sources":["../../support/Service.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,OAAO;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAE3B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EACb,IAAI,EAAE,CAAC,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG;QAC3C,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,GACA,CAAC;IAoBJ;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;CAO5E;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,UAAU,OAAO,CAAC,GAAG;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC"}

package/dist/support/discover.d.ts

@@ -130,11 +130,19 @@ export declare class DiscoveryError extends Error {
  * where the caller is a scheduler and the alternative is a boot order that
  * depends on the filesystem.
  *
+ * `onSkipped` is handed every export that did *not* match, with the file it came
+ * from. Discovery's characteristic failure is a thing the author wrote and this
+ * walk cannot see, and by the time an export has been discarded here the
+ * information about why is gone — the caller is left holding "four classes"
+ * where the directory holds five. A caller that can recognise its own
+ * near-misses, as `discoverCommands` recognises a builder chain that was never
+ * finished, uses this to say so by name instead.
+ *
  * @throws DiscoveryError if a walked file cannot be imported. Not a skip: a file
  * that will not load is a class the caller was going to be told about and now is
  * not, which is the failure discovery exists to remove.
  */
-export declare function discoverClasses<T extends ClassLike>(dir: string, base: T, ignore?: string[]): Promise<T[]>;
+export declare function discoverClasses<T extends ClassLike>(dir: string, base: T, ignore?: string[], onSkipped?: (value: unknown, file: string) => void): Promise<T[]>;
 /**
  * The directory an app's `app/` sits in, as the running process can know it.
  *

package/dist/support/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../support/discover.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAqCxE;AAED;;;GAGG;AACH,KAAK,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAE5D;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,SAAS,EACvD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,EACP,MAAM,GAAE,MAAM,EAAO,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Bd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../support/discover.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAqCxE;AAED;;;GAGG;AACH,KAAK,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAE5D;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,SAAS,EACvD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,EACP,MAAM,GAAE,MAAM,EAAO,EACrB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GACjD,OAAO,CAAC,CAAC,EAAE,CAAC,CAiCd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/support/index.d.ts

@@ -1,4 +1,5 @@
 export { ServiceProvider } from "./ServiceProvider";
+export { Service, type ServiceConstructor } from "./Service";
 export { Repository, type ConfigItems } from "./Repository";
 export { createConfigRepository, loadConfigFrom } from "./loadConfig";
 export { withDefaults } from "./withDefaults";

package/dist/support/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../support/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,cAAc,EACd,eAAe,EACf,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../support/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,cAAc,EACd,eAAe,EACf,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/support/index.js

@@ -1,4 +1,4 @@
 // @bun
-import{tb as K,ub as L,vb as M,wb as Q}from"../chunk-bm6q0q1q.js";import{xb as R}from"../chunk-k4mjcvsm.js";import{ue as J}from"../chunk-8vnbvfmd.js";import{Ge as g}from"../chunk-j4rkk01q.js";import"../chunk-zwpx6z5f.js";import{readdir as q}from"fs/promises";import{join as z,parse as c}from"path";var A=[".ts",".tsx",".js",".mjs",".jsx"];function B(f={}){let v={};for(let[C,D]of Object.entries(f))v[C]=j(D);return new g(v)}async function H(f,v=new g){let C=[];try{C=await q(f)}catch(x){return v}let D=C.filter((x)=>{let{ext:F,name:P}=c(x);return A.includes(F)&&!P.startsWith(".")}).sort();for(let x of D){let{name:F}=c(x),P=await import(z(f,x));v.set(F,j(P))}return v}function j(f){if(f&&typeof f==="object"&&"default"in f)return f.default;return f}export{J as withDefaults,K as sourceFiles,Q as projectRoot,H as loadConfigFrom,M as discoverClasses,B as createConfigRepository,R as ServiceProvider,g as Repository,L as DiscoveryError};
+import{Bb as S,Cb as U,Db as V,Eb as W}from"../chunk-ha7n1c94.js";import{Fb as Y}from"../chunk-ttzkn1qd.js";import{Ce as R}from"../chunk-3y9nf09k.js";import{Ke as F,Me as q}from"../chunk-mt2755rs.js";import"../chunk-qyaqg07q.js";import"../chunk-0h3jr9d9.js";class v{static token;async boot(){}static inject(){if(!this.token)throw Error(`Service [${this.name}] does not declare a \`static token\`, so the container has no key to resolve it by.`);try{return q(this)}catch(x){throw Error(`Could not inject [${this.name}]. Services are constructed when the kernel boots, so `+"inject() only works from code that runs after that \u2014 a constructor default or a method "+`body, never module top level. Check that [${this.name}] is listed in \`services\` on your Kernel.`,{cause:x})}}static with(x){let f=new this;for(let[C,g]of Object.entries(x))if(g!==void 0)f[C]=g;return f}}import{readdir as H}from"fs/promises";import{join as J,parse as z}from"path";var L=[".ts",".tsx",".js",".mjs",".jsx"];function M(x={}){let f={};for(let[C,g]of Object.entries(x))f[C]=B(g);return new F(f)}async function Q(x,f=new F){let C=[];try{C=await H(x)}catch(D){return f}let g=C.filter((D)=>{let{ext:P,name:j}=z(D);return L.includes(P)&&!j.startsWith(".")}).sort();for(let D of g){let{name:P}=z(D),j=await import(J(x,D));f.set(P,B(j))}return f}function B(x){if(x&&typeof x==="object"&&"default"in x)return x.default;return x}export{R as withDefaults,S as sourceFiles,W as projectRoot,Q as loadConfigFrom,V as discoverClasses,M as createConfigRepository,Y as ServiceProvider,v as Service,F as Repository,U as DiscoveryError};
 
-//# debugId=57A0058B0002363264756E2164756E21
+//# debugId=94EA4BF19A2C421664756E2164756E21

package/dist/support/index.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../support/loadConfig.ts"],
+  "sources": ["../support/Service.ts", "../support/loadConfig.ts"],
   "sourcesContent": [
+    "import type { ServiceToken } from \"../container/Container\";\nimport { app } from \"../foundation/app\";\n\n/**\n * Base for the application's own long-lived singletons — an API client, a\n * billing gateway, a search index. A subclass declares a `static token`, holds\n * its settings as ordinary fields, and is listed in `services` on the Kernel;\n * the kernel constructs it once and awaits its `boot()` before the first\n * request is served.\n *\n * ### Why the settings are fields and not a config slice\n *\n * `app/config/*.ts` exists because you do not own the class. `MailManager` and\n * `AuthManager` ship with the framework, so a config slice is the only place\n * you can reach in and change them. You *do* own a `Service` subclass, so there\n * is nothing to reach in from the outside for — a field is a real declaration\n * the compiler checks, where a config slice is a string key and a cast over\n * `Repository.get`, which returns `any`. Use `.with()` to override at the\n * wiring site or in a test.\n *\n * ### Why `boot()` is async and the constructor is not\n *\n * `Container.make` is synchronous, so a lazily-constructed service could never\n * await anything. Construction therefore does no I/O — it runs during the\n * kernel's synchronous phase, which is what makes an instance available to a\n * provider's `boot()` — and everything that needs to await happens in `boot()`,\n * during the asynchronous phase. The cost is that every listed service is\n * constructed and booted on every application boot, including in a worker\n * thread and in every test that boots a kernel. Keep `boot()` cheap: validate\n * settings there, and open connections lazily inside the methods that need\n * them.\n */\nexport abstract class Service {\n  /**\n   * The container key. Required, and a string literal rather than the class's\n   * implicit `.name`, for the same reason every other service in the framework\n   * carries one — see the note on `ServiceToken`. Minification renames the\n   * class; it cannot rename a string.\n   */\n  static token: string;\n\n  /**\n   * Awaited once during kernel boot, in `services` order. A service whose\n   * `boot()` needs another service must be listed after it.\n   */\n  async boot(): Promise<void> {}\n\n  /**\n   * The booted singleton for the current application.\n   *\n   * Written as a constructor default so a controller reads as an ordinary\n   * class and stays constructible by hand:\n   *\n   *   class FooController extends Controller {\n   *     constructor(private billing = Billing.inject()) {\n   *       super();\n   *     }\n   *   }\n   *\n   * The default is evaluated when the controller is constructed — per request,\n   * inside the kernel's async context — so this resolves against the\n   * Application handling that request, and a test that passes its own instance\n   * never evaluates it at all.\n   */\n  static inject<T>(\n    this: (abstract new (...args: any[]) => T) & {\n      token: string;\n      name: string;\n    },\n  ): T {\n    if (!this.token) {\n      throw new Error(\n        `Service [${this.name}] does not declare a \\`static token\\`, so the container has no key to resolve it by.`,\n      );\n    }\n\n    try {\n      return app(this as ServiceToken<T>);\n    } catch (cause) {\n      throw new Error(\n        `Could not inject [${this.name}]. Services are constructed when the kernel boots, so ` +\n          `inject() only works from code that runs after that — a constructor default or a method ` +\n          `body, never module top level. Check that [${this.name}] is listed in \\`services\\` on ` +\n          `your Kernel.`,\n        { cause },\n      );\n    }\n  }\n\n  /**\n   * A configured instance: constructs the service and assigns over its fields.\n   * Typed against the subclass, which a constructor parameter on this base\n   * class could not be — there is no `Partial<this>` in a constructor\n   * signature.\n   *\n   *   services = [Billing.with({ apiKey: process.env.STAGING_KEY })];\n   *   const billing = Billing.with({ apiKey: \"test\" }); // in a test\n   *\n   * A key whose value is `undefined` is skipped rather than assigned. The first\n   * line above is the reason: `process.env.STAGING_KEY` is `undefined` in every\n   * environment that does not set it, and `Object.assign` would copy that over\n   * the field's declared default — so the service would boot holding\n   * `undefined` where it had a perfectly good fallback. An absent value is not\n   * an override; write `null` if you mean to clear a field.\n   */\n  static with<T extends Service>(this: new () => T, overrides: Partial<T>): T {\n    const instance = new this();\n    for (const [key, value] of Object.entries(overrides)) {\n      if (value !== undefined) instance[key] = value;\n    }\n    return instance;\n  }\n}\n\n/**\n * A `Service` subclass, as the Kernel's `services` array accepts it. The array\n * also takes instances, which is what `.with()` returns.\n */\nexport type ServiceConstructor = (new () => Service) & {\n  token: string;\n  name: string;\n};\n",
     "import { readdir } from \"node:fs/promises\";\nimport { join, parse } from \"node:path\";\n\nimport { Repository } from \"./Repository\";\n\nconst CONFIG_EXTENSIONS = [\".ts\", \".tsx\", \".js\", \".mjs\", \".jsx\"];\n\n// Builds a Repository from an already-imported map of config modules. The map\n// key becomes the top-level config key, so `{ mail: mailModule }` is readable\n// as `config.get(\"mail.driver\")`. Each entry may be either the module namespace\n// (its `default` export is unwrapped) or the config object itself.\nexport function createConfigRepository(\n  modules: Record<string, any> = {},\n): Repository {\n  const items: Record<string, any> = {};\n\n  for (const [key, mod] of Object.entries(modules)) {\n    items[key] = unwrap(mod);\n  }\n\n  return new Repository(items);\n}\n\n// Reads every config module in an app's `app/config` directory into a\n// Repository. The file's basename is the top-level key: `app/config/mail.ts`\n// populates `mail.*`. A missing directory yields an empty Repository so apps\n// that declare no config still boot.\nexport async function loadConfigFrom(\n  directory: string,\n  repository = new Repository(),\n): Promise<Repository> {\n  let entries: string[] = [];\n\n  try {\n    entries = await readdir(directory);\n  } catch (err) {\n    return repository;\n  }\n\n  const files = entries\n    .filter((entry) => {\n      const { ext, name } = parse(entry);\n      return CONFIG_EXTENSIONS.includes(ext) && !name.startsWith(\".\");\n    })\n    .sort();\n\n  for (const file of files) {\n    const { name } = parse(file);\n    const mod = await import(join(directory, file));\n    repository.set(name, unwrap(mod));\n  }\n\n  return repository;\n}\n\nfunction unwrap(mod: any) {\n  if (mod && typeof mod === \"object\" && \"default\" in mod) {\n    return mod.default;\n  }\n  return mod;\n}\n"
   ],
-  "mappings": ";iPAAA,aAAS,eACT,UAAS,MAAM,aAIf,IAAM,EAAoB,CAAC,MAAO,OAAQ,MAAO,OAAQ,MAAM,EAMxD,SAAS,CAAsB,CACpC,EAA+B,CAAC,EACpB,CACZ,IAAM,EAA6B,CAAC,EAEpC,QAAY,EAAK,KAAQ,OAAO,QAAQ,CAAO,EAC7C,EAAM,GAAO,EAAO,CAAG,EAGzB,OAAO,IAAI,EAAW,CAAK,EAO7B,eAAsB,CAAc,CAClC,EACA,EAAa,IAAI,EACI,CACrB,IAAI,EAAoB,CAAC,EAEzB,GAAI,CACF,EAAU,MAAM,EAAQ,CAAS,EACjC,MAAO,EAAK,CACZ,OAAO,EAGT,IAAM,EAAQ,EACX,OAAO,CAAC,IAAU,CACjB,IAAQ,MAAK,QAAS,EAAM,CAAK,EACjC,OAAO,EAAkB,SAAS,CAAG,GAAK,CAAC,EAAK,WAAW,GAAG,EAC/D,EACA,KAAK,EAER,QAAW,KAAQ,EAAO,CACxB,IAAQ,QAAS,EAAM,CAAI,EACrB,EAAM,MAAa,SAAK,EAAW,CAAI,GAC7C,EAAW,IAAI,EAAM,EAAO,CAAG,CAAC,EAGlC,OAAO,EAGT,SAAS,CAAM,CAAC,EAAU,CACxB,GAAI,GAAO,OAAO,IAAQ,UAAY,YAAa,EACjD,OAAO,EAAI,QAEb,OAAO",
-  "debugId": "57A0058B0002363264756E2164756E21",
+  "mappings": ";2RAgCO,CAAe,JAAQ,EAOrB,OAMD,AAAI,EAAkB,QAmBrB,OAAS,EAKX,CACH,GAAI,CAAC,KAAK,MACR,MAAU,MACR,YAAY,KAAK,0FACnB,EAGF,GAAI,CACF,OAAO,EAAI,IAAuB,EAClC,MAAO,EAAO,CACd,MAAU,MACR,qBAAqB,KAAK,6DACxB,+FACA,6CAA6C,KAAK,kDAEpD,CAAE,OAAM,CACV,SAoBG,KAAuB,CAAoB,EAA0B,CAC1E,IAAM,EAAW,IAAI,KACrB,QAAY,EAAK,KAAU,OAAO,QAAQ,CAAS,EACjD,GAAI,IAAU,OAAW,EAAS,GAAO,EAE3C,OAAO,EAEX,CChHA,kBAAS,oBACT,eAAS,WAAM,aAIf,IAAM,EAAoB,CAAC,MAAO,OAAQ,MAAO,OAAQ,MAAM,EAMxD,SAAS,CAAsB,CACpC,EAA+B,CAAC,EACpB,CACZ,IAAM,EAA6B,CAAC,EAEpC,QAAY,EAAK,KAAQ,OAAO,QAAQ,CAAO,EAC7C,EAAM,GAAO,EAAO,CAAG,EAGzB,OAAO,IAAI,EAAW,CAAK,EAO7B,eAAsB,CAAc,CAClC,EACA,EAAa,IAAI,EACI,CACrB,IAAI,EAAoB,CAAC,EAEzB,GAAI,CACF,EAAU,MAAM,EAAQ,CAAS,EACjC,MAAO,EAAK,CACZ,OAAO,EAGT,IAAM,EAAQ,EACX,OAAO,CAAC,IAAU,CACjB,IAAQ,MAAK,QAAS,EAAM,CAAK,EACjC,OAAO,EAAkB,SAAS,CAAG,GAAK,CAAC,EAAK,WAAW,GAAG,EAC/D,EACA,KAAK,EAER,QAAW,KAAQ,EAAO,CACxB,IAAQ,QAAS,EAAM,CAAI,EACrB,EAAM,MAAa,SAAK,EAAW,CAAI,GAC7C,EAAW,IAAI,EAAM,EAAO,CAAG,CAAC,EAGlC,OAAO,EAGT,SAAS,CAAM,CAAC,EAAU,CACxB,GAAI,GAAO,OAAO,IAAQ,UAAY,YAAa,EACjD,OAAO,EAAI,QAEb,OAAO",
+  "debugId": "94EA4BF19A2C421664756E2164756E21",
   "names": []
 }

package/dist/testing/Page.d.ts

@@ -0,0 +1,166 @@
+import { type ComponentType, type PropsWithChildren, type ReactNode } from "react";
+import { type FallbackProps } from "react-error-boundary";
+import type { User } from "../auth/types";
+import { type QueryConfig } from "../client/QueryManagerContext";
+import type { Breadcrumb } from "../client/useBreadcrumbs";
+/**
+ * A dictionary as `Dictionary.create` produces it: a name and a
+ * `{ key: { locale: string } }` map.
+ *
+ * Typed structurally rather than as `Dictionary<T>` for two reasons. It keeps
+ * `gemi/testing` from importing `gemi/i18n` — a server entry, which reaches the
+ * `Lang` facade and through it the container. And it means an object literal of
+ * the same shape is accepted, so a test never *has* to import the app's
+ * dictionaries at all.
+ *
+ * Only `name` and `dictionary` are read — both plain data. `Dictionary`'s
+ * server-only methods (`render`, `reference`, which throw once `window` is
+ * defined) are never called from here.
+ */
+export interface PageDictionary {
+    name: string;
+    dictionary: Record<string, Record<string, string>>;
+}
+export interface PageProps {
+    /**
+     * The URL the view is mounted at. A template (`/app/:orgId/chat`) is resolved
+     * against `params`, so the same string can be pasted from the router.
+     */
+    pathname?: string;
+    /** Route params, as the router would have parsed them out of `pathname`. */
+    params?: Record<string, string>;
+    /** `"?tab=recent"`, `"tab=recent"`, or `{ tab: "recent" }`. */
+    searchParams?: string | Record<string, string | number | boolean>;
+    hash?: string;
+    /** The locale `useTranslator` and `useLocale` report. */
+    locale?: string;
+    /**
+     * The app's default locale. Links and `useNavigate` omit the locale segment
+     * for it, so leaving this equal to `locale` (the default) keeps hrefs
+     * unprefixed — set it to seed a page being viewed in a non-default locale.
+     */
+    defaultLocale?: string;
+    supportedLocales?: string[];
+    /**
+     * Dictionaries the components under test translate against — the app's own,
+     * or literals of the same shape.
+     *
+     * Note what importing the app's costs: `app/i18n/index.ts` imports
+     * `gemi/i18n`, a server entry, so the test file pulls the container and
+     * `node:async_hooks` into its module graph. Nothing there runs (and nothing
+     * here calls it), so it is fine under any runner that has Node builtins —
+     * vitest, `bun test` — and not under one that renders in a real browser. Use
+     * `translations` there, which is the shape the client actually receives.
+     */
+    dictionaries?: PageDictionary[];
+    /**
+     * Translations for the current locale, already resolved: dictionary name →
+     * key → string. This is the shape the server serializes onto the page, so it
+     * is what the client reads at runtime — and it imports nothing.
+     *
+     * ```tsx
+     * <Page translations={{ Chat: { greeting: "Hello {{name}}" } }}>
+     * ```
+     *
+     * Merged over `dictionaries`, so the two compose: seed from the app's real
+     * dictionary and override the one key a test is about.
+     */
+    translations?: Record<string, Record<string, string>>;
+    /**
+     * Data `useQuery` finds already cached, keyed by API path — the path passed
+     * to `useQuery`, without the `/api` prefix the client adds when it fetches.
+     * A key may carry a query string (`"/lists?page=2"`) to seed one search
+     * variant.
+     *
+     * The cache is keyed by the *resolved* path, so a key's `:params` are
+     * resolved against the page's `params` — and a key naming one the page does
+     * not carry is an error, naming the key. That case is common enough to be
+     * worth the loud failure: a query often takes its params from the call site
+     * rather than the route (`useQuery("/orgs/:orgId/lists", { params: { orgId } })`
+     * with `orgId` in component state), and the right seed for it is the resolved
+     * path, `"/orgs/abc/lists"`.
+     *
+     * Seeded at mount only: a component that mutates or refetches its data owns
+     * the cache from then on.
+     */
+    queryData?: Record<string, unknown>;
+    /** App-wide `useQuery` defaults, as `createRoot` threads them. */
+    queryConfig?: QueryConfig;
+    /**
+     * What `useUser()` reports. Defaults to `null` — an anonymous visitor — and
+     * either way the hook resolves from here without issuing a request.
+     */
+    user?: Partial<User> | null;
+    /** What `useBreadcrumbs()` returns, in order. */
+    breadcrumbs?: Breadcrumb[];
+    /**
+     * The theme `useTheme()` starts on. The app reads a visitor's stored choice
+     * out of `localStorage`; a test has no session to have made one in, so this
+     * seeds it without writing to storage. `setTheme` works from either.
+     */
+    theme?: "light" | "dark" | "system";
+    /**
+     * Fallback for the `Suspense` boundary wrapped around the children — the
+     * stand-in for the view's own `Loading` export, which the real router
+     * supplies. Defaults to `null`.
+     */
+    fallback?: ReactNode;
+    /**
+     * Renders in place of the children when one throws, mirroring a view's
+     * `Error` export. Without it a thrown render (an errored suspense query,
+     * say) propagates out of `render()` and fails the test, which is usually
+     * what you want.
+     */
+    errorFallback?: ComponentType<FallbackProps>;
+    /**
+     * Called when something navigates — a `Link` click, `useNavigate().push`.
+     * The navigation is reported, not performed: `<Page>` renders one route and
+     * does not re-resolve the tree, so `useLocation()` keeps reporting the
+     * pathname it was given.
+     */
+    onNavigate?: (href: string, action: "push" | "replace") => void;
+}
+/**
+ * Mounts a component with the inputs a view normally arrives with — route
+ * params, the current locale and its dictionaries, prefetched query data, the
+ * signed-in user — so a unit test can assert what it renders rather than only
+ * its empty state.
+ *
+ * ```tsx
+ * import { render, screen } from "@testing-library/react";
+ * import { Page } from "gemi/testing";
+ *
+ * render(
+ *   <Page
+ *     pathname="/app/:orgId/chat"
+ *     params={{ orgId: "abc" }}
+ *     queryData={{ "/organizations/:orgId/messages": [{ id: 1, body: "hi" }] }}
+ *     dictionaries={[ChatDictionary]}
+ *   >
+ *     <OrgChat />
+ *   </Page>,
+ * );
+ *
+ * expect(screen.getByText("hi")).toBeDefined();
+ * ```
+ *
+ * It is a plain component, so it composes with any renderer — Testing
+ * Library's `render`, `react-test-renderer`, or `renderToString`.
+ *
+ * Two things it does not do.
+ *
+ * It does not route: there is no view tree and no route manifest behind it, so
+ * a navigation is reported through `onNavigate` rather than resolved. To
+ * assert the page *after* one, render a second `<Page>`.
+ *
+ * And under `renderToString` it renders the server's own no-data branch for an
+ * *unseeded* query rather than suspending — deliberately, because suspending
+ * there is the streaming server's job: `createRoot` threads the request's
+ * `ServerQueryStore` through `ServerQueryContext`, and that store is what runs
+ * the route handler. A harness has no request and no handler to run, so there
+ * is nothing to suspend on. Seeded queries render their data on the server
+ * exactly as they do in the browser; unseeded ones behave as a route with no
+ * `Query.prefetch` does, framework warning included.
+ */
+export declare const Page: (props: PropsWithChildren<PageProps>) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Page.d.ts.map

package/dist/testing/Page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Page.d.ts","sourceRoot":"","sources":["../../testing/Page.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAI1C,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAYvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,kEAAkE;IAClE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;CACjE;AA6ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,iBAAiB,CAAC,SAAS,CAAC,4CA4PvD,CAAC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { Page } from "./Page";
+export type { PageProps, PageDictionary } from "./Page";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC"}