solid-tag-runtime 0.0.12 → 0.0.13

package/docs/README.md

@@ -0,0 +1,23 @@
+# solid-tag-runtime documentation
+
+`solid-tag-runtime` is a runtime module system for dynamically defined Solid JSX/JavaScript modules. The core package remains module-first and DOM-independent; browser/DOM behavior lives in `solid-tag-runtime/html`.
+
+## Start here
+
+- [Getting started](./getting-started.md)
+- [Runtime modules and resolution](./modules.md)
+- [HTML runtime and ownership](./html-runtime.md)
+- [Declarative rendering](./rendering.md)
+- [`<solid-render>`](./solid-render.md)
+- [Lifecycle events](./lifecycle-events.md)
+- [Persistent compile cache](./compile-cache.md)
+
+## API reference
+
+- [Core runtime API](./api/runtime.md)
+- [HTML runtime API](./api/html.md)
+- [Compile-cache API](./api/compile-cache.md)
+
+## Engineering design
+
+The root [`ARCHITECTURE.md`](../ARCHITECTURE.md) is the engineering handoff and decision log. It documents internal invariants, compiler/linker boundaries, ownership rules, and compatibility decisions.

package/docs/api/compile-cache.md

@@ -0,0 +1,103 @@
+# Compile-cache API
+
+## Providers
+
+```ts
+import {
+  createMemoryCompileCache,
+  createLocalStorageCompileCache,
+  createIndexedDBCompileCache,
+} from "solid-tag-runtime";
+```
+
+### Memory
+
+```ts
+const store = createMemoryCompileCache();
+```
+
+### localStorage
+
+```ts
+const store = createLocalStorageCompileCache({
+  prefix: "solid-tag-runtime:compile-cache:",
+});
+```
+
+### IndexedDB
+
+```ts
+const store = createIndexedDBCompileCache({
+  database: "my-app-runtime",
+  storeName: "artifacts",
+  databaseVersion: 1,
+});
+```
+
+## Runtime configuration
+
+```ts
+const runtime = createRuntime({
+  compileCache: {
+    store,
+    namespace: "main",
+    version: "1",
+    maxEntries: 500,
+    maxBytes: 50 * 1024 * 1024,
+    maxAge: 30 * 24 * 60 * 60 * 1000,
+  },
+});
+```
+
+## Store contract
+
+```ts
+interface CompileCacheStore {
+  kind?: string;
+
+  get(key): Promise<CachedCompileRecord | undefined>;
+  set(key, record): Promise<void>;
+  delete(key): Promise<boolean | void>;
+
+  clear?({ prefix? }): Promise<number | void>;
+  entries?({ prefix? }): Promise<Array<[string, CachedCompileRecord]>>;
+}
+```
+
+`clear()` and `entries()` are used by namespace/version management and built-in pruning. Custom stores that omit them can still serve normal lookup/write/delete operations, but cache-wide management is limited.
+
+## Cache modes
+
+```ts
+await runtime.compile(id, { cache: "use" });
+await runtime.compile(id, { cache: "refresh" });
+await runtime.compile(id, { cache: "bypass" });
+```
+
+## Management
+
+```ts
+await runtime.compileCache.invalidate(id);
+await runtime.compileCache.clear();
+await runtime.compileCache.clear({ allVersions: true });
+```
+
+## Events
+
+```text
+compile-cache-hit
+compile-cache-miss
+compile-cache-write
+compile-cache-refresh
+compile-cache-bypass
+compile-cache-error
+compile-cache-evict
+```
+
+All events are observational.
+
+## Failure and quota behavior
+
+Normal cache lookup/write failures are optimization failures rather than module failures. A quota-style write failure triggers pruning and one write retry before `compile-cache-error` is emitted.
+
+Explicit management operations such as `runtime.compileCache.clear()` may reject because the caller explicitly requested the storage mutation.

package/docs/api/html.md

