solid-tag-runtime 0.0.1

package/README.md

@@ -0,0 +1,324 @@
+# solid-tag-runtime
+
+`solid-tag-runtime` is a small runtime module system for applications that want to load, compose, and execute Solid JSX modules dynamically in the browser.
+
+It builds on [`solid-tag`](https://www.npmjs.com/package/solid-tag):
+
+```text
+JSX source modules
+      ↓
+solid-tag
+      ↓
+JavaScript containing html``
+      ↓
+solid-tag-runtime module linker
+      ↓
+@solidjs/html + the host application's Solid runtime
+```
+
+The package is intentionally runtime-oriented. It is not a build plugin and does not require a traditional application compilation workflow for the dynamic modules it executes.
+
+## Installation
+
+```bash
+npm install solid-tag-runtime solid-tag
+```
+
+`solid-tag-runtime` does **not** install its own copy of Solid. A host application can expose its already-loaded Solid modules with `defineModule()` so dynamically loaded components share the same reactive runtime.
+
+## Create a runtime
+
+```ts
+import { createRuntime } from "solid-tag-runtime";
+
+const runtime = createRuntime();
+```
+
+For a real Solid application, register the host runtime:
+
+```ts
+import * as Solid from "solid-js";
+import * as SolidWeb from "@solidjs/web";
+import html from "@solidjs/html";
+
+const runtime = createRuntime({
+  modules: {
+    "solid-js": Solid,
+    "@solidjs/web": SolidWeb,
+    "@solidjs/html": { default: html },
+  },
+});
+```
+
+This is important: dynamic modules now use the **same** `solid-js`, `@solidjs/web`, and `@solidjs/html` instances as the host application.
+
+## Define and import runtime modules
+
+```ts
+runtime.define(
+  "/ui/Button.jsx",
+  `
+    export function Button(props) {
+      return (
+        <button onClick={props.onClick}>
+          {props.children}
+        </button>
+      );
+    }
+  `,
+);
+```
+
+A second module can import the first one normally:
+
+```ts
+runtime.define(
+  "/features/Counter.jsx",
+  `
+    import { createSignal } from "solid-js";
+    import { Button } from "../ui/Button.jsx";
+
+    export function Counter() {
+      const [count, setCount] = createSignal(0);
+
+      return (
+        <Button onClick={() => setCount(value => value + 1)}>
+          Count: {count()}
+        </Button>
+      );
+    }
+  `,
+);
+
+const counterModule = await runtime.import("/features/Counter.jsx");
+
+counterModule.Counter;
+```
+
+The runtime compiles and links the dependency graph automatically.
+
+## `toModule()`
+
+For one-off source strings:
+
+```ts
+const module = await runtime.toModule(`
+  export function MyComponent(props) {
+    return <>{props.message} {props.name}</>;
+  }
+`);
+
+const MyComponent = module.MyComponent;
+```
+
+`toModule()` creates an anonymous runtime module, compiles it with `solid-tag`, evaluates it as a real ES module, and returns the module namespace.
+
+It is asynchronous because the runtime preserves ES-module-style evaluation rather than using `new Function()`.
+
+## `toComponent()`
+
+For the common single-component case:
+
+```ts
+const MyComponent = await runtime.toComponent(
+  `
+    export function MyComponent(props) {
+      return <div>{props.message}</div>;
+    }
+  `,
+  { exportName: "MyComponent" },
+);
+```
+
+For a default export:
+
+```ts
+const Counter = await runtime.toComponent(`
+  export default function Counter() {
+    return <button>Count</button>;
+  }
+`);
+```
+
+## Inject application values as modules
+
+The runtime deliberately does not rewrite unresolved identifiers into a magical scope object.
+
+Instead, application scope can be expressed as a normal module:
+
+```ts
+const [count, setCount] = createSignal(0);
+
+runtime.defineModule("@app/state", {
+  count,
+  setCount,
+});
+```
+
+Runtime source imports those references normally:
+
+```tsx
+import { count, setCount } from "@app/state";
+
+export function Counter() {
+  return (
+    <button onClick={() => setCount(value => value + 1)}>
+      {count()}
+    </button>
+  );
+}
+```
+
+This works for:
+
+- Solid signals and setters
+- stores
+- components
+- callbacks
+- services
+- data objects
+- application utilities
+
+The values cross the boundary as actual JavaScript references; they are not serialized.
+
+## Expose existing components
+
+```ts
+runtime.defineModule("@app/components", {
+  Button,
+  Dialog,
+  Card,
+});
+```
+
+Then runtime JSX can use them like any other module:
+
+```tsx
+import { Button } from "@app/components";
+
+export function SaveButton() {
+  return <Button>Save</Button>;
+}
+```
+
+## URL modules
+
+A package or external library can be mapped to a native ESM URL:
+
+```ts
+runtime.defineUrl(
+  "some-library",
+  "https://esm.sh/some-library@1.2.3",
+);
+```
+
+Then dynamic modules can write:
+
+```js
+import something from "some-library";
+```
+
+## Plain JavaScript modules
+
+JSX transformation can be disabled per module:
+
+```ts
+runtime.define(
+  "/config.js",
+  `export const value = 42;`,
+  { format: "js" },
+);
+```
+
+This is useful when the same runtime graph contains both JSX-backed modules and ordinary JavaScript modules.
+
+## Compilation without execution
+
+```ts
+runtime.define("/App.jsx", source);
+
+const compiled = await runtime.compile("/App.jsx");
+
+console.log(compiled.code);
+console.log(compiled.dependencies);
+console.log(compiled.diagnostics);
+```
+
+This is useful for editors, debugging tools, and inspecting the exact `html\`\`` output generated by `solid-tag`.
+
+## Module graph introspection
+
+```ts
+runtime.modules();
+runtime.dependencies("/App.jsx");
+runtime.dependents("/ui/Button.jsx");
+runtime.getModuleInfo("/App.jsx");
+```
+
+## Updating modules
+
+```ts
+runtime.update("/ui/Button.jsx", newButtonSource);
+
+const app = await runtime.import("/App.jsx");
+```
+
+Updating a module invalidates its compiled URL and its dependent runtime modules. Re-importing produces a newly linked graph.
+
+Existing references to an older module namespace/component are not mutated. Applications that implement live editing should import the updated entry module again.
+
+## Custom resolution
+
+```ts
+const runtime = createRuntime({
+  resolve(specifier, importer) {
+    if (specifier.startsWith("@ui/")) {
+      return `/ui/${specifier.slice(4)}`;
+    }
+  },
+});
+```
+
+Default runtime resolution supports:
+
+- exact virtual module IDs
+- relative virtual imports
+- absolute virtual paths
+- registered URL modules
+- native/bare imports when `allowNativeImports` is enabled
+
+## Native imports
+
+`allowNativeImports` defaults to `true`.
+
+This means an unresolved bare import can be left for the browser's native module resolver/import map:
+
+```ts
+const runtime = createRuntime({
+  allowNativeImports: true,
+});
+```
+
+Set it to `false` when all module dependencies must be explicitly registered with the runtime.
+
+## Runtime lifecycle
+
+```ts
+runtime.invalidate("/App.jsx");
+runtime.dispose();
+```
+
+`dispose()` revokes generated module URLs and clears the host-module registry for that runtime instance.
+
+## Current limitations
+
+The first version deliberately keeps module semantics constrained:
+
+- circular dependencies between runtime-defined source modules are not supported yet
+- generated modules normally use Blob URLs in browsers, so CSP must permit the chosen execution strategy
+- host-module export bridges expose the export values present when the bridge module is created; redefining the host module invalidates dependents
+- module updates create new module identities; already-held namespaces/components remain the old version
+- TypeScript/TSX parsing depends on what the underlying `solid-tag` compiler supports
+- this package is **not a security sandbox**; loaded source executes with the privileges of the page
+
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the detailed design and decision log.

package/index.d.ts

@@ -0,0 +1,119 @@
+export type ModuleFormat = "jsx" | "js";
+
+export interface ModuleNamespaceLike {
+  readonly [key: string]: unknown;
+}
+
+export interface CompilerImportReference {
+  specifier: string;
+  start: number;
+  end: number;
+  kind?: string;
+}
+
+export interface RuntimeCompiler {
+  analyze(source: string, context?: { id?: string; format?: ModuleFormat }): {
+    imports?: CompilerImportReference[];
+    needsHtmlRuntime?: boolean;
+  };
+  transform(source: string, context?: {
+    id?: string;
+    format?: ModuleFormat;
+    htmlImportSource?: string;
+  }): {
+    code: string;
+    diagnostics?: unknown[];
+    changed?: boolean;
+  };
+}
+
+export interface ModuleUrlBackend {
+  readonly kind?: string;
+  create(code: string, id?: string): string;
+  revoke?(url: string): void;
+}
+
+export interface RuntimeOptions {
+  compiler?: RuntimeCompiler;
+  compilerOptions?: Record<string, unknown>;
+  modules?: Record<string, ModuleNamespaceLike | Function>;
+  urls?: Record<string, string>;
+  allowNativeImports?: boolean;
+  resolve?: (specifier: string, importer: string | null, runtime: SolidTagRuntime) => string | void;
+  moduleUrlBackend?: ModuleUrlBackend;
+}
+
+export interface DefineOptions {
+  format?: ModuleFormat;
+}
+
+export interface ToModuleOptions extends DefineOptions {
+  id?: string;
+}
+
+export interface ToComponentOptions extends ToModuleOptions {
+  exportName?: string;
+}
+
+export interface ModuleInfo {
+  id: string;
+  kind: "source" | "host" | "url";
+  state: string;
+  version: number;
+  format?: ModuleFormat;
+  dependencies: string[];
+  dependents: string[];
+  url?: string;
+  diagnostics: unknown[];
+}
+
+export interface CompileResult {
+  id: string;
+  kind: "source" | "host" | "url";
+  code?: string;
+  url?: string;
+  dependencies: string[];
+  diagnostics: unknown[];
+}
+
+export interface SolidTagRuntime {
+  define(id: string, source: string, options?: DefineOptions): string;
+  update(id: string, source: string, options?: DefineOptions): string;
+  defineModule(id: string, namespace: ModuleNamespaceLike | Function): string;
+  defineUrl(id: string, url: string): string;
+  import(id: string): Promise<ModuleNamespaceLike>;
+  compile(id: string): Promise<CompileResult>;
+  toModule(source: string, options?: ToModuleOptions): Promise<ModuleNamespaceLike>;
+  toComponent<T extends Function = Function>(source: string, options?: ToComponentOptions): Promise<T>;
+  has(id: string): boolean;
+  invalidate(id: string, options?: { dependents?: boolean }): string[];
+  modules(): ModuleInfo[];
+  dependencies(id: string): string[];
+  dependents(id: string): string[];
+  getModuleInfo(id: string): ModuleInfo | undefined;
+  resolve(specifier: string, importer?: string | null): string;
+  dispose(): void;
+}
+
+export declare function createRuntime(options?: RuntimeOptions): SolidTagRuntime;
+export declare function createRuntimeCore(options: RuntimeOptions & { compiler: RuntimeCompiler }): SolidTagRuntime;
+export declare function createSolidTagCompiler(options?: {
+  tag?: string;
+  transformOptions?: Record<string, unknown>;
+}): RuntimeCompiler;
+
+export declare function createDefaultModuleUrlBackend(): ModuleUrlBackend;
+export declare function createBlobModuleUrlBackend(): ModuleUrlBackend;
+export declare function createDataModuleUrlBackend(): ModuleUrlBackend;
+
+export declare class SolidTagRuntimeError extends Error {}
+export declare class ModuleResolutionError extends SolidTagRuntimeError {
+  specifier: string;
+  importer: string | null;
+}
+export declare class CircularDependencyError extends SolidTagRuntimeError {
+  cycle: string[];
+}
+export declare class ModuleCompileError extends SolidTagRuntimeError {
+  id: string;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "solid-tag-runtime",
+  "version": "0.0.1",
+  "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./compiler": {
+      "types": "./index.d.ts",
+      "import": "./src/compiler.js",
+      "default": "./src/compiler.js"
+    },
+    "./runtime": {
+      "types": "./index.d.ts",
+      "import": "./src/runtime.js",
+      "default": "./src/runtime.js"
+    }
+  },
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "ARCHITECTURE.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "solid-tag": "^0.0.1"
+  },
+  "scripts": {
+    "test": "node ./test/run.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "jsx",
+    "runtime",
+    "module",
+    "tagged-template",
+    "browser"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/compiler.js

@@ -0,0 +1,77 @@
+import { parseJSX, transformModule } from "solid-tag";
+
+export function createSolidTagCompiler(options = {}) {
+  const {
+    tag = "html",
+    transformOptions = {},
+  } = options;
+
+  return {
+    analyze(source) {
+      const ast = parseJSX(source);
+      const imports = [];
+      let needsHtmlRuntime = false;
+      walk(ast, node => {
+        if (node.type === "JSXElement" || node.type === "JSXFragment") needsHtmlRuntime = true;
+        if (
+          (node.type === "ImportDeclaration" ||
+            node.type === "ExportNamedDeclaration" ||
+            node.type === "ExportAllDeclaration") &&
+          node.source &&
+          typeof node.source.value === "string"
+        ) {
+          imports.push({
+            specifier: node.source.value,
+            start: node.source.start,
+            end: node.source.end,
+            kind: node.type,
+          });
+          return;
+        }
+
+        if (
+          node.type === "ImportExpression" &&
+          node.source &&
+          (node.source.type === "Literal" || node.source.type === "StringLiteral") &&
+          typeof node.source.value === "string"
+        ) {
+          imports.push({
+            specifier: node.source.value,
+            start: node.source.start,
+            end: node.source.end,
+            kind: "ImportExpression",
+          });
+        }
+      });
+
+      return { imports, needsHtmlRuntime };
+    },
+
+    transform(source, context = {}) {
+      return transformModule(source, {
+        ...transformOptions,
+        tag,
+        injectHtmlImport: true,
+        htmlImportSource: context.htmlImportSource ?? "@solidjs/html",
+      });
+    },
+  };
+}
+
+function walk(node, visit) {
+  if (!node || typeof node !== "object") return;
+  visit(node);
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "loc" || key === "range" || key === "parent") continue;
+    if (!value) continue;
+
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child === "object" && typeof child.type === "string") walk(child, visit);
+      }
+    } else if (typeof value === "object" && typeof value.type === "string") {
+      walk(value, visit);
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,32 @@
+export class SolidTagRuntimeError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "SolidTagRuntimeError";
+  }
+}
+
+export class ModuleResolutionError extends SolidTagRuntimeError {
+  constructor(specifier, importer, message) {
+    super(message ?? `Could not resolve module ${JSON.stringify(specifier)} from ${JSON.stringify(importer ?? "<runtime>")}.`);
+    this.name = "ModuleResolutionError";
+    this.specifier = specifier;
+    this.importer = importer ?? null;
+  }
+}
+
+export class CircularDependencyError extends SolidTagRuntimeError {
+  constructor(cycle) {
+    super(`Circular virtual module dependency is not supported yet: ${cycle.join(" -> ")}`);
+    this.name = "CircularDependencyError";
+    this.cycle = [...cycle];
+  }
+}
+
+export class ModuleCompileError extends SolidTagRuntimeError {
+  constructor(id, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to compile module ${JSON.stringify(id)}: ${detail}`, { cause });
+    this.name = "ModuleCompileError";
+    this.id = id;
+  }
+}

package/src/index.js

@@ -0,0 +1,21 @@
+import { createSolidTagCompiler } from "./compiler.js";
+import { createRuntime as createRuntimeCore } from "./runtime.js";
+
+export function createRuntime(options = {}) {
+  const compiler = options.compiler ?? createSolidTagCompiler(options.compilerOptions);
+  return createRuntimeCore({ ...options, compiler });
+}
+
+export { createSolidTagCompiler } from "./compiler.js";
+export { createRuntime as createRuntimeCore } from "./runtime.js";
+export {
+  createDefaultModuleUrlBackend,
+  createBlobModuleUrlBackend,
+  createDataModuleUrlBackend,
+} from "./url-backend.js";
+export {
+  SolidTagRuntimeError,
+  ModuleResolutionError,
+  CircularDependencyError,
+  ModuleCompileError,
+} from "./errors.js";