browser-module-runtime 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# browser-module-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A framework-neutral browser module runtime with a native ESM linker, independent module registries, package-source and version resolution, a pre/compile/post build pipeline, caching, and optional HTML rendering.
+
+## Install
+
+```sh
+npm install browser-module-runtime@0.0.1
+```
+
+## Define, import and update modules
+
+```js
+import { createRuntime } from 'browser-module-runtime';
+
+const runtime = createRuntime({
+  packages: {provider: 'esm.sh', versions: {'just-versions': '0.0.1'}},
+});
+
+runtime.define('/math.js', 'export const double = n => n * 2;');
+const {double} = await runtime.import('/math.js');
+console.log(double(21)); // 42
+
+await runtime.dispose();
+```
+
+The factory is synchronous; asynchronous plugin setup is exposed as `runtime.ready`. The `import`, `compile`, `mount`, and `loadSource` methods await readiness. `dispose()` is async.
+
+## Modules and package sources
+
+The core supports `define`, `defineMany`, `defineModule`, `defineUrl`, `import`, `compile`, `update`, `invalidate`, `remove`, and `clear`, plus graph inspection and subscriptions. Runtime-specific package selections support esm.sh, jsDelivr, npm versions, and supported GitHub/PR locators:
+
+```js
+const runtime = createRuntime({
+  packages: {
+    provider: 'esm.sh',
+    versions: {
+      'just-versions': '0.0.2',
+      'lodash-es': 'jsdelivr:4.17.21',
+      versioning: 'esm.sh:gh/mizulu/versioning@0.0.1',
+    },
+  },
+});
+```
+
+Package-root mappings include supported subpath imports (for example `lodash-es/debounce`), subject to the source/provider's rules.
+
+## Compilers and rendering
+
+The default source format is JavaScript. Additional formats and rendering are opt-in through plugins such as `browser-runtime-solid`, `browser-runtime-svelte`, and `browser-runtime-octane`.
+
+```js
+const runtime = createRuntime({plugins: [myCompilerAndRenderer]});
+runtime.define('/Widget.sample', source, {type: 'sample'});
+const handle = await runtime.mount({module: '/Widget.sample', target: '#app'});
+await handle.dispose();
+```
+
+### Public exports
+
+- `browser-module-runtime`: runtime, build pipeline, cache and resolver utilities
+- `browser-module-runtime/html`: `registerHTML` and generic `<runtime-render>` integration
+- `browser-module-runtime/packages`: package policy utilities
+- `browser-module-runtime/cache`: compile-cache implementations
+
+`<runtime-render>` mounts framework plugins into its own element. This new generic API is distinct from the older `solid-tag-runtime` and `<solid-render>` APIs; use those packages for applications requiring their existing behavior.

package/html.d.ts

@@ -0,0 +1,3 @@
+import type {Runtime} from './index.js';
+export interface HTMLController {readonly name:string;readonly runtime:Runtime;registerExisting():Promise<void>;scan():Promise<void>;disconnect():Promise<void>}
+export declare function registerHTML(runtime:Runtime,options?:{name?:string;root?:Document|Element;observe?:boolean}):HTMLController;

package/index.d.ts