@@ -0,0 +1,83 @@
+# HTML runtime API
+
+```ts
+import {
+  createHTMLRuntime,
+  registerHTML,
+  observeHTML,
+  defineScript,
+  registerSolidRenderElement,
+} from "solid-tag-runtime/html";
+```
+
+## Controller
+
+```ts
+const html = createHTMLRuntime(runtime, options);
+```
+
+Common options:
+
+- `scope`
+- `root`
+- `appendTo`
+- `acceptUnscoped`
+- `executeEntries`
+- `executeRenders`
+- `onError`
+
+## Discovery and observation
+
+```ts
+await html.register(options?);
+await html.observe(options?);
+await html.flush(options?);
+html.disconnect();
+```
+
+## Explicit ownership
+
+```ts
+await html.registerElement(element, options?);
+await html.append(element, options?);
+await html.addModule(options);
+await html.updateElement(element, options?);
+await html.removeElement(element, options?);
+```
+
+## Root/append lifecycle
+
+```ts
+await html.setRoot(root, options?);
+await html.moveTo(root, options?);
+html.setAppendTarget(target);
+
+html.root;
+html.appendTarget;
+```
+
+## Introspection
+
+```ts
+html.owns(element);
+html.getModuleId(element);
+html.getElement(moduleId);
+```
+
+## Events
+
+```ts
+html.subscribe(listener);
+html.subscribe(type, listener);
+html.subscribe(types, listener);
+```
+
+## Convenience functions
+
+```ts
+await registerHTML(runtime, options?);
+await defineScript(runtime, element, options?);
+const observer = await observeHTML(runtime, options?);
+```
+
+For rendering semantics see [Declarative rendering](../rendering.md) and [`<solid-render>`](../solid-render.md).

package/docs/api/runtime.md

@@ -0,0 +1,87 @@
+# Core runtime API
+
+```ts
+import { createRuntime } from "solid-tag-runtime";
+```
+
+## Creation
+
+```ts
+const runtime = createRuntime(options);
+```
+
+Important options:
+
+- `modules` — initial host namespace modules
+- `urls` — initial URL modules
+- `compiler` / `compilerOptions`
+- `resolve`
+- `allowNativeImports`
+- `moduleUrlBackend`
+- `compileCache` — optional persistent pre-link compiler cache
+
+## Definition
+
+```ts
+runtime.define(id, source, options?);
+runtime.defineMany(definitions);
+runtime.defineModule(id, namespace);
+runtime.defineUrl(id, url);
+runtime.update(id, source, options?);
+```
+
+## Loading/compilation
+
+```ts
+await runtime.import(id);
+await runtime.compile(id, { cache?: "use" | "refresh" | "bypass" });
+await runtime.toModule(source, options?);
+await runtime.toComponent(source, options?);
+```
+
+`runtime.compile()` preserves its public meaning: it returns the current linked/executable code and URL. The persistent cache stores an internal pre-link artifact instead.
+
+## Lifecycle
+
+```ts
+runtime.invalidate(id, {
+  dependents?: boolean,
+  compile?: boolean,
+});
+
+runtime.remove(id, options?);
+runtime.clear(options?);
+runtime.dispose();
+```
+
+## Introspection
+
+```ts
+runtime.has(id);
+runtime.resolve(specifier, importer?);
+runtime.modules();
+runtime.dependencies(id);
+runtime.dependents(id);
+runtime.getModuleInfo(id);
+```
+
+## Events
+
+```ts
+runtime.subscribe(listener);
+runtime.subscribe(type, listener);
+runtime.subscribe(types, listener);
+```
+
+See [Lifecycle events](../lifecycle-events.md).
+
+## Compile-cache management
+
+```ts
+runtime.compileCache.enabled;
+await runtime.compileCache.invalidate(id);
+await runtime.compileCache.clear();
+await runtime.compileCache.clear({ allVersions: true });
+```
+
+See [Compile-cache API](./compile-cache.md).

package/docs/compile-cache.md

