browser-module-runtime 0.0.6 → 0.0.8

package/README.md

@@ -5,7 +5,7 @@ A framework-neutral browser module runtime with a native ESM linker, independent
 ## Install
 
 ```sh
-npm install browser-module-runtime@0.0.1
+npm install browser-module-runtime@0.0.8
 ```
 
 ## Define, import and update modules
@@ -59,7 +59,7 @@ 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/html`: `createHTMLRuntime` and generic `<runtime-render>` integration
 - `browser-module-runtime/packages`: package policy utilities
 - `browser-module-runtime/cache`: compile-cache implementations
 
@@ -68,12 +68,12 @@ await handle.dispose();
 ### Scoped HTML (development branch)
 
 ```js
-import {registerHTML} from 'browser-module-runtime/html';
-registerHTML(runtime,{scope:'app',root:document}); // No initial scan or observer
+import {createHTMLRuntime} from 'browser-module-runtime/html';
+createHTMLRuntime(runtime,{scope:'app',root:document}); // No initial scan or observer
 ```
 
 ```html
-<runtime-render scope="app" module="/Counter.jsx" props='{"initial":5}'></runtime-render>
+<runtime-render scope="app" module="/Counter.jsx" prop:initial={5}></runtime-render>
 ```
 
-The custom element waits for the runtime and module automatically. For already parsed inert script declarations use an explicit `await html.registerExisting()`; choose `observe:true` only when discovering uncontrolled future script insertions is necessary. Use `html.appendAndRegister(script)` for controlled injection. See `docs/SCOPED_HTML.md` in the workspace. These behaviors are **not** part of previously published npm `0.0.4` without a new release.
+Individual `prop:*` attributes support typed brace-wrapped safe literals, raw strings, and boolean presence; they override bulk `props` and react to attribute changes. The custom element waits for the runtime and module automatically. For already parsed inert script declarations use an explicit `await html.process()`; choose `observe:true` only when discovering uncontrolled future script insertions is necessary. Use `html.appendAndRegister(script)` for controlled injection. See `docs/SCOPED_HTML.md` in the workspace. These behaviors are **not** part of previously published npm `0.0.4` without a new release.

package/html.d.ts

@@ -1,8 +1,6 @@
 import type {Runtime} from './index.js';
 import type {WebComponentOptions} from './web-components.js';
 export interface HTMLController {
-  /** Scope name; `name` is a backwards compatible alias. */
-  readonly name:string;
   readonly scope:string;
   readonly root:Document|Element;
   readonly appendTarget:Document|Element;
@@ -14,18 +12,14 @@ export interface HTMLController {
   appendScript(script:HTMLScriptElement,target?:Document|Element):Promise<HTMLScriptElement>;
   /** Controlled append and register without a subtree scan. */
   appendAndRegister(script:HTMLScriptElement,target?:Document|Element):Promise<HTMLScriptElement>;
-  /** Explicit one-time discovery of scripts under root. */
-  registerExisting():Promise<void>;
-  /** Alias for registerExisting. */
-  scan():Promise<void>;
-  setRoot(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
-  moveTo(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
+  /** Preferred explicit, repeatable processing of existing source declarations. */
+  process():Promise<void>;
+  setRoot(root:Document|Element,options?:{processExisting?:boolean}):Promise<Document|Element>;
+  moveTo(root:Document|Element,options?:{processExisting?:boolean}):Promise<Document|Element>;
   disconnect():Promise<void>;
 }
-export interface RegisterHTMLOptions {
+export interface HTMLRuntimeOptions {
   scope?:string;
-  /** Backward compatible alias for scope. */
-  name?:string;
   root?:Document|Element;
   /** Whether an element without an explicit scope can be owned by this controller. */
   acceptUnscoped?:boolean;
@@ -33,4 +27,9 @@ export interface RegisterHTMLOptions {
   observe?:boolean;
 }
 /** Does not scan automatically. <runtime-render> itself is an autonomous custom element. */
-export declare function registerHTML(runtime:Runtime,options?:RegisterHTMLOptions):HTMLController;
+export declare function createHTMLRuntime(runtime:Runtime,options?:HTMLRuntimeOptions):HTMLController;
+
+/** High-level one-shot HTML discovery. Registers the controller and processes existing inert scripts.
+ * Returns the controller for subsequent root, observer and lifecycle operations.
+ */
+export declare function processHTML(runtime:Runtime,options?:HTMLRuntimeOptions):Promise<HTMLController>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-module-runtime",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "type": "module",
   "exports": {
     ".": {

package/src/html/index.js

@@ -1,7 +1,7 @@
 /** Scoped HTML integration: autonomous rendering, explicit discovery, opt-in observation. */
 import {registerWebComponent} from '../web-components/index.js';
 import {getScopeRegistry,requestedScope,containsRoot} from './scopes.js';
-import {parseObjectProps as parseObject} from './props.js';
+import {parseObjectProps as parseObject,readRenderProps,renderPropFingerprint} from './props.js';
 
 function emit(el,type,detail){const win=el.ownerDocument.defaultView;el.dispatchEvent(new win.CustomEvent(type,{detail,bubbles:true,composed:true}));}
 function state(el,value){el.setAttribute('data-runtime-state',value);}
@@ -17,15 +17,23 @@ function defineAutonomousElements(doc){
   if(!win.customElements.get('runtime-render')){
     class RuntimeRender extends win.HTMLElement {
       static get observedAttributes(){return ['scope','runtime','data-runtime','module','component','props'];}
-      constructor(){super();this._owner=null;this._handle=null;this._abort=null;this._generation=0;this._unsubscribe=null;this._pending=null;this._lastProps='';this._reported=null;}
+      constructor(){super();this._owner=null;this._handle=null;this._abort=null;this._generation=0;this._unsubscribe=null;this._pending=null;this._lastProps='';this._reported=null;this._propObserver=null;}
       connectedCallback(){
         if(!this._unsubscribe)this._unsubscribe=getScopeRegistry(doc).subscribe(()=>this._reconcile());
+        // Custom elements cannot wildcard observedAttributes; observe only
+        // prop:* changes, without scanning the document or polling.
+        if(!this._propObserver&&typeof win.MutationObserver==='function'){
+          this._propObserver=new win.MutationObserver(records=>{
+            if(records.some(r=>r.attributeName?.toLowerCase().startsWith('prop:')))this._reconcile();
+          });
+          this._propObserver.observe(this,{attributes:true});
+        }
         this._reconcile();
       }
       disconnectedCallback(){
         const generation=++this._generation;
         if(this._pending&&!this._handle){this._key=null;this._abort?.abort();}
-        queueMicrotask(()=>{if(!this.isConnected&&generation===this._generation){this._unsubscribe?.();this._unsubscribe=null;this._key=null;this._pending=null;this._release().catch(e=>this._report(e));state(this,'disposed');}});
+        queueMicrotask(()=>{if(!this.isConnected&&generation===this._generation){this._unsubscribe?.();this._unsubscribe=null;this._propObserver?.disconnect();this._propObserver=null;this._key=null;this._pending=null;this._release().catch(e=>this._report(e));state(this,'disposed');}});
       }
       attributeChangedCallback(name,oldValue,newValue){if(oldValue!==newValue&&this.isConnected)this._reconcile();}
       _report(error){state(this,'error');if(this._reported!==error){this._reported=error;emit(this,'runtime-error',{error,module:this.getAttribute('module'),scope:requestedScope(this)});}}
@@ -39,7 +47,7 @@ function defineAutonomousElements(doc){
         const match=getScopeRegistry(doc).resolve(this);
         const id=this.getAttribute('module')||'';
         const exportName=this.getAttribute('component')||'default';
-        const propsText=this.getAttribute('props')||'{}';
+        const propsText=(this.getAttribute('props')||'{}')+'|'+renderPropFingerprint(this);
         const key=match.controller&&`${match.controller.id}|${id}|${exportName}`;
         // Reconcile only on meaningful changes, not unrelated registry notifications.
         if(match.error&&this._lastErrorMessage===match.error.message)return;
@@ -55,7 +63,7 @@ function defineAutonomousElements(doc){
         if(match.error){this._report(match.error);if(previous)previous.dispose().catch(e=>this._report(e));return;}
         if(!controller||!id){state(this,'pending');if(previous)previous.dispose().catch(e=>this._report(e));return;}
         let props;
-        try{props=parseObject(propsText,'runtime-render props');}catch(e){this._report(e);if(previous)previous.dispose().catch(err=>this._report(err));return;}
+        try{props=readRenderProps(this);}catch(e){this._report(e);if(previous)previous.dispose().catch(err=>this._report(err));return;}
         this._reported=null;
         if(previous&&this._previousKey===key){
           // Update props in place where supported, otherwise remount.
@@ -110,14 +118,14 @@ function defineAutonomousElements(doc){
 }
 let sequence=0;
 /** Register a scoped HTML controller. Never scans automatically. */
-export function registerHTML(runtime,options={}){
-  const {name,scope,root=globalThis.document,observe=false,acceptUnscoped=true}=options;
-  if(!root)throw new TypeError('registerHTML requires a DOM root');
+export function createHTMLRuntime(runtime,options={}){
+  const {scope="default",root=globalThis.document,observe=false,acceptUnscoped=true}=options;
+  if(!root)throw new TypeError('createHTMLRuntime requires a DOM root');
   const doc=rootDocument(root);
-  if(!doc)throw new TypeError('registerHTML root must belong to a document');
+  if(!doc)throw new TypeError('createHTMLRuntime root must belong to a document');
   const registry=getScopeRegistry(doc);
   defineAutonomousElements(doc);
-  const resolvedScope=scope||name||'default';
+  const resolvedScope=scope;
   let alive=true,observer=null,currentRoot=root,appendTarget=root,pending=Promise.resolve();
   const controller={id:++sequence,scope:resolvedScope,get root(){return currentRoot;},acceptUnscoped,runtime,get alive(){return alive;},defineElement};
   function defineElement(tag,config){return registerWebComponent(runtime,{...config,tag,document:doc});}
@@ -166,11 +174,11 @@ export function registerHTML(runtime,options={}){
     await registerScript(script);
     return script;
   }
-  async function setRoot(nextRoot,{registerExisting=false}={}){
+  async function setRoot(nextRoot,{processExisting=false}={}){
     if(!alive)throw new Error('HTML controller is disconnected');
     if(rootDocument(nextRoot)!==doc)throw new Error('HTML root must remain in the same document');
     if(observer)observer.disconnect();currentRoot=nextRoot;registry.notify();enableObservation();
-    if(registerExisting)await scheduleScan();
+    if(processExisting)await scheduleScan();
     return nextRoot;
   }
   async function moveTo(nextRoot,opts){const moved=await setRoot(nextRoot,opts);appendTarget=nextRoot;return moved;}
@@ -181,5 +189,20 @@ export function registerHTML(runtime,options={}){
   }
   registry.add(controller);
   enableObservation();
-  return {name:resolvedScope,scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,registerExisting:scheduleScan,scan:scheduleScan,setRoot,moveTo,disconnect,get root(){return currentRoot;},get appendTarget(){return appendTarget;}};
+  return {scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,process:scheduleScan,setRoot,moveTo,disconnect,get root(){return currentRoot;},get appendTarget(){return appendTarget;}};
+}
+
+/** Create a scoped HTML controller and process existing source declarations once.
+ * Unlike createHTMLRuntime(), this convenience function explicitly performs discovery.
+ * Returns the controller so callers can use appendAndRegister(), setRoot() or disconnect().
+ */
+export async function processHTML(runtime,options={}){
+  const controller=createHTMLRuntime(runtime,options);
+  try{
+    await controller.process();
+    return controller;
+  }catch(error){
+    await controller.disconnect();
+    throw error;
+  }
 }

package/src/html/props.js

@@ -3,7 +3,19 @@
  * strings, trailing commas, nested arrays/objects). No expressions or code.
  */
 export function parseObjectProps(value, context = 'props') {
-  if (value == null || value.trim() === '') return {};
+  return parseValue(value, context, true);
+}
+
+/** Parse the safe literal subset for individual `prop:name={value}` attributes. */
+export function parseDataLiteral(value, context = 'prop') {
+  return parseValue(value, context, false);
+}
+
+function parseValue(value, context, objectOnly) {
+  if (value == null || value.trim() === '') {
+    if (objectOnly) return {};
+    throw new SyntaxError(`${context}: Empty data literal`);
+  }
   if (value.length > 100_000) throw new SyntaxError(`${context}: props literal is too large`);
   let offset = 0;
   const error = (message) => { throw new SyntaxError(`${context}: ${message} at character ${offset + 1}`); };
@@ -100,7 +112,7 @@ export function parseObjectProps(value, context = 'props') {
     error('Unclosed array');
   }
   space();
-  if (peek() !== '{') {
+  if (objectOnly && peek() !== '{') {
     // Preserve the old object-only error wording for callers relying on it.
     try { const json = JSON.parse(value); if (json === null || typeof json !== 'object' || Array.isArray(json)) throw new Error(`${context} must be a JSON object or safe object literal`); }
     catch (e) { if (e.message.includes('must be a JSON object')) throw e; }
@@ -110,3 +122,41 @@ export function parseObjectProps(value, context = 'props') {
   if (offset !== value.length) error('Unexpected trailing content');
   return result;
 }
+
+/**
+ * Declarative per-prop attributes override the bulk props object. Mirrors the
+ * legacy Solid semantics without evaluating expressions from HTML markup.
+ *
+ *   prop:initial={5}       => 5
+ *   prop:enabled={true}    => true
+ *   prop:label="Hello"      => "Hello"
+ *   prop:options={{x:1}}  => {x:1}
+ *   prop:busy              => true
+ */
+export function readRenderProps(element) {
+  const props = parseObjectProps(element.getAttribute('props'), 'runtime-render props');
+  for (const attribute of Array.from(element.attributes ?? [])) {
+    const name = String(attribute.name).toLowerCase();
+    if (!name.startsWith('prop:')) continue;
+    const key = name.slice(5).replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+    if (!key) continue;
+    if (['__proto__', 'constructor', 'prototype'].includes(key)) {
+      throw new SyntaxError(`runtime-render prop:${key}: Forbidden attribute key`);
+    }
+    const raw = String(attribute.value);
+    const trimmed = raw.trim();
+    const parsed = raw === '' ? true : trimmed.startsWith('{') && trimmed.endsWith('}')
+      ? parseDataLiteral(trimmed.slice(1, -1), `runtime-render prop:${key}`)
+      : raw;
+    props[key] = parsed;
+  }
+  return props;
+}
+
+/** Immutable fingerprint of dynamic `prop:*` attributes for mount reconciliation. */
+export function renderPropFingerprint(element) {
+  return JSON.stringify(Array.from(element.attributes ?? [])
+    .filter(attr => String(attr.name).toLowerCase().startsWith('prop:'))
+    .map(attr => [String(attr.name).toLowerCase(), String(attr.value)])
+    .sort(([a], [b]) => a.localeCompare(b)));
+}