@@ -0,0 +1,107 @@
+export type ScriptType = string;
+export type Diagnostic = { message?: string; code?: string; [key: string]: unknown };
+export type EmittedAsset = { type: 'css' | 'asset'; id?: string; content: string };
+export interface ModuleSource { id: string; source: string; type?: string; format?: string; imports?: Record<string, unknown> }
+export interface BuildState { code: string; assets?: EmittedAsset[]; diagnostics?: Diagnostic[]; map?: string }
+export interface BuildContext { id: string; type: string; format: string; plugin: string }
+export type TransformHook = (input: BuildState, context: BuildContext) => void | string | BuildState | Promise<void | string | BuildState>;
+export interface CompilerAdapter {
+  types: string[];
+  extensions?: string[];
+  compile(source: string, context: BuildContext): string | BuildState | Promise<string | BuildState>;
+  analyze?(code: string, context: BuildContext): Array<{specifier:string;start:number;end:number;kind:string}> | Promise<Array<{specifier:string;start:number;end:number;kind:string}>>;
+}
+export interface MountContext<Props = Record<string, unknown>> {
+  component: unknown;
+  target: Element;
+  props: Props;
+  runtime: Runtime;
+  id: string;
+}
+export interface RendererAdapter {
+  name?: string;
+  types: string[];
+  mount(input: MountContext): Promise<RendererHandle> | RendererHandle;
+}
+export interface RendererHandle {
+  dispose(): void | Promise<void>;
+  updateProps?(props: Record<string, unknown>): void | Promise<void>;
+}
+export interface MountHandle {
+  ready: Promise<void>;
+  capabilities: {updateProps: boolean};
+  updateProps(props: Record<string, unknown>): Promise<void>;
+  dispose(): Promise<void>;
+}
+export interface RuntimePlugin {
+  name: string;
+  version: string;
+  cacheKey?: string;
+  /** Framework-owned exact package roots merged into the runtime package policy. */
+  packageEntries?: NonNullable<PackageOptions['entries']>;
+  compilers?: CompilerAdapter[];
+  renderers?: RendererAdapter[];
+  preprocess?: TransformHook[];
+  postprocess?: TransformHook[];
+  load?(options: {id: string; url: string; type?: string}, context: {runtime: Runtime}): string | {code: string} | undefined | Promise<string | {code:string} | undefined>;
+  configure?(context: {runtime: Runtime; pipeline: unknown}): void | Promise<void>;
+  dispose?(): void | Promise<void>;
+}
+export type PackageOptions = {
+  provider?: 'esm.sh' | 'esm' | 'jsdelivr' | 'jsDelivr';
+  versions?: Record<string,string>;
+  entries?: Record<string, {provider?: string;source?:string;version?:string;repository?:string;package?:string;ref?:string;url?:string;subpaths?:boolean}>;
+};
+export interface RuntimeOptions {
+  plugins?: RuntimePlugin[];
+  defaultType?: string;
+  packages?: PackageOptions;
+  modules?: Record<string, object>;
+  urls?: Record<string,string>;
+  compileCache?: boolean | Record<string,unknown>;
+  allowNativeImports?: boolean;
+  resolve?(specifier:string,importer?:string):string | undefined;
+  fallbackResolve?(specifier:string,importer?:string):string | undefined;
+}
+export interface Runtime {
+  ready: Promise<void>;
+  define(id:string,source:string,config?:{type?:string;format?:string;imports?:Record<string,unknown>}):string;
+  defineMany(definitions:ModuleSource[]):string[];
+  update(id:string,source:string,config?:{type?:string;format?:string;imports?:Record<string,unknown>}):string;
+  defineModule(id:string, namespace:object | Function):string;
+  defineUrl(id:string,url:string):string;
+  loadSource(id:string,options?:{type?:string;url?:string}):Promise<string>;
+  import(id:string):Promise<Record<string,any>>;
+  compile(id:string,options?:Record<string,unknown>):Promise<{id:string;code?:string;url?:string;dependencies:string[];diagnostics:Diagnostic[];assets?:EmittedAsset[]}>;
+  mount(options:{module:string;export?:string;target:Element|string;props?:Record<string,unknown>}):Promise<MountHandle>;
+  remove(id:string,opts?:Record<string,unknown>):boolean;
+  clear(opts?:Record<string,unknown>):string[];
+  has(id:string):boolean;
+  invalidate(id:string,opts?:Record<string,unknown>):string[];
+  resolve(specifier:string,importer?:string):string;
+  inspectPackageResolution(specifier:string):Record<string,unknown>|undefined;
+  subscribe(listener:(event:Record<string,unknown>)=>void):()=>void;
+  modules():Array<Record<string,unknown>>;
+  dependencies(id:string):string[];
+  dependents(id:string):string[];
+  getModuleInfo(id:string):Record<string,unknown>|undefined;
+  getSourceType(id:string):string|undefined;
+  getSupportedTypes():string[];
+  getBuildArtifact(id:string):BuildState|undefined;
+  compileCache: Record<string,unknown>;
+  dispose():Promise<void>;
+}
+export declare function createRuntime(options?:RuntimeOptions):Runtime;
+export declare function analyzeImports(source:string):Array<{specifier:string;start:number;end:number;kind:string}>;
+export declare class BuildPhaseError extends Error {phase:string;id:string;plugin?:string;cause:unknown}
+export declare function createBuildPipeline(options?:{plugins?:RuntimePlugin[];defaultType?:string}):{compile(source:string,ctx:{id:string;format:string}):Promise<BuildState>;detectType(id:string,explicit?:string):string;formats:string[]};
+export declare function createStyleManager():{acquire(asset:{id:string;content:string},target?:Document|ShadowRoot):()=>void;dispose():void;readonly size:number};
+export declare class PackageVersionResolutionError extends Error {code:string}
+export declare function parsePackageSpecifier(specifier:string):{packageName:string;subpath:string}|undefined;
+export declare function createPackagePolicy(options?:PackageOptions):unknown;
+export declare function createMemoryCompileCache(options?:Record<string,unknown>):unknown;
+export declare function createLocalStorageCompileCache(options?:Record<string,unknown>):unknown;
+export declare function createIndexedDBCompileCache(options?:Record<string,unknown>):unknown;
+export declare function createDefaultModuleUrlBackend():unknown;
+export declare function createBlobModuleUrlBackend():unknown;
+export declare function createDataModuleUrlBackend():unknown;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "browser-module-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./html": {
+      "types": "./html.d.ts",
+      "import": "./src/html/index.js"
+    },
+    "./packages": "./src/engine/package-resolution/index.js",
+    "./cache": "./src/engine/compile-cache.js"
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "html.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "description": "Browser-native module runtime with scoped imports, package resolution, compilation pipelines, and declarative HTML rendering.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "browser",
+    "esm",
+    "runtime",
+    "modules",
+    "compiler"
+  ]
+}