@@ -0,0 +1,271 @@
+# Persistent compile cache
+
+Persistent compile caching is opt-in. It stores **pre-link compiled artifacts**, not linked runtime modules.
+
+```text
+source
+  ↓
+compile
+  ↓
+compiled artifact   ← persistent cache boundary
+  ↓
+link
+  ↓
+module URL
+  ↓
+native import/evaluation
+```
+
+The cache accelerates parsing/transformation/module-reference analysis while all runtime-dependent linking stays fresh.
+
+## What is persisted
+
+A compiled artifact contains linker-ready JavaScript and import-reference metadata:
+
+```ts
+{
+  code,
+  imports,
+  diagnostics,
+  sourceMap?
+}
+```
+
+Import metadata refers to the **compiled code**, not the original JSX source.
+
+## What is never persisted
+
+- linked source containing current Blob/data/dependency URLs
+- Blob/data URLs
+- module URL backend results
+- host bridge identities
+- native module namespaces
+- import promises
+- runtime resolver output
+
+## Enable IndexedDB caching
+
+IndexedDB is the recommended browser backend:
+
+```ts
+import {
+  createRuntime,
+  createIndexedDBCompileCache,
+} from "solid-tag-runtime";
+
+const runtime = createRuntime({
+  compileCache: {
+    store: createIndexedDBCompileCache({
+      database: "my-app-runtime",
+    }),
+    namespace: "main",
+    version: "1",
+  },
+});
+```
+
+Without `compileCache`, persistent lookup/write behavior is disabled.
+
+## localStorage
+
+Useful for small demos and debugging:
+
+```ts
+import { createLocalStorageCompileCache } from "solid-tag-runtime";
+
+const store = createLocalStorageCompileCache();
+```
+
+`localStorage` is synchronous underneath, smaller, and less suitable for large compiled artifacts. The provider still exposes the same async store interface.
+
+## Memory provider
+
+```ts
+import { createMemoryCompileCache } from "solid-tag-runtime";
+
+const store = createMemoryCompileCache();
+```
+
+This is useful for tests, benchmarks, and validating cache identity across runtime instances within one page/process.
+
+## Cache identity
+
+The logical artifact key includes:
+
+```text
+artifact ABI
++ compiler fingerprint
++ source format
++ compile-affecting context
++ exact source SHA-256
+```
+
+It deliberately excludes:
+
+- dependency versions/source
+- resolver state
+- module URL backend
+- host-module values
+- module ID by default
+
+Therefore identical source may share one compiler artifact under different module IDs while linking relative imports independently for each ID.
+
+## Compiler fingerprint
+
+The default `solid-tag` compiler supplies a stable fingerprint. A custom compiler must provide one to use persistent storage safely:
+
+```ts
+const compiler = {
+  fingerprint: "my-compiler:v3",
+  compile(source, context) {
+    return artifact;
+  },
+};
+```
+
+The fingerprint may be a function when compilation behavior depends on context:
+
+```ts
+fingerprint(context) {
+  return `my-compiler:v3:${context.format}`;
+}
+```
+
+A custom compiler without a stable fingerprint still compiles normally, but persistent caching is bypassed and a one-time warning/event is produced.
+
+## `use`, `refresh`, and `bypass`
+
+```ts
+await runtime.compile("/App.jsx", { cache: "use" });
+await runtime.compile("/App.jsx", { cache: "refresh" });
+await runtime.compile("/App.jsx", { cache: "bypass" });
+```
+
+### `use`
+
+Read reusable compiler artifacts; compile/write on miss.
+
+### `refresh`
+
+Skip reusable artifact reads for the requested module, compile fresh, and replace the stored record.
+
+### `bypass`
+
+Compile the requested module fresh without persistent read/write.
+
+Dependencies continue using their normal reusable artifacts.
+
+## Graph invalidation vs compiler invalidation
+
+Normal invalidation preserves compiler artifacts:
+
+```ts
+runtime.invalidate("/Button.jsx");
+```
+
+This revokes/rebuilds linked/evaluated graph state but keeps syntax work reusable.
+
+Force only the requested module to compile fresh next time:
+
+```ts
+runtime.invalidate("/Button.jsx", {
+  compile: true,
+});
+```
+
+Dependents relink but are not forced to recompile.
+
+## Persistent cache management
+
+Delete the current module's stored artifact:
+
+```ts
+await runtime.compileCache.invalidate("/App.jsx");
+```
+
+Clear the current namespace/version:
+
+```ts
+await runtime.compileCache.clear();
+```
+
+Clear all versions in the current namespace:
+
+```ts
+await runtime.compileCache.clear({
+  allVersions: true,
+});
+```
+
+These are cache-management operations, not graph-removal APIs.
+
+## Application version
+
+```ts
+compileCache: {
+  namespace: "editor",
+  version: "2026.10.3",
+  store,
+}
+```
+
+Changing `version` creates logical misses without requiring an eager database scan/deletion. It is the application-controlled global invalidation switch.
+
+## Bounds
+
+```ts
+compileCache: {
+  store,
+  namespace: "editor",
+  version: "1",
+  maxEntries: 500,
+  maxBytes: 50 * 1024 * 1024,
+  maxAge: 30 * 24 * 60 * 60 * 1000,
+}
+```
+
+Built-in stores support basic age/entry/byte pruning. This is intentionally simple; cross-tab locks and sophisticated global LRU are not part of the first implementation.
+
+## Failure behavior
+
+Persistent storage is an optimization. Read/write/corruption/provider failures fall back to normal compilation whenever possible and are observable through `compile-cache-error`.
+
+For quota-style write failures, the runtime first prunes eligible/older records and retries the write once. If that retry also fails, it emits `compile-cache-error` and continues with the freshly compiled in-memory artifact. Cache failure never makes normal module compilation unavailable.
+
+Explicit management calls such as `compileCache.clear()` may reject when the explicitly requested storage operation cannot be completed.
+
+## Introspection
+
+```ts
+runtime.getModuleInfo("/App.jsx")?.compileCache;
+```
+
+Example fields:
+
+```ts
+{
+  enabled: true,
+  status: "hit",
+  source: "indexeddb",
+  key: "...",
+  compilerFingerprint: "...",
+  sourceHash: "...",
+  compileContextHash: "..."
+}
+```
+
+## Dependency-only changes
+
+If `/App.jsx` imports `/Button.jsx` and only `Button` source changes:
+
+```text
+Button
+  → compiler miss/new artifact
+  → relink
+
+App
+  → compiler artifact reused
+  → relink against new Button URL
+```
+
+This is the primary reason the persistent cache boundary is pre-link rather than linked output.

