@sola-air-ui/compiler 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sola-air-ui/compiler",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Compiler for Sola single-file components (.sola) \u2014 transforms template + script + style to ES modules",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -18,7 +18,7 @@ if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
     --target <esm|iife>       Output format (default: esm)
                                 esm  — ES module with import/export (default, for bundlers)
                                 iife — Self-contained IIFE for no-bundler environments
-                                       (ServiceNow Service Portal, plain <script> tags)
+                                       (enterprise portal widgets, plain <script> tags)
     --export-name <Name>      Global name for IIFE target (default: SolaComponent)
                               The compiled component mounts as window['Name'](el, props)
     -v, --version             Print compiler version

package/src/index.js

@@ -6,6 +6,14 @@ const { version: COMPILER_VERSION } = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8')
 );
 
+// Names every compiled component imports from core under their own name. A
+// script that imports one of these again is not given a second binding.
+const CORE_PROVIDED = new Set([
+  'createSignal', 'createDerived', 'createEffect', 'createIntent', 'createData',
+  'createPersistentSignal', 'onMount', 'onDestroy', 'pushContext', 'popContext',
+  '__flush_mounts', '__flush_destroys', '__untrack'
+]);
+
 const VOID_ELEMENTS = new Set([
   'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
   'link', 'meta', 'param', 'source', 'track', 'wbr'
@@ -32,18 +40,81 @@ function hashString(str) {
   return 'sola-' + Math.abs(hash).toString(36);
 }
 
+// Split on `sep` characters that are not inside (), [] or a string, so
+// `:is(a, b)` and `:global(.x, .y)` are not torn apart at their commas.
+function splitTopLevel(text, isSep) {
+  const parts = [];
+  let depth = 0, quote = null, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) { if (c === '\\') i++; else if (c === quote) quote = null; continue; }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth--;
+    else if (depth === 0 && isSep(c)) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+// Put the scope class on one compound selector, before any pseudo-class or
+// pseudo-element (button:hover → button.hash:hover).
+function addScopeToCompound(compound, scopeHash) {
+  const pseudoIdx = compound.search(/::?[\w-]/);
+  if (pseudoIdx > 0) {
+    return `${compound.slice(0, pseudoIdx)}.${scopeHash}${compound.slice(pseudoIdx)}`;
+  }
+  return `${compound}.${scopeHash}`;
+}
+
+// `:global(sel)` opts a piece of a selector out of scoping, so a scoped
+// component can style markup it did not create (e.g. the output of {@html}):
+//   .msg :global(table)  →  .msg.hash table
+//   :global(body)        →  body
+// The scope class always goes on the last compound that is not global.
+function scopeSelector(selector, scopeHash) {
+  const tokens = [];       // alternating compounds and combinators
+  let depth = 0, cur = '', comb = '';
+  const flushCompound = () => { if (cur) { tokens.push({ compound: cur }); cur = ''; } };
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i];
+    if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth--;
+    if (depth === 0 && /[\s>+~]/.test(c)) {
+      flushCompound();
+      comb += c;
+      continue;
+    }
+    if (comb) { tokens.push({ comb }); comb = ''; }
+    cur += c;
+  }
+  flushCompound();
+  if (comb) tokens.push({ comb });
+
+  let last = -1;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.compound === undefined) continue;
+    const m = t.compound.match(/^:global\(([\s\S]*)\)$/);
+    // A comma list must stay grouped, or `.a :global(.x, .y)` would turn into
+    // two selectors and leave `.y` outside `.a`.
+    const group = (inner) => (splitTopLevel(inner, c => c === ',').length > 1 ? `:is(${inner})` : inner);
+    if (m) { t.compound = group(m[1]); t.global = true; }
+    else if (t.compound.includes(':global(')) {
+      t.compound = t.compound.replace(/:global\(([\s\S]*?)\)/g, (_, inner) => group(inner));
+      t.global = true;
+    } else { last = i; }
+  }
+  if (last >= 0) tokens[last].compound = addScopeToCompound(tokens[last].compound, scopeHash);
+  return tokens.map(t => t.compound ?? t.comb).join('');
+}
+
 function scopeSelectorList(selector, scopeHash) {
-  return selector
-    .split(',')
+  return splitTopLevel(selector, c => c === ',')
     .map(part => {
       const trimmed = part.trim();
       if (!trimmed) return part;
-      // Insert scope hash before pseudo-class/element (e.g. button:hover → button.hash:hover)
-      const pseudoIdx = trimmed.search(/::?[\w-]/);
-      if (pseudoIdx > 0) {
-        return `${trimmed.slice(0, pseudoIdx)}.${scopeHash}${trimmed.slice(pseudoIdx)}`;
-      }
-      return `${trimmed}.${scopeHash}`;
+      return scopeSelector(trimmed, scopeHash);
     })
     .join(', ');
 }
