solid-tag-runtime 0.0.11 → 0.0.13

package/ARCHITECTURE.md

@@ -518,77 +518,166 @@ This avoids introducing a second template language, implicit lexical scope rules
 
 ## 9. Compiler adapter boundary
 
-The runtime engine itself does not depend on Acorn or the `solid-tag` AST.
+The runtime engine remains independent of the `solid-tag` AST. `0.0.13` formalizes a linker-ready **CompiledArtifact** boundary so compiler work can be cached before runtime-specific linking.
 
-It requires a compiler adapter with two operations:
+Preferred compiler contract:
 
 ```ts
 interface RuntimeCompiler {
-  analyze(source, context): {
-    imports: ImportReference[];
-    needsHtmlRuntime?: boolean;
-  };
-
-  transform(source, context): {
-    code: string;
-    diagnostics?: unknown[];
-  };
+  fingerprint?: string | ((context: CompileContext) => string | Promise<string>);
+  cacheContext?: (context: CompileContext) => unknown | Promise<unknown>;
+
+  compile?(
+    source: string,
+    context: CompileContext,
+  ): CompiledArtifact | Promise<CompiledArtifact>;
+
+  // Transitional compatibility path:
+  analyze?(source, context): { imports: ImportReference[] };
+  transform?(source, context): { code: string; diagnostics?: unknown[] };
 }
 ```
 
-The default adapter lives in `src/compiler.js` and uses:
+The default adapter in `src/compiler.js` uses `solid-tag` and provides a stable fingerprint. JSX transformation runs **before** linking and intentionally leaves module specifiers unresolved. The resulting artifact is analyzed after transformation so import-reference offsets point into compiled JavaScript, not the original JSX source.
 
-```text
-solid-tag.parseJSX()
-solid-tag.transformModule()
+Conceptual artifact:
+
+```ts
+interface CompiledArtifact {
+  schema: 1;
+  code: string;
+  imports: ImportReference[];
+  diagnostics: unknown[];
+  sourceMap?: string;
+}
 ```
 
+The older `analyze()` + `transform()` pair remains supported for custom compilers. For that compatibility path the runtime transforms first, then analyzes the transformed code to construct the same artifact shape.
+
+A custom compiler may compile normally without a fingerprint, but persistent artifact reuse is disabled because the runtime must never guess compiler identity.
+
 ### Why this boundary exists
 
-It allows future compiler implementations without rewriting the runtime module system.
+It separates:
 
-Possible future adapters include:
+```text
+compiler
+  syntax transformation + module-reference analysis
 
-- a TSX-capable `solid-tag` backend
-- another JSX parser
-- pre-tagged source processing
-- reverse/tagged transformations for tooling
+linker
+  runtime resolution + dependency URL rewriting
+```
 
-The module graph must remain independent of parser details.
+That boundary supports persistent compile caching and also keeps future TSX compilers, compiler workers, build-time artifacts, and alternate parsers independent from graph/link execution.
 
-## 10. Linking pipeline
+## 10. Compile, cache, and linking pipeline
 
-For a source module `/features/Counter.jsx`:
+The source-module pipeline is now explicitly:
 
 ```text
 source
   ↓
-compiler.analyze()
+compile source syntax
   ↓
-collect static imports / re-exports / literal dynamic imports
+CompiledArtifact
+  │  transformed code
+  │  unresolved import specifiers
+  │  import offsets into transformed code
+  │  diagnostics/source map
+  │
+  ├──────── optional persistent cache boundary
+  │
   ↓
-resolve each specifier
+resolve imports against current runtime graph
   ↓
-ensure virtual dependencies have module URLs
+ensure current dependency module URLs
   ↓
-rewrite import string literals to linked URLs
+rewrite artifact import ranges
   ↓
-solid-tag transformation (for JSX format)
+linked executable JavaScript
   ↓
-create native module URL
+module URL backend
   ↓
