@backtickjs/core 0.1.10 → 0.2.0

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 }) => {
@@ -36,33 +36,27 @@ export async function Home() {
 }
 ```
 
-`$node` and `$Counter` are splices: `node` is a server variable, written into the bundle as data; `Counter` is a script. `$useState` is a splice too, of an export the client provides. What can be spliced is `Spliceable`: data, and scripts. [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick) has what can cross, what can't, and how server and client components compose.
+`$node` and `$Counter` are splices: `node` is a server variable, written into the bundle as data; `Counter` is a script. `$useState` is a splice too, of an export the client provides. What can be spliced is `Spliceable`: data, and scripts. [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick/) has what can cross, what can't, and how server and client components compose.
 
 A script every component shares, like a context or a store, is made once with `once`: one value for the bundle, where an expression script would run again at each read.
 
 ```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.
 
 ## API
 
@@ -73,17 +67,22 @@ The client must provide that package, and the server must list it in the bundler
 - `Spliced<T>`: what a spliceable value becomes on the client (`Client<U>` becomes `U`; arrays and objects map member by member).
 - `createImport<T>({ name, from, version })`: an export of a module the client provides, as a value a script can splice.
 - `isClientImport`, `ClientImport`: its check and type.
+- `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()`.
+- `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)
+- [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick/), [Scripts in depth](https://backtickjs.com/docs/scripts-in-depth/)
 
 ## License
 

package/dist/Bundle.d.ts

@@ -0,0 +1,9 @@
+declare const value: unique symbol;
+/**
+ * A bundle's code, which runs to a `T`: what the bundler writes for a
+ * `Client<T>`, as it reaches the client, from the server.
+ */
+export type Bundle<T> = string & {
+    readonly [value]: T;
+};
+export {};

package/dist/Bundle.js

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

package/dist/Bundle.js.map

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

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,19 +6,19 @@ export type Param = {
     kind: "capture";
     key: string;
 };
-export interface ClientModule {
+export interface ScriptModule {
     readonly id: string;
     readonly code: string;
     readonly map: string;
     readonly dependencies: readonly string[];
     readonly params: readonly Param[];
-    readonly kind: "function" | "expression" | "block";
+    readonly kind: "function" | "class" | "expression" | "block";
 }
 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/ClientScript.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AA4CA,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,MAAM,UAAU,MAAM,CACpB,MAAoB,EACpB,IAA2B;IAE3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC"}
+{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AA6CA,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,MAAM,UAAU,MAAM,CACpB,MAAoB,EACpB,IAA2B;IAE3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC"}

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/ModuleMap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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

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

package/dist/ModuleMap.js.map

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

package/dist/Spliceable.d.ts

@@ -20,6 +20,6 @@ export type SplicesAs<T> = [T] extends [Spliceable] ? T : T extends (...args: ne
 };
 export type Spliced<T> = T extends Client<infer U> ? U : T extends readonly (infer Item extends Spliceable)[] ? number extends T["length"] ? Spliced<Item>[] : {
     -readonly [K in keyof T]: Spliced<T[K]>;
-} : T extends object ? {
+} : T extends string | number | bigint | boolean ? T : T extends object ? {
     -readonly [K in keyof T]: Spliced<T[K]>;
 } : T;

package/dist/cjs.d.ts

@@ -0,0 +1,14 @@
+import type { Bundle } from "./Bundle.js";
+import type { ModuleMap } from "./ModuleMap.js";
+export type { ModuleMap };
+/**
+ * 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
+ * app runs what its server answers. The bundles it runs in turn, with `exec`,
+ * get the same modules. Fetching the bundle, and when, is the app's. The
+ * entry an app imports is its format: a web page imports
+ * `@backtickjs/core/es`.
+ *
+ *     const screen = await execRoot(bundle, moduleMap);
+ */
+export declare function execRoot<T>(bundle: Bundle<T>, moduleMap: ModuleMap): Promise<Awaited<T>>;

package/dist/cjs.js

@@ -0,0 +1,22 @@
+/**
+ * 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
+ * app runs what its server answers. The bundles it runs in turn, with `exec`,
+ * get the same modules. Fetching the bundle, and when, is the app's. The
+ * entry an app imports is its format: a web page imports
+ * `@backtickjs/core/es`.
+ *
+ *     const screen = await execRoot(bundle, moduleMap);
+ */
+export async function execRoot(bundle, moduleMap) {
+    const require = (specifier) => {
+        if (!Object.hasOwn(moduleMap, specifier)) {
+            throw new Error(`The bundle requires "${specifier}", which this app doesn't provide.`);
+        }
+        return moduleMap[specifier];
+    };
+    const module = { exports: {} };
+    new Function("module", "exports", "require", bundle)(module, module.exports, require);
+    return module.exports;
+}
+//# sourceMappingURL=cjs.js.map

