solid-tag-runtime 0.0.12 → 0.0.14

package/examples/render.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>solid-tag-runtime rendering</title>
+  </head>
+  <body>
+    <div id="app"></div>
+
+    <!-- Define a reusable runtime module. -->
+    <script type="solid-jsx" data-solid-runtime="main" module="/Counter.jsx">
+      import { createSignal } from "solid-js";
+
+      export default function Counter(props) {
+        const [count, setCount] = createSignal(0);
+        return (
+          <button onClick={() => setCount(value => value + 1)}>
+            {props.label}: {count()}
+          </button>
+        );
+      }
+    </script>
+
+    <!-- Define + mount one declaration-owned instance into #app. -->
+    <script
+      type="solid-jsx"
+      data-solid-runtime="main"
+      module="/App.jsx"
+      render="#app"
+    >
+      export default function App() {
+        return <h1>Mounted by &lt;script render&gt;</h1>;
+      }
+    </script>
+
+    <!-- Reference the already-defined Counter module and create independent instances. -->
+    <solid-render
+      data-solid-runtime="main"
+      module="/Counter.jsx"
+      prop:label="Counter A"
+    ></solid-render>
+
+    <solid-render
+      data-solid-runtime="main"
+      module="/Counter.jsx"
+      prop:label="Counter B"
+    ></solid-render>
+
+    <!--
+      This bootstrap is ordinary JavaScript. The surrounding application/import
+      map is responsible for resolving Solid and solid-tag-runtime bare imports.
+    -->
+    <script type="module">
+      import * as Solid from "solid-js";
+      import * as SolidWeb from "@solidjs/web";
+      import html from "@solidjs/html";
+      import { createRuntime } from "solid-tag-runtime";
+      import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+      const runtime = createRuntime({
+        modules: {
+          "solid-js": Solid,
+          "@solidjs/web": SolidWeb,
+          "@solidjs/html": { default: html },
+        },
+      });
+
+      const htmlRuntime = createHTMLRuntime(runtime, {
+        scope: "main",
+        root: document,
+        appendTo: document.body,
+        acceptUnscoped: false,
+      });
+
+      await htmlRuntime.register();
+      await htmlRuntime.observe({ registerExisting: false });
+    </script>
+  </body>
+</html>

package/examples/solid-runtime.js

@@ -0,0 +1,24 @@
+import { createSolidRuntime } from "solid-tag-runtime/solid";
+
+const runtime = await createSolidRuntime({
+  solid: {
+    source: "auto",
+    // Optional when the host/import map cannot resolve the complete family:
+    fallbackProvider: "esm.sh",
+  },
+  modules: {
+    "@app/config": {
+      greeting: "Hello",
+    },
+  },
+});
+
+runtime.define("/Greeting.jsx", `
+  import { greeting } from "@app/config";
+
+  export default function Greeting() {
+    return <p>{greeting} from createSolidRuntime()</p>;
+  }
+`);
+
+export default runtime;

package/index.d.ts

@@ -1,30 +1,58 @@
 export type ModuleFormat = "jsx" | "js";
+export type CompileCacheMode = "use" | "refresh" | "bypass";
 
 export interface ModuleNamespaceLike {
   readonly [key: string]: unknown;
 }
 