-import(moduleUrl)
+native import/evaluation
+```
+
+For `/features/Counter.jsx`, the persistent artifact may still contain:
+
+```js
+import { createSignal } from "solid-js";
+import html from "@solidjs/html";
+import { Button } from "../ui/Button.jsx";
+```
+
+Only the linker turns those specifiers into current host bridges, external URLs, or generated runtime module URLs.
+
+### Persistent compile cache
+
+`0.0.13` adds an opt-in persistent compile cache.
+
+The stored artifact is **pre-link**. Never persist:
+
+- dependency Blob/data URLs
+- linked executable source
+- module URL backend output
+- native module namespaces/import promises
+- host bridge identities
+- custom resolver output
+
+Logical compile identity is content-addressed from:
+
+```text
+artifact ABI
++ compiler fingerprint
++ source format
++ compile-affecting context hash
++ exact source SHA-256
+```
+
+Module ID is excluded by default. Dependency source/version, resolver state, host values, and module URL backend are also excluded because they belong to linking/evaluation rather than compilation.
+
+This means identical source can reuse one artifact under multiple module IDs while relative imports are still linked independently per importer.
+
+Built-in stores:
+
+```text
+createIndexedDBCompileCache()   recommended persistent browser backend
+createLocalStorageCompileCache() convenience/small-artifact backend
+createMemoryCompileCache()      tests/benchmarks/process-local reuse
+```
+
+Persistent caching is configured on `createRuntime({ compileCache })` and remains fully opt-in.
+
+### Invalidation layers
+
+The runtime now distinguishes:
+
+```text
+compile artifact
+linked executable graph
+native evaluated module identity
 ```
 
-Example graph:
+Normal `runtime.invalidate(id)` invalidates linked/evaluated state while preserving the reusable compiled artifact. `runtime.invalidate(id, { compile: true })` additionally forces only the requested module to compile fresh on its next link. Dependents relink but retain their own compiler artifacts.
+
+`runtime.update(id, newSource)` naturally computes a different content key for the changed source. Old persistent artifacts are not eagerly deleted because they may still be useful to another runtime, tab, module ID, or undo/revert operation.
+
+Public `runtime.compile()` retains its existing meaning: it returns linked/executable code and URL. Internal persistent artifacts are not silently substituted into the public result.
+
+### Cache controls
 
 ```text