package/docs/getting-started.md

@@ -0,0 +1,105 @@
+# Getting started
+
+## Install
+
+```bash
+npm install solid-tag-runtime solid-tag
+```
+
+The runtime intentionally does not bundle its own Solid runtime. Register the host application's existing Solid modules so dynamically compiled code shares the same reactive system.
+
+```ts
+import * as Solid from "solid-js";
+import * as SolidWeb from "@solidjs/web";
+import html from "@solidjs/html";
+import { createRuntime } from "solid-tag-runtime";
+
+const runtime = createRuntime({
+  modules: {
+    "solid-js": Solid,
+    "@solidjs/web": SolidWeb,
+    "@solidjs/html": { default: html },
+  },
+});
+```
+
+## Define and import a module
+
+```ts
+runtime.define("/Counter.jsx", `
+  import { createSignal } from "solid-js";
+
+  export default function Counter() {
+    const [count, setCount] = createSignal(0);
+    return (
+      <button onClick={() => setCount(value => value + 1)}>
+        {count()}
+      </button>
+    );
+  }
+`);
+
+const module = await runtime.import("/Counter.jsx");
+module.default;
+```
+
+Relative imports between runtime modules work normally:
+
+```ts
+runtime.define("/ui/Button.jsx", `
+  export function Button(props) {
+    return <button>{props.children}</button>;
+  }
+`);
+
+runtime.define("/App.jsx", `
+  import { Button } from "./ui/Button.jsx";
+
+  export default function App() {
+    return <Button>Hello</Button>;
+  }
+`);
+```
+
+## Browser HTML adapter
+
+```ts
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+const htmlRuntime = createHTMLRuntime(runtime, {
+  scope: "main",
+  root: document,
+});
+
+await htmlRuntime.register();
+await htmlRuntime.observe({ registerExisting: false });
+```
+
+Declarative source:
+
+```html
+<script
+  type="solid-jsx"
+  data-solid-runtime="main"
+  module="/App.jsx"
+>
+  export default function App() {
+    return <h1>Hello</h1>;
+  }
+</script>
+```
+
+See [HTML runtime](./html-runtime.md), [declarative rendering](./rendering.md), and [`<solid-render>`](./solid-render.md) for browser-specific behavior.
+
+## Browser import maps
+
+When loading through an import map, map both the package root and HTML subpath to the same release:
+
+```json
+{
+  "imports": {
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.13",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.13/html"
+  }
+}
+```