solid-tag-runtime 0.0.13 → 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,6 +557,36 @@ 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 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.
@@ -1364,3 +1435,26 @@ Rules now enforced:
 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.
+

package/README.md

@@ -11,10 +11,10 @@ pre-link compiled artifact
     ↓
 solid-tag-runtime linker
     ↓
-@solidjs/html + host Solid runtime
+host Solid runtime
 ```
 
-The core package is module-first and DOM-independent. Browser discovery, ownership, declarative rendering, and `<solid-render>` live in the `solid-tag-runtime/html` adapter.
+The core package is module-first and DOM-independent. Browser discovery, ownership, declarative rendering, and `<solid-render>` live in `solid-tag-runtime/html`. Optional Solid setup/provider helpers live in `solid-tag-runtime/solid`.
 
 ## Install
 
@@ -22,7 +22,36 @@ The core package is module-first and DOM-independent. Browser discovery, ownersh
 npm install solid-tag-runtime solid-tag
 ```
 
-## Quick start
+## Easiest Solid setup
+
+`0.0.14` adds an opt-in high-level Solid integration:
+
+```ts
+import { createSolidRuntime } from "solid-tag-runtime/solid";
+
+const runtime = await createSolidRuntime({
+  modules: {
+    "@app/state": state,
+  },
+});
+```
+
+The helper resolves the standard family:
+
+```text
+solid-js
+@solidjs/web
+@solidjs/html
+@solidjs/signals
+```
+
+Existing browser/bundler resolution and import-map mappings are preferred. Missing packages may be filled through an inferred/configured provider. Existing mappings are never rewritten, and user-provided modules override automatic defaults.
+
+`createSolidRuntime()` also installs a **lazy** Solid DOM integration used by wrapperless `<script render>` mounts. It does not establish a document render/delegation host until a wrapperless render actually needs one.
+
+See [Solid runtime setup](./docs/solid-runtime-setup.md).
+
+## Low-level setup remains unchanged
 
 ```ts
 import * as Solid from "solid-js";
@@ -37,7 +66,36 @@ const runtime = createRuntime({
     "@solidjs/html": { default: html },
   },
 });
+```
+
+`createRuntime()` remains synchronous and does not know about CDNs, browser import maps, Solid version inference, or document event delegation.
+
+## Composable Solid module loader
 
