solid-tag-runtime 0.0.13 → 0.0.15

package/docs/solid-runtime-setup.md

@@ -0,0 +1,181 @@
+# Solid runtime setup and provider resolution
+
+`solid-tag-runtime/solid` is an **optional additive integration layer**. The core `createRuntime()` API remains synchronous and provider-agnostic.
+
+## Standard Solid family
+
+The helper treats these packages as one coordinated runtime family:
+
+```text
+solid-js
+@solidjs/web
+@solidjs/html
+@solidjs/signals
+```
+
+The family is resolved coherently rather than as four unrelated imports.
+
+## High-level setup
+
+```ts
+import { createSolidRuntime } from "solid-tag-runtime/solid";
+
+const runtime = await createSolidRuntime({
+  modules: {
+    "@app/state": state,
+  },
+});
+```
+
+`createSolidRuntime()`:
+
+1. resolves/imports the standard Solid family;
+2. merges those namespaces with `modules`;
+3. gives caller-supplied modules precedence;
+4. calls the normal runtime engine;
+5. installs a lazy Solid integration capability used by wrapperless DOM rendering.
+
+The returned value is the normal `SolidTagRuntime` API.
+
+## Low-level setup
+
+Nothing changes for applications that already own their exact Solid namespaces:
+
+```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 },
+  },
+});
+```
+
+This path performs no provider detection and installs no implicit DOM delegation behavior.
+
+## Composable loader
+
+```ts
+import { loadSolidModules } from "solid-tag-runtime/solid";
+
+const solidModules = await loadSolidModules();
+
+const runtime = createRuntime({
+  modules: {
+    ...solidModules,
+    "@app/state": state,
+  },
+});
+```
+
+The returned object is directly compatible with the existing `modules` option.
+
+## Resolution precedence
+
+For the standard family the loader uses this precedence:
+
+```text
+1. already supplied namespace
+2. explicit specifier override
+3. existing browser import-map/effective host resolution
+4. provider inferred from an existing Solid-family mapping
+5. provider inferred weakly from other page mappings
+6. configured fallback provider
+7. actionable failure
+```
+
+Existing mappings are authoritative. The helper never silently replaces them.
+
+## Source modes
+
+```ts
+await loadSolidModules({ source: "auto" });
+await loadSolidModules({ source: "host" });
+await loadSolidModules({ source: "esm.sh" });
+await loadSolidModules({ source: "jsdelivr" });
+```
+
+### `auto`
+
+Use host/browser resolution first. Fill missing packages only when a coherent provider path can be determined.
+
+If only part of the Solid family resolves from an opaque host/bundler identity and the loader cannot identify the provider/version behind that runtime, `auto` fails instead of filling the rest from a CDN. This prevents a hidden second Solid runtime. Supply the missing namespaces explicitly or provide a coherent mapping/provider configuration.
+
+### `host`
+
+Use only already-resolvable host/bundler/browser modules. No CDN fallback is allowed.
+
+### `esm.sh`
+
+Use explicit/existing mappings where present and generate missing package URLs through the esm.sh adapter.
+
+### `jsdelivr`
+
+Use explicit/existing mappings where present and generate missing package URLs through the jsDelivr adapter. Cases that cannot safely preserve a pre-existing Solid identity fail rather than mixing providers silently.
+
+## Tested fallback version
+
+When provider fallback is needed and there is no versioned Solid anchor, this release uses a documented tested family version rather than CDN `latest`:
+
+```ts
+import { TESTED_SOLID_VERSION } from "solid-tag-runtime/solid";
+```
+
+For `0.0.14` and `0.0.15`, the tested fallback line is Solid `2.0.0-rc.13`.
+
+If an existing Solid mapping is explicitly versioned, that version becomes the family anchor for generated siblings. An explicitly unversioned existing mapping remains unversioned; the loader does not pretend it is pinned.
+
+## esm.sh identity handling
+
+When an authoritative page mapping exists, generated esm.sh siblings externalize that dependency so the browser resolves it through the existing mapping.
+
+When there is no existing core anchor, generated sibling package URLs pin coordinated Solid dependencies through provider-specific `deps` parameters. Solid 2's family direction is modeled with `@solidjs/signals` as the reactive core consumed by `solid-js`, then `@solidjs/web`, then `@solidjs/html`; the generated URLs pin/externalize that family closure rather than treating `@solidjs/signals` as depending back on `solid-js`.
+
+Provider query details remain isolated in the provider adapter; the core runtime does not know they exist.
+
+## Import maps are read-only
+
+The helpers may inspect import-map script contents and use the browser's effective resolver, but they never insert or rewrite import maps.
+
+```text
+loadSolidModules()
+createSolidRuntime()
+    ↓
+read/detect only
+    ↓
+no global import-map mutation
+```
+
+If an application wants to install an import map, it should do so before module evaluation using application-owned tooling.
+
+## User overrides
+
+Caller modules win:
+
+```ts
+const runtime = await createSolidRuntime({
+  modules: {
+    "solid-js": CustomSolid,
+    "@app/state": state,
+  },
+});
+```
+
+This is the escape hatch for custom builds, embedded runtimes, tests, and applications that already control dependency identity.
+
+## Wrapperless delegation capability
+
+`createSolidRuntime()` installs one private capability used by the HTML adapter:
+
+```text
+ensureDelegation(document)
+```
+
+Normal users do not call it. It is invoked lazily only when wrapperless `<script render>` mounting requires Solid's delegated-event infrastructure.
+
+See [Wrapperless delegation](./wrapperless-delegation.md).

