browser-runtime-solid 0.0.2 → 0.0.3

package/README.md

@@ -1,32 +1,59 @@
 # browser-runtime-solid
 
-Optional Solid JSX compiler and renderer plugin for [`browser-module-runtime`](https://www.npmjs.com/package/browser-module-runtime).
+Solid 2 JSX compiler/renderer adapter for [`browser-module-runtime`](https://www.npmjs.com/package/browser-module-runtime). This plugin is **optional**; generic runtime imports do not load Solid unless you register the adapter.
 
-## Install
-
-```sh
-npm install browser-module-runtime@0.0.1 browser-runtime-solid@0.0.1 solid-tag@0.0.3
-```
-
-Solid rendering also needs the Solid DOM runtime available through your host's import map or runtime module configuration.
-
-## Usage
+## Pinned Solid 2 family (recommended for standalone browser modules)
 
 ```js
 import {createRuntime} from 'browser-module-runtime';
-import {solid} from 'browser-runtime-solid';
+import {solid} from 'browser-module-frameworks'; // or 'browser-runtime-solid'
 
-const runtime = createRuntime({plugins: [solid()]});
-runtime.define('/Counter.jsx', `
+const runtime=createRuntime({plugins:[solid({version:'2.0.0-rc.13',provider:'esm.sh'})]});
+runtime.define('/Counter.jsx',`
   import {createSignal} from 'solid-js';
-  export default function Counter() {
-    const [count,setCount] = createSignal(0);
-    return <button onClick={() => setCount(n => n + 1)}>Count: {count()}</button>;
+  export default function Counter(){
+    const [count,setCount]=createSignal(0);
+    return <button onClick={()=>setCount(n=>n+1)}>Count: {count()}</button>;
   }
-`, {type:'solid-jsx'});
+`,{type:'solid-jsx'});
+const mount=await runtime.mount({module:'/Counter.jsx',target:'#app'});
+// Later: await mount.dispose(); await runtime.dispose();
+```
+
+A pinned adapter controls **four** framework packages as one compatible family: `solid-js`, `@solidjs/web`, `@solidjs/html`, and `@solidjs/signals`. The pinned JSX transformer `solid-tag` has a *separate* `tagVersion` (default `0.0.3`), so `solid-tag` need not match the Solid release. Generated imports, including `solid-js/internal` and the `solid-js/web` alias to `@solidjs/web`, are linked through the same runtime-local policy used to load the renderer. The tested Solid version is `2.0.0-rc.13`. This does **not** change or depend on a browser-global Solid import map.
+
+One standalone HTML page can import just the generic engine and aggregator using `esmesm`:
+
+```html
+<script src="https://raw.esm.sh/esmesm@0.0.3/bootstrap.js"
+  data-map="browser-module-runtime@0.0.3; browser-module-frameworks@0.0.2"></script>
+```
+
+The rest is controlled per runtime by `solid({version,...})`. See `examples/06-solid-versioning.html` in the workspace; before npm publication of 0.0.3 open `/examples/06-solid-versioning.html?local=1` through `bun run dev`.
 
-const handle = await runtime.mount({module:'/Counter.jsx', target:'#app'});
-// Later: await handle.dispose(); await runtime.dispose();
+## Host-managed imports (backward-compatible)
+
+```js
+const runtime=createRuntime({plugins:[solid({source:'host'})]});
+// equivalent to solid() or solid({source:'auto'}) without a version/provider
 ```
 
-This plugin lazily compiles JSX through `solid-tag` and mounts via `@solidjs/web.render`. It handles `type="solid-jsx"`; coherent Solid module identity is the application's responsibility. It is not an alias of `solid-tag-runtime` and does not replace that package's specialized HTML/delegation APIs.
+Use this when an application bundler or `esmesm` import map already coordinates the Solid packages and `solid-tag`. Host mode does **not** silently mix partially resolved host modules with CDN fallbacks. For pinned mode, the adapter selects only the esm.sh provider because other providers have not passed Solid-family identity checks.
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `version` | Exact Solid 2 family semver; enables runtime-local pinning |
+| `provider` | `esm.sh` for pinned mode; other providers reject for now |
+| `source` | `auto` (default), `host`, `esm.sh`; `auto` uses pinned mode when configured, otherwise host |
+| `fallbackProvider` | Enables a deterministic provider-managed default version when `version` is omitted |
+| `tagVersion` | Separate exact `solid-tag` compiler release, default `0.0.3` in pinned mode |
+| `compiler`, `render`, `web` | Existing compiler/renderer injection and optional `@solidjs/web` namespace |
+| `transformOptions` | Forwarded to `solid-tag.transformModule` |
+| `delegatedEvents` | Iterable of Solid delegated event names; omitted uses renderer or compatibility defaults |
+| `modules` | Host namespaces supported in host mode; family names forbidden in pinned mode |
+
+A pinned mode owns `solid-js`, `@solidjs/web`, `@solidjs/html`, `@solidjs/signals`, and `solid-tag`. Conflicting application pins and host namespaces are rejected before importing the CDN compiler. After mounting, Solid 2 document delegation is set up once per document/renderer; individual component disposals stay independent. Shadow DOM is not part of the currently verified delegation surface.
+
+The plugin is not a drop-in replacement for `solid-tag-runtime@0.0.34` or its specialized HTML controller. Browser integration tests should be run before publishing new Solid provider versions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-runtime-solid",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "exports": {
     ".": {
@@ -25,7 +25,7 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "browser-module-runtime": "0.0.2",
+    "browser-module-runtime": "0.0.3",
     "solid-tag": "0.0.3",
     "@solidjs/web": "*"
   },

package/src/delegation.js

@@ -0,0 +1,30 @@
+// The document's delegated event listener is associated with a particular
+// @solidjs/web namespace, not with any individual mounted component.
+const hostsByDocument=new WeakMap();
+const eventsByNamespace=new WeakMap();
+const defaultEvents=Object.freeze([
+  'beforeinput','click','dblclick','contextmenu','focusin','focusout','input',
+  'keydown','keyup','mousedown','mousemove','mouseout','mouseover','mouseup',
+  'pointerdown','pointermove','pointerout','pointerover','pointerup',
+  'touchend','touchmove','touchstart'
+]);
+
+export function ensureSolidDelegation(web,document,requestedEvents){
+  if(!web || !document || typeof web.render!=='function')return;
+  let byRenderer=hostsByDocument.get(document);
+  if(!byRenderer){byRenderer=new WeakMap();hostsByDocument.set(document,byRenderer);}
+  if(!byRenderer.has(web)){
+    // Solid 2 requires a root rendered on document to own delegated events.
+    const dispose=web.render(()=>undefined,document);
+    byRenderer.set(web,{dispose});
+  }
+  if(typeof web.delegateEvents!=='function')return;
+  let byDocument=eventsByNamespace.get(web);
+  if(!byDocument){byDocument=new WeakMap();eventsByNamespace.set(web,byDocument);}
+  let installed=byDocument.get(document);
+  if(!installed){installed=new Set();byDocument.set(document,installed);}
+  const raw=requestedEvents??web.DelegatedEvents??defaultEvents;
+  const fresh=[...new Set(Array.from(raw||[],event=>String(event).trim().toLowerCase()))]
+    .filter(event=>event&&!installed.has(event));
+  if(fresh.length){web.delegateEvents(fresh,document);fresh.forEach(event=>installed.add(event));}
+}

package/src/index.d.ts

@@ -2,8 +2,24 @@ import type {RuntimePlugin} from 'browser-module-runtime';
 export interface SolidAdapterOptions {
  compiler?: {compile?(source:string,options?:Record<string,unknown>):unknown;transformModule?(source:string,options?:Record<string,unknown>):unknown};
  render?: (component:()=>unknown,target:Element)=>void|(()=>void);
+ /** Optional @solidjs/web module namespace for injected renderer/delegation. */
+ web?: {render:(fn:()=>unknown,target:Document|Element)=>void|(()=>void);delegateEvents?:(events:string[],doc:Document)=>void;DelegatedEvents?:Iterable<string>};
  modules?:Record<string,object>;
+ /** The actual Solid framework family version (independent of adapter version). */
  version?:string;
+ /** auto: pinned if version/provider specified, otherwise host; host: caller import map; esm.sh: pinned CDN. */
+ source?:'auto'|'host'|'esm.sh'|'jsdelivr';
+ provider?:'esm.sh'|'jsdelivr';
+ fallbackProvider?:'esm.sh'|'jsdelivr';
+ /** Independently versioned JSX transformer, pinned only in CDN mode. */
+ tagVersion?:string;
  transformOptions?:Record<string,unknown>;
+ delegatedEvents?:Iterable<string>;
 }
+export declare class SolidVersionError extends Error {code:string;}
 export declare function solid(options?:SolidAdapterOptions):RuntimePlugin;
+export declare const SOLID_PACKAGES:ReadonlyArray<string>;
+export declare const TESTED_SOLID_VERSION:string;
+export declare function selectSolidMode(options?:SolidAdapterOptions):{mode:'host'|'pinned';version?:string;provider?:string;tagVersion?:string};
+export declare function solidPackageUrl(name:string,version:string,subpath?:string):string;
+export declare function createSolidFamilyRules(version:string):Record<string,unknown>;

package/src/index.js

@@ -1,14 +1,36 @@
-/** Solid is optional. The generic core never imports or loads Solid. */
-export function solid({compiler,render,modules={},version='0.0.3',transformOptions={}}={}) {
+import {createSolidFamilyRules,selectSolidMode} from './version-family.js';
+import {ensureSolidDelegation} from './delegation.js';
+export {SolidVersionError,selectSolidMode,createSolidFamilyRules,solidPackageUrl,SOLID_PACKAGES,TESTED_SOLID_VERSION} from './version-family.js';
+
+/** Optional Solid 2 adapter, including independently pinned runtime families. */
+export function solid({compiler,render,web,modules={},version,source='auto',provider,fallbackProvider,tagVersion,
+  transformOptions={},delegatedEvents}={}) {
+  const selection=selectSolidMode({version,source,provider,fallbackProvider,tagVersion});
+  if(selection.mode==='pinned'){
+    for(const name of Object.keys(modules)) {
+      if(name==='solid-tag'||Object.hasOwn(createSolidFamilyRules(selection.version),name))
+        throw new Error(`SOLID_VERSION_CONFLICT: caller-owned ${JSON.stringify(name)} namespace cannot be verified against pinned Solid ${selection.version}. Use source:"host" for supplied namespaces.`);
+    }
+  }
   let transformer=compiler;
   let renderFunction=render;
+  let webNamespace=web;
+  let ownerRuntime;
   return {
-    name:'solid',version:String(version),
-    async configure({runtime}) {for(const [id,ns] of Object.entries(modules))runtime.defineModule(id,ns);},
+    name:'solid',version:'0.0.3',frameworkVersion:selection.version,source:selection.mode,
+    cacheKey:JSON.stringify({solidMode:selection.mode,solidVersion:selection.version??null,tagVersion:selection.tagVersion??null,transformOptions}),
+    ...(selection.mode==='pinned'?{
+      packageFamilyRules:createSolidFamilyRules(selection.version),
+      packageEntries:{'solid-tag':{provider:'esm.sh',version:selection.tagVersion}}
+    }:{}),
+    async configure({runtime}) {
+      ownerRuntime=runtime;
+      for(const [id,ns] of Object.entries(modules))runtime.defineModule(id,ns);
+    },
     compilers:[{
       types:['solid-jsx'],extensions:['.jsx'],
       async compile(source,{id}) {
-        transformer ||= await import('solid-tag');
+        transformer ||= await (ownerRuntime ? ownerRuntime.import('solid-tag') : import('solid-tag'));
         if (typeof transformer.compile==='function')return transformer.compile(source,{id});
         if(typeof transformer.transformModule!=='function')throw new TypeError('solid-tag transformer requires transformModule()');
         const result=await transformer.transformModule(source,{...transformOptions,injectHtmlImport:true,htmlImportSource:'@solidjs/html'});
@@ -18,7 +40,12 @@ export function solid({compiler,render,modules={},version='0.0.3',transformOptio
     renderers:[{
       name:'solid',types:['solid-jsx'],
       async mount({component,target,props}) {
-        renderFunction ||= (await import('@solidjs/web')).render;
+        if(!renderFunction){
+          webNamespace ||= await (ownerRuntime ? ownerRuntime.import('@solidjs/web') : import('@solidjs/web'));
+          renderFunction=webNamespace.render;
+        }
+        if(typeof renderFunction!=='function')throw new TypeError('@solidjs/web renderer requires render().');
+        if(webNamespace)ensureSolidDelegation(webNamespace,target.ownerDocument||globalThis.document,delegatedEvents);
         const dispose=renderFunction(()=>component(props),target);
         return {dispose};
       }

package/src/version-family.js

@@ -0,0 +1,79 @@
+/**
+ * Solid 2's browser package family has a shared reactive core. For pinned CDN
+ * operation, ALL imports (compiler-produced modules and renderer) must use the
+ * same per-runtime package URL rules. No document import-map mutations.
+ *
+ * Based on the dependency closure used by solid-tag-runtime@0.0.34.
+ */
+export const SOLID_PACKAGES = Object.freeze([
+  'solid-js', '@solidjs/web', '@solidjs/html', '@solidjs/signals'
+]);
+export const TESTED_SOLID_VERSION = '2.0.0-rc.13';
+export const TESTED_SOLID_TAG_VERSION = '0.0.3';
+const exactVersion = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export class SolidVersionError extends Error {
+  constructor(code, message, details = {}) {
+    super(`${code}: ${message}`);
+    this.name = 'SolidVersionError';
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+const closures = Object.freeze({
+  'solid-js': ['@solidjs/signals'],
+  '@solidjs/web': ['solid-js', '@solidjs/signals'],
+  '@solidjs/html': ['@solidjs/web', 'solid-js', '@solidjs/signals'],
+  '@solidjs/signals': []
+});
+
+export function selectSolidMode({version, source='auto', provider, fallbackProvider, tagVersion}={}) {
+  if(!['auto','host','esm.sh','jsdelivr'].includes(source))
+    throw new SolidVersionError('SOLID_SOURCE_INVALID',`Unsupported source ${JSON.stringify(source)}.`,{source});
+  if(provider!==undefined && !['esm.sh','jsdelivr'].includes(provider))
+    throw new SolidVersionError('SOLID_PROVIDER_INVALID',`Unsupported provider ${JSON.stringify(provider)}.`,{provider});
+  if(fallbackProvider!==undefined && !['esm.sh','jsdelivr'].includes(fallbackProvider))
+    throw new SolidVersionError('SOLID_PROVIDER_INVALID',`Unsupported fallbackProvider ${JSON.stringify(fallbackProvider)}.`,{fallbackProvider});
+  if(provider && source!=='auto' && source!=='host' && provider!==source)
+    throw new SolidVersionError('SOLID_PROVIDER_CONFLICT',`source ${source} conflicts with provider ${provider}.`);
+  if(source==='host' && (version!=null || provider || fallbackProvider))
+    throw new SolidVersionError('SOLID_VERSION_CONFLICT','source:"host" cannot guarantee a pinned version or CDN provider. Use source:"auto" or source:"esm.sh".');
+  const pinned = version!=null || provider!=null || fallbackProvider!=null || source==='esm.sh' || source==='jsdelivr';
+  if(!pinned){
+    if(tagVersion!=null)throw new SolidVersionError('SOLID_TAG_VERSION_REQUIRES_PROVIDER','tagVersion requires a pinned Solid provider (or a host-owned solid-tag mapping).');
+    return Object.freeze({mode:'host',source});
+  }
+  const selectedProvider = provider || (source==='auto'?fallbackProvider:source) || 'esm.sh';
+  if(selectedProvider!=='esm.sh')throw new SolidVersionError('SOLID_PROVIDER_UNSAFE',`Pinned Solid families through ${selectedProvider} are not verified for shared reactive identity. Use esm.sh.`);
+  const familyVersion=version??TESTED_SOLID_VERSION;
+  const compilerVersion=tagVersion??TESTED_SOLID_TAG_VERSION;
+  if(typeof familyVersion!=='string'||!exactVersion.test(familyVersion))
+    throw new SolidVersionError('SOLID_VERSION_INVALID',`Expected exact Solid semver; received ${JSON.stringify(familyVersion)}.`);
+  if(typeof compilerVersion!=='string'||!exactVersion.test(compilerVersion))
+    throw new SolidVersionError('SOLID_TAG_VERSION_INVALID',`Expected exact solid-tag semver; received ${JSON.stringify(compilerVersion)}.`);
+  return Object.freeze({mode:'pinned',source,provider:selectedProvider,version:familyVersion,tagVersion:compilerVersion});
+}
+
+/** Produce an esm.sh URL with pinned sibling dependencies. */
+export function solidPackageUrl(name, version, subpath='') {
+  // Solid 2 moved the DOM implementation into @solidjs/web. Preserve its
+  // historical `solid-js/web` import spelling for compiled JSX and plugins.
+  if(name==='solid-js' && (subpath==='/web'||subpath.startsWith('/web/')))
+    return solidPackageUrl('@solidjs/web',version,subpath.slice(4));
+  if(!SOLID_PACKAGES.includes(name))throw new SolidVersionError('SOLID_PACKAGE_INVALID',`Not a Solid-family root: ${name}`);
+  if(subpath && (!subpath.startsWith('/') || subpath.startsWith('//') || /[?#%\\]/.test(subpath)))
+    throw new SolidVersionError('SOLID_SUBPATH_INVALID',`Invalid Solid package subpath: ${subpath}`);
+  const url=new URL(`https://esm.sh/${name}@${version}${subpath}`);
+  const deps=closures[name].map(dep=>`${dep}@${version}`);
+  if(deps.length)url.searchParams.set('deps',deps.join(','));
+  return url.href;
+}
+
+/** Generic policy extension; the core does not need to know Solid package names. */
+export function createSolidFamilyRules(version){
+  return Object.fromEntries(SOLID_PACKAGES.map(name=>[name,{
+    version, provider:'esm.sh', url:solidPackageUrl(name,version),
+    subpathUrl:subpath=>solidPackageUrl(name,version,subpath)
+  }]));
+}