package/src/build/analyze.js

@@ -0,0 +1,54 @@
+/** Tiny dependency lexer for executable ESM. It does not transform source text.
+ * String offsets include quote delimiters, matching the linker ABI.
+ * Dynamic imports with non-literal arguments are deliberately left native.
+ * This lexer is not a full JS/TS parser. A production compiler may provide an
+ * `imports` array based on its own AST; see docs/BUILD_PIPELINE.md.
+ */
+export function analyzeImports(code) {
+  const tokens = lex(String(code));
+  const imports = [];
+  function push(t, kind) {
+    if (t?.type === 'string') imports.push({specifier:t.value,start:t.start,end:t.end,kind});
+  }
+  for (let i=0; i<tokens.length; i++) {
+    const t = tokens[i];
+    if (t.value === 'import') {
+      const next = tokens[i+1];
+      if (next?.value === '.' ) continue; // import.meta
+      if (next?.value === '(') { push(tokens[i+2], 'dynamic'); continue; }
+      if (next?.type === 'string') { push(next,'static'); continue; }
+      for (let j=i+1; j<tokens.length; j++) {
+        if (tokens[j].value === 'from' && tokens[j+1]?.type === 'string') {push(tokens[j+1],'static');break;}
+        if (tokens[j].value === ';' || tokens[j].value === 'import' || tokens[j].value === 'export') break;
+      }
+    } else if (t.value === 'export') {
+      for (let j=i+1;j<tokens.length;j++) {
+        if (tokens[j].value === 'from' && tokens[j+1]?.type === 'string') {push(tokens[j+1],'export');break;}
+        if (tokens[j].value === ';' || tokens[j].value === 'import' || tokens[j].value === 'export') break;
+      }
+    }
+  }
+  return imports.sort((a,b)=>a.start-b.start).filter((t,i,a)=>i===0||t.start!==a[i-1].start);
+}
+function lex(code) {
+  const result=[]; let i=0; const len=code.length;
+  while(i<len) {
+    const start=i, c=code[i], n=code[i+1];
+    if (/\s/.test(c)) {i++;continue;}
+    if(c==='/'&&n==='/'){i+=2;while(i<len&&code[i]!=='\n')i++;continue;}
+    if(c==='/'&&n==='*'){i+=2;while(i<len&&!(code[i]==='*'&&code[i+1]==='/'))i++;i=Math.min(len,i+2);continue;}
+    if(c==='\''||c==='"') {
+      const quote=c; i++; let value='';
+      while(i<len) {let x=code[i++];if(x==='\\'){const escaped=code[i++]; value += escaped==='n'?'\n':escaped==='r'?'\r':escaped==='t'?'\t':escaped??'';continue;}if(x===quote)break; value+=x;}
+      result.push({type:'string',value,start,end:i});continue;
+    }
+    if(c==='`') { i++;while(i<len) {if(code[i]==='\\'){i+=2;continue;}if(code[i++]==='`')break;}continue; }
+    if(/[A-Za-z_$]/.test(c)){i++;while(i<len&&/[\w$]/.test(code[i]))i++;result.push({type:'word',value:code.slice(start,i),start,end:i});continue;}
+    if(c==='/'&&regexPrefix(result.at(-1))) {i++; let inClass=false;while(i<len) {if(code[i]==='\\'){i+=2;continue;}if(code[i]==='[')inClass=true;if(code[i]===']')inClass=false;if(code[i++]==='/'&&!inClass)break;}while(i<len&&/[a-z]/i.test(code[i]))i++;continue;}
+    result.push({type:'symbol',value:c,start,end:++i});
+  }
+  return result;
+}
+function regexPrefix(previous) {
+  return !previous || ['=','(', '[', '{', ':', ',', ';', '!', '?', 'return', '=>'].includes(previous.value);
+}

package/src/build/pipeline.js