package/docs/wrapperless-delegation.md

@@ -0,0 +1,81 @@
+# Wrapperless Solid 2 event delegation
+
+Bare declarative rendering uses marker ranges instead of a container element:
+
+```html
+<script type="solid-jsx" render>
+  export default function App() {
+    return <button onClick={() => console.log("clicked")}>Click</button>;
+  }
+</script>
+```
+
+Each declaration remains an **independent Solid reactive root**.
+
+## Ownership model
+
+```text
+Document
+│
+│ lazily, once per Document × @solidjs/web namespace:
+├── delegation host
+│
+├── wrapperless declaration A
+│     └── createRoot A + insert(range A)
+│
+└── wrapperless declaration B
+      └── createRoot B + insert(range B)
+```
+
+The delegation host exists only for DOM/event infrastructure. It is not the reactive parent of the wrapperless roots.
+
+Disposing A does not dispose B and does not tear down the document host.
+
+## When it is initialized
+
+The high-level factory:
+
+```ts
+await createSolidRuntime(...)
+```
+
+installs the capability but performs no DOM work immediately.
+
+The first wrapperless range mount does:
+
+```text
+ensure document delegation host
+ensure delegated event types
+create independent root
+insert component into marker range
+```
+
+If the application never performs wrapperless rendering, no document delegation host is created by this feature.
+
+## Selector rendering is unchanged
+
+```html
+<script type="solid-jsx" render="#app">
+```
+
+continues to use normal Solid container rendering.
+
+## `<solid-render>` is unchanged
+
+```html
+<solid-render module="/Counter.jsx"></solid-render>
+```
+
+continues to use its own persistent light-DOM container. This feature does not change its ownership model.
+
+## Low-level `createRuntime()`
+
+The core runtime deliberately does not install Solid-specific DOM behavior.
+
+If wrapperless delegated-event setup should be automatic, use `createSolidRuntime()` from `solid-tag-runtime/solid`.
+
+Advanced low-level users remain free to supply their own render adapter or host DOM setup.
+
+## Delegated events
+
+The integration prefers the renderer's exported delegated-event set when available and otherwise uses the standard Solid/dom-expressions delegated UI event family. Registration is idempotent per renderer/document pair.

package/examples/solid-runtime.js

@@ -0,0 +1,24 @@
+import { createSolidRuntime } from "solid-tag-runtime/solid";
+
+const runtime = await createSolidRuntime({
+  solid: {
+    source: "auto",
+    // Optional when the host/import map cannot resolve the complete family:
+    fallbackProvider: "esm.sh",
+  },
+  modules: {
+    "@app/config": {
+      greeting: "Hello",
+    },
+  },
+});
+
+runtime.define("/Greeting.jsx", `
+  import { greeting } from "@app/config";
+
+  export default function Greeting() {
+    return <p>{greeting} from createSolidRuntime()</p>;
+  }
+`);
+
+export default runtime;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -23,6 +23,11 @@
       "types": "./html.d.ts",
       "import": "./src/html.js",
       "default": "./src/html.js"
+    },
+    "./solid": {
+      "types": "./solid.d.ts",
+      "import": "./src/solid/index.js",
+      "default": "./src/solid/index.js"
     }
   },
   "main": "./src/index.js",
@@ -32,6 +37,7 @@
     "src",
     "index.d.ts",
     "html.d.ts",
+    "solid.d.ts",
     "README.md",
     "ARCHITECTURE.md",
     "docs",

package/solid.d.ts

