browser-module-runtime 0.0.5 → 0.0.7

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.7
 ```
 
 ## Define, import and update modules
@@ -73,7 +73,7 @@ registerHTML(runtime,{scope:'app',root:document}); // No initial scan or observe
 ```
 
 ```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

@@ -14,12 +14,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. */
+  /** Preferred explicit, repeatable processing of existing source declarations. */
+  process():Promise<void>;
+  /** @deprecated Use process(). */
   registerExisting():Promise<void>;
-  /** Alias for registerExisting. */
+  /** @deprecated Use process(). */
   scan():Promise<void>;
-  setRoot(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
-  moveTo(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
+  setRoot(root:Document|Element,options?:{processExisting?:boolean;registerExisting?:boolean}):Promise<Document|Element>;
+  moveTo(root:Document|Element,options?:{processExisting?:boolean;registerExisting?:boolean}):Promise<Document|Element>;
   disconnect():Promise<void>;
 }
 export interface RegisterHTMLOptions {
@@ -34,3 +36,8 @@ export interface RegisterHTMLOptions {
 }
 /** Does not scan automatically. <runtime-render> itself is an autonomous custom element. */
 export declare function registerHTML(runtime:Runtime,options?:RegisterHTMLOptions):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?:RegisterHTMLOptions):Promise<HTMLController>;

package/package.json

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

package/src/html/index.js

@@ -1,14 +1,8 @@
 /** 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,readRenderProps,renderPropFingerprint} from './props.js';
 
-function parseObject(value,context){
-  if(value==null||value==='')return {};
-  let result;
-  try{result=JSON.parse(value);}catch(e){throw new Error(`Invalid JSON in ${context}: ${e.message}`);}
-  if(!result||typeof result!=='object'||Array.isArray(result))throw new Error(`${context} must be a JSON object`);
-  return result;
-}
 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);}
 function rootDocument(root){return root?.nodeType===9?root:root?.ownerDocument;}
@@ -23,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)});}}
@@ -45,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;
@@ -61,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.
@@ -172,11 +174,13 @@ export function registerHTML(runtime,options={}){
     await registerScript(script);
     return script;
   }
-  async function setRoot(nextRoot,{registerExisting=false}={}){
+  async function setRoot(nextRoot,{processExisting,registerExisting=false}={}){
+    // processExisting is preferred; registerExisting remains a legacy alias.
+    const shouldProcess=processExisting??registerExisting;
     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(shouldProcess)await scheduleScan();
     return nextRoot;
   }
   async function moveTo(nextRoot,opts){const moved=await setRoot(nextRoot,opts);appendTarget=nextRoot;return moved;}
@@ -187,5 +191,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 {name:resolvedScope,scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,process:scheduleScan,registerExisting:scheduleScan,scan:scheduleScan,setRoot,moveTo,disconnect,get root(){return currentRoot;},get appendTarget(){return appendTarget;}};
+}
+
+/** Create a scoped HTML controller and process existing source declarations once.
+ * Unlike registerHTML(), 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=registerHTML(runtime,options);
+  try{
+    await controller.process();
+    return controller;
+  }catch(error){
+    await controller.disconnect();
+    throw error;
+  }
 }

package/src/html/props.js

@@ -0,0 +1,162 @@
+/** Parse declarative object props without eval or executing JavaScript.
+ * Accepts JSON and a safe JS-literal subset (unquoted keys, single-quoted
+ * strings, trailing commas, nested arrays/objects). No expressions or code.
+ */
+export function parseObjectProps(value, context = 'props') {
+  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}`); };
+  const peek = () => value[offset];
+  const space = () => { while (offset < value.length && /\s/.test(peek())) offset++; };
+  const forbidKey = (key) => {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') error(`Forbidden object key ${key}`);
+    return key;
+  };
+  function str() {
+    const quote = value[offset++];
+    let result = '';
+    while (offset < value.length) {
+      let c = value[offset++];
+      if (c === quote) return result;
+      if (c === '\n' || c === '\r') error('Unterminated string');
+      if (c !== '\\') { result += c; continue; }
+      if (offset >= value.length) error('Unterminated string escape');
+      c = value[offset++];
+      const escapes = {n:'\n', r:'\r', t:'\t', b:'\b', f:'\f', v:'\v', '0':'\0'};
+      if (Object.hasOwn(escapes, c)) { result += escapes[c]; continue; }
+      if (c === 'u' || c === 'x') {
+        const count = c === 'u' ? 4 : 2;
+        const hex = value.slice(offset, offset + count);
+        if (!new RegExp(`^[a-fA-F0-9]{${count}}$`).test(hex)) error('Invalid hex string escape');
+        result += String.fromCharCode(parseInt(hex, 16)); offset += count; continue;
+      }
+      if ('\\\'"/'.includes(c)) { result += c; continue; }
+      error(`Unsupported string escape \\${c}`);
+    }
+    error('Unterminated string');
+  }
+  function readValue(depth = 0) {
+    if (depth > 40) error('Props nesting is too deep');
+    space();
+    const c = peek();
+    if (c === '{') return object(depth + 1);
+    if (c === '[') return array(depth + 1);
+    if (c === '"' || c === "'") return str();
+    const next = value.slice(offset);
+    const number = next.match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/);
+    if (number) {
+      offset += number[0].length;
+      const n = Number(number[0]);
+      if (!Number.isFinite(n)) error('Numbers must be finite');
+      return n;
+    }
+    for (const [word, literal] of [['true',true],['false',false],['null',null]]) {
+      if (next.startsWith(word) && !/[\w$]/.test(next[word.length] ?? '')) {
+        offset += word.length; return literal;
+      }
+    }
+    error('Expected a literal value (no expressions or functions)');
+  }
+  function key() {
+    space();
+    if (peek() === '"' || peek() === "'") return forbidKey(str());
+    const token = value.slice(offset).match(/^[A-Za-z_$][A-Za-z0-9_$]*/);
+    if (!token) error('Expected an object key');
+    offset += token[0].length;
+    return forbidKey(token[0]);
+  }
+  function object(depth) {
+    offset++; space();
+    const result = {};
+    if (peek() === '}') { offset++; return result; }
+    while (offset < value.length) {
+      const prop = key();space();
+      if (value[offset++] !== ':') error('Expected : after an object key');
+      const val = readValue(depth);
+      if (Object.hasOwn(result, prop)) error(`Duplicate object key ${prop}`);
+      result[prop] = val;
+      space();
+      const delimiter = value[offset++];
+      if (delimiter === '}') return result;
+      if (delimiter !== ',') error('Expected , or }');
+      space();
+      if (peek() === '}') { offset++; return result; }
+    }
+    error('Unclosed object');
+  }
+  function array(depth) {
+    offset++; space();
+    const result = [];
+    if (peek() === ']') { offset++; return result; }
+    while (offset < value.length) {
+      result.push(readValue(depth));space();
+      const delimiter = value[offset++];
+      if (delimiter === ']') return result;
+      if (delimiter !== ',') error('Expected , or ]');
+      space();
+      if (peek() === ']') { offset++; return result; }
+    }
+    error('Unclosed array');
+  }
+  space();
+  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; }
+    error('Props must be a JSON object or safe object literal');
+  }
+  const result = readValue();space();
+  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)));
+}