solid-tag-runtime 0.0.12 → 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
 ```
 
-Example graph:
+Persistent caching is configured on `createRuntime({ compileCache })` and remains fully opt-in.
+
+### Invalidation layers
+
+The runtime now distinguishes:
 
 ```text
-/features/Counter.jsx
-  ├── solid-js             → host bridge module
-  ├── @solidjs/html        → host bridge module
-  └── ../ui/Button.jsx     → compiled virtual source URL
+compile artifact
+linked executable graph
+native evaluated module identity
 ```
 
+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
+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:
@@ -1254,3 +1343,24 @@ Rules now enforced:
 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`.
+