@@ -0,0 +1,77 @@
+import type {
+  ModuleNamespaceLike,
+  RuntimeOptions,
+  SolidTagRuntime,
+} from "./index.js";
+
+export type SolidRuntimePackageName =
+  | "solid-js"
+  | "@solidjs/web"
+  | "@solidjs/html"
+  | "@solidjs/signals";
+
+export type SolidModuleProviderId = "esm.sh" | "jsdelivr";
+export type SolidModuleSource = "auto" | "host" | SolidModuleProviderId;
+
+export interface SolidRuntimeModules {
+  "solid-js": ModuleNamespaceLike | Function;
+  "@solidjs/web": ModuleNamespaceLike | Function;
+  "@solidjs/html": ModuleNamespaceLike | Function;
+  "@solidjs/signals": ModuleNamespaceLike | Function;
+}
+
+export interface LoadSolidModulesOptions {
+  /** Resolution policy. `auto` prefers the existing host/page resolver first. */
+  source?: SolidModuleSource;
+  /** CDN used only when `auto` cannot complete the family through the host. */
+  fallbackProvider?: SolidModuleProviderId;
+  /** Version used for provider-generated URLs when no versioned Solid anchor exists. */
+  version?: string;
+  /** Already-resolved namespaces. Provided entries are never re-imported. */
+  modules?: Partial<SolidRuntimeModules>;
+  /** Explicit URL/specifier overrides. Exact values are preserved. */
+  specifiers?: Partial<Record<SolidRuntimePackageName, string>>;
+  /** Optional Document used for read-only import-map/provider inspection. */
+  document?: Document;
+}
+
+export interface CreateSolidRuntimeOptions extends Omit<RuntimeOptions, "modules"> {
+  /** Application/host modules. User entries override automatically loaded defaults. */
+  modules?: RuntimeOptions["modules"] & Partial<SolidRuntimeModules>;
+  /** Options for resolving the standard Solid package family. */
+  solid?: LoadSolidModulesOptions;
+}
+
+export interface SolidResolutionInspection {
+  pageMappings: Map<string, string>;
+  authoritativeMappings: Map<string, string>;
+  provider?: SolidModuleProviderId;
+  version?: string;
+}
+
+export declare class SolidModuleResolutionError extends Error {
+  provider?: string;
+  version?: string;
+  missing?: string[];
+}
+
+export declare const SOLID_RUNTIME_PACKAGES: readonly [
+  "solid-js",
+  "@solidjs/web",
+  "@solidjs/html",
+  "@solidjs/signals",
+];
+
+export declare const TESTED_SOLID_VERSION: string;
+
+export declare function loadSolidModules(
+  options?: LoadSolidModulesOptions,
+): Promise<SolidRuntimeModules>;
+
+export declare function createSolidRuntime(
+  options?: CreateSolidRuntimeOptions,
+): Promise<SolidTagRuntime>;
+
+export declare function inspectSolidResolution(
+  options?: Pick<LoadSolidModulesOptions, "specifiers" | "document">,
+): SolidResolutionInspection;

package/src/html/delegated-events.js

@@ -0,0 +1,69 @@
+// Solid/dom-expressions' standard delegated event family. Prefer a renderer's
+// exported DelegatedEvents set when present; this is the compatibility fallback.
+export const DEFAULT_SOLID_DELEGATED_EVENTS = Object.freeze([
+  "beforeinput",
+  "click",
+  "dblclick",
+  "contextmenu",
+  "focusin",
+  "focusout",
+  "input",
+  "keydown",
+  "keyup",
+  "mousedown",
+  "mousemove",
+  "mouseout",
+  "mouseover",
+  "mouseup",
+  "pointerdown",
+  "pointermove",
+  "pointerout",
+  "pointerover",
+  "pointerup",
+  "touchend",
+  "touchmove",
+  "touchstart",
+]);
+
+const delegatedByRenderer = new WeakMap();
+
+export function ensureDelegatedEvents(web, document, events) {
+  if (!web || (typeof web !== "object" && typeof web !== "function")) {
+    throw new TypeError("Solid delegation requires an @solidjs/web namespace.");
+  }
+  if (!document) throw new TypeError("Solid delegation requires a Document.");
+  if (typeof web.delegateEvents !== "function") return [];
+
+  let byDocument = delegatedByRenderer.get(web);
+  if (!byDocument) {
+    byDocument = new WeakMap();
+    delegatedByRenderer.set(web, byDocument);
+  }
+  let delegated = byDocument.get(document);
+  if (!delegated) {
+    delegated = new Set();
+    byDocument.set(document, delegated);
+  }
+
+  const requested = normalizeEvents(events ?? web.DelegatedEvents ?? DEFAULT_SOLID_DELEGATED_EVENTS);
+  const fresh = requested.filter(event => !delegated.has(event));
+  if (!fresh.length) return [];
+
+  web.delegateEvents(fresh, document);
+  for (const event of fresh) delegated.add(event);
+  return fresh;
+}
+
+function normalizeEvents(events) {
+  if (!events) return [];
+  const values = typeof events[Symbol.iterator] === "function" ? Array.from(events) : [];
+  const result = [];
+  const seen = new Set();
+  for (const value of values) {
+    const event = String(value ?? "").trim().toLowerCase();
+    if (!event || seen.has(event)) continue;
+    seen.add(event);
+    result.push(event);
+  }
+  return result;
+}