+export interface CompileContext {
+  id?: string;
+  format?: ModuleFormat;
+}
+
 export interface CompilerImportReference {
   specifier: string;
   start: number;
   end: number;
-  kind?: string;
+  kind?: "static" | "dynamic" | "export" | string;
+}
+
+export interface CompiledArtifact {
+  schema?: number;
+  code: string;
+  imports: CompilerImportReference[];
+  diagnostics?: unknown[];
+  sourceMap?: string;
+  changed?: boolean;
 }
 
 export interface RuntimeCompiler {
-  analyze(source: string, context?: { id?: string; format?: ModuleFormat }): {
+  /** Stable identity required for persistent compile-cache reuse. */
+  fingerprint?: string | ((context: CompileContext) => string | Promise<string>);
+  /** Additional compile-affecting context to include in persistent cache identity. */
+  cacheContext?: (context: CompileContext) => unknown | Promise<unknown>;
+  /** Preferred compiler boundary: return a linker-ready pre-link artifact. */
+  compile?(source: string, context?: CompileContext): CompiledArtifact | Promise<CompiledArtifact>;
+  /** Transitional compiler API retained for compatibility. */
+  analyze?(source: string, context?: CompileContext): {
+    imports?: CompilerImportReference[];
+    needsHtmlRuntime?: boolean;
+  } | Promise<{
     imports?: CompilerImportReference[];
     needsHtmlRuntime?: boolean;
-  };
-  transform(source: string, context?: {
-    id?: string;
-    format?: ModuleFormat;
-    htmlImportSource?: string;
-  }): {
+  }>;
+  /** Transitional compiler API retained for compatibility. */
+  transform?(source: string, context?: CompileContext & { htmlImportSource?: string }): {
+    code: string;
+    diagnostics?: unknown[];
+    changed?: boolean;
+    sourceMap?: string;
+  } | Promise<{
     code: string;
     diagnostics?: unknown[];
     changed?: boolean;
-  };
+    sourceMap?: string;
+  }>;
 }
 
 export interface ModuleUrlBackend {
@@ -33,6 +61,53 @@ export interface ModuleUrlBackend {
   revoke?(url: string): void;
 }
 
+export interface CachedCompileRecord {
+  schema: number;
+  key: string;
+  artifactAbi: string;
+  sourceHash: string;
+  format: string;
+  compilerFingerprint: string;
+  compileContextHash: string;
+  artifact: CompiledArtifact;
+  createdAt: number;
+  lastUsedAt?: number;
+  byteSize?: number;
+  artifactHash?: string;
+}
+
+export interface CompileCacheStore {
+  readonly kind?: string;
+  get(key: string): Promise<CachedCompileRecord | undefined>;
+  set(key: string, value: CachedCompileRecord): Promise<void>;
+  delete(key: string): Promise<boolean | void>;
+  clear?(options?: { prefix?: string }): Promise<number | void>;
+  entries?(options?: { prefix?: string }): Promise<Array<[string, CachedCompileRecord]>>;
+}
+
+export interface CompileCacheOptions {
+  enabled?: boolean;
+  store: CompileCacheStore;
+  namespace?: string;
+  version?: string;
+  maxEntries?: number;
+  maxBytes?: number;
+  /** Maximum record age in milliseconds. */
+  maxAge?: number;
+}
+
+export interface LocalStorageLike {
+  readonly length: number;
+  key(index: number): string | null;
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface IndexedDBFactoryLike {
+  open(name: string, version?: number): any;
+}
+
 export interface RuntimeOptions {
   compiler?: RuntimeCompiler;
   compilerOptions?: Record<string, unknown>;
@@ -41,6 +116,8 @@ export interface RuntimeOptions {
   allowNativeImports?: boolean;
   resolve?: (specifier: string, importer: string | null, runtime: SolidTagRuntime) => string | void;
   moduleUrlBackend?: ModuleUrlBackend;
+  /** Opt-in persistent pre-link compile artifact cache. */
+  compileCache?: CompileCacheOptions | false;
 }
 
 export interface DefineOptions {
@@ -55,6 +132,20 @@ export interface ToComponentOptions extends ToModuleOptions {
   exportName?: string;
 }
 
+export interface CompileOptions {
+  cache?: CompileCacheMode;
+}
+
+export interface CompileCacheInfo {
+  enabled: boolean;
+  status: "none" | "hit" | "miss" | "refresh" | "bypass";
+  source?: string;
+  key?: string;
+  compilerFingerprint?: string;
+  sourceHash?: string;
+  compileContextHash?: string;
+}
+
 export interface ModuleInfo {
   id: string;
   kind: "source" | "host" | "url";
@@ -65,6 +156,7 @@ export interface ModuleInfo {
   dependents: string[];
   url?: string;
   diagnostics: unknown[];
+  compileCache?: CompileCacheInfo;
 }
 
 export interface CompileResult {
@@ -91,6 +183,23 @@ export interface ClearRuntimeOptions {
   preserveHostModules?: boolean;
 }
 
+export interface InvalidateOptions {
+  dependents?: boolean;
+  /** Force only the requested source module to compile fresh on its next link. */
+  compile?: boolean;
+}
+
+export interface RuntimeCompileCache {
+  readonly enabled: boolean;
+  readonly namespace?: string;
+  readonly version?: string;
+  readonly store?: string;
+  /** Delete the current module's stored compiler artifact without graph invalidation. */
+  invalidate(id: string): Promise<boolean>;
+  /** Clear current namespace/version, or all versions within the current namespace. */
+  clear(options?: { allVersions?: boolean }): Promise<number>;
+}
+
 export type ModuleResolutionKind =
   | "custom"
   | "registered"
@@ -113,28 +222,57 @@ export interface LinkedDependency {
   resolvedId: string;
 }
 
+export type CompileCacheErrorOperation =
+  | "identity"
+  | "fingerprint"
+  | "read"
+  | "write"
+  | "delete"
+  | "clear"
+  | "prune";
+
+interface RuntimeEventBase {
+  runtimeId: string;
+  timestamp: number;
+}
+
+interface CompileCacheEventBase extends RuntimeEventBase {
+  id?: string;
+  key?: string;
+  store?: string;
+  source?: string;
+  durationMs?: number;
+  byteSize?: number;
+}
+
 export type RuntimeLifecycleEvent =
-  | { runtimeId: string; timestamp: number; type: "module-defined"; id: string; kind: ModuleInfo["kind"]; version: number; operation: "define" | "defineMany" | "update" | "defineModule" | "defineUrl"; replaced: boolean; module: ModuleInfo }
-  | { runtimeId: string; timestamp: number; type: "module-updated"; id: string; kind: ModuleInfo["kind"]; previousVersion: number; version: number; format?: ModuleFormat; module: ModuleInfo }
-  | { runtimeId: string; timestamp: number; type: "modules-defined"; ids: string[]; modules: ModuleInfo[] }
-  | { runtimeId: string; timestamp: number; type: "module-resolving"; specifier: string; importer: string | null }
-  | { runtimeId: string; timestamp: number; type: "module-resolved"; specifier: string; importer: string | null; resolvedId: string; resolutionKind: ModuleResolutionKind }
-  | { runtimeId: string; timestamp: number; type: "module-linking"; id: string; kind: ModuleInfo["kind"]; version: number }
-  | { runtimeId: string; timestamp: number; type: "module-linked"; id: string; kind: ModuleInfo["kind"]; version: number; dependencies: LinkedDependency[]; module: ModuleInfo }
-  | { runtimeId: string; timestamp: number; type: "module-invalidated"; id: string; kind: ModuleInfo["kind"]; version: number; reason: string }
-  | { runtimeId: string; timestamp: number; type: "module-compiled"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo }
-  | { runtimeId: string; timestamp: number; type: "module-evaluating"; id: string; kind: ModuleInfo["kind"]; version: number }
-  | { runtimeId: string; timestamp: number; type: "module-evaluated"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo }
-  | { runtimeId: string; timestamp: number; type: "module-removed"; id: string; kind: ModuleInfo["kind"]; version: number; invalidateDependents: boolean }
-  | { runtimeId: string; timestamp: number; type: "module-error"; id?: string; kind?: ModuleInfo["kind"]; version?: number; phase: ModuleErrorPhase; error: unknown }
-  | { runtimeId: string; timestamp: number; type: "runtime-cleared"; ids: string[]; preserveHostModules: boolean }
-  | { runtimeId: string; timestamp: number; type: "runtime-disposed" };
+  | (RuntimeEventBase & { type: "module-defined"; id: string; kind: ModuleInfo["kind"]; version: number; operation: "define" | "defineMany" | "update" | "defineModule" | "defineUrl"; replaced: boolean; module: ModuleInfo })
+  | (RuntimeEventBase & { type: "module-updated"; id: string; kind: ModuleInfo["kind"]; previousVersion: number; version: number; format?: ModuleFormat; module: ModuleInfo })
+  | (RuntimeEventBase & { type: "modules-defined"; ids: string[]; modules: ModuleInfo[] })
+  | (RuntimeEventBase & { type: "module-resolving"; specifier: string; importer: string | null })
+  | (RuntimeEventBase & { type: "module-resolved"; specifier: string; importer: string | null; resolvedId: string; resolutionKind: ModuleResolutionKind })
+  | (RuntimeEventBase & { type: "module-linking"; id: string; kind: ModuleInfo["kind"]; version: number })
+  | (RuntimeEventBase & { type: "module-linked"; id: string; kind: ModuleInfo["kind"]; version: number; dependencies: LinkedDependency[]; module: ModuleInfo })
+  | (RuntimeEventBase & { type: "module-invalidated"; id: string; kind: ModuleInfo["kind"]; version: number; reason: string })
+  | (RuntimeEventBase & { type: "module-compiled"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo })
+  | (RuntimeEventBase & { type: "module-evaluating"; id: string; kind: ModuleInfo["kind"]; version: number })
+  | (RuntimeEventBase & { type: "module-evaluated"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo })
+  | (RuntimeEventBase & { type: "module-removed"; id: string; kind: ModuleInfo["kind"]; version: number; invalidateDependents: boolean })
+  | (RuntimeEventBase & { type: "module-error"; id?: string; kind?: ModuleInfo["kind"]; version?: number; phase: ModuleErrorPhase; error: unknown })
+  | (RuntimeEventBase & { type: "runtime-cleared"; ids: string[]; preserveHostModules: boolean })
+  | (RuntimeEventBase & { type: "runtime-disposed" })
+  | (CompileCacheEventBase & { type: "compile-cache-hit" })
+  | (CompileCacheEventBase & { type: "compile-cache-miss" })
+  | (CompileCacheEventBase & { type: "compile-cache-write" })
+  | (CompileCacheEventBase & { type: "compile-cache-refresh" })
+  | (CompileCacheEventBase & { type: "compile-cache-bypass"; reason?: "requested" | "missing-compiler-fingerprint" | string })
+  | (CompileCacheEventBase & { type: "compile-cache-evict"; reason: "maxAge" | "maxEntries" | "maxBytes" | "invalid" | string })
+  | (CompileCacheEventBase & { type: "compile-cache-error"; operation: CompileCacheErrorOperation | string; error: unknown });
 
 export type RuntimeLifecycleEventType = RuntimeLifecycleEvent["type"];
 export type RuntimeLifecycleEventOfType<T extends RuntimeLifecycleEventType> =
   Extract<RuntimeLifecycleEvent, { type: T }>;
 
-
 export interface SolidTagRuntime {
   define(id: string, source: string, options?: DefineOptions): string;
   defineMany(definitions: SourceModuleDefinition[]): string[];
@@ -142,13 +280,15 @@ export interface SolidTagRuntime {
   defineModule(id: string, namespace: ModuleNamespaceLike | Function): string;
   defineUrl(id: string, url: string): string;
   import(id: string): Promise<ModuleNamespaceLike>;
-  compile(id: string): Promise<CompileResult>;
+  /** Returns the current linked/executable representation; cache controls affect compiler artifact lookup only. */
+  compile(id: string, options?: CompileOptions): 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[];
+  invalidate(id: string, options?: InvalidateOptions): string[];
   remove(id: string, options?: RemoveModuleOptions): boolean;
   clear(options?: ClearRuntimeOptions): string[];
+  readonly compileCache: RuntimeCompileCache;
   subscribe(listener: (event: RuntimeLifecycleEvent) => void): () => boolean;
   subscribe<T extends RuntimeLifecycleEventType>(
     type: T,
@@ -173,6 +313,22 @@ export declare function createSolidTagCompiler(options?: {
   transformOptions?: Record<string, unknown>;
 }): RuntimeCompiler;
 
+export declare function createMemoryCompileCache(options?: {
+  records?: Map<string, CachedCompileRecord>;
+}): CompileCacheStore;
+
+export declare function createLocalStorageCompileCache(options?: {
+  storage?: LocalStorageLike;
+  prefix?: string;
+}): CompileCacheStore;
+
+export declare function createIndexedDBCompileCache(options?: {
+  database?: string;
+  storeName?: string;
+  databaseVersion?: number;
+  indexedDB?: IndexedDBFactoryLike;
+}): CompileCacheStore;
+
 export declare function createDefaultModuleUrlBackend(): ModuleUrlBackend;
 export declare function createBlobModuleUrlBackend(): ModuleUrlBackend;
 export declare function createDataModuleUrlBackend(): ModuleUrlBackend;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -23,6 +23,11 @@
       "types": "./html.d.ts",
       "import": "./src/html.js",
       "default": "./src/html.js"
+    },
+    "./solid": {
+      "types": "./solid.d.ts",
+      "import": "./src/solid/index.js",
+      "default": "./src/solid/index.js"
     }
   },
   "main": "./src/index.js",
@@ -32,12 +37,15 @@
     "src",
     "index.d.ts",
     "html.d.ts",
+    "solid.d.ts",
     "README.md",
-    "ARCHITECTURE.md"
+    "ARCHITECTURE.md",
+    "docs",
+    "examples"
   ],
   "sideEffects": false,
   "dependencies": {
-    "solid-tag": "^0.0.1"
+    "solid-tag": "0.0.1"
   },
   "scripts": {
     "test": "node ./test/run.mjs",

package/solid.d.ts

@@ -0,0 +1,77 @@
+import type {
+  ModuleNamespaceLike,
+  RuntimeOptions,
+  SolidTagRuntime,
+} from "./index.js";
+
+export type SolidRuntimePackageName =
+  | "solid-js"
+  | "@solidjs/web"
+  | "@solidjs/html"
+  | "@solidjs/signals";
+
+export type SolidModuleProviderId = "esm.sh" | "jsdelivr";
+export type SolidModuleSource = "auto" | "host" | SolidModuleProviderId;
+
+export interface SolidRuntimeModules {
+  "solid-js": ModuleNamespaceLike | Function;
+  "@solidjs/web": ModuleNamespaceLike | Function;
+  "@solidjs/html": ModuleNamespaceLike | Function;
+  "@solidjs/signals": ModuleNamespaceLike | Function;
+}
+
+export interface LoadSolidModulesOptions {
+  /** Resolution policy. `auto` prefers the existing host/page resolver first. */
+  source?: SolidModuleSource;
+  /** CDN used only when `auto` cannot complete the family through the host. */
+  fallbackProvider?: SolidModuleProviderId;
+  /** Version used for provider-generated URLs when no versioned Solid anchor exists. */
+  version?: string;
+  /** Already-resolved namespaces. Provided entries are never re-imported. */
+  modules?: Partial<SolidRuntimeModules>;
+  /** Explicit URL/specifier overrides. Exact values are preserved. */
+  specifiers?: Partial<Record<SolidRuntimePackageName, string>>;
+  /** Optional Document used for read-only import-map/provider inspection. */
+  document?: Document;
+}
+
+export interface CreateSolidRuntimeOptions extends Omit<RuntimeOptions, "modules"> {
+  /** Application/host modules. User entries override automatically loaded defaults. */
+  modules?: RuntimeOptions["modules"] & Partial<SolidRuntimeModules>;
+  /** Options for resolving the standard Solid package family. */
+  solid?: LoadSolidModulesOptions;
+}
+
+export interface SolidResolutionInspection {
+  pageMappings: Map<string, string>;
+  authoritativeMappings: Map<string, string>;
+  provider?: SolidModuleProviderId;
+  version?: string;
+}
+
+export declare class SolidModuleResolutionError extends Error {
+  provider?: string;
+  version?: string;
+  missing?: string[];
+}
+
+export declare const SOLID_RUNTIME_PACKAGES: readonly [
+  "solid-js",
+  "@solidjs/web",
+  "@solidjs/html",
+  "@solidjs/signals",
+];
+
+export declare const TESTED_SOLID_VERSION: string;
+
+export declare function loadSolidModules(
+  options?: LoadSolidModulesOptions,
+): Promise<SolidRuntimeModules>;
+
+export declare function createSolidRuntime(
+  options?: CreateSolidRuntimeOptions,
+): Promise<SolidTagRuntime>;
+
+export declare function inspectSolidResolution(
+  options?: Pick<LoadSolidModulesOptions, "specifiers" | "document">,
+): SolidResolutionInspection;