@@ -262,7 +333,7 @@ function preprocessTemplate(template, dynAttrs, handlers) {
           } else if (hasDyn) {
             // Build a string-concatenation expression instead of a runtime backtick
             // template literal. Confirmed by driving a real browser against a live
-            // ServiceNow Service Portal instance: its widget-script delivery pipeline
+            // enterprise portal instance: its widget-script delivery pipeline
             // silently mangles `${expr}` interpolation inside a template literal down
             // to bare, unevaluated expression text (e.g. `background: ${x}` becomes
             // the literal string "background: x" — the function reference itself,
@@ -540,7 +611,7 @@ function collectReactiveVars(ast) {
             decl.init.callee.type === 'Identifier' && decl.id.type === 'Identifier') {
           const macro = decl.init.callee.name;
           if (macro === '$state' || macro === '$persist') vars.state.add(decl.id.name);
-          else if (macro === '$derived') vars.derived.add(decl.id.name);
+          else if (macro === '$derived' || macro === '$lastEvent') vars.derived.add(decl.id.name);
           else if (macro === '$intent') vars.intent.add(decl.id.name);
           else if (macro === '$data') vars.data.add(decl.id.name);
         }
@@ -638,7 +709,7 @@ function emitReactiveEdits(rootNode, src, vars, edits, initialShadows) {
         const isMemberProp = p.type === 'MemberExpression' && p.property === node && !p.computed;
         const isCallee = (p.type === 'CallExpression' || p.type === 'NewExpression') && p.callee === node;
         const isAssignTarget = (p.type === 'AssignmentExpression' && p.left === node) || p.type === 'UpdateExpression';
-        const isPropertyKey = p.type === 'Property' && p.key === node && !p.computed && !p.shorthand;
+        const isPropertyKey = p.type === 'Property' && p.key === node && !p.computed;
         const isShorthand = p.type === 'Property' && p.shorthand && p.value === node;
         const isMemberObject = p.type === 'MemberExpression' && p.object === node;
 
@@ -826,6 +897,12 @@ export function compile(source, options = {}) {
   const stateVars = new Set();
   const exportedProps = [];
   const componentImports = [];
+  // Every other import in the script. They used to be deleted, so a package
+  // import (`import DataCard from '@sola-air-ui/ui/data-card'`, or anything from
+  // '@sola-air-ui/core' that the compiler does not already provide) was gone from
+  // the output and left an undefined name behind.
+  const otherImports = [];
+  const coreImportExtras = [];
 
   let reactiveVars = NO_REACTIVE_VARS;
   if (strippedScript.trim()) {
@@ -851,6 +928,21 @@ export function compile(source, options = {}) {
             node.specifiers.forEach(spec => {
               componentImports.push({ localName: spec.local.name, path: src });
             });
+          } else if (src === '@sola-air-ui/core' || src === '@sola/core') {
+            // The compiler already imports these names under their own names.
+            // Importing one again would be a duplicate binding, so keep only the
+            // rest: names it does not provide, and aliased ones.
+            node.specifiers.forEach(spec => {
+              if (spec.type !== 'ImportSpecifier') return;
+              const imported = spec.imported.name ?? spec.imported.value;
+              if (spec.local.name === imported && CORE_PROVIDED.has(imported)) return;
+              coreImportExtras.push({ imported, local: spec.local.name });
+            });
+          } else {
+            otherImports.push({
+              code: strippedScript.slice(node.start, node.end).trim().replace(/;?$/, ';'),
+              locals: node.specifiers.map(spec => spec.local.name)
+            });
           }
           edits.push({
             start: node.start,
@@ -874,6 +966,16 @@ export function compile(source, options = {}) {
           removedRanges.push([node.start, node.end]);
         }
 
+        // $on('type', handler): subscribe to a bus event for the life of the
+        // component. Compiles to onDestroy(__solaBus.on(type, handler)). The handler
+        // stays in place so signals read inside it are rewritten like any other.
+        if (node.type === 'ExpressionStatement' && node.expression.type === 'CallExpression' &&
+            node.expression.callee.type === 'Identifier' && node.expression.callee.name === '$on') {
+          const call = node.expression;
+          edits.push({ start: call.callee.start, end: call.callee.end, replacement: 'onDestroy(__solaBus.on' });
+          edits.push({ start: call.end, end: call.end, replacement: ')' });
+        }
+
         // $state()/$derived()/$effect()/$intent()/$data() macro declarations.
         // Bracket edits (head + tail) leave the argument expression in place so
         // the reactive rewrite pass below can still auto-call signals inside it.
@@ -907,6 +1009,16 @@ export function compile(source, options = {}) {
               } else {
                 edits.push({ start: node.start, end: node.end, replacement: `const ${varName} = createDerived(() => undefined);` });
               }
+            } else if (macro === '$lastEvent') {
+              // let ctx = $lastEvent('type'): the latest payload of a bus event as a
+              // reactive accessor, released when the component is destroyed.
+              const varName = decl.id.name;
+              if (arg) {
+                edits.push({ start: node.start, end: arg.start, replacement: `const ${varName} = __solaBus.signal(` });
+                edits.push({ start: lastArg.end, end: node.end, replacement: `); onDestroy(${varName}.dispose);` });
+              } else {
+                edits.push({ start: node.start, end: node.end, replacement: `const ${varName} = () => undefined;` });
+              }
             } else if (macro === '$effect') {
               if (arg) {
                 edits.push({ start: node.start, end: arg.start, replacement: `createEffect(` });
@@ -967,6 +1079,11 @@ export function compile(source, options = {}) {
   let uid = 0;
   let domCode = '';
   const importedComponentSet = new Set(componentImports.map(i => i.localName));
+  // A capitalised tag that matches a name imported from a package is a component
+  // too (`import DataCard from '@sola-air-ui/ui/data-card'`), not only a `.sola` path.
+  for (const imp of otherImports) {
+    for (const name of imp.locals) if (/^[A-Z]/.test(name)) importedComponentSet.add(name);
+  }
 
   const sourceFile = options.filename || '<component>';
 
@@ -1047,25 +1164,43 @@ export function compile(source, options = {}) {
       domCode += `  ${parentVar}.appendChild(${cid}_target);\n`;
 
       // Dynamically-bound props (rows={items}) arrive here as __soladyn_N__ placeholders —
-      // resolve them back to the real expression from dynAttrs and pass it as a raw
-      // (unquoted) property so the child receives live data, not the placeholder text.
+      // resolve them back to the real expression from dynAttrs.
       //
       // `onXxx`-named props (e.g. onChange={handler}) arrive as a
       // __solahandler_N__ marker, because preprocessTemplate cannot tell a
       // component apart from a native element and lifts both the same way.
       // Either way the expression is passed through as a live function.
+      //
+      // Three kinds of dynamic prop:
+      //  - a bare name (rows={items}) is passed as-is. For a $state that is the
+      //    signal accessor, which is how a child receives live data (the shipped
+      //    components accept either an accessor or a plain value);
+      //  - an expression that reads a signal (title={ctx.title}) is evaluated
+      //    with the signal reads rewritten, and the child is re-mounted when
+      //    the value changes;
+      //  - an expression that reads no signal (text={msg.text} in an {#each})
+      //    is evaluated once, when the child is mounted.
       const propEntries = [];
+      let reactiveProps = false;
       for (const [key, val] of Object.entries(node.attribs || {})) {
         const dynMatch = /^__soladyn_(\d+)__$/.exec(val);
         const handlerMatch = /^__solahandler_(\d+)__$/.exec(val);
-        // Dynamic (non-event) component props are deliberately NOT auto-called:
-        // passing the getter is how a child receives live data today, and
-        // README-syntax components rely on it.
-        const propValue = dynMatch
-          ? `(${dynAttrs[parseInt(dynMatch[1], 10)]})`
-          : handlerMatch
-            ? `(${rewrite(handlers[parseInt(handlerMatch[1], 10)])})`
-            : JSON.stringify(val);
+        let propValue;
+        if (dynMatch) {
+          const raw = dynAttrs[parseInt(dynMatch[1], 10)];
+          if (/^\s*[A-Za-z_$][\w$]*\s*$/.test(raw)) {
+            propValue = `(${raw})`;
+          } else {
+            checkExpression(raw, 'component prop');
+            const rewritten = rewrite(raw);
+            if (rewritten !== raw) reactiveProps = true;
+            propValue = `(${rewritten})`;
+          }
+        } else if (handlerMatch) {
+          propValue = `(${rewrite(handlers[parseInt(handlerMatch[1], 10)])})`;
+        } else {
+          propValue = JSON.stringify(val);
+        }
         propEntries.push(`${JSON.stringify(key)}: ${propValue}`);
       }
 
@@ -1079,7 +1214,21 @@ export function compile(source, options = {}) {
         propEntries.push(`children: ${slotVar}`);
       }
 
-      domCode += `  ${node.name}(${cid}_target, { ${propEntries.join(', ')} });\n`;
+      // The child mounts untracked, so nothing it reads while building itself
+      // can re-run the parent's effect. Its teardown is kept and registered with
+      // whatever scope is being built, so it runs when that scope is destroyed.
+      domCode += `  let ${cid}_unmount = null;\n`;
+      domCode += `  onDestroy(() => { if (typeof ${cid}_unmount === 'function') ${cid}_unmount(); ${cid}_unmount = null; });\n`;
+      if (reactiveProps) {
+        domCode += `  createEffect(() => {\n`;
+        domCode += `    const ${cid}_props = { ${propEntries.join(', ')} };\n`;
+        domCode += `    if (typeof ${cid}_unmount === 'function') __untrack(${cid}_unmount);\n`;
+        domCode += `    ${cid}_target.textContent = '';\n`;
+        domCode += `    ${cid}_unmount = __untrack(() => ${node.name}(${cid}_target, ${cid}_props));\n`;
+        domCode += `  });\n`;
+      } else {
+        domCode += `  ${cid}_unmount = __untrack(() => ${node.name}(${cid}_target, { ${propEntries.join(', ')} }));\n`;
+      }
       return;
     }
 
@@ -1090,37 +1239,50 @@ export function compile(source, options = {}) {
     }
 
     // {#if ...} {:else} ... {/if}
+    //
+    // Each time a branch is built it gets its own scope (pushContext). Effects,
+    // onDestroy callbacks and child components created inside register with that
+    // scope, and switching or removing the branch destroys it, so nothing built
+    // for a branch that is no longer on the page keeps running.
     if (node.name === 'sola-if') {
       const cid = `c${uid++}`;
       domCode += `  const ${cid}_a = document.createComment('if');\n`;
       domCode += `  ${parentVar}.appendChild(${cid}_a);\n`;
       domCode += `  let ${cid}_els = [];\n`;
-      
+      domCode += `  let ${cid}_ctx = null;\n`;
+      domCode += `  onDestroy(() => { if (${cid}_ctx) { __flush_destroys(${cid}_ctx); ${cid}_ctx = null; } });\n`;
+
       const thenChild = node.children.find(c => c.name === 'sola-then');
       const elseChild = node.children.find(c => c.name === 'sola-else');
 
-      domCode += `  createEffect(() => {\n`;
-      domCode += `    ${cid}_els.forEach(e => e.remove()); ${cid}_els = [];\n`;
-      domCode += `    if (${rewrite(node.attribs.condition)}) {\n`;
-      if (thenChild) {
+      const emitBranch = (branch) => {
+        if (!branch) return;
+        domCode += `      ${cid}_ctx = pushContext();\n`;
+        domCode += `      try {\n`;
         domCode += `      const f = document.createDocumentFragment();\n`;
-        thenChild.children.forEach(child => emitNode(child, 'f', locals));
+        branch.children.forEach(child => emitNode(child, 'f', locals));
         domCode += `      Array.from(f.childNodes).forEach(n => ${cid}_els.push(n));\n`;
         domCode += `      ${cid}_a.parentNode.insertBefore(f, ${cid}_a.nextSibling);\n`;
-      }
+        domCode += `      } finally { popContext(${cid}_ctx); }\n`;
+      };
+
+      domCode += `  createEffect(() => {\n`;
+      domCode += `    if (${cid}_ctx) { __flush_destroys(${cid}_ctx); ${cid}_ctx = null; }\n`;
+      domCode += `    ${cid}_els.forEach(e => e.remove()); ${cid}_els = [];\n`;
+      domCode += `    if (${rewrite(node.attribs.condition)}) {\n`;
+      emitBranch(thenChild);
       domCode += `    } else {\n`;
-      if (elseChild) {
-        domCode += `      const f = document.createDocumentFragment();\n`;
-        elseChild.children.forEach(child => emitNode(child, 'f', locals));
-        domCode += `      Array.from(f.childNodes).forEach(n => ${cid}_els.push(n));\n`;
-        domCode += `      ${cid}_a.parentNode.insertBefore(f, ${cid}_a.nextSibling);\n`;
-      }
+      emitBranch(elseChild);
       domCode += `    }\n`;
       domCode += `  });\n`;
       return;
     }
 
     // {#each} with optional keyed diffing: {#each items as item (item.id)}
+    //
+    // Like {#if}, what is built for the list gets its own scope so it can be
+    // destroyed: the whole list for an unkeyed each, one scope per key for a
+    // keyed one (so removing an item stops that item's effects and children).
     if (node.name === 'sola-each') {
       const eid = `e${uid++}`;
       // Item/index names shadow signals inside the loop body and key expression
@@ -1134,70 +1296,53 @@ export function compile(source, options = {}) {
       domCode += `  const ${eid}_a = document.createComment('each');\n`;
       domCode += `  ${parentVar}.appendChild(${eid}_a);\n`;
       if (keyExpr) {
-        // Keyed: maintain a Map<key, Node[]> and reconcile on each run
+        // Keyed: maintain a Map<key, { nodes, ctx }> and reconcile on each run
         // Reconcile by walking the new order and moving each key's nodes into
         // place against a cursor. The previous version only ever inserted, and
         // against an anchor it never advanced — so reordering a keyed list (a
         // sort, a drag, a reverse) left the DOM in its original order, silently.
-        domCode += `  let ${eid}_keyMap = new Map();
-`;
-        domCode += `  createEffect(() => {
-`;
-        domCode += `    const _items = ${arrayExpr} || [];
-`;
-        domCode += `    const _parent = ${eid}_a.parentNode;
-`;
-        domCode += `    const _seen = new Set();
-`;
-        domCode += `    let _cursor = ${eid}_a.nextSibling;
-`;
-        domCode += `    for (let _i = 0; _i < _items.length; _i++) {
-`;
-        domCode += `      const ${node.attribs.item} = _items[_i];
-`;
-        if (node.attribs.index) domCode += `      const ${node.attribs.index} = _i;
-`;
-        domCode += `      const _key = String(${keyExpr});
-`;
-        domCode += `      _seen.add(_key);
-`;
-        domCode += `      let _nodes = ${eid}_keyMap.get(_key);
-`;
-        domCode += `      if (!_nodes) {
-`;
-        domCode += `        const f = document.createDocumentFragment();
-`;
+        domCode += `  let ${eid}_keyMap = new Map();\n`;
+        domCode += `  onDestroy(() => { for (const _e of ${eid}_keyMap.values()) __flush_destroys(_e.ctx); ${eid}_keyMap.clear(); });\n`;
+        domCode += `  createEffect(() => {\n`;
+        domCode += `    const _items = ${arrayExpr} || [];\n`;
+        domCode += `    const _parent = ${eid}_a.parentNode;\n`;
+        domCode += `    const _seen = new Set();\n`;
+        domCode += `    let _cursor = ${eid}_a.nextSibling;\n`;
+        domCode += `    for (let _i = 0; _i < _items.length; _i++) {\n`;
+        domCode += `      const ${node.attribs.item} = _items[_i];\n`;
+        if (node.attribs.index) domCode += `      const ${node.attribs.index} = _i;\n`;
+        domCode += `      const _key = String(${keyExpr});\n`;
+        domCode += `      _seen.add(_key);\n`;
+        domCode += `      let _entry = ${eid}_keyMap.get(_key);\n`;
+        domCode += `      if (!_entry) {\n`;
+        domCode += `        const _kctx = pushContext();\n`;
+        domCode += `        try {\n`;
+        domCode += `        const f = document.createDocumentFragment();\n`;
         node.children.forEach(child => emitNode(child, 'f', eachLocals));
-        domCode += `        _nodes = Array.from(f.childNodes);
-`;
-        domCode += `        ${eid}_keyMap.set(_key, _nodes);
-`;
-        domCode += `      }
-`;
-        domCode += `      for (const _n of _nodes) {
-`;
-        domCode += `        if (_n === _cursor) { _cursor = _cursor.nextSibling; }
-`;
-        domCode += `        else { _parent.insertBefore(_n, _cursor); }
-`;
-        domCode += `      }
-`;
-        domCode += `    }
-`;
-        domCode += `    for (const [_k, _stale] of ${eid}_keyMap) {
-`;
-        domCode += `      if (!_seen.has(_k)) { _stale.forEach(n => n.remove()); ${eid}_keyMap.delete(_k); }
-`;
-        domCode += `    }
-`;
-        domCode += `  });
-`;
+        domCode += `        _entry = { nodes: Array.from(f.childNodes), ctx: _kctx };\n`;
+        domCode += `        } finally { popContext(_kctx); }\n`;
+        domCode += `        ${eid}_keyMap.set(_key, _entry);\n`;
+        domCode += `      }\n`;
+        domCode += `      for (const _n of _entry.nodes) {\n`;
+        domCode += `        if (_n === _cursor) { _cursor = _cursor.nextSibling; }\n`;
+        domCode += `        else { _parent.insertBefore(_n, _cursor); }\n`;
+        domCode += `      }\n`;
+        domCode += `    }\n`;
+        domCode += `    for (const [_k, _stale] of ${eid}_keyMap) {\n`;
+        domCode += `      if (!_seen.has(_k)) { __flush_destroys(_stale.ctx); _stale.nodes.forEach(n => n.remove()); ${eid}_keyMap.delete(_k); }\n`;
+        domCode += `    }\n`;
+        domCode += `  });\n`;
       } else {
         // Unkeyed: full teardown + rebuild
         domCode += `  let ${eid}_els = [];\n`;
+        domCode += `  let ${eid}_ctx = null;\n`;
+        domCode += `  onDestroy(() => { if (${eid}_ctx) { __flush_destroys(${eid}_ctx); ${eid}_ctx = null; } });\n`;
         domCode += `  createEffect(() => {\n`;
+        domCode += `    if (${eid}_ctx) { __flush_destroys(${eid}_ctx); ${eid}_ctx = null; }\n`;
         domCode += `    ${eid}_els.forEach(e => e.remove()); ${eid}_els = [];\n`;
         domCode += `    const _items = ${arrayExpr} || [];\n`;
+        domCode += `    ${eid}_ctx = pushContext();\n`;
+        domCode += `    try {\n`;
         domCode += `    const f = document.createDocumentFragment();\n`;
         domCode += `    for (let _i = 0; _i < _items.length; _i++) {\n`;
         domCode += `      const ${node.attribs.item} = _items[_i];\n`;
@@ -1206,6 +1351,7 @@ export function compile(source, options = {}) {
         domCode += `    }\n`;
         domCode += `    Array.from(f.childNodes).forEach(n => ${eid}_els.push(n));\n`;
         domCode += `    ${eid}_a.parentNode.insertBefore(f, ${eid}_a.nextSibling);\n`;
+        domCode += `    } finally { popContext(${eid}_ctx); }\n`;
         domCode += `  });\n`;
       }
       return;
@@ -1273,24 +1419,39 @@ export function compile(source, options = {}) {
   root.children.forEach(child => emitNode(child, '__target'));
 
   // Assemble final output module
-  const CORE_EXPORTS = 'createSignal, createDerived, createEffect, createIntent, createData, createPersistentSignal, onMount, onDestroy, pushContext, popContext, __flush_mounts, __flush_destroys';
+  const CORE_EXPORTS = [...CORE_PROVIDED].join(', ');
+  // The default bus is imported under an alias so a user variable named `bus`
+  // cannot shadow what $on / $lastEvent compile to.
+  const ESM_CORE_IMPORTS = CORE_EXPORTS + ', bus as __solaBus';
+  const IIFE_CORE_PULL = CORE_EXPORTS + ', bus: __solaBus';
   let output = '';
   output += `// Compiled by @sola-air-ui/compiler v${COMPILER_VERSION}\n`;
 
   if (target === 'iife') {
-    // ServiceNow / no-bundler mode: pull from window.SolaCore global
+    // No-bundler mode: pull from window.SolaCore global
     output += `(function() {\n`;
-    output += `const { ${CORE_EXPORTS} } = window.SolaCore;\n`;
+    const iifeExtras = coreImportExtras.map(e => (e.local === e.imported ? e.imported : `${e.imported}: ${e.local}`));
+    output += `const { ${[IIFE_CORE_PULL, ...iifeExtras].join(', ')} } = window.SolaCore;\n`;
     for (const imp of componentImports) {
       output += `// Note: sub-component ${imp.localName} must be pre-loaded before this script\n`;
     }
+    for (const imp of otherImports) {
+      output += `// Note: ${imp.locals.join(', ')} must be loaded before this script (no-bundler output cannot import)\n`;
+    }
     output += `\n`;
     output += `window['${options.exportName || 'SolaComponent'}'] = function mount(__target, props = {}) {\n`;
   } else {
-    output += `import { ${CORE_EXPORTS} } from '@sola-air-ui/core';\n`;
+    output += `import { ${ESM_CORE_IMPORTS} } from '@sola-air-ui/core';\n`;
+    if (coreImportExtras.length) {
+      const names = coreImportExtras.map(e => (e.local === e.imported ? e.imported : `${e.imported} as ${e.local}`));
+      output += `import { ${names.join(', ')} } from '@sola-air-ui/core';\n`;
+    }
     for (const imp of componentImports) {
       output += `import ${imp.localName} from '${imp.path}';\n`;
     }
+    for (const imp of otherImports) {
+      output += `${imp.code}\n`;
+    }
     output += `\n`;
     output += `export default function mount(__target, props = {}) {\n`;
   }
@@ -1336,6 +1497,13 @@ export function compile(source, options = {}) {
   output += `};\n`;
   if (target === 'iife') {
     output += `})();\n`;
+  } else if (options.exportStyles) {
+    // Opt-in: the stylesheet and its scope class as module exports, for hosts
+    // that mount into a Shadow Root and adopt the CSS themselves (e.g. via
+    // adoptedStyleSheets). Off by default so existing build scripts that append
+    // their own `css` / `scopeHash` exports, or strip exports, keep working.
+    output += `\nexport const scopeHash = ${JSON.stringify(scopeHash)};\n`;
+    output += `export const css = \`${escapeTemplateLiteral(scopedCss || '')}\`;\n`;
   }
 
   // The reactive rewrite can add or remove characters within a line but never
@@ -1355,6 +1523,41 @@ export function compile(source, options = {}) {
     code: output,
     scopeHash,
     css: scopedCss,
-    map
+    map,
+    dts: buildDeclarations(exportedProps, !!options.exportStyles)
   };
 }
+
+// Best-effort TypeScript type for a prop, from the literal its default is
+// declared with. Anything it cannot read confidently is `unknown`, which stays
+// safe for callers rather than claiming a precision it does not have.
+function inferPropType(defaultSrc) {
+  const d = String(defaultSrc ?? '').trim();
+  if (/^(['"`])[\s\S]*\1$/.test(d)) return 'string';
+  if (/^-?\d[\d_]*(\.\d+)?([eE][+-]?\d+)?$/.test(d)) return 'number';
+  if (d === 'true' || d === 'false') return 'boolean';
+  // A null or undefined default says nothing about the type. `unknown` would stop a
+  // TypeScript host from reading or calling the prop; `any` lets it.
+  if (d === 'null' || d === 'undefined') return 'any';
+  if (d.startsWith('[')) return 'unknown[]';
+  if (d.startsWith('{')) return 'Record<string, unknown>';
+  if (/^(\(.*\)|\w+)\s*=>|^function\b/.test(d)) return '(...args: any[]) => any';
+  return 'unknown';
+}
+
+// A `.d.ts` for a compiled component, so a TypeScript host can import the
+// compiled module with its props checked. Every prop is optional because each
+// has a default.
+function buildDeclarations(props, exportStyles) {
+  const fields = props
+    .map(p => `  ${/^[A-Za-z_$][\w$]*$/.test(p.name) ? p.name : JSON.stringify(p.name)}?: ${inferPropType(p.default)};`)
+    .join('\n');
+  return [
+    `export interface Props {${fields ? '\n' + fields + '\n' : ''}}`,
+    `/** Mounts the component into \`target\` and returns a teardown function. */`,
+    `declare function mount(target: Element | ShadowRoot, props?: Props): () => void;`,
+    `export default mount;`,
+    ...(exportStyles ? [`export declare const scopeHash: string;`, `export declare const css: string;`] : []),
+    ``
+  ].join('\n');
+}

package/types/index.d.ts

@@ -4,7 +4,7 @@ export interface CompileOptions {
   /**
    * 'esm' (default) emits a module importing from @sola-air-ui/core.
    * 'iife' emits a self-contained bundle reading from window.SolaCore, for
-   * ServiceNow and other no-bundler hosts.
+   * enterprise portals and other no-bundler hosts.
    */
   target?: 'esm' | 'iife';
   /** Global name the IIFE build registers itself under. Default 'SolaComponent'. */