@backtickjs/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-François Bisson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @backtickjs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Install
+
+```sh
+npm install @backtickjs/core
+```
+
+## Usage
+
+A server component reads data on the server and returns a client script. A client component is a script written as an arrow function, used as a `<$Name>` tag:
+
+```tsx
+import { cs } from "@backtickjs/core";
+import { useState } from "@backtickjs/react";
+
+// A client component: it runs on the client.
+const Counter = cs`(props: { start: number }) => {
+  const [count, setCount] = $useState(props.start);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}`;
+
+// A server component: it runs on your server for every request.
+export async function Home() {
+  const node = process.version;
+  return cs`(
+    <main>
+      <p>Assembled with Node {$node}.</p>
+      <$Counter start={3} />
+    </main>
+  )`;
+}
+```
+
+`$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. A server component is drawn inside a script through a splice: `{${<Footer />}}`.
+
+What can be spliced is `Spliceable`: strings, numbers, booleans, `null`, `undefined`, plain arrays and objects of those, and scripts. Host functions and class instances can't be spliced; a function the client calls is written as a script, `` cs`(n: number) => …` ``.
+
+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:
+
+```ts
+import { createImport } from "@backtickjs/core";
+
+const greet = createImport<() => string>({
+  name: "greet",
+  from: "my-native-module",
+  version: "^1.0.0",
+});
+// In a script: cs`<p>{$greet()}</p>`
+```
+
+The client must provide that package, and the server must list it in the bundler's `packageVersions` at a version in that range.
+
+## API
+
+- `cs`: the tag for client scripts. Compiled at build time; throws if called uncompiled.
+- `Client<T>`: the type of a script that stands for a `T` on the client.
+- `Spliceable`: what a server may splice into a script.
+- `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.
+- `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.
+
+## 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/packages/react), [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/packages/react-native), [`@backtickjs/solid-js`](https://github.com/backtickjs/backtick/tree/main/packages/solid-js): framework adapters
+- [`@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
+- [Documentation](https://backtickjs.com/docs)
+
+## License
+
+MIT

package/dist/Client.d.ts

@@ -0,0 +1,5 @@
+declare const ClientBrand: unique symbol;
+export interface Client<T> {
+    readonly [ClientBrand]: T;
+}
+export {};

package/dist/Client.js

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

package/dist/Client.js.map

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

package/dist/ClientImport.d.ts

@@ -0,0 +1,17 @@
+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.
+ */
+export interface ClientImport<T> extends Client<T> {
+    readonly "@backtickjs": "ClientImport";
+    readonly name: string;
+    readonly from: string;
+    readonly version: string;
+}
+export declare function isClientImport(value: unknown): value is ClientImport<unknown>;
+export declare function createImport<T>({ name, from, version, }: {
+    name: string;
+    from: string;
+    version: string;
+}): Client<T>;

package/dist/ClientImport.js

@@ -0,0 +1,17 @@
+export function isClientImport(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "@backtickjs" in value &&
+        value["@backtickjs"] === "ClientImport");
+}
+// `T` is what the module's own declarations say the export is; nothing here
+// can check the two agree, and the module the client resolves is what does.
+export function createImport({ name, from, version, }) {
+    return {
+        "@backtickjs": "ClientImport",
+        name,
+        from,
+        version,
+    };
+}
+//# sourceMappingURL=ClientImport.js.map

package/dist/ClientImport.js.map

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

package/dist/ClientScript.d.ts

@@ -0,0 +1,22 @@
+import type { Spliceable } from "./Spliceable.js";
+export type Param = {
+    kind: "splice";
+    bindings: readonly string[];
+} | {
+    kind: "capture";
+    key: string;
+};
+export interface ClientModule {
+    readonly id: string;
+    readonly code: string;
+    readonly map: string;
+    readonly dependencies: readonly string[];
+    readonly params: readonly Param[];
+}
+export interface ClientScript {
+    readonly "@backtickjs": "ClientScript";
+    readonly module: ClientModule;
+    readonly args: readonly Spliceable[];
+}
+export declare function isClientScript(value: unknown): value is ClientScript;
+export declare function create(module: ClientModule, args: readonly Spliceable[]): ClientScript;