@@ -0,0 +1,62 @@
+import {analyzeImports} from './analyze.js';
+
+export class BuildPhaseError extends Error {
+  constructor(phase, id, plugin, cause){super(`${phase} failed for ${id}${plugin?` in ${plugin}`:''}: ${cause?.message||cause}`,{cause});this.name='BuildPhaseError';this.phase=phase;this.id=id;this.plugin=plugin;}
+}
+
+export function createBuildPipeline({plugins=[],defaultType='javascript',onArtifact=()=>{}}={}) {
+  const byType=new Map([['javascript',{type:'javascript',plugin:'native',compiler: {compile(source){return {code:source};}}}], ['js',{type:'js',plugin:'native',compiler:{compile(source){return {code:source};}}}]]);
+  const formatsByExtension=new Map([['.js','javascript'],['.mjs','javascript']]);
+  for(const plugin of plugins){
+    if(!plugin?.name||!plugin.version)throw new TypeError('Plugins must declare name and stable version.');
+    for(const compiler of plugin.compilers||[]){
+      if(typeof compiler.compile!=='function')throw new TypeError(`Compiler in ${plugin.name} needs compile()`);
+      for(const type of compiler.types||[]) {
+        if(byType.has(type))throw new Error(`Compiler type ${type} registered twice`);
+        byType.set(type,{type,plugin:plugin.name,pluginVersion:plugin.version,compiler});
+      }
+      for(const ext of compiler.extensions||[]){if(formatsByExtension.has(ext)) formatsByExtension.set(ext,null);else formatsByExtension.set(ext,compiler.types?.[0]);}
+    }
+  }
+  const phases=['preprocess','postprocess'];
+  const hooks=Object.fromEntries(phases.map(phase=>[phase,plugins.flatMap(p=>(p[phase]||[]).map(fn=>({name:p.name,run:fn}))) ]));
+  function detectType(id,explicit){
+    if(explicit)return explicit;
+    const ext=/\.[A-Za-z0-9]+$/.exec(id)?.[0]?.toLowerCase();
+    const detected=ext&&formatsByExtension.get(ext);
+    if(ext&&formatsByExtension.has(ext)&&!detected)throw new Error(`Ambiguous extension ${ext}; provide an explicit type.`);
+    return detected||defaultType;
+  }
+  async function stage(phase,p,src,ctx){
+    try {const out=await p.run(src,ctx);return normalizeStage(out,src);}catch(error){throw new BuildPhaseError(phase,ctx.id,p.name,error);}
+  }
+  async function compile(source,{id,format:type='javascript'}={}) {
+    const chosen=byType.get(type);
+    if(!chosen)throw new BuildPhaseError('compile',id,null,new Error(`No compiler registered for script type ${type}`));
+    const ctx={id,format:type,type,plugin:chosen.plugin};let state={code:String(source),assets:[],diagnostics:[]};
+    for(const hook of hooks.preprocess)state=await stage('preprocess',hook,state,ctx);
+    try {state=normalizeStage(await chosen.compiler.compile(state.code,ctx),state);}catch(error){throw new BuildPhaseError('compile',id,chosen.plugin,error);}
+    for(const hook of hooks.postprocess)state=await stage('postprocess',hook,state,ctx);
+    let imports;
+    try {
+      imports=typeof chosen.compiler.analyze==='function'
+        ? await chosen.compiler.analyze(state.code,ctx)
+        : analyzeImports(state.code);
+      if(!Array.isArray(imports))throw new TypeError('Compiler analyze() must return an array of import references');
+    }catch(error){throw new BuildPhaseError('analyze',id,chosen.plugin,error);}
+    const artifact={code:state.code,imports, diagnostics:state.diagnostics, ...(state.map?{sourceMap:state.map}:{}),assets:state.assets};
+    onArtifact(id,artifact);
+    return artifact;
+  }
+  function fingerprint(ctx={}) {
+    const signature=plugins.map(p=>[p.name,p.version,p.cacheKey??''].join(':')).join('|');
+    return `browser-module-runtime:pipeline:v1:${signature}:${ctx.format||''}`;
+  }
+  return {compile,fingerprint,detectType,formats:[...byType.keys()],owners:byType,plugins};
+}
+function normalizeStage(result,prior) {
+  if(result==null)return prior;
+  if(typeof result==='string')return {...prior,code:result};
+  if(!result||typeof result.code!=='string')throw new TypeError('Processor must return code string, artifact with code, or undefined.');
+  return {...prior,...result,assets:[...(prior.assets||[]),...(result.assets||[])],diagnostics:[...(prior.diagnostics||[]),...(result.diagnostics||[])]};
+}