solid-tag-runtime 0.0.12 → 0.0.14

package/ARCHITECTURE.md

@@ -44,7 +44,9 @@ The runtime should allow applications to:
 11. support normal JavaScript modules in the same graph
 12. declaratively mount runtime component exports through the HTML adapter
 13. reuse existing runtime modules through a light-DOM `solid-render` custom element
-14. keep the JSX compiler replaceable behind a narrow adapter
+14. optionally resolve a coherent standard Solid package family without teaching the core runtime about providers
+15. lazily establish Solid 2 delegated-event infrastructure for wrapperless range mounts while preserving independent reactive roots
+16. keep the JSX compiler replaceable behind a narrow adapter
 
 ## 3. Current non-goals
 
@@ -58,6 +60,8 @@ The initial package does not attempt to provide:
 - circular runtime source-module support
 - transparent live replacement of already-held component references
 - full HMR propagation semantics
+- provider/CDN policy inside the core `createRuntime()` implementation
+- automatic import-map mutation
 
 These may be added later without changing the module-first public model. HTML script discovery was added in `0.0.2` as a separate browser adapter rather than as a responsibility of the core module engine.
 
@@ -69,7 +73,11 @@ Application
    ├── host Solid runtime
    │     ├── solid-js
    │     ├── @solidjs/web
-   │     └── @solidjs/html
+   │     ├── @solidjs/html
+   │     └── @solidjs/signals
+   │
+   ├── solid-tag-runtime/solid       (optional setup/provider integration)
+   │       └── resolves host namespaces, then calls the normal runtime
    │
    └── solid-tag-runtime
           │
@@ -153,6 +161,39 @@ runtime.dispose();
 
 Lifecycle subscriptions are synchronous observational notifications. They do not intercept or modify runtime behavior. Resolution behavior remains customizable through `resolve()`, compilation through the compiler adapter, and executable-module creation through `ModuleUrlBackend`.
 
+### Optional Solid integration subpath
+
+`solid-tag-runtime/solid` is additive and does not change the low-level runtime contract:
+
+```ts
+const modules = await loadSolidModules(options?);
+const runtime = await createSolidRuntime(options?);
+```
+
+The integration resolves the canonical family:
+
+```text
+solid-js
+@solidjs/web
+@solidjs/html
+@solidjs/signals
+```
+
+`loadSolidModules()` returns ordinary namespaces compatible with the existing `modules` option. `createSolidRuntime()` composes that loader with the normal runtime and installs one private `SolidRuntimeIntegration` capability used by higher-level DOM features. Caller-provided modules win over automatic defaults.
+
+Important boundaries:
+
+1. `createRuntime()` remains synchronous and never performs provider/import-map work.
+2. Provider-specific logic is isolated under `src/solid/providers/`.
+3. Existing browser/import-map mappings are authoritative and are never rewritten.
+4. A versioned Solid-family mapping becomes a provider/version identity anchor for generated siblings.
+5. esm.sh generated siblings externalize authoritative mapped dependencies and pin coordinated missing dependencies when no anchor exists.
+6. jsDelivr mixed-provider cases that cannot safely preserve core Solid identity fail rather than silently loading another runtime.
+7. CDN fallback uses a package-tested Solid family version when no versioned anchor exists; provider `latest` is not the hidden default.
+8. The integration layer may inspect page import maps and effective resolution, but it never mutates import maps.
+
+The integration registry itself is a private `WeakMap<runtime, integration>`; the core module graph does not store provider metadata or DOM delegation state.
+
 ## 6. Module kinds
 
 The runtime currently has three module record kinds.
@@ -516,79 +557,198 @@ The adapter does not transform arbitrary document HTML into JSX and does not cur
 
 This avoids introducing a second template language, implicit lexical scope rules, or ambiguous ownership of already-parsed DOM.
 
+### Wrapperless Solid 2 delegated-event integration
+
+A bare declarative render keeps the existing marker-range ownership model:
+
+```text
+<script render> A                 <script render> B
+      ↓                                  ↓
+createRoot A                        createRoot B
+      ↓                                  ↓
+insert(range A)                     insert(range B)
+```
+
+Solid 2 delegated handlers may require a DOM render/delegation context for the containing `Document`. A runtime created through `createSolidRuntime()` therefore carries a private lazy capability:
+
+```ts
+ensureDelegation(document);
+```
+
+The first wrapperless range mount calls it immediately before its normal `createRoot() + insert()` path. The capability:
+
+1. creates/reuses one lightweight `render(() => undefined, document)` host keyed by **Document × `@solidjs/web` namespace identity**;
+2. ensures the delegated event set through that same renderer namespace;
+3. does not render application components inside the host;
+4. does not use `runWithOwner()` and does not parent wrapperless roots under the host owner;
+5. stays alive independently of any one marker range.
+
+Selector rendering (`render="#target"`) remains normal container rendering. `<solid-render>` remains a persistent light-DOM container and is unchanged by this integration. Low-level runtimes created by `createRuntime()` do not receive this capability automatically.
+
+The delegated event helper prefers `@solidjs/web.DelegatedEvents` when available and otherwise uses the standard Solid/dom-expressions delegated UI-event family. Registration is idempotent per renderer/document pair.
+
 ## 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
 ```
 
-Example graph:
+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
+```
+
+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:
@@ -1254,3 +1414,47 @@ 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`.
+
+### 0.0.14 — additive Solid runtime setup and lazy wrapperless delegation
+
+Decision: add `solid-tag-runtime/solid` as an opt-in integration layer while keeping `createRuntime()` provider-agnostic and synchronous.
+
+Public setup layers:
+
+```text
+createRuntime()
+    low-level; caller supplies already-resolved namespaces
+
+loadSolidModules()
+    resolves/imports the coordinated Solid family
+
+createSolidRuntime()
+    loadSolidModules + createRuntime + private lazy Solid integration
+```
+
+Resolution rules preserve explicit/effective page mappings before provider generation. Provider-specific URL logic lives outside the core runtime. The built-in fallback policy targets the tested Solid `2.0.0-rc.13` family rather than silently following CDN `latest`. esm.sh generation uses dependency externalization/pinning to preserve one Solid identity; its family model treats `@solidjs/signals` as the Solid 2 reactive core consumed by `solid-js`, with `@solidjs/web` and `@solidjs/html` layered above it. jsDelivr mixed-provider situations that cannot be guaranteed are rejected. Import maps are read-only inputs and are never mutated.
+
+Decision: fix wrapperless Solid 2 delegated events with the smallest ownership-preserving change. `createSolidRuntime()` installs `ensureDelegation(document)` but does not execute it eagerly. The first wrapperless range mount creates/reuses one document-level delegation host per `Document × @solidjs/web namespace`, ensures delegated event types, then proceeds with the existing independent `createRoot() + insert()` mount.
+
+The delegation host is infrastructure only. It is not a shared application owner, is not a parent of declarative roots, is not disposed with an individual range, and does not change selector rendering or `<solid-render>` container ownership. Low-level `createRuntime()` behavior is unchanged.
+