package/dist/ClientScript.js

@@ -0,0 +1,10 @@
+export function isClientScript(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "@backtickjs" in value &&
+        value["@backtickjs"] === "ClientScript");
+}
+export function create(module, args) {
+    return { "@backtickjs": "ClientScript", module, args };
+}
+//# sourceMappingURL=ClientScript.js.map

package/dist/ClientScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AAmCA,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

@@ -0,0 +1,28 @@
+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
+ * a drawing may stand.
+ */
+export interface JsxElement extends Client<unknown> {
+    readonly "@backtickjs": "JsxElement";
+    readonly type: string | ((props: never) => unknown);
+    readonly props: unknown;
+}
+export declare function isJsxElement(value: unknown): value is JsxElement;
+export declare function createJsxElement(type: string | ((props: never) => unknown), props: unknown): JsxElement;
+/**
+ * A JSX expression: in a script, what the framework draws, so it fits the
+ * framework's slots; on the host, a client value standing for it, so it
+ * splices.
+ */
+export type JsxElementOf<T> = T & Client<T>;
+/**
+ * What a tag may name: an intrinsic element; a component as a script sees it,
+ * answering what the framework draws (a client component, or a server
+ * component lowered); or a server component on the host, answering a script
+ * that draws, or nothing.
+ */
+export type JsxElementTypeOf<T> = string | ((props: never) => T) | ((props: never) => Client<T> | null | Promise<Client<T> | null>);

package/dist/JsxElement.js

@@ -0,0 +1,10 @@
+export function isJsxElement(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "@backtickjs" in value &&
+        value["@backtickjs"] === "JsxElement");
+}
+export function createJsxElement(type, props) {
+    return { "@backtickjs": "JsxElement", type, props };
+}
+//# sourceMappingURL=JsxElement.js.map

package/dist/JsxElement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsxElement.js","sourceRoot":"","sources":["../src/JsxElement.ts"],"names":[],"mappings":"AAeA,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;AAED,MAAM,UAAU,gBAAgB,CAC9B,IAA0C,EAC1C,KAAc;IAEd,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAgB,CAAC;AACpE,CAAC"}

package/dist/Spliceable.d.ts

@@ -0,0 +1,15 @@
+import type { Client } from "./Client.js";
+/**
+ * What the host may splice: the value written out, a script standing in for
+ * it, or a container mixing the two. Not a host function, which is host code:
+ * a client function is a script, cs`(n: number) => …`. An index signature rather than a mapped
+ * type, so it can be named in a `satisfies` without a type to walk.
+ */
+export type Spliceable = Client<unknown> | null | undefined | number | boolean | string | readonly Spliceable[] | {
+    readonly [key: string]: Spliceable;
+};
+export type Spliced<T> = T extends Client<infer U> ? U : T extends readonly (infer Item extends Spliceable)[] ? Spliced<Item>[] : T extends {
+    readonly [key: string]: Spliceable;
+} ? {
+    -readonly [K in keyof T]: Spliced<T[K]>;
+} : T;

package/dist/Spliceable.js

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

package/dist/Spliceable.js.map

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

package/dist/cs.d.ts

@@ -0,0 +1,23 @@
+import type { Client } from "./Client.js";
+import { create } from "./ClientScript.js";
+import type { Spliceable } from "./Spliceable.js";
+import type { Spliced } from "./Spliceable.js";
+declare function lift<T>(_: T): Client<T>;
+declare function splice<T extends [T] extends [Spliceable] ? unknown : Spliceable>(_: T): unknown extends Spliced<T> ? any : Spliced<T>;
+/**
+ * The globals a project declares — its libs, `@types`, a `declare global` —
+ * as an ordinary object type: reading one it doesn't declare is an error
+ * however strict the project is, where `typeof globalThis` itself lets it
+ * through as `any` without `noImplicitAny`.
+ */
+export type GlobalThis = {
+    [Key in keyof typeof globalThis]: (typeof globalThis)[Key];
+};
+export declare const cs: ((_strings: TemplateStringsArray, ..._values: unknown[]) => Client<unknown>) & {
+    create: typeof create;
+    lift: typeof lift;
+    splice: typeof splice;
+} & {
+    readonly globalThis: GlobalThis;
+};
+export {};

