@backtickjs/core 0.1.11 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 The `cs` tag and the types around it. A client script, written `` cs`…` `` inside a server component, is code that runs on the client; values from the server cross into it as splices written `$name`, type-checked on both sides. Every Backtick app imports `cs` from here, whatever its UI framework.
 
-`cs` is compiled at build time, so a project also needs a build plugin (`@backtickjs/node-plugin` or `@backtickjs/bun-plugin`), an adapter for its framework (`@backtickjs/react`, `@backtickjs/react-native` or `@backtickjs/solid-js`) and `@backtickjs/tsc` for type checking. Called without the compiler, `cs` throws. `npx create-backtick-app@latest` sets all of this up.
+`cs` is compiled at build time, so a project also needs a build plugin (`@backtickjs/node-plugin` or `@backtickjs/bun-plugin`), its framework's JSX package (`@backtickjs/jsx-react` or `@backtickjs/jsx-solid`) and `@backtickjs/tsc` for type checking. Called without the compiler, `cs` throws. `npx create-backtick-app@latest` sets all of this up.
 
 ## Install
 
@@ -16,7 +16,7 @@ A server component reads data on the server and returns a client script. A clien
 
 ```tsx
 import { cs } from "@backtickjs/core";
-import { useState } from "@backtickjs/react";
+import { useState } from "react" with { backtick: "client" };
 
 // A client component: it runs on the client.
 const Counter = cs`(props: { start: number }) => {
@@ -42,27 +42,67 @@ A script every component shares, like a context or a store, is made once with `o
 
 ```tsx
 import { cs, once } from "@backtickjs/core";
-import { createContext, useContext } from "@backtickjs/react";
+import { createContext, useContext } from "react" with { backtick: "client" };
 
 const ThemeContext = once(cs`$createContext("light")`);
 const Label = cs`() => <p>{$useContext($ThemeContext)}</p>`;
 // In a script: <$ThemeContext.Provider value="dark"><$Label /></$ThemeContext.Provider>
 ```
 
-To use a package the client provides beyond what an adapter covers, describe its export with `createImport`. `from` is the specifier the bundle imports, and `version` the semver range of its package that the export works with:
+To use a package the client provides, import it with `with { backtick: "client" }`. The server never loads it: each name is what the client provides, typed as the package types it, and a script splices it:
 
 ```ts
-import { createImport } from "@backtickjs/core";
-
-const greet = createImport<() => string>({
-  name: "greet",
-  from: "my-native-module",
-  version: "^1.0.0",
-});
+import { greet } from "my-native-module" with { backtick: "client" };
 // In a script: cs`<p>{$greet()}</p>`
 ```
 
-The client must provide that package, and the server must list it in the bundler's `modules` at a version in that range.
+The package must be installed where the server's file finds it, for its types and its version. The client must provide it, and the server must list it in the bundler's `modules` at that version or a later one of the same major. The compiler writes each name as what `createImport({ name, from, version })` makes, which a hand-written import can call too.
+
+## Every build in users' hands
+
+A store build carries the modules it was built with, at their versions, for as long as it's installed, while your server moves on. Each build sends the modules it carries, and the server bundles its screens for exactly those: there's nothing to record before a build ships, and any version of your server can draw for any build.
+
+1. **The app's module map** offers what screens may require, each from a package in `package.json`'s dependencies. A platform that differs gets its own file, as Metro picks files: `client/moduleMap.web.ts` for the web.
+
+2. **The app's config carries its packages' versions.** `installedPackages`, from `@backtickjs/core/node`, reads the installed version of each of the app's dependencies from `node_modules`. In an Expo app, `app.config.ts` puts them in the config, which Expo embeds in the app:
+
+   ```ts
+   // app.config.ts
+   import { installedPackages } from "@backtickjs/core/node";
+   import type { ConfigContext, ExpoConfig } from "expo/config";
+
+   export default ({ config, projectRoot }: ConfigContext): ExpoConfig => ({
+     ...(config as ExpoConfig),
+     extra: {
+       ...config.extra,
+       backtick: { packages: installedPackages(projectRoot) },
+     },
+   });
+   ```
+
+3. **The app sends its modules** however it reaches its server: a header, a GraphQL variable. `modulesOf` gives each module in the map its package's version, and throws as the app starts without them, or for a module from a package that isn't a dependency:
+
+   ```ts
+   import { modulesOf } from "@backtickjs/core";
+
+   const modules = JSON.stringify(
+     modulesOf(moduleMap, Constants.expoConfig?.extra?.backtick?.packages),
+   );
+   fetch(url, { headers: { "x-backtick-modules": modules } });
+   ```
+
+4. **The server bundles for them:**
+
+   ```ts
+   const modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
+   const bundle = await bundler.build({ input, modules });
+   ```
+
+   The bundler refuses modules that aren't `{ "specifier": "version" }`, and a screen that imports a module the build doesn't carry, or at a version it can't run. To draw differently for builds that lack a module, or to ask old ones to update, check with `supports` from [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): `supports(modules, "react-native", ">=0.86")`.
+
+In development, a reload keeps the app config the app was opened with, and its versions with it: after upgrading a package, close the app and open it again.
+
+A test draws a screen with a module map of its own, stand-ins included; its modules are that map's, at the versions the app installs: `modulesOf(moduleMap, installedPackages(projectRoot))`.
 
 ## API
 
@@ -76,16 +116,18 @@ The client must provide that package, and the server must list it in the bundler
 - `Bundle<T>`: a bundle's code, branded with what it runs to. `bundler.build(…).generate(…)` writes one.
 - `execRoot(bundle, moduleMap)`, from `@backtickjs/core/cjs`: in a React Native app, runs the CommonJS bundle it starts from to its value, as a promise, with `require` answered from `moduleMap`, a `ModuleMap`: the modules the app provides, by specifier.
 - `execRoot(bundle)`, from `@backtickjs/core/es`: in a web page, imports the ES bundle it starts from and resolves to its value, the page's import map answering its imports. Each format has its own entry, so a React Native app's bundler never reads the ES one's `import()`.
+- `modulesOf(moduleMap, packages)`: the modules `moduleMap`, a `ModuleMap`, offers, each at its package's version in `packages`, for the app to send its server.
+- `installedPackages(projectRoot)`, from `@backtickjs/core/node`: the installed version of each of the app's dependencies, read from `node_modules`. Node only.
 - `exec`: in a script, `$exec(bundle)` runs another bundle as the script's own was run, with the same modules, to a promise of its value.
 - `isClientExec`, `ClientExec`: its check and type.
 - `SplicesAs<T>`: `T` as a splice checks it, member by member. Used by the bundler to check its input.
-- `createJsxElement`, `isJsxElement`, `JsxElement`, `JsxElementOf`, `JsxElementTypeOf`: what a server-side JSX tag evaluates to before bundling. Used by adapters' JSX runtimes.
-- `create`, `isClientScript`, `ClientScript`, `ClientModule`, `Param`: the compiled form of a script, written by the compiler and read by the bundler. Not for application code.
+- `createJsxElement`, `isJsxElement`, `JsxElement`, `JsxElementOf`, `JsxElementTypeOf`: what a server-side JSX tag evaluates to before bundling. Used by the JSX packages' runtimes.
+- `create`, `isClientScript`, `ClientScript`, `ScriptModule`, `Param`: the compiled form of a script, written by the compiler and read by the bundler. Not for application code.
 
 ## Related
 
 - [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): runs server components and writes the bundle
-- [`@backtickjs/react`](https://github.com/backtickjs/backtick/tree/main/adapters/react), [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/adapters/react-native), [`@backtickjs/solid-js`](https://github.com/backtickjs/backtick/tree/main/adapters/solid-js): framework adapters
+- [`@backtickjs/jsx-react`](https://github.com/backtickjs/backtick/tree/main/packages/jsx-react), [`@backtickjs/jsx-solid`](https://github.com/backtickjs/backtick/tree/main/packages/jsx-solid): each framework's JSX
 - [`@backtickjs/node-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/node-plugin), [`@backtickjs/bun-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/bun-plugin): compile scripts as your server loads them
 - [`@backtickjs/tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc): type-checks scripts and their splices
 - [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick/), [Scripts in depth](https://backtickjs.com/docs/scripts-in-depth/)

package/dist/ClientImport.d.ts

@@ -1,7 +1,8 @@
 import type { Client } from "./Client.js";
 /**
  * An export of a module the client provides, held as a value: what a script
- * splices to use it, and what a bundle imports it by.
+ * splices to use it, and what a bundle imports it by. The compiler writes one
+ * per name of `import { View } from "react-native" with { backtick: "client" }`.
  */
 export interface ClientImport<T> extends Client<T> {
     readonly "@backtickjs": "ClientImport";

package/dist/ClientImport.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientImport.js","sourceRoot":"","sources":["../src/ClientImport.ts"],"names":[],"mappings":"AAeA,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK,cAAc,CACxC,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAI,EAC9B,IAAI,EACJ,IAAI,EACJ,OAAO,GAKR;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,IAAI;QACJ,IAAI;QACJ,OAAO;KACsB,CAAC;AAClC,CAAC"}
+{"version":3,"file":"ClientImport.js","sourceRoot":"","sources":["../src/ClientImport.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK,cAAc,CACxC,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAI,EAC9B,IAAI,EACJ,IAAI,EACJ,OAAO,GAKR;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,IAAI;QACJ,IAAI;QACJ,OAAO;KACsB,CAAC;AAClC,CAAC"}

package/dist/ClientModule.d.ts

@@ -0,0 +1,8 @@
+import type { Client } from "./Client.js";
+/**
+ * A module's exports as client imports, each typed by its declaration: what
+ * the editor checks the names of a client import against.
+ */
+export type ClientModule<M> = {
+    readonly [Name in keyof M]: Client<M[Name]>;
+};

package/dist/ClientModule.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ClientModule.js.map

package/dist/ClientModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientModule.js","sourceRoot":"","sources":["../src/ClientModule.ts"],"names":[],"mappings":""}

package/dist/ClientScript.d.ts

@@ -6,7 +6,7 @@ export type Param = {
     kind: "capture";
     key: string;
 };
-export interface ClientModule {
+export interface ScriptModule {
     readonly id: string;
     readonly code: string;
     readonly map: string;
@@ -16,9 +16,9 @@ export interface ClientModule {
 }
 export interface ClientScript {
     readonly "@backtickjs": "ClientScript";
-    readonly module: ClientModule;
+    readonly module: ScriptModule;
     readonly args: readonly Spliceable[];
     readonly once?: true;
 }
 export declare function isClientScript(value: unknown): value is ClientScript;
-export declare function create(module: ClientModule, args: readonly Spliceable[]): ClientScript;
+export declare function create(module: ScriptModule, args: readonly Spliceable[]): ClientScript;

package/dist/JsxElement.d.ts

@@ -2,8 +2,8 @@ import type { Client } from "./Client.js";
 /**
  * What a JSX tag evaluates to on the server, before bundling resolves it: the
  * tag and its props, which are the server's own. What a drawing is, is the
- * adapter's; this is what the bundler expands. A client value, of the type its
- * adapter names (Solid's: its element), so a host may hand one over wherever
+ * JSX package's; this is what the bundler expands. A client value, of the type
+ * its JSX package names (Solid's: its element), so a host may hand one over wherever
  * a drawing may stand.
  */
 export interface JsxElement extends Client<unknown> {

package/dist/cjs.d.ts

@@ -1,6 +1,5 @@
 import type { Bundle } from "./Bundle.js";
-import type { ModuleMap } from "./ModuleMap.js";
-export type { ModuleMap };
+import type { ModuleMap } from "./modulesOf.js";
 /**
  * Executes a CommonJS bundle an app starts from, the one nothing else runs,
  * to its value, with `require` answered from `moduleMap`: how a React Native

package/dist/cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"cjs.js","sourceRoot":"","sources":["../src/cjs.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAiB,EACjB,SAAoB;IAEpB,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAClD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAqB,CAAC;AACtC,CAAC"}
+{"version":3,"file":"cjs.js","sourceRoot":"","sources":["../src/cjs.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAiB,EACjB,SAAoB;IAEpB,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAClD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAqB,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -7,7 +7,9 @@ export type { Client } from "./Client.js";
 export { once } from "./once.js";
 export type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 export { createImport, isClientImport, type ClientImport, } from "./ClientImport.js";
+export type { ClientModule } from "./ClientModule.js";
 export type { Bundle } from "./Bundle.js";
 export { exec, isClientExec, type ClientExec } from "./exec.js";
 export { createJsxElement, isJsxElement, type JsxElement, type JsxElementOf, type JsxElementTypeOf, } from "./JsxElement.js";
-export { create, type ClientModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";
+export { create, type ScriptModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";
+export { modulesOf, type ModuleMap } from "./modulesOf.js";

package/dist/index.js

@@ -8,10 +8,13 @@ export { cs } from "./cs.js";
 export { once } from "./once.js";
 export { createImport, isClientImport, } from "./ClientImport.js";
 export { exec, isClientExec } from "./exec.js";
-// A drawing as a host builds one: what an adapter's JSX runtime makes, and
+// A drawing as a host builds one: what a JSX package's runtime makes, and
 // what the bundler expands.
 export { createJsxElement, isJsxElement, } from "./JsxElement.js";
 // What a template compiles to: the compiler writes one and the bundler reads
 // it, so the shape is neither end's.
 export { create, isClientScript, } from "./ClientScript.js";
+// What an app provides bundles, and what it sends its server for them: the
+// modules it offers, at its packages' versions.
+export { modulesOf } from "./modulesOf.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,wCAAwC;AACxC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EACL,YAAY,EACZ,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAEhE,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EACL,gBAAgB,EAChB,YAAY,GAIb,MAAM,iBAAiB,CAAC;AAEzB,6EAA6E;AAC7E,qCAAqC;AACrC,OAAO,EACL,MAAM,EAGN,cAAc,GAEf,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,wCAAwC;AACxC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EACL,YAAY,EACZ,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAEhE,0EAA0E;AAC1E,4BAA4B;AAC5B,OAAO,EACL,gBAAgB,EAChB,YAAY,GAIb,MAAM,iBAAiB,CAAC;AAEzB,6EAA6E;AAC7E,qCAAqC;AACrC,OAAO,EACL,MAAM,EAGN,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B,2EAA2E;AAC3E,gDAAgD;AAChD,OAAO,EAAE,SAAS,EAAkB,MAAM,gBAAgB,CAAC"}

package/dist/modulesOf.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a bundle may import, by specifier: each the module the app imported
+ * for it. What a web page's import map does, for an app, with modules for
+ * values instead of URLs:
+ *
+ *     import * as React from "react";
+ *     import * as JSXRuntime from "react/jsx-runtime";
+ *     import * as ReactNative from "react-native";
+ *
+ *     export const moduleMap = {
+ *       react: React,
+ *       "react/jsx-runtime": JSXRuntime,
+ *       "react-native": ReactNative,
+ *     };
+ */
+export type ModuleMap = Readonly<Record<string, unknown>>;
+/**
+ * The modules `moduleMap` offers, each at the version in `packages` of the
+ * package it comes from: what the app sends however it reaches its server, a
+ * header, a GraphQL variable, for the server to bundle screens it can run.
+ * An Expo app passes them from its config, where `app.config.ts` puts
+ * `installedPackages(projectRoot)`. Throws as the app starts without them, or
+ * for a module from a package that isn't a dependency.
+ *
+ *     const modules = modulesOf(
+ *       moduleMap,
+ *       Constants.expoConfig?.extra?.backtick?.packages,
+ *     );
+ */
+export declare function modulesOf(moduleMap: ModuleMap, packages: Readonly<Record<string, string>> | null | undefined): Record<string, string>;

package/dist/modulesOf.js

@@ -0,0 +1,31 @@
+// The package a module specifier is in: `react` for `react/jsx-runtime`.
+function packageOf(specifier) {
+    const segments = specifier.split("/");
+    return segments.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+}
+/**
+ * The modules `moduleMap` offers, each at the version in `packages` of the
+ * package it comes from: what the app sends however it reaches its server, a
+ * header, a GraphQL variable, for the server to bundle screens it can run.
+ * An Expo app passes them from its config, where `app.config.ts` puts
+ * `installedPackages(projectRoot)`. Throws as the app starts without them, or
+ * for a module from a package that isn't a dependency.
+ *
+ *     const modules = modulesOf(
+ *       moduleMap,
+ *       Constants.expoConfig?.extra?.backtick?.packages,
+ *     );
+ */
+export function modulesOf(moduleMap, packages) {
+    if (packages == null) {
+        throw new Error("No packages: does app.config.ts put installedPackages(projectRoot) in the config's extra?");
+    }
+    return Object.fromEntries(Object.keys(moduleMap).map((specifier) => {
+        const version = packages[packageOf(specifier)];
+        if (version === undefined) {
+            throw new Error(`The module map offers ${JSON.stringify(specifier)}, but ${packageOf(specifier)} isn't in package.json's dependencies.`);
+        }
+        return [specifier, version];
+    }));
+}
+//# sourceMappingURL=modulesOf.js.map

package/dist/modulesOf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modulesOf.js","sourceRoot":"","sources":["../src/modulesOf.ts"],"names":[],"mappings":"AAiBA,yEAAyE;AACzE,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACvB,SAAoB,EACpB,QAA6D;IAE7D,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,SAAS,CAAC,SAAS,CAAC,wCAAwC,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The installed version of each of the app's dependencies, at `projectRoot`:
+ * what a build made from it now carries there, for `modulesOf`. Node only: an
+ * Expo app calls it from `app.config.ts`, and passes it on in the config.
+ *
+ *     export default ({ config, projectRoot }: ConfigContext) => ({
+ *       ...config,
+ *       extra: {
+ *         ...config.extra,
+ *         backtick: { packages: installedPackages(projectRoot) },
+ *       },
+ *     });
+ */
+export declare function installedPackages(projectRoot: string): Record<string, string>;

package/dist/node.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// Where a package is installed for the app at `projectRoot`, as Node finds
+// it: in its node_modules, or the nearest above, as a workspace hoists it.
+function installed(projectRoot, name) {
+    for (let directory = projectRoot;; directory = dirname(directory)) {
+        const file = join(directory, "node_modules", name, "package.json");
+        if (existsSync(file))
+            return file;
+        if (dirname(directory) === directory) {
+            throw new Error(`${projectRoot}: ${name} isn't installed`);
+        }
+    }
+}
+/**
+ * The installed version of each of the app's dependencies, at `projectRoot`:
+ * what a build made from it now carries there, for `modulesOf`. Node only: an
+ * Expo app calls it from `app.config.ts`, and passes it on in the config.
+ *
+ *     export default ({ config, projectRoot }: ConfigContext) => ({
+ *       ...config,
+ *       extra: {
+ *         ...config.extra,
+ *         backtick: { packages: installedPackages(projectRoot) },
+ *       },
+ *     });
+ */
+export function installedPackages(projectRoot) {
+    const { dependencies = {} } = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+    return Object.fromEntries(Object.keys(dependencies).map((name) => [
+        name,
+        JSON.parse(readFileSync(installed(projectRoot, name), "utf8")).version,
+    ]));
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,SAAS,CAAC,WAAmB,EAAE,IAAY;IAClD,KAAK,IAAI,SAAS,GAAG,WAAW,GAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACnE,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,KAAK,IAAI,kBAAkB,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CACtC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CACX,CAAC;IAC/C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI;QAEF,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAG9D,CAAC,OAAO;KACV,CAAC,CACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "description": "The cs tag for Backtick client scripts, and the types for the values that cross from server to client",
   "keywords": [
     "backtick",
@@ -36,6 +36,10 @@
     "./es": {
       "types": "./dist/es.d.ts",
       "default": "./dist/es.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
     }
   },
   "files": [

package/src/ClientImport.ts

@@ -2,14 +2,16 @@ import type { Client } from "./Client.js";
 
 /**
  * An export of a module the client provides, held as a value: what a script
- * splices to use it, and what a bundle imports it by.
+ * splices to use it, and what a bundle imports it by. The compiler writes one
+ * per name of `import { View } from "react-native" with { backtick: "client" }`.
  */
 export interface ClientImport<T> extends Client<T> {
   readonly "@backtickjs": "ClientImport";
+  // the export, or `*` for the module's namespace
   readonly name: string;
   // the specifier the client resolves
   readonly from: string;
-  // the versions of `from`'s package it works with, a semver range
+  // the exact version of `from`'s package it's typed against
   readonly version: string;
 }
 

package/src/ClientModule.ts

@@ -0,0 +1,7 @@
+import type { Client } from "./Client.js";
+
+/**
+ * A module's exports as client imports, each typed by its declaration: what
+ * the editor checks the names of a client import against.
+ */
+export type ClientModule<M> = { readonly [Name in keyof M]: Client<M[Name]> };

package/src/ClientScript.ts

@@ -10,7 +10,7 @@ export type Param =
   | { kind: "capture"; key: string };
 
 // The compiled code of one `cs`, shared by every script it creates.
-export interface ClientModule {
+export interface ScriptModule {
   // `<fileHash>:<line>:<column>` of the `cs`. The hash keeps ids from two
   // files apart: they match only when the files are identical.
   readonly id: string;
@@ -35,7 +35,7 @@ export interface ClientModule {
 // flag reads the same.
 export interface ClientScript {
   readonly "@backtickjs": "ClientScript";
-  readonly module: ClientModule;
+  readonly module: ScriptModule;
   // one per splice, in parameter order
   readonly args: readonly Spliceable[];
   // one value for the bundle, made at its top, rather than code run at each
@@ -53,7 +53,7 @@ export function isClientScript(value: unknown): value is ClientScript {
 }
 
 export function create(
-  module: ClientModule,
+  module: ScriptModule,
   args: readonly Spliceable[],
 ): ClientScript {
   return { "@backtickjs": "ClientScript", module, args };

package/src/JsxElement.ts

@@ -3,8 +3,8 @@ import type { Client } from "./Client.js";
 /**
  * What a JSX tag evaluates to on the server, before bundling resolves it: the
  * tag and its props, which are the server's own. What a drawing is, is the
- * adapter's; this is what the bundler expands. A client value, of the type its
- * adapter names (Solid's: its element), so a host may hand one over wherever
+ * JSX package's; this is what the bundler expands. A client value, of the type
+ * its JSX package names (Solid's: its element), so a host may hand one over wherever
  * a drawing may stand.
  */
 export interface JsxElement extends Client<unknown> {
@@ -29,7 +29,7 @@ export function createJsxElement(
   return { "@backtickjs": "JsxElement", type, props } as JsxElement;
 }
 
-// What an adapter's JSX namespace types its `Element` and `ElementType` as,
+// What a JSX package's namespace types its `Element` and `ElementType` as,
 // given what its framework draws (Solid's `JSX.Element`, React's `ReactNode`).
 // One namespace types both a host's JSX and a script's, so each type answers
 // for both sides.

package/src/cjs.ts

@@ -1,7 +1,5 @@
 import type { Bundle } from "./Bundle.js";
-import type { ModuleMap } from "./ModuleMap.js";
-
-export type { ModuleMap };
+import type { ModuleMap } from "./modulesOf.js";
 
 /**
  * Executes a CommonJS bundle an app starts from, the one nothing else runs,

package/src/index.ts

@@ -17,13 +17,14 @@ export {
   isClientImport,
   type ClientImport,
 } from "./ClientImport.js";
+export type { ClientModule } from "./ClientModule.js";
 // A bundle's code, typed by what it runs to, and, in a script, executing
 // another as this one was. The one an app starts from is executed by
 // `@backtickjs/core/cjs` or `@backtickjs/core/es`.
 export type { Bundle } from "./Bundle.js";
 export { exec, isClientExec, type ClientExec } from "./exec.js";
 
-// A drawing as a host builds one: what an adapter's JSX runtime makes, and
+// A drawing as a host builds one: what a JSX package's runtime makes, and
 // what the bundler expands.
 export {
   createJsxElement,
@@ -37,8 +38,12 @@ export {
 // it, so the shape is neither end's.
 export {
   create,
-  type ClientModule,
+  type ScriptModule,
   type ClientScript,
   isClientScript,
   type Param,
 } from "./ClientScript.js";
+
+// What an app provides bundles, and what it sends its server for them: the
+// modules it offers, at its packages' versions.
+export { modulesOf, type ModuleMap } from "./modulesOf.js";

package/src/modulesOf.ts

@@ -0,0 +1,57 @@
+/**
+ * What a bundle may import, by specifier: each the module the app imported
+ * for it. What a web page's import map does, for an app, with modules for
+ * values instead of URLs:
+ *
+ *     import * as React from "react";
+ *     import * as JSXRuntime from "react/jsx-runtime";
+ *     import * as ReactNative from "react-native";
+ *
+ *     export const moduleMap = {
+ *       react: React,
+ *       "react/jsx-runtime": JSXRuntime,
+ *       "react-native": ReactNative,
+ *     };
+ */
+export type ModuleMap = Readonly<Record<string, unknown>>;
+
+// The package a module specifier is in: `react` for `react/jsx-runtime`.
+function packageOf(specifier: string): string {
+  const segments = specifier.split("/");
+  return segments.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+}
+
+/**
+ * The modules `moduleMap` offers, each at the version in `packages` of the
+ * package it comes from: what the app sends however it reaches its server, a
+ * header, a GraphQL variable, for the server to bundle screens it can run.
+ * An Expo app passes them from its config, where `app.config.ts` puts
+ * `installedPackages(projectRoot)`. Throws as the app starts without them, or
+ * for a module from a package that isn't a dependency.
+ *
+ *     const modules = modulesOf(
+ *       moduleMap,
+ *       Constants.expoConfig?.extra?.backtick?.packages,
+ *     );
+ */
+export function modulesOf(
+  moduleMap: ModuleMap,
+  packages: Readonly<Record<string, string>> | null | undefined,
+): Record<string, string> {
+  if (packages == null) {
+    throw new Error(
+      "No packages: does app.config.ts put installedPackages(projectRoot) in the config's extra?",
+    );
+  }
+  return Object.fromEntries(
+    Object.keys(moduleMap).map((specifier) => {
+      const version = packages[packageOf(specifier)];
+      if (version === undefined) {
+        throw new Error(
+          `The module map offers ${JSON.stringify(specifier)}, but ${packageOf(specifier)} isn't in package.json's dependencies.`,
+        );
+      }
+      return [specifier, version];
+    }),
+  );
+}

package/src/node.ts

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// Where a package is installed for the app at `projectRoot`, as Node finds
+// it: in its node_modules, or the nearest above, as a workspace hoists it.
+function installed(projectRoot: string, name: string): string {
+  for (let directory = projectRoot; ; directory = dirname(directory)) {
+    const file = join(directory, "node_modules", name, "package.json");
+    if (existsSync(file)) return file;
+    if (dirname(directory) === directory) {
+      throw new Error(`${projectRoot}: ${name} isn't installed`);
+    }
+  }
+}
+
+/**
+ * The installed version of each of the app's dependencies, at `projectRoot`:
+ * what a build made from it now carries there, for `modulesOf`. Node only: an
+ * Expo app calls it from `app.config.ts`, and passes it on in the config.
+ *
+ *     export default ({ config, projectRoot }: ConfigContext) => ({
+ *       ...config,
+ *       extra: {
+ *         ...config.extra,
+ *         backtick: { packages: installedPackages(projectRoot) },
+ *       },
+ *     });
+ */
+export function installedPackages(projectRoot: string): Record<string, string> {
+  const { dependencies = {} } = JSON.parse(
+    readFileSync(join(projectRoot, "package.json"), "utf8"),
+  ) as { dependencies?: Record<string, string> };
+  return Object.fromEntries(
+    Object.keys(dependencies).map((name) => [
+      name,
+      (
+        JSON.parse(readFileSync(installed(projectRoot, name), "utf8")) as {
+          version: string;
+        }
+      ).version,
+    ]),
+  );
+}

package/dist/ModuleMap.d.ts

@@ -1,16 +0,0 @@
-/**
- * What a bundle may import, by specifier: each the module the app imported
- * for it. What a web page's import map does, for an app, with modules for
- * values instead of URLs:
- *
- *     import * as React from "react";
- *     import * as JSXRuntime from "react/jsx-runtime";
- *     import * as ReactNative from "react-native";
- *
- *     export const moduleMap = {
- *       react: React,
- *       "react/jsx-runtime": JSXRuntime,
- *       "react-native": ReactNative,
- *     };
- */
-export type ModuleMap = Readonly<Record<string, unknown>>;

package/dist/ModuleMap.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=ModuleMap.js.map

package/dist/ModuleMap.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ModuleMap.js","sourceRoot":"","sources":["../src/ModuleMap.ts"],"names":[],"mappings":""}

package/src/ModuleMap.ts

@@ -1,16 +0,0 @@
-/**
- * What a bundle may import, by specifier: each the module the app imported
- * for it. What a web page's import map does, for an app, with modules for
- * values instead of URLs:
- *
- *     import * as React from "react";
- *     import * as JSXRuntime from "react/jsx-runtime";
- *     import * as ReactNative from "react-native";
- *
- *     export const moduleMap = {
- *       react: React,
- *       "react/jsx-runtime": JSXRuntime,
- *       "react-native": ReactNative,
- *     };
- */
-export type ModuleMap = Readonly<Record<string, unknown>>;