solid-tag-runtime 0.0.12 → 0.0.14

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`, 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/basic.js

@@ -0,0 +1,41 @@
+import { createRuntime } from "solid-tag-runtime";
+import * as Solid from "solid-js";
+import * as SolidWeb from "@solidjs/web";
+import html from "@solidjs/html";
+
+const runtime = createRuntime({
+  modules: {
+    "solid-js": Solid,
+    "@solidjs/web": SolidWeb,
+    "@solidjs/html": { default: html },
+  },
+});
+
+runtime.define(
+  "/Button.jsx",
+  `
+    export function Button(props) {
+      return <button onClick={props.onClick}>{props.children}</button>;
+    }
+  `,
+);
+
+runtime.define(
+  "/Counter.jsx",
+  `
+    import { createSignal } from "solid-js";
+    import { Button } from "./Button.jsx";
+
+    export function Counter() {
+      const [count, setCount] = createSignal(0);
+      return (
+        <Button onClick={() => setCount(value => value + 1)}>
+          Count: {count()}
+        </Button>
+      );
+    }
+  `,
+);
+
+const { Counter } = await runtime.import("/Counter.jsx");
+console.log(Counter);

package/examples/compile-cache.js

@@ -0,0 +1,35 @@
+import {
+  createRuntime,
+  createIndexedDBCompileCache,
+} from "solid-tag-runtime";
+
+const store = createIndexedDBCompileCache({
+  database: "my-app-runtime",
+});
+
+function createAppRuntime() {
+  return createRuntime({
+    compileCache: {
+      store,
+      namespace: "main",
+      version: "1",
+      maxEntries: 500,
+      maxBytes: 50 * 1024 * 1024,
+    },
+  });
+}
+
+// First runtime: compile miss + persistent write.
+const first = createAppRuntime();
+first.define("/config.js", `export const value = 42;`, { format: "js" });
+await first.import("/config.js");
+console.log("first", first.getModuleInfo("/config.js")?.compileCache);
+first.dispose();
+
+// New runtime, same source and cache namespace/version: compile hit.
+// Linking, module URL creation, and native evaluation are still fresh.
+const second = createAppRuntime();
+second.define("/config.js", `export const value = 42;`, { format: "js" });
+await second.import("/config.js");
+console.log("second", second.getModuleInfo("/config.js")?.compileCache);
+second.dispose();

package/examples/main.tsx

@@ -0,0 +1,318 @@
+import { render } from "@solidjs/web";
+import * as Solid from "solid-js";
+import * as SolidWeb from "@solidjs/web";
+import html from "@solidjs/html";
+import { createRuntime } from "solid-tag-runtime";
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+// A tiny type helper for module exports returned by solid-tag-runtime.
+type Component<P = Record<string, unknown>> = (props: P) => any;
+
+async function main() {
+  const root = document.getElementById("root");
+  if (!root) throw new Error("Missing #root element");
+
+  // ---------------------------------------------------------------------------
+  // 1. Host application state
+  // ---------------------------------------------------------------------------
+  // These signals are created by the Solid runtime already bundled with the app.
+  // Runtime-created modules receive the exact same signal/accessor references.
+
+  const [hostCount, setHostCount] = Solid.createSignal(100);
+  const [hostMessage, setHostMessage] = Solid.createSignal(
+    "Hello from the host application",
+  );
+
+  // ---------------------------------------------------------------------------
+  // 2. Create the runtime and reuse this application's Solid modules
+  // ---------------------------------------------------------------------------
+  // This is important: dynamic components do NOT load another Solid runtime.
+
+  const runtime = createRuntime({
+    modules: {
+      "solid-js": Solid,
+      "@solidjs/web": SolidWeb,
+      "@solidjs/html": { default: html },
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // 3. Expose host-owned state/services as a normal runtime module
+  // ---------------------------------------------------------------------------
+  // Runtime source can now use:
+  //
+  //   import { hostCount, setHostCount } from "@app/state";
+  //
+  // No serialization or global-variable rewriting is involved.
+
+  runtime.defineModule("@app/state", {
+    hostCount,
+    setHostCount,
+    hostMessage,
+    setHostMessage,
+  });
+
+  // ---------------------------------------------------------------------------
+  // 4. Observe runtime module scripts added to the document
+  // ---------------------------------------------------------------------------
+  // We already own registration in this demo, so only watch scripts added from
+  // this point forward. Each observed batch is fully defined before any entry
+  // in that batch executes.
+
+  const htmlRuntime = createHTMLRuntime(runtime, {
+    scope: "main",
+    root: document,
+    appendTo: document.body,
+    acceptUnscoped: false,
+  });
+
+  await htmlRuntime.observe({
+    registerExisting: false,
+    onError(error) {
+      console.error("Observed runtime module failed", error);
+    },
+  });
+
+  // This script is inert to the browser because its type is solid-jsx, but the
+  // solid-tag-runtime HTML adapter discovers it through MutationObserver.
+  const observedModuleScript = document.createElement("script");
+  observedModuleScript.type = "solid-jsx";
+  observedModuleScript.setAttribute("data-solid-runtime", "main");
+  observedModuleScript.setAttribute("module", "/observed/Badge.jsx");
+  observedModuleScript.textContent = `
+    export function ObservedBadge(props) {
+      return (
+        <small
+          style={{
+            display: "inline-block",
+            padding: "4px 8px",
+            border: "1px dashed #777",
+            "border-radius": "999px"
+          }}
+        >
+          Observed module: {props.children}
+        </small>
+      );
+    }
+  `;
+  document.body.append(observedModuleScript);
+
+  // MutationObserver is automatic; flush() is useful when the application wants
+  // to explicitly wait until discovered modules are ready before importing them.
+  await htmlRuntime.flush();
+
+  // ---------------------------------------------------------------------------
+  // 5. Define a reusable runtime JSX module
+  // ---------------------------------------------------------------------------
+
+  runtime.define(
+    "/ui/Button.jsx",
+    `
+      export function Button(props) {
+        return (
+          <button
+            type="button"
+            onClick={props.onClick}
+            style={{
+              padding: "8px 12px",
+              border: "1px solid #777",
+              "border-radius": "6px",
+              cursor: "pointer"
+            }}
+          >
+            {props.children}
+          </button>
+        );
+      }
+    `,
+  );
+
+  // ---------------------------------------------------------------------------
+  // 6. Define another runtime module that imports Button + host state + Solid
+  // ---------------------------------------------------------------------------
+
+  runtime.define(
+    "/features/Counter.jsx",
+    `
+      import { createSignal } from "solid-js";
+      import { Button } from "../ui/Button.jsx";
+      import { hostCount, setHostCount } from "@app/state";
+
+      export function Counter() {
+        const [localCount, setLocalCount] = createSignal(0);
+
+        return (
+          <section
+            style={{
+              display: "grid",
+              gap: "10px",
+              padding: "16px",
+              border: "1px solid #555",
+              "border-radius": "8px"
+            }}
+          >
+            <strong>Runtime Counter module</strong>
+
+            <div>Local runtime signal: {localCount()}</div>
+            <div>Host application signal: {hostCount()}</div>
+
+            <div style={{ display: "flex", gap: "8px", "flex-wrap": "wrap" }}>
+              <Button onClick={() => setLocalCount(value => value + 1)}>
+                Increment local
+              </Button>
+
+              <Button onClick={() => setHostCount(value => value + 1)}>
+                Increment host
+              </Button>
+            </div>
+          </section>
+        );
+      }
+    `,
+  );
+
+  // ---------------------------------------------------------------------------
+  // 7. toModule(): create an anonymous runtime module and get its exports
+  // ---------------------------------------------------------------------------
+
+  const greetingModule = await runtime.toModule(`
+    export function Greeting(props) {
+      return (
+        <p style={{ margin: 0, opacity: 0.8 }}>
+          Runtime module says: Hello {props.name}!
+        </p>
+      );
+    }
+  `);
+
+  // A compiled module namespace can itself be exposed as a named host module.
+  // That lets other runtime modules import it normally.
+  runtime.defineModule("@runtime/greeting", greetingModule);
+
+  // ---------------------------------------------------------------------------
+  // 8. Define the runtime application module
+  // ---------------------------------------------------------------------------
+  // It imports another runtime JSX module, an anonymous module namespace that we
+  // registered above, and host state.
+
+  runtime.define(
+    "/App.jsx",
+    `
+      import { Counter } from "./features/Counter.jsx";
+      import { Greeting } from "@runtime/greeting";
+      import { ObservedBadge } from "./observed/Badge.jsx";
+      import { hostMessage, setHostMessage } from "@app/state";
+
+      export function App(props) {
+        return (
+          <main
+            style={{
+              display: "grid",
+              gap: "16px",
+              width: "min(680px, calc(100% - 32px))",
+              margin: "40px auto",
+              "font-family": "system-ui, sans-serif"
+            }}
+          >
+            <h1 style={{ margin: 0 }}>{props.title}</h1>
+
+            <Greeting name={props.name} />
+
+            <ObservedBadge>
+              discovered through MutationObserver
+            </ObservedBadge>
+
+            <p style={{ margin: 0 }}>
+              Host message: {hostMessage()}
+            </p>
+
+            <button
+              type="button"
+              onClick={() =>
+                setHostMessage("The runtime App changed host-owned state")
+              }
+            >
+              Change host message from runtime code
+            </button>
+
+            <Counter />
+          </main>
+        );
+      }
+    `,
+  );
+
+  // ---------------------------------------------------------------------------
+  // 9. Import the runtime module and use its exported component in host JSX
+  // ---------------------------------------------------------------------------
+
+  const appModule = await runtime.import("/App.jsx");
+  const RuntimeApp = appModule.App as Component<{
+    title: string;
+    name: string;
+  }>;
+
+  const disposeRender = render(
+    () => (
+      <RuntimeApp
+        title="solid-tag-runtime demo"
+        name="Solid"
+      />
+    ),
+    root,
+  );
+
+  // ---------------------------------------------------------------------------
+  // 10. Runtime module graph introspection
+  // ---------------------------------------------------------------------------
+
+  console.table(runtime.modules());
+  console.log("/App.jsx dependencies:", runtime.dependencies("/App.jsx"));
+  console.log(
+    "/features/Counter.jsx dependencies:",
+    runtime.dependencies("/features/Counter.jsx"),
+  );
+  console.log(
+    "/ui/Button.jsx dependents:",
+    runtime.dependents("/ui/Button.jsx"),
+  );
+
+  // You can inspect the transformed module source too.
+  const compiledCounter = await runtime.compile("/features/Counter.jsx");
+  console.log("Compiled Counter module:\n", compiledCounter.code);
+
+  // Optional demo/debug handle from the browser console.
+  Object.assign(globalThis, {
+    solidTagDemo: {
+      runtime,
+      hostCount,
+      setHostCount,
+      hostMessage,
+      setHostMessage,
+      htmlRuntime,
+      dispose() {
+        htmlRuntime.disconnect();
+        observedModuleScript.remove();
+        disposeRender();
+        runtime.dispose();
+      },
+    },
+  });
+}
+
+main().catch(error => {
+  console.error("solid-tag-runtime demo failed", error);
+
+  const root = document.getElementById("root");
+  if (root) {
+    const pre = document.createElement("pre");
+    pre.style.whiteSpace = "pre-wrap";
+    pre.style.color = "crimson";
+    pre.textContent =
+      error instanceof Error
+        ? error.stack ?? error.message
+        : String(error);
+
+    root.replaceChildren(pre);
+  }
+});