package/dist/cs.js

@@ -0,0 +1,27 @@
+import { create } from "./ClientScript.js";
+// The root of a script
+function lift(_) {
+    throw new Error("Don't call `cs.lift` directly; it's used to generate virtual " +
+        "code for the typechecker. Write code using cs`...` instead.");
+}
+// A constraint that is `unknown` for a value that splices, rather than
+// `Spliceable` itself or an intersection with it: either of those keeps a
+// literal a literal instead of widening it. What can't be spliced is refused
+// once, where it is written, and is `any` after: refused, `T` falls back to
+// `Spliceable`, which splices to `unknown`.
+function splice(_) {
+    throw new Error("Don't call `cs.splice` directly; it's used to generate virtual " +
+        "code for the typechecker. Write code using cs`...` instead.");
+}
+// What hangs off the tag.
+const members = {
+    create,
+    lift,
+    splice,
+};
+// `globalThis`, which a name the script didn't bind is read off. In the type
+// and not in the object: nothing runs the virtual code it is written in.
+export const cs = Object.assign((_strings, ..._values) => {
+    throw new Error("`cs` was not compiled. Is @backtickjs set up for this project?");
+}, members);
+//# sourceMappingURL=cs.js.map

package/dist/cs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cs.js","sourceRoot":"","sources":["../src/cs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI3C,uBAAuB;AACvB,SAAS,IAAI,CAAI,CAAI;IACnB,MAAM,IAAI,KAAK,CACb,+DAA+D;QAC7D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,4CAA4C;AAC5C,SAAS,MAAM,CACb,CAAI;IAEJ,MAAM,IAAI,KAAK,CACb,iEAAiE;QAC/D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,0BAA0B;AAC1B,MAAM,OAAO,GAAG;IACd,MAAM;IACN,IAAI;IACJ,MAAM;CACP,CAAC;AAYF,6EAA6E;AAC7E,yEAAyE;AACzE,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAC7B,CAAC,QAA8B,EAAE,GAAG,OAAkB,EAAmB,EAAE;IACzE,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;AACJ,CAAC,EACD,OAEC,CACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Backtick: the `cs` tag, what a host may hand a client, and what a template
+ * compiles to.
+ */
+export { cs } from "./cs.js";
+export type { Client } from "./Client.js";
+export type { Spliceable, Spliced } from "./Spliceable.js";
+export { createImport, isClientImport, type ClientImport, } from "./ClientImport.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";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Backtick: the `cs` tag, what a host may hand a client, and what a template
+ * compiles to.
+ */
+// The tag, and how a host language spells a script standing in for a value.
+export { cs } from "./cs.js";
+export { createImport, isClientImport, } from "./ClientImport.js";
+// A drawing as a host builds one: what an adapter's JSX 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";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAM7B,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"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The cs tag for Backtick client scripts, and the types for the values that cross from server to client",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "server-driven-ui",
+    "server-components",
+    "jsx",
+    "typescript",
+    "tagged-template"
+  ],
+  "homepage": "https://backtickjs.com",
+  "bugs": {
+    "url": "https://github.com/backtickjs/backtick/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backtickjs/backtick.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "author": "Jean-François Bisson <jf@backtickjs.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/._cache",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "clean": "rm -rf node_modules dist .turbo",
+    "test": "node --test \"test/**/*.test.ts\""
+  }
 }

package/src/Client.ts

@@ -0,0 +1,4 @@
+declare const ClientBrand: unique symbol;
+export interface Client<T> {
+  readonly [ClientBrand]: T;
+}

package/src/ClientImport.ts