+If you want provider-aware setup but still want to call `createRuntime()` yourself:
+
+```ts
+import { loadSolidModules } from "solid-tag-runtime/solid";
+import { createRuntime } from "solid-tag-runtime";
+
+const solidModules = await loadSolidModules({
+  source: "auto",
+  fallbackProvider: "esm.sh",
+});
+
+const runtime = createRuntime({
+  modules: {
+    ...solidModules,
+    "@app/state": state,
+  },
+});
+```
+
+Provider logic is isolated from the core runtime. `loadSolidModules()` reads existing mappings/resolution but never mutates import maps. If a host resolves only part of the Solid family but its identity is opaque, automatic CDN mixing is rejected rather than risking a second Solid runtime.
+
+## Define runtime modules
+
+```ts
 runtime.define("/Greeting.jsx", `
   export default function Greeting() {
     return <p>Hello from runtime JSX</p>;
@@ -79,11 +137,15 @@ Bare `render` mounts in place without adding a wrapper:
 ```html
 <script type="solid-jsx" module="/Message.jsx" render>
   export default function Message() {
-    return <strong>Hello</strong>;
+    return <button onClick={() => console.log("clicked")}>Click</button>;
   }
 </script>
 ```
 
+When the runtime was created with `createSolidRuntime()`, wrapperless mounting lazily ensures Solid's document-level delegated-event infrastructure while keeping every declaration in its own independently disposable `createRoot() + insert()` root.
+
+See [Wrapperless delegation](./docs/wrapperless-delegation.md).
+
 ## Reusable `<solid-render>` instances
 
 ```html
@@ -101,7 +163,7 @@ Bare `render` mounts in place without adding a wrapper:
 
 ## Persistent compile cache
 
-`0.0.13` adds an opt-in persistent cache for **pre-link compiler artifacts**. Runtime-specific linked URLs and evaluated module namespaces are never persisted.
+The opt-in compile cache persists **pre-link compiler artifacts**. Runtime-specific linked URLs and evaluated module namespaces are never persisted.
 
 ```ts
 import {
@@ -120,29 +182,23 @@ const runtime = createRuntime({
 });
 ```
 
-The cache key is content-based and includes the source hash, compiler fingerprint, artifact ABI, format, and compile-affecting context. Dependency versions and resolver state are deliberately excluded, so unchanged importers can reuse compiler work and relink against changed dependencies.
-
-```ts
-await runtime.compile("/App.jsx", { cache: "use" });
-await runtime.compile("/App.jsx", { cache: "refresh" });
-await runtime.compile("/App.jsx", { cache: "bypass" });
-
-await runtime.compileCache.invalidate("/App.jsx");
-await runtime.compileCache.clear();
-```
+See [Persistent compile cache](./docs/compile-cache.md).
 
 ## Documentation
 
-The detailed documentation now lives under [`docs/`](./docs/README.md):
+Detailed documentation lives under [`docs/`](./docs/README.md):
 
 - [Getting started](./docs/getting-started.md)
+- [Solid runtime setup and providers](./docs/solid-runtime-setup.md)
 - [Runtime modules and resolution](./docs/modules.md)
 - [HTML runtime and ownership](./docs/html-runtime.md)
 - [Declarative rendering](./docs/rendering.md)
+- [Wrapperless delegation](./docs/wrapperless-delegation.md)
 - [`<solid-render>`](./docs/solid-render.md)
 - [Lifecycle events](./docs/lifecycle-events.md)
 - [Persistent compile cache](./docs/compile-cache.md)
 - [Core runtime API](./docs/api/runtime.md)
+- [Solid integration API](./docs/api/solid.md)
 - [HTML runtime API](./docs/api/html.md)
 - [Compile-cache API](./docs/api/compile-cache.md)
 
@@ -150,17 +206,20 @@ For engineering invariants and design decisions, see [`ARCHITECTURE.md`](./ARCHI
 
 ## Browser import maps
 
-When loading from an import map, map both entries to the same version:
+When loading from an import map, map every used package 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"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.14",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.14/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.14/solid"
   }
 }
 ```
 
+The Solid helper does **not** inject or mutate import maps.
+
 ## Current limitations
 
 - runtime-defined source-module cycles are not supported yet
@@ -168,3 +227,4 @@ When loading from an import map, map both entries to the same version:
 - persistent compile caching is an optimization, not a security sandbox
 - already-held namespace/component references are not mutated by module updates
 - TypeScript/TSX support depends on the configured compiler
+- the built-in provider layer currently supports esm.sh and jsDelivr; unsafe mixed-provider cases fail rather than silently loading a second Solid runtime

package/docs/README.md

@@ -1,13 +1,15 @@
 # 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`.
+`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`, and optional Solid setup/provider logic lives in `solid-tag-runtime/solid`.
 
 ## Start here
 
 - [Getting started](./getting-started.md)
+- [Solid runtime setup and provider resolution](./solid-runtime-setup.md)
 - [Runtime modules and resolution](./modules.md)
 - [HTML runtime and ownership](./html-runtime.md)
 - [Declarative rendering](./rendering.md)
+- [Wrapperless Solid 2 delegation](./wrapperless-delegation.md)
 - [`<solid-render>`](./solid-render.md)
 - [Lifecycle events](./lifecycle-events.md)
 - [Persistent compile cache](./compile-cache.md)
@@ -15,9 +17,10 @@
 ## API reference
 
 - [Core runtime API](./api/runtime.md)
+- [Solid integration API](./api/solid.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.
+The root [`ARCHITECTURE.md`](../ARCHITECTURE.md) is the engineering handoff and decision log. It documents internal invariants, compiler/linker boundaries, ownership rules, provider-resolution boundaries, and compatibility decisions.

package/docs/api/html.md

@@ -81,3 +81,9 @@ const observer = await observeHTML(runtime, options?);
 ```
 
 For rendering semantics see [Declarative rendering](../rendering.md) and [`<solid-render>`](../solid-render.md).
+
+## Wrapperless delegated events
+
+For bare `<script render>` ranges, automatic Solid delegated-event setup is available when the underlying runtime was created with `createSolidRuntime()` from `solid-tag-runtime/solid`.
+
+The HTML adapter asks the runtime's private Solid integration to establish document-level delegation lazily, then keeps the declaration in its existing independent `createRoot() + insert()` lifecycle. Selector renders and `<solid-render>` retain their existing container semantics.

package/docs/api/solid.md

@@ -0,0 +1,71 @@
+# Solid integration API
+
+```ts
+import {
+  createSolidRuntime,
+  loadSolidModules,
+  inspectSolidResolution,
+  SOLID_RUNTIME_PACKAGES,
+  TESTED_SOLID_VERSION,
+} from "solid-tag-runtime/solid";
+```
+
+## `loadSolidModules(options?)`
+
+Returns the standard Solid family as host-module namespaces:
+
+```ts
+const modules = await loadSolidModules({
+  source: "auto",
+  fallbackProvider: "esm.sh",
+  version: "2.0.0-rc.13",
+});
+```
+
+Options:
+
+- `source`: `"auto" | "host" | "esm.sh" | "jsdelivr"`
+- `fallbackProvider`: `"esm.sh" | "jsdelivr"`
+- `version`: provider fallback version when no versioned anchor exists
+- `modules`: already-resolved standard namespaces
+- `specifiers`: explicit URL/specifier overrides
+- `document`: optional document for read-only import-map inspection
+
+`source: "auto"` refuses to mix a partially resolved opaque host Solid family with CDN-generated siblings when the existing runtime identity cannot be established safely.
+
+## `createSolidRuntime(options?)`
+
+Async convenience factory:
+
+```ts
+const runtime = await createSolidRuntime({
+  modules: {
+    "@app/state": state,
+  },
+  solid: {
+    source: "auto",
+    fallbackProvider: "esm.sh",
+  },
+});
+```
+
+All ordinary runtime options remain available. `modules` supplied by the caller override automatic Solid defaults.
+
+The factory also installs the private lazy delegation capability used by wrapperless HTML rendering.
+
+## `inspectSolidResolution(options?)`
+
+Read-only helper for tooling/debugging:
+
+```ts
+const info = inspectSolidResolution();
+```
+
+Returns detected import-map mappings plus inferred provider/version information. It does not import modules and does not mutate the page.
+
+## Constants
+
+```ts
+SOLID_RUNTIME_PACKAGES;
+TESTED_SOLID_VERSION;
+```

package/docs/getting-started.md

@@ -6,7 +6,29 @@
 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.
+The runtime intentionally does not bundle its own Solid runtime.
+
+## High-level Solid setup
+
+For the shortest setup path:
+
+```ts
+import { createSolidRuntime } from "solid-tag-runtime/solid";
+
+const runtime = await createSolidRuntime({
+  modules: {
+    "@app/state": state,
+  },
+});
+```
+
+This resolves/imports the standard Solid family and installs lazy wrapperless event-delegation support.
+
+See [Solid runtime setup](./solid-runtime-setup.md) for import-map/provider/version behavior.
+
+## Low-level setup
+
+If the host already owns exact namespaces, keep using the synchronous core primitive:
 
 ```ts
 import * as Solid from "solid-js";
@@ -43,23 +65,7 @@ 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>;
-  }
-`);
-```
+Relative imports between runtime modules work normally.
 
 ## Browser HTML adapter
 
@@ -89,17 +95,18 @@ Declarative source:
 </script>
 ```
 
-See [HTML runtime](./html-runtime.md), [declarative rendering](./rendering.md), and [`<solid-render>`](./solid-render.md) for browser-specific behavior.
+See [HTML runtime](./html-runtime.md), [declarative rendering](./rendering.md), and [`<solid-render>`](./solid-render.md).
 
 ## Browser import maps
 
-When loading through an import map, map both the package root and HTML subpath to the same release:
+Map every used package subpath explicitly:
 
 ```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"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.14",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.14/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.14/solid"
   }
 }
 ```

package/docs/html-runtime.md

@@ -110,3 +110,11 @@ html.setAppendTarget(document.head);
 ```
 
 `root` controls discovery/observation; `appendTarget` controls where explicit additions are inserted. Reparenting the exact same root node does not require `setRoot()`.