package/dist/cjs.js.map

@@ -0,0 +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"}

package/dist/es.d.ts

@@ -0,0 +1,11 @@
+import type { Bundle } from "./Bundle.js";
+/**
+ * Executes an ES bundle a web page starts from, the one nothing else runs, to
+ * its value: imported from a `data:` URL, the page's import map answering its
+ * imports, and those of the bundles it runs in turn with `exec`. Apart from
+ * `@backtickjs/core/cjs`, so a React Native app never reads its `import()`:
+ * Metro rejects one of anything but a string literal, and Hermes has none.
+ *
+ *     const screen = await execRoot(bundle);
+ */
+export declare function execRoot<T>(bundle: Bundle<T>): Promise<Awaited<T>>;

package/dist/es.js

@@ -0,0 +1,14 @@
+/**
+ * Executes an ES bundle a web page starts from, the one nothing else runs, to
+ * its value: imported from a `data:` URL, the page's import map answering its
+ * imports, and those of the bundles it runs in turn with `exec`. Apart from
+ * `@backtickjs/core/cjs`, so a React Native app never reads its `import()`:
+ * Metro rejects one of anything but a string literal, and Hermes has none.
+ *
+ *     const screen = await execRoot(bundle);
+ */
+export async function execRoot(bundle) {
+    const module = (await import("data:text/javascript," + encodeURIComponent(bundle)));
+    return module.default;
+}
+//# sourceMappingURL=es.js.map

package/dist/es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"es.js","sourceRoot":"","sources":["../src/es.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,MAAiB;IACjD,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAC1B,uBAAuB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CACrD,CAA4B,CAAC;IAC9B,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC"}

package/dist/exec.d.ts

@@ -0,0 +1,14 @@
+import type { Bundle } from "./Bundle.js";
+import type { Client } from "./Client.js";
+/**
+ * Executes a bundle on the client, as the bundle reading it was run, with the
+ * same modules, and resolves to its value: what a script fetched at runtime
+ * from the server, which the bundler couldn't see. As CommonJS, a function of
+ * `require`, handed the bundle's own; as an ES module, imported from a `data:`
+ * URL, which the page's import map answers.
+ */
+export interface ClientExec extends Client<(<T>(bundle: Bundle<T>) => Promise<Awaited<T>>)> {
+    readonly "@backtickjs": "ClientExec";
+}
+export declare const exec: Client<(<T>(bundle: Bundle<T>) => Promise<Awaited<T>>)>;
+export declare function isClientExec(value: unknown): value is ClientExec;

package/dist/exec.js

@@ -0,0 +1,10 @@
+export const exec = {
+    "@backtickjs": "ClientExec",
+};
+export function isClientExec(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "@backtickjs" in value &&
+        value["@backtickjs"] === "ClientExec");
+}
+//# sourceMappingURL=exec.js.map

package/dist/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,IAAI,GAA0D;IACzE,aAAa,EAAE,YAAY;CACH,CAAC;AAE3B,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK,YAAY,CACtC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -7,5 +7,8 @@ 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";

package/dist/index.js

@@ -7,7 +7,8 @@
 export { cs } from "./cs.js";
 export { once } from "./once.js";
 export { createImport, isClientImport, } from "./ClientImport.js";