package/src/html/delegation-host.js

@@ -0,0 +1,29 @@
+const hostsByDocument = new WeakMap();
+
+export function ensureDocumentDelegationHost(web, document) {
+  if (!web || (typeof web !== "object" && typeof web !== "function")) {
+    throw new TypeError("Solid delegation requires an @solidjs/web namespace.");
+  }
+  if (!document) throw new TypeError("Solid delegation requires a Document.");
+  if (typeof web.render !== "function") {
+    throw new TypeError("@solidjs/web does not provide render() required for document delegation.");
+  }
+
+  let byRenderer = hostsByDocument.get(document);
+  if (!byRenderer) {
+    byRenderer = new WeakMap();
+    hostsByDocument.set(document, byRenderer);
+  }
+
+  let host = byRenderer.get(web);
+  if (host) return host;
+
+  const dispose = web.render(() => undefined, document);
+  host = {
+    document,
+    web,
+    dispose: typeof dispose === "function" ? dispose : undefined,
+  };
+  byRenderer.set(web, host);
+  return host;
+}

package/src/html.js

@@ -1219,7 +1219,8 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
     }
   }
 
-  const observer = new MutationObserverImpl(() => {
+  const observer = new MutationObserverImpl(records => {
+    if (!observerMutationsRequireScan(controller, records, callOptions)) return;
     void enqueueObserverScan(controller, callOptions).catch(() => {});
   });
 
@@ -1247,6 +1248,80 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   return result;
 }
 
+function observerMutationsRequireScan(controller, records, callOptions = {}) {
+  const mutations = Array.from(records ?? []);
+
+  // MutationObserver never invokes its callback with an empty batch, but custom
+  // test/host implementations sometimes do. Preserve the historical conservative
+  // behavior for those implementations instead of silently dropping discovery.
+  if (mutations.length === 0) return true;
+
+  const selector = callOptions.selector ?? controller.selector;
+
+  for (const mutation of mutations) {
+    if (!mutation || mutation.type !== "childList") return true;
+
+    const addedNodes = mutation.addedNodes;
+    const removedNodes = mutation.removedNodes;
+    if (addedNodes == null || removedNodes == null) return true;
+
+    for (const node of Array.from(addedNodes)) {
+      if (nodeOrDescendantMatches(node, selector)) return true;
+
+      // <solid-render> is not part of the script selector, but observer batch
+      // completion is also a retry boundary for newly connected render instances.
+      if (nodeOrDescendantMatches(node, "solid-render")) return true;
+    }
+
+    for (const node of Array.from(removedNodes)) {
+      if (removedNodeContainsMountedDeclaration(controller, node)) return true;
+    }
+  }
+
+  return false;
+}
+
+function nodeOrDescendantMatches(node, selector) {
+  if (!node) return false;
+
+  try {
+    if (typeof node.matches === "function" && node.matches(selector)) return true;
+    if (typeof node.querySelector === "function" && node.querySelector(selector)) return true;
+    if (typeof node.querySelectorAll === "function" && node.querySelectorAll(selector)?.length > 0) return true;
+  } catch {
+    // A custom selector/DOM implementation that cannot be classified safely
+    // should keep the old conservative behavior rather than miss discovery.
+    return true;
+  }
+
+  // Standard DOM nodes that did not match above cannot affect discovery.
+  if (typeof node.nodeType === "number") return false;
+
+  // Unknown host DOM objects cannot be classified safely.
+  return typeof node.getAttribute === "function";
+}
+
+function removedNodeContainsMountedDeclaration(controller, node) {
+  if (!node) return false;
+
+  for (const record of controller.bindings.values()) {
+    if (!record.mount) continue;
+    const anchor = record.mount.mode === "in-place"
+      ? record.range?.startMarker
+      : record.element;
+    if (!anchor) continue;
+    if (node === anchor) return true;
+
+    try {
+      if (typeof node.contains === "function" && node.contains(anchor)) return true;
+    } catch {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 function stopObserver(controller, options = {}) {
   if (!controller.connected && !controller.observer) return;
   const root = controller.observerRoot;

package/src/render.js

@@ -1,4 +1,5 @@
 import { SolidTagRuntimeError } from "./errors.js";
+import { getSolidRuntimeIntegration } from "./solid/integration.js";
 
 export class HTMLRenderError extends SolidTagRuntimeError {
   constructor(message, options = {}) {
@@ -68,6 +69,9 @@ export function createDefaultHTMLRenderAdapter(runtime) {
 
     async mountRange({ parent, before, startMarker, endMarker, Component, props }) {
       const { Solid, Web } = await getSolidModules();
+      const document = parent?.ownerDocument ?? globalThis.document;
+      const integration = getSolidRuntimeIntegration(runtime);
+      if (integration && document) integration.ensureDelegation(document);
       if (typeof Solid.createRoot !== "function") {
         throw new HTMLRenderError("solid-js does not provide createRoot().");
       }

package/src/solid/import-map.js

@@ -0,0 +1,29 @@
+export function readImportMapImports(document = globalThis.document) {
+  const imports = new Map();
+  if (!document || typeof document.querySelectorAll !== "function") return imports;
+
+  let scripts = [];
+  try {
+    scripts = Array.from(document.querySelectorAll('script[type="importmap"]'));
+  } catch {
+    return imports;
+  }
+
+  for (const script of scripts) {
+    const text = String(script?.textContent ?? "").trim();
+    if (!text) continue;
+    try {
+      const parsed = JSON.parse(text);
+      const values = parsed?.imports;
+      if (!values || typeof values !== "object") continue;
+      for (const [specifier, target] of Object.entries(values)) {
+        if (typeof target === "string" && target) imports.set(specifier, target);
+      }
+    } catch {
+      // Import-map parsing is advisory here. The browser remains authoritative
+      // for actual resolution; malformed page maps must not crash inspection.
+    }
+  }
+
+  return imports;
+}

package/src/solid/index.js

@@ -0,0 +1,67 @@
+import { createRuntime as createRuntimeCore } from "../runtime.js";
+import { installSolidRuntimeIntegration } from "./integration.js";
+import {
+  SOLID_RUNTIME_PACKAGES,
+  TESTED_SOLID_VERSION,
+  pickSolidRuntimeModules,
+} from "./packages.js";
+import {
+  SolidModuleResolutionError,
+  createDefaultSolidEnvironment,
+  inspectSolidResolution,
+  loadSolidModulesWithEnvironment,
+} from "./resolve.js";
+
+export { SOLID_RUNTIME_PACKAGES, TESTED_SOLID_VERSION } from "./packages.js";
+export { SolidModuleResolutionError, inspectSolidResolution } from "./resolve.js";
+
+export async function loadSolidModules(options = {}) {
+  return loadSolidModulesWithEnvironment(options, createDefaultSolidEnvironment());
+}
+
+export async function createSolidRuntime(options = {}) {
+  return createSolidRuntimeWithEnvironment(options, createDefaultSolidEnvironment());
+}
+
+// Internal/testable composition point. It intentionally is not part of the
+// package's documented public type surface.
+export async function createSolidRuntimeWithEnvironment(options = {}, environment) {
+  const {
+    solid = {},
+    modules = {},
+    compiler: suppliedCompiler,
+    compilerOptions,
+    ...runtimeOptions
+  } = options;
+
+  const suppliedSolidModules = pickSolidRuntimeModules(modules);
+  const loadedSolidModules = await loadSolidModulesWithEnvironment({
+    ...solid,
+    modules: {
+      ...(solid.modules ?? {}),
+      ...suppliedSolidModules,
+    },
+  }, environment);
+
+  const mergedModules = {
+    ...loadedSolidModules,
+    ...modules,
+  };
+
+  let compiler = suppliedCompiler;
+  if (!compiler) {
+    // Keep the optional /solid layer cheap/testable when the caller already
+    // supplies a compiler, while preserving createRuntime()'s default behavior.
+    const { createSolidTagCompiler } = await import("../compiler.js");
+    compiler = createSolidTagCompiler(compilerOptions);
+  }
+
+  const runtime = createRuntimeCore({
+    ...runtimeOptions,
+    compiler,
+    modules: mergedModules,
+  });
+
+  installSolidRuntimeIntegration(runtime, pickSolidRuntimeModules(mergedModules));
+  return runtime;
+}