+
+## Solid-aware wrapperless rendering
+
+A low-level `createRuntime()` controller behaves exactly as before and does not install Solid-specific document infrastructure.
+
+When the runtime comes from `createSolidRuntime()` in `solid-tag-runtime/solid`, a bare `<script render>` can lazily request the document-level delegated-event setup required by Solid 2. Each marker-range declaration still owns an independent reactive root and disposer; the delegation host is infrastructure only and is not a shared reactive owner.
+
+See [Solid runtime setup](./solid-runtime-setup.md) and [Wrapperless delegation](./wrapperless-delegation.md).

package/docs/rendering.md

@@ -16,6 +16,8 @@ A runtime script can define a module and mount one component instance.
 
 Without `component`, rendering selects `module.default`.
 
+Selector rendering continues to use normal Solid container rendering.
+
 ## Named export
 
 ```html
@@ -49,6 +51,10 @@ Bare `render` means mount at the exact declaration position:
 
 The adapter replaces the declaration with an owned marker range. No wrapper is introduced.
 
+Each in-place render owns its own `createRoot() + insert()` lifecycle. When the runtime comes from `createSolidRuntime()`, the first wrapperless mount lazily establishes the document-level Solid delegation infrastructure needed by delegated handlers such as `onClick`. That infrastructure is not the reactive owner of the mounted ranges.
+
+See [Wrapperless Solid 2 delegation](./wrapperless-delegation.md).
+
 ## Registration ordering
 
 All matching declarations in a discovered batch are defined before any `entry` or `render` declaration executes. An importer may therefore appear before its dependency in document order.