@@ -0,0 +1,42 @@
+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.
+ */
+export interface ClientImport<T> extends Client<T> {
+  readonly "@backtickjs": "ClientImport";
+  readonly name: string;
+  // the specifier the client resolves
+  readonly from: string;
+  // the versions of `from`'s package it works with, a semver range
+  readonly version: string;
+}
+
+export function isClientImport(value: unknown): value is ClientImport<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "@backtickjs" in value &&
+    value["@backtickjs"] === "ClientImport"
+  );
+}
+
+// `T` is what the module's own declarations say the export is; nothing here
+// can check the two agree, and the module the client resolves is what does.
+export function createImport<T>({
+  name,
+  from,
+  version,
+}: {
+  name: string;
+  from: string;
+  version: string;
+}): Client<T> {
+  return {
+    "@backtickjs": "ClientImport",
+    name,
+    from,
+    version,
+  } as unknown as ClientImport<T>;
+}

package/src/ClientScript.ts

@@ -0,0 +1,50 @@
+import type { Spliceable } from "./Spliceable.js";
+
+// One parameter of a script's function. Splices come first, in the order the
+// script reads them, then captures.
+export type Param =
+  // a host value, passed as a function the script calls with `bindings`
+  // wherever it reads it, a tag (`<$Card>`) among them
+  | { kind: "splice"; bindings: readonly string[] }
+  // a variable of the enclosing script
+  | { kind: "capture"; key: string };
+
+// The compiled code of one `cs`, shared by every script it creates.
+export interface ClientModule {
+  // `<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;
+  // A module-table entry, `(module, exports, require) => { … }`, whose default
+  // export is the script's function.
+  readonly code: string;
+  // Source map into the host file, without its content.
+  readonly map: string;
+  // The modules `code` requires.
+  readonly dependencies: readonly string[];
+  // `params[i]` is the function's `$splice<i>` or `$capture<i>`
+  readonly params: readonly Param[];
+}
+
+// One run of a `cs`: its module, and the values that run passes it.
+export interface ClientScript {
+  readonly "@backtickjs": "ClientScript";
+  readonly module: ClientModule;
+  // one per splice, in parameter order
+  readonly args: readonly Spliceable[];
+}
+
+export function isClientScript(value: unknown): value is ClientScript {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "@backtickjs" in value &&
+    value["@backtickjs"] === "ClientScript"
+  );
+}
+
+export function create(
+  module: ClientModule,
+  args: readonly Spliceable[],
+): ClientScript {
+  return { "@backtickjs": "ClientScript", module, args };
+}

package/src/JsxElement.ts

@@ -0,0 +1,53 @@
+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
+ * a drawing may stand.
+ */
+export interface JsxElement extends Client<unknown> {
+  readonly "@backtickjs": "JsxElement";
+  readonly type: string | ((props: never) => unknown);
+  readonly props: unknown;
+}
+
+export function isJsxElement(value: unknown): value is JsxElement {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "@backtickjs" in value &&
+    value["@backtickjs"] === "JsxElement"
+  );
+}
+
+export function createJsxElement(
+  type: string | ((props: never) => unknown),
+  props: unknown,
+): JsxElement {
+  return { "@backtickjs": "JsxElement", type, props } as JsxElement;
+}
+
+// What an adapter's JSX 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.
+
+/**
+ * A JSX expression: in a script, what the framework draws, so it fits the
+ * framework's slots; on the host, a client value standing for it, so it
+ * splices.
+ */
+export type JsxElementOf<T> = T & Client<T>;
+
+/**
+ * What a tag may name: an intrinsic element; a component as a script sees it,
+ * answering what the framework draws (a client component, or a server
+ * component lowered); or a server component on the host, answering a script
+ * that draws, or nothing.
+ */
+export type JsxElementTypeOf<T> =
+  | string
+  | ((props: never) => T)
+  | ((props: never) => Client<T> | null | Promise<Client<T> | null>);

package/src/Spliceable.ts