-/features/Counter.jsx
-  ├── solid-js             → host bridge module
-  ├── @solidjs/html        → host bridge module
-  └── ../ui/Button.jsx     → compiled virtual source URL
+use      read reusable artifact; compile/write on miss
+refresh  compile requested module fresh and replace artifact
+bypass   compile requested module fresh without persistent read/write
 ```
 
+Explicit persistent management lives under `runtime.compileCache` and is separate from graph removal/invalidation.
+
+### Failure model
+
+Persistent caching is an optimization. Read/write/validation/pruning failures emit compile-cache lifecycle diagnostics and fall back to normal compilation whenever possible. Explicit management operations may surface the storage error because the caller explicitly requested that storage mutation.
+
 ## 11. Resolution rules
 
 Resolution order is conceptually:
@@ -1191,7 +1280,7 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 10. Initial light-DOM child nodes are captured once and exposed as reusable `props.children`; named slots and dynamic child recapture are not part of this phase.
 11. Multiple elements may share one evaluated module namespace while owning independent Solid component roots.
 12. Disconnect disposes the mounted root; reconnect mounts a fresh component instance from the retained declaration inputs.
-13. Custom-element registration is global/idempotent per `CustomElementRegistry`. `createHTMLRuntime()` registers it after installing the controller in the shared registry; registration/observation paths remain idempotent. `registerSolidRenderElement()` remains available for explicit/custom-registry use.
+13. Custom-element registration is global/idempotent per `CustomElementRegistry`, but controller creation does **not** eagerly upgrade existing `solid-render` elements. Initial `register()` / `observe()` first install the complete declarative script batch and then ensure the custom element is registered. `registerSolidRenderElement()` remains available for explicit/custom-registry use.
 14. Runtime/controller disposal tears down both script-owned mounts and connected `solid-render` instances so no Solid owners are orphaned.
 
 Rendering lifecycle joins the existing HTML event stream through `render-mounting`, `render-mounted`, `render-disposing`, and `render-disposed`; failures are also reported through `html-error` with `render`/`solid-render` operations. Lifecycle subscriptions remain observational and cannot alter rendering.
@@ -1235,3 +1324,43 @@ Rules now enforced:
 7. `/ui/Button.jsx` and `./ui/Button.jsx` both resolve to the same registered virtual ID `/ui/Button.jsx` when imported at top level from the correct runtime.
 
 This keeps DOM routing and module routing failures separate and produces actionable errors instead of accidental browser network requests.
+
+
+### 0.0.12 — declarative registration barrier for `solid-render`
+
+Decision: an existing `<solid-render>` must never fail simply because its referenced `<script module>` has not yet been installed by the HTML adapter's initial registration pass.
+
+The 0.0.11 routing fix correctly selected the containing runtime, but `createHTMLRuntime()` still registered the global custom element immediately. Defining a custom element upgrades already-present `<solid-render>` nodes synchronously. Their `connectedCallback()` could therefore call `runtime.import("/ui/Button.jsx")` before `html.register()` had scanned and defined an earlier `<script module="/ui/Button.jsx">`, producing a legitimate but transient `ModuleResolutionError`.
+
+Rules now enforced:
+
+1. `createHTMLRuntime()` installs the controller in the shared registry but does not eagerly define/upgrade `<solid-render>`.
+2. Initial `register()` and initial `observe()` install their complete matching script batch first, then ensure the global custom element is registered. This preserves document-level declaration-before-instance semantics even though custom-element upgrade timing is synchronous.
+3. If the `solid-render` class was already registered globally by another controller, a connected instance may still run before this controller's declaration pass. A missing virtual module during an active registration/observer pass is treated as a pending reference rather than a terminal render error.
+4. After the registration/observer batch settles, pending instances inside that controller's root are retried. If the module is still missing after the batch, normal `solid-render` error semantics apply.
+5. A pending instance is also retried when its selected runtime later emits `module-defined` for the resolved module ID. This supports dynamically arriving declarative/programmatic modules without remounting already-successful instances.
+6. Retries remain generation-guarded, so stale async work cannot replace a newer module/component/runtime identity.
+7. The existing graph invariant remains unchanged: all declarations in a discovered script batch are defined before entry/render execution or recovery mounts are allowed to succeed.
+
+This separates three orderings that must all be correct: DOM parsing order, custom-element upgrade/connection timing, and runtime module-definition timing.
+
+### 0.0.13 — pre-link persistent compile cache and structured documentation
+
+Decision: persistent caching stores only fully syntax-compiled, linker-ready artifacts. Runtime-specific dependency resolution, generated module URLs, host bridge identity, and native evaluation remain session-local.
+
+Rules now enforced:
+
+1. JSX transformation happens before runtime linking; import metadata is collected against transformed code so cached offsets remain valid.
+2. Persistent artifact identity includes artifact ABI, compiler fingerprint, source format, compile-affecting context, and exact source SHA-256.
+3. Module ID, dependency versions, resolver state, host values, and URL-backend choice are not part of the default compile key.
+4. Identical source may therefore share an artifact across module IDs while relative imports are linked separately for each importer.
+5. The default `solid-tag` compiler exposes a stable fingerprint. Custom compilers without a fingerprint continue to work but persistent caching is bypassed rather than guessed.
+6. `runtime.invalidate()` preserves compiler artifacts by default. `{ compile: true }` forces only the requested module to compile fresh; dependents relink without forced recompilation.
+7. `runtime.compile(id, { cache: "use" | "refresh" | "bypass" })` controls compiler-artifact lookup while preserving the existing public linked/executable compile result.
+8. `runtime.compileCache.invalidate()` and `.clear()` manage stored artifacts without deleting runtime module definitions.
+9. IndexedDB, localStorage, and memory providers share one async store contract. Provider failures never make normal compilation unavailable. Quota-style write failures trigger pruning plus one retry; a failed retry becomes an observational cache error while the freshly compiled in-memory artifact remains usable.
+10. Optional `maxAge`, `maxEntries`, and `maxBytes` bounds provide deliberately simple pruning; sophisticated global LRU and cross-tab locking remain deferred.
+11. Compile-cache lifecycle events remain observational and integrate with the existing typed subscription system.
+12. Package documentation is now organized under `docs/`, with feature guides and `docs/api/` references. The root README is an entry point; this architecture file remains the engineering handoff/decision log.
+13. HTML documentation explicitly requires `<solid-render></solid-render>` rather than XML-style `<solid-render />`; custom elements are not HTML void elements and self-closing syntax can accidentally capture following DOM as initial `props.children`.
+