solid-tag-runtime 0.0.12 → 0.0.14

package/docs/getting-started.md

@@ -0,0 +1,112 @@
+# Getting started
+
+## Install
+
+```bash
+npm install solid-tag-runtime solid-tag
+```
+
+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";
+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 },
+  },
+});
+```
+
+## Define and import a module
+
+```ts
+runtime.define("/Counter.jsx", `
+  import { createSignal } from "solid-js";
+
+  export default function Counter() {
+    const [count, setCount] = createSignal(0);
+    return (
+      <button onClick={() => setCount(value => value + 1)}>
+        {count()}
+      </button>
+    );
+  }
+`);
+
+const module = await runtime.import("/Counter.jsx");
+module.default;
+```
+
+Relative imports between runtime modules work normally.
+
+## Browser HTML adapter
+
+```ts
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+const htmlRuntime = createHTMLRuntime(runtime, {
+  scope: "main",
+  root: document,
+});
+
+await htmlRuntime.register();
+await htmlRuntime.observe({ registerExisting: false });
+```
+
+Declarative source:
+
+```html
+<script
+  type="solid-jsx"
+  data-solid-runtime="main"
+  module="/App.jsx"
+>
+  export default function App() {
+    return <h1>Hello</h1>;
+  }
+</script>
+```
+
+See [HTML runtime](./html-runtime.md), [declarative rendering](./rendering.md), and [`<solid-render>`](./solid-render.md).
+
+## Browser import maps
+
+Map every used package subpath explicitly:
+
+```json
+{
+  "imports": {
+    "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

@@ -0,0 +1,120 @@
+# HTML runtime and ownership
+
+`solid-tag-runtime/html` adapts the core module graph to browser DOM declarations. The core runtime itself does not scan or own DOM.
+
+## Create a controller
+
+```ts
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+const html = createHTMLRuntime(runtime, {
+  scope: "main",
+  root: document,
+  acceptUnscoped: false,
+});
+```
+
+## Register existing declarations
+
+```ts
+await html.register();
+```
+
+## Observe later declarations
+
+```ts
+await html.observe({ registerExisting: false });
+
+// after external DOM mutations
+await html.flush();
+```
+
+## Script declarations
+
+```html
+<script
+  type="solid-jsx"
+  data-solid-runtime="main"
+  module="/ui/Button.jsx"
+>
+  export function Button(props) {
+    return <button>{props.children}</button>;
+  }
+</script>
+```
+
+Supported source types include `solid-jsx`, `solid-js`, and `solid-module` (plus `text/...` aliases).
+
+## `src` vs `module`
+
+```html
+<script
+  type="solid-jsx"
+  src="./source/Button.jsx"
+  module="/ui/Button.jsx"
+></script>
+```
+
+- `src` = where source is loaded from
+- `module` = identity in the runtime graph
+
+## Ownership
+
+A physical runtime script element has at most one HTML controller owner.
+
+```ts
+await html.registerElement(script);
+await html.append(script);
+await html.addModule({ id: "/dynamic.js", source, format: "js" });
+
+html.owns(script);
+html.getModuleId(script);
+html.getElement("/dynamic.js");
+```
+
+Ownership is claimed before asynchronous source loading or DOM insertion, preventing observer/manual-registration races.
+
+## Update and remove owned declarations
+
+```ts
+script.textContent = updatedSource;
+await html.updateElement(script);
+
+await html.removeElement(script);
+```
+
+Ordinary DOM removal does not implicitly delete a runtime module. The explicit controller APIs keep DOM ownership and runtime graph lifecycle synchronized.
+
+## Multiple runtimes
+
+```ts
+const main = createHTMLRuntime(mainRuntime, {
+  scope: "main",
+  acceptUnscoped: false,
+});
+
+const preview = createHTMLRuntime(previewRuntime, {
+  scope: "preview",
+  acceptUnscoped: false,
+});
+```
+
+`data-solid-runtime` is declarative routing metadata. In-memory ownership is authoritative.
+
+## Root lifecycle
+
+```ts
+await html.setRoot(nextRoot);
+await html.moveTo(nextRoot);
+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/lifecycle-events.md

@@ -0,0 +1,77 @@
+# Lifecycle events
+
+Lifecycle subscriptions are observational. They cannot cancel compilation, change resolution, modify source, or stop rendering.
+
+## Core runtime
+
+Catch all events:
+
+```ts
+const leave = runtime.subscribe(event => {
+  console.log(event.type, event);
+});
+```
+
+One event type:
+
+```ts
+const leaveErrors = runtime.subscribe("module-error", event => {
+  console.error(event.phase, event.error);
+});
+```
+
+Several event types:
+
+```ts
+const leaveEvaluation = runtime.subscribe(
+  ["module-evaluating", "module-evaluated"],
+  event => console.log(event.type, event.id),
+);
+```
+
+Each call returns its own disposer.
+
+### Core event groups
+
+Definition/lifecycle:
+
+- `module-defined`
+- `module-updated`
+- `modules-defined`
+- `module-invalidated`
+- `module-removed`
+- `runtime-cleared`
+- `runtime-disposed`
+
+Resolution/link/evaluation:
+
+- `module-resolving`
+- `module-resolved`
+- `module-linking`
+- `module-linked`
+- `module-compiled`
+- `module-evaluating`
+- `module-evaluated`
+- `module-error`
+
+Compile-cache events:
+
+- `compile-cache-hit`
+- `compile-cache-miss`
+- `compile-cache-write`
+- `compile-cache-refresh`
+- `compile-cache-bypass`
+- `compile-cache-error`
+- `compile-cache-evict`
+
+## HTML runtime
+
+```ts
+html.subscribe("element-registered", event => {
+  console.log(event.moduleId);
+});
+```
+
+HTML events cover ownership, observation, roots, entry execution, render mounting/disposal, warnings, and errors.
+
+Listener exceptions are isolated from runtime/HTML operations and are reported to the console rather than aborting the underlying action.

package/docs/modules.md

@@ -0,0 +1,93 @@
+# Runtime modules and resolution
+
+The primary abstraction in `solid-tag-runtime` is a module. Components are ordinary module exports.
+
+## Source modules
+
+```ts
+runtime.define("/math.js", `export const answer = 42;`, {
+  format: "js",
+});
+```
+
+JSX is the default format:
+
+```ts
+runtime.define("/Greeting.jsx", `
+  export default function Greeting() {
+    return <p>Hello</p>;
+  }
+`);
+```
+
+## Host modules
+
+Expose existing JavaScript values by reference:
+
+```ts
+runtime.defineModule("@app/state", {
+  count,
+  setCount,
+});
+```
+
+Dynamic modules import those references normally:
+
+```tsx
+import { count, setCount } from "@app/state";
+```
+
+Host values are not serialized.
+
+## URL modules
+
+```ts
+runtime.defineUrl(
+  "some-library",
+  "https://example.test/library.js",
+);
+```
+
+## Resolution
+
+Resolution is runtime-local. The default rules are:
+
+1. custom `resolve()` callback
+2. exact registered ID
+3. absolute URL
+4. absolute virtual path
+5. relative virtual path
+6. unresolved bare native import when `allowNativeImports:true`
+7. otherwise `ModuleResolutionError`
+
+Virtual paths do not silently become network requests. Missing `/ui/Button.jsx` or `./Button.jsx` is a runtime-resolution error.
+
+```ts
+runtime.resolve("./Button.jsx", "/ui/App.jsx");
+// /ui/Button.jsx
+```
+
+## Batch definition
+
+```ts
+runtime.defineMany([
+  { id: "/dep.js", source: "export const value = 41;", format: "js" },
+  { id: "/main.js", source: 'import { value } from "./dep.js"; export const answer = value + 1;', format: "js" },
+]);
+```
+
+The complete batch is installed before buffered lifecycle events are published.
+
+## Updates and removal
+
+```ts
+runtime.update("/Button.jsx", newSource);
+runtime.remove("/Button.jsx");
+runtime.clear();
+```
+
+Updates/removals invalidate linked/evaluated dependents. Compiler artifacts follow the separate cache rules documented in [Persistent compile cache](./compile-cache.md).
+
+## Current cycle limitation
+
+Circular graphs between runtime-defined source modules are rejected. The current native-module URL backend requires final dependency URLs before an importing URL can be created.

package/docs/rendering.md

@@ -0,0 +1,71 @@
+# Declarative rendering
+
+A runtime script can define a module and mount one component instance.
+
+## Render into a selector
+
+```html
+<div id="app"></div>
+
+<script type="solid-jsx" module="/App.jsx" render="#app">
+  export default function App() {
+    return <h1>Hello</h1>;
+  }
+</script>
+```
+
+Without `component`, rendering selects `module.default`.
+
+Selector rendering continues to use normal Solid container rendering.
+
+## Named export
+
+```html
+<script
+  type="solid-jsx"
+  module="/widgets.jsx"
+  render="#app"
+  component="Counter"
+>
+  export function Counter() {
+    return <button>Counter</button>;
+  }
+</script>
+```
+
+## In-place rendering
+
+Bare `render` means mount at the exact declaration position:
+
+```html
+<p>Before</p>
+
+<script type="solid-jsx" module="/Message.jsx" render>
+  export default function Message() {
+    return <strong>Hello</strong>;
+  }
+</script>
+
+<p>After</p>
+```
+
+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.
+
+## `entry` vs `render`
+
+- `entry` = evaluate a module for side effects
+- `render` = evaluate a module because a component export must mount
+
+Combining `entry` and `render` on one declaration is rejected.
+
+## Runtime scope diagnostics
+
+A scoped render declaration is immediate work. If `data-solid-runtime="main"` cannot be handled by any registered controller covering that DOM root, the HTML adapter emits `html-warning` with code `unresolved-runtime-scope` and logs one warning.

package/docs/solid-render.md

@@ -0,0 +1,111 @@
+# `<solid-render>`
+
+`<solid-render>` references an already-defined runtime module and mounts a component instance into its own light DOM.
+
+```html
+<script type="solid-jsx" module="/Counter.jsx">
+  export default function Counter() {
+    return <button>Counter</button>;
+  }
+</script>
+
+<solid-render module="/Counter.jsx"></solid-render>
+```
+
+## Important HTML syntax rule
+
+**Always use an explicit closing tag in HTML.**
+
+Correct:
+
+```html
+<solid-render module="/Counter.jsx"></solid-render>
+```
+
+Do not write:
+
+```html
+<solid-render module="/Counter.jsx" />
+```
+
+Custom elements are not HTML void elements. The HTML parser ignores the XML-style self-closing slash, so following siblings may become children of `<solid-render>`. Because initial child content is captured as `props.children`, this can make later page content appear to disappear.
+
+## Named component
+
+```html
+<solid-render
+  module="/widgets.jsx"
+  component="Counter"
+></solid-render>
+```
+
+## Runtime selection
+
+```html
+<solid-render
+  data-solid-runtime="main"
+  module="/Counter.jsx"
+></solid-render>
+```
+
+The selected controller must match scope rules and contain the element within its configured root.
+
+## Declarative props
+
+```html
+<solid-render
+  module="/UserCard.jsx"
+  prop:name="Alice"
+  prop:user-id="42"
+  prop:compact
+></solid-render>
+```
+
+Rules:
+
+- `prop:user-id` becomes `userId`
+- a present empty prop becomes `true`
+- other attribute values remain strings
+- renderer configuration (`module`, `component`, `data-solid-runtime`) is not forwarded
+- `prop:module` is a normal component prop and does not collide with renderer `module`
+
+## Programmatic props
+
+```ts
+const element = document.querySelector("solid-render");
+
+element.props = {
+  user,
+  onSave,
+  service,
+};
+```
+
+Programmatic values may contain arbitrary JavaScript references and override declarative `prop:*` values.
+
+## Reactive updates
+
+Changing `prop:*` or `.props` updates the existing component instance without remounting.
+
+Changing `module`, `component`, or `data-solid-runtime` changes render identity and therefore disposes/remounts.
+
+## Children
+
+Initial child DOM becomes `props.children`:
+
+```html
+<solid-render module="/Card.jsx">
+  <p>Hello from HTML.</p>
+</solid-render>
+```
+
+Initial children are captured once. Named slots and dynamic child recapture are not part of the current API.
+
+## Multiple instances
+
+```html
+<solid-render module="/Counter.jsx"></solid-render>
+<solid-render module="/Counter.jsx"></solid-render>
+```
+
+The evaluated module namespace is shared, while each element owns an independent Solid component/root lifecycle.