-// A drawing as a host builds one: what an adapter's JSX runtime makes, and
+export { exec, isClientExec } from "./exec.js";
+// 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

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;AAE3B,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "The cs tag for Backtick client scripts, and the types for the values that cross from server to client",
   "keywords": [
     "backtick",
@@ -28,6 +28,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./cjs": {
+      "types": "./dist/cjs.d.ts",
+      "default": "./dist/cjs.js"
+    },
+    "./es": {
+      "types": "./dist/es.d.ts",
+      "default": "./dist/es.js"
     }
   },
   "files": [

package/src/Bundle.ts

@@ -0,0 +1,7 @@
+declare const value: unique symbol;
+
+/**
+ * A bundle's code, which runs to a `T`: what the bundler writes for a
+ * `Client<T>`, as it reaches the client, from the server.
+ */
+export type Bundle<T> = string & { readonly [value]: T };

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;
@@ -24,8 +24,9 @@ export interface ClientModule {
   // `params[i]` is the function's `$splice<i>` or `$capture<i>`
   readonly params: readonly Param[];
   // What the script is written as: a function, `(props) => …`, which a splice
-  // reads as that function; or an expression or a block, which a splice runs.
-  readonly kind: "function" | "expression" | "block";
+  // reads as that function; a class, `class … {}`, one class for the bundle;
+  // or an expression or a block, which a splice runs.
+  readonly kind: "function" | "class" | "expression" | "block";
 }
 
 // One run of a `cs`: its module, and the values that run passes it. The rest
@@ -34,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
@@ -52,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/ModuleMap.ts

@@ -0,0 +1,16 @@
+/**
+ * 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/src/Spliceable.ts

@@ -34,7 +34,7 @@ export type SplicesAs<T> = [T] extends [Spliceable]
 //   Client<U>                 -> U
 //   T[], [A, B]               -> Spliced<T>[], [Spliced<A>, Spliced<B>]
 //   { k: T }                  -> { k: Spliced<T> }
-//   primitives                -> unchanged
+//   primitives                -> unchanged, branded ones too e.g. `Bundle<T>`
 // A tuple maps homomorphically, which keeps it a tuple; any other array stays
 // `Spliced<Item>[]`, which TypeScript defers, so `Spliceable[]` doesn't recurse.
 export type Spliced<T> =
@@ -44,6 +44,8 @@ export type Spliced<T> =
       ? number extends T["length"]
         ? Spliced<Item>[]
         : { -readonly [K in keyof T]: Spliced<T[K]> }
-      : T extends object
-        ? { -readonly [K in keyof T]: Spliced<T[K]> }
-        : T;
+      : T extends string | number | bigint | boolean
+        ? T
+        : T extends object
+          ? { -readonly [K in keyof T]: Spliced<T[K]> }
+          : T;

package/src/cjs.ts

@@ -0,0 +1,35 @@
+import type { Bundle } from "./Bundle.js";
+import type { ModuleMap } from "./ModuleMap.js";
+
+export type { ModuleMap };
+
+/**
+ * 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
+ * app runs what its server answers. The bundles it runs in turn, with `exec`,
+ * get the same modules. Fetching the bundle, and when, is the app's. The
+ * entry an app imports is its format: a web page imports
+ * `@backtickjs/core/es`.
+ *
+ *     const screen = await execRoot(bundle, moduleMap);
+ */
+export async function execRoot<T>(
+  bundle: Bundle<T>,
+  moduleMap: ModuleMap,
+): Promise<Awaited<T>> {
+  const require = (specifier: string): unknown => {
+    if (!Object.hasOwn(moduleMap, specifier)) {
+      throw new Error(
+        `The bundle requires "${specifier}", which this app doesn't provide.`,
+      );
+    }
+    return moduleMap[specifier];
+  };
+  const module = { exports: {} as unknown };
+  new Function("module", "exports", "require", bundle)(
+    module,
+    module.exports,
+    require,
+  );
+  return module.exports as Awaited<T>;
+}

package/src/es.ts

@@ -0,0 +1,17 @@
+import type { Bundle } from "./Bundle.js";
+
+/**
+ * Executes an ES bundle a web page starts from, the one nothing else runs, to
+ * its value: imported from a `data:` URL, the page's import map answering its
+ * imports, and those of the bundles it runs in turn with `exec`. Apart from
+ * `@backtickjs/core/cjs`, so a React Native app never reads its `import()`:
+ * Metro rejects one of anything but a string literal, and Hermes has none.
+ *
+ *     const screen = await execRoot(bundle);
+ */
+export async function execRoot<T>(bundle: Bundle<T>): Promise<Awaited<T>> {
+  const module = (await import(
+    "data:text/javascript," + encodeURIComponent(bundle)
+  )) as { default: Awaited<T> };
+  return module.default;
+}

package/src/exec.ts

@@ -0,0 +1,28 @@
+import type { Bundle } from "./Bundle.js";
+import type { Client } from "./Client.js";
+
+/**
+ * Executes a bundle on the client, as the bundle reading it was run, with the
+ * same modules, and resolves to its value: what a script fetched at runtime
+ * from the server, which the bundler couldn't see. As CommonJS, a function of
+ * `require`, handed the bundle's own; as an ES module, imported from a `data:`
+ * URL, which the page's import map answers.
+ */
+export interface ClientExec extends Client<
+  <T>(bundle: Bundle<T>) => Promise<Awaited<T>>
+> {
+  readonly "@backtickjs": "ClientExec";
+}
+
+export const exec: Client<<T>(bundle: Bundle<T>) => Promise<Awaited<T>>> = {
+  "@backtickjs": "ClientExec",
+} as unknown as ClientExec;
+
+export function isClientExec(value: unknown): value is ClientExec {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "@backtickjs" in value &&
+    value["@backtickjs"] === "ClientExec"
+  );
+}

package/src/index.ts

@@ -17,8 +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,
@@ -32,7 +38,7 @@ export {
 // it, so the shape is neither end's.
 export {
   create,
-  type ClientModule,
+  type ScriptModule,
   type ClientScript,
   isClientScript,
   type Param,