@@ -0,0 +1,31 @@
+import type { Client } from "./Client.js";
+
+/**
+ * What the host may splice: the value written out, a script standing in for
+ * it, or a container mixing the two. Not a host function, which is host code:
+ * a client function is a script, cs`(n: number) => …`. An index signature rather than a mapped
+ * type, so it can be named in a `satisfies` without a type to walk.
+ */
+export type Spliceable =
+  | Client<unknown>
+  | null
+  | undefined
+  | number
+  | boolean
+  | string
+  | readonly Spliceable[]
+  | { readonly [key: string]: Spliceable };
+
+// What a spliceable becomes on the client:
+//   Client<U>                 -> U
+//   T[]                       -> Spliced<T>[]
+//   { k: T }                  -> { k: Spliced<T> }
+//   primitives                -> unchanged
+export type Spliced<T> =
+  T extends Client<infer U>
+    ? U
+    : T extends readonly (infer Item extends Spliceable)[]
+      ? Spliced<Item>[]
+      : T extends { readonly [key: string]: Spliceable }
+        ? { -readonly [K in keyof T]: Spliced<T[K]> }
+        : T;

package/src/cs.ts

@@ -0,0 +1,56 @@
+import type { Client } from "./Client.js";
+import { create } from "./ClientScript.js";
+import type { Spliceable } from "./Spliceable.js";
+import type { Spliced } from "./Spliceable.js";
+
+// The root of a script
+function lift<T>(_: T): Client<T> {
+  throw new Error(
+    "Don't call `cs.lift` directly; it's used to generate virtual " +
+      "code for the typechecker. Write code using cs`...` instead.",
+  );
+}
+
+// A constraint that is `unknown` for a value that splices, rather than
+// `Spliceable` itself or an intersection with it: either of those keeps a
+// literal a literal instead of widening it. What can't be spliced is refused
+// once, where it is written, and is `any` after: refused, `T` falls back to
+// `Spliceable`, which splices to `unknown`.
+function splice<T extends [T] extends [Spliceable] ? unknown : Spliceable>(
+  _: T,
+): unknown extends Spliced<T> ? any : Spliced<T> {
+  throw new Error(
+    "Don't call `cs.splice` directly; it's used to generate virtual " +
+      "code for the typechecker. Write code using cs`...` instead.",
+  );
+}
+
+// What hangs off the tag.
+const members = {
+  create,
+  lift,
+  splice,
+};
+
+/**
+ * The globals a project declares — its libs, `@types`, a `declare global` —
+ * as an ordinary object type: reading one it doesn't declare is an error
+ * however strict the project is, where `typeof globalThis` itself lets it
+ * through as `any` without `noImplicitAny`.
+ */
+export type GlobalThis = {
+  [Key in keyof typeof globalThis]: (typeof globalThis)[Key];
+};
+
+// `globalThis`, which a name the script didn't bind is read off. In the type
+// and not in the object: nothing runs the virtual code it is written in.
+export const cs = Object.assign(
+  (_strings: TemplateStringsArray, ..._values: unknown[]): Client<unknown> => {
+    throw new Error(
+      "`cs` was not compiled. Is @backtickjs set up for this project?",
+    );
+  },
+  members as typeof members & {
+    readonly globalThis: GlobalThis;
+  },
+);

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Backtick: the `cs` tag, what a host may hand a client, and what a template
+ * compiles to.
+ */
+
+// The tag, and how a host language spells a script standing in for a value.
+export { cs } from "./cs.js";
+export type { Client } from "./Client.js";
+
+// What a host may hand a client: data, a script, or an export of a module the
+// client provides.
+export type { Spliceable, Spliced } from "./Spliceable.js";
+export {
+  createImport,
+  isClientImport,
+  type ClientImport,
+} from "./ClientImport.js";
+
+// A drawing as a host builds one: what an adapter's JSX runtime makes, and
+// what the bundler expands.
+export {
+  createJsxElement,
+  isJsxElement,
+  type JsxElement,
+  type JsxElementOf,
+  type JsxElementTypeOf,
+} 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,
+  type ClientModule,
+  type ClientScript,
+  isClientScript,
+  type Param,
+} from "./ClientScript.js";