tutuca 0.9.78 → 0.9.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.78",
+  "version": "0.9.79",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",

package/skill/tutuca/advanced.md

@@ -43,30 +43,31 @@ Touch is wired up too (drag fires after a small move threshold).
 ## Dynamic Bindings
 
 For passing values "context-style" through nested components without prop
-drilling. Define on the producer; alias on consumers; resolve as `*name`.
+drilling. **`provide`** on the producer; **`lookup`** on consumers;
+resolve as `*name`.
 
 ```js
 const Theme = component({
   name: "Theme",
   fields: { color: "blue" },
-  dynamic: { color: ".color" },
-  on: {
-    stackEnter() {
-      return ["color"];
-    },
-  },
+  provide: { color: ".color" },
 });
 const Child = component({
-  dynamic: { color: { for: "Theme.color", default: "'gray'" } },
+  lookup: { color: { for: "Theme.color", default: "'gray'" } },
   view: html`<p :style="$'color: {*color}'"></p>`,
 });
 ```
 
-`on.stackEnter()` is required only on the **producer** (the component
-declaring `dynamic: { name: ".field" }` to expose a value). It returns
-the list of dynamic-binding names this component pushes onto the stack
-when entering its render. Consumers (which only alias via
-`{ for: "Producer.name", default: ... }`) don't need it.
+A **`provide`** maps an exported name to a field expression. Every
+provide is evaluated and pushed onto the dynamic stack automatically
+when the producer is entered during render — there is no hook to opt in.
+
+A **`lookup`** reads a value the `*name` way: the key is the name used
+in views (`*color`), the value is `"Producer.provideName"`, or
+`{ for: "Producer.provideName", default: ".field" }` to supply a
+fallback when no producer is in scope (default is optional — without it
+a miss resolves to `null`). A `*name` that names the component's own
+`provide` resolves to the nearest provided value (including its own).
 
 ### Dynamic vars as render targets
 
@@ -80,23 +81,26 @@ component-render target and an iteration source:
 <div @each="*items"><x render-it></x></div>  <!-- iterate a dynamic seq -->
 ```
 
-The producer's `dynamic` value is an **expression**, not only a bare
-field — it can be a sequence/map item access:
+A `provide` value must be **addressable** — a `.field` or a `.seq[.key]`
+seq-access, nothing else. (It is both read as `*name` *and* used as a
+render-target / teleport path, so a method or constant — which has no
+path — is a lint error.) A `lookup` `default`, by contrast, is only a
+value fallback and accepts the full grammar, including constants like
+`'gray'`. A `provide` can be a sequence/map item access:
 
 ```js
 const Root = component({
   name: "Root",
   fields: { items: IMap(), selectedKey: "" },
-  dynamic: {
+  provide: {
     items: ".items",                  // the whole sequence
     selected: ".items[.selectedKey]", // seq-access to one entry
   },
-  on: { stackEnter() { return ["items", "selected"]; } },
 });
 ```
 
 There is **no `*name[.key]` form** — a consumer never indexes a dynamic
-var. The seq-access lives in the producer's `dynamic` declaration; the
+var. The seq-access lives in the producer's `provide` declaration; the
 consumer just reads the resolved value as `*name`.
 
 **Teleporting.** The component rendered via `<x render="*selected">`

package/skill/tutuca/core.md

@@ -305,7 +305,7 @@ component({
   bubble:  { itemPicked(item, ctx) { return this.setSelected(item); } },
   response:{ loadData(res, err, ctx) { return this.setItems(res); } },
   statics: { fromData(d) { return this.make({ count: d.n ?? 0 }); } },
-  // dynamic: { ... }, on: { stackEnter() {...} }   // see advanced.md
+  // provide: { ... }, lookup: { ... }   // see advanced.md
 });
 ```
 
@@ -416,6 +416,48 @@ statics: {
 // usage: TreeRoot.Class.fromData([...])
 ```
 
+### One definition, multiple scopes (`clone`)
+
+A component is built once and bound to a scope at `registerComponents`
+time: that scope owns the component's `Class`, the per-instance
+component tag, and the scope-bound `make`/statics. Re-registering the
+*same* component object into another scope rebinds it (last wins) —
+fine for a fresh re-setup, but it means a single definition can't be
+live in two scopes at once.
+
+To register the same definition into a second scope simultaneously, use
+`Comp.clone()` — it returns a fresh, fully independent `Component` (new
+id, its own `Class`) built from the same spec:
+
+```js
+scopeA.registerComponents([Widget]);
+scopeB.registerComponents([Widget.clone()]); // independent Class + scope
+```
+
+Each clone has its own `Class`, so `getCompFor(instance)` and a static's
+`this.scope` / `this.make` resolve unambiguously to the scope that
+instance belongs to — even after immutable `.set()` updates, since the
+component tag lives on the (per-scope) prototype.
+
+**Caveat — statics that reach a child by its module-level const.** A
+static like `fromData` that builds a *different* child type by naming the
+imported const directly (`Item.Class.fromData(v)` above) hardcodes the
+child's *original* scope. In a single-scope app that's the only scope, so
+it's fine. But once you `clone()` either component into another scope, the
+parent clone still deserializes children through the original `Item` —
+wrong scope. For multi-scope safety, resolve the child through the
+caller's scope instead of the module-level const:
+
+```js
+fromData({ items = [] }) {
+  const Item = this.scope.lookupComponent("Item");
+  return this.make({ items: items.map((v) => Item.Class.fromData(v)) });
+}
+```
+
+Recursion into the *same* type needs no lookup — use `this.fromData(v)`
+(or `this.make`), which already targets the caller's scope.
+
 ## Text Rendering
 
 ```html
@@ -459,6 +501,14 @@ consequences:
 - Macro registry keys are lowercased on insert for the same reason
   (see *Macros* below).
 
+Tutuca auto-namespaces by subtree: elements inside `<svg>` get the SVG
+namespace and elements inside `<math>` get MathML, with spec-cased local
+names preserved (`linearGradient`, `viewBox`). A `<foreignObject>` switches
+its children back to the HTML namespace. Customised built-in elements work
+via `is="..."` (e.g. `<button is="x-fancy">`); `is` is applied when the
+element is created, so it must be a static attribute — setting it later
+does not upgrade the element.
+
 ## Event Handling
 
 ```html

package/skill/tutuca/semantics.md

@@ -106,7 +106,7 @@ bubble handler can reply to the originator via `ctx.sendAtPath(ctx.targetPath,
 ## Dynamic-var teleporting
 
 A component rendered through `<x render="*sel">` *physically lives* at the
-producer that declared `dynamic: { sel: … }`, not under the consumer that
+producer that declared `provide: { sel: … }`, not under the consumer that
 wrote the render. The reconstructed dispatch path keeps every intermediate
 component (so bubbling visits them), but `toTransactionPath()` teleports
 the `DynStep`: it pops the steps tagged with the marker's `interiorCids`
@@ -115,7 +115,7 @@ mutation therefore lands on the producer's data, and the consumer's view
 of it updates in lock-step. Authoring view: *Teleporting* in
 [advanced.md](./advanced.md).
 
-When the producer's `dynamic` value is a seq-access (`.sheets[.selId]`),
+When the producer's `provide` value is a seq-access (`.sheets[.selId]`),
 the teleported steps include a `SeqAccessStep` — which is where async key
 races come from.
 

package/skill/tutuca-source/tutuca.ext.js

@@ -474,6 +474,7 @@ var G_BOOL = K_FIELD | K_METHOD | K_BIND | K_DYN | K_CONST;
 var G_TEXT = G_BOOL | K_STRTPL;
 var G_COMPONENT = K_FIELD | K_SEQ | K_DYN;
 var G_SEQUENCE = K_FIELD | K_DYN;
+var G_PROVIDE = K_FIELD | K_SEQ;
 var G_FIELD = K_FIELD | K_METHOD | K_CONST | K_STR | K_SEQ;
 var G_VALUE = K_FIELD | K_METHOD | K_BIND | K_DYN | K_NAME | K_TYPE | K_REQUEST | K_CONST;
 var G_PRED_ARG = G_BOOL | K_STR;
@@ -592,6 +593,9 @@ class ValParser {
   parseField(s, px) {
     return this._parseSingle(s, px, G_FIELD);
   }
+  parseProvide(s, px) {
+    return this._parseSingle(s, px, G_PROVIDE);
+  }
   parseHandlerArg(s, px) {
     return this._parseSingle(s, px, G_HANDLER_ARG);
   }
@@ -1578,21 +1582,22 @@ function h(tagName, properties, children, namespace) {
 }
 
 // src/anode.js
-function resolveDynProducer(comp, dynName) {
-  const dyn = comp?.dynamic?.[dynName];
-  if (dyn == null)
-    return null;
-  let producerComp, producerDyn;
-  if (dyn.compName != null) {
-    producerComp = comp.scope?.lookupComponent(dyn.compName);
-    producerDyn = producerComp?.dynamic?.[dyn.dynName];
+function resolveDynProducer(comp, name) {
+  let producerComp, producerProvide;
+  const lk = comp?.lookup?.[name];
+  if (lk != null) {
+    producerComp = comp.scope?.lookupComponent(lk.compName);
+    producerProvide = producerComp?.provide?.[lk.provideName];
   } else {
+    const p = comp?.provide?.[name];
+    if (p == null)
+      return null;
     producerComp = comp;
-    producerDyn = dyn;
+    producerProvide = p;
   }
-  if (producerComp == null || producerDyn == null)
+  if (producerComp == null || producerProvide == null)
     return null;
-  const pi = producerDyn.val?.toPathItem?.() ?? null;
+  const pi = producerProvide.val?.toPathItem?.() ?? null;
   return { producerCompId: producerComp.id, producerSteps: pi ? [pi] : [] };
 }
 
@@ -2335,9 +2340,6 @@ class Components {
   getCompFor(v) {
     return v?.[this.getComponentSymbol]?.() ?? null;
   }
-  getOnEnterFor(v) {
-    return this.getCompFor(v)?.on.stackEnter ?? defaultOnStackEnter;
-  }
   getHandlerFor(v, name, key) {
     return this.getCompFor(v)?.[key][name] ?? null;
   }
@@ -2407,36 +2409,30 @@ class ComponentStack {
   }
 }
 
-class Dynamic {
+class ProvideInfo {
   constructor(name, val, symbol) {
     this.name = name;
     this.val = val;
     this.symbol = symbol;
   }
-  getSymbol(_stack) {
-    return this.symbol;
-  }
-  evalAndBind(stack, binds) {
-    binds[this.getSymbol(stack)] = this.val.eval(stack);
-  }
 }
 
-class DynamicAlias extends Dynamic {
-  constructor(name, val, compName, dynName) {
-    super(name, val, null);
+class LookupInfo {
+  constructor(name, compName, provideName, val) {
+    this.name = name;
     this.compName = compName;
-    this.dynName = dynName;
-  }
-  _resolveSymbol(stack) {
-    return stack.lookupType(this.compName)?.dynamic[this.dynName]?.symbol ?? null;
+    this.provideName = provideName;
+    this.val = val;
+    this._sym = undefined;
   }
-  getSymbol(stack) {
-    this.symbol ??= this._resolveSymbol(stack);
-    return this.symbol;
+  getProducerSymbol(stack) {
+    if (this._sym === undefined)
+      this._sym = stack.lookupType(this.compName)?.provide?.[this.provideName]?.symbol ?? null;
+    return this._sym;
   }
 }
 var isString = (v) => typeof v === "string";
-var _rawSpecKeys = "name view style commonStyle globalStyle input receive bubble response alter on views dynamic fields methods statics";
+var _rawSpecKeys = "name view style commonStyle globalStyle input receive bubble response alter views provide lookup fields methods statics";
 var KNOWN_SPEC_KEYS = new Set(_rawSpecKeys.split(" "));
 var _compId = 0;
 
@@ -2453,35 +2449,47 @@ class Component {
     this.bubble = o.bubble ?? {};
     this.response = o.response ?? {};
     this.alter = o.alter ?? {};
-    this.on = { stackEnter: o.on?.stackEnter ?? defaultOnStackEnter };
     for (const name in o.views ?? {}) {
       const v = o.views[name];
       const { view, style } = isString(v) ? { view: v } : v;
       this.views[name] = new View(name, view, style);
     }
-    this._rawDynamic = o.dynamic ?? {};
-    this.dynamic = {};
+    this._rawProvide = o.provide ?? {};
+    this._rawLookup = o.lookup ?? {};
+    this.provide = {};
+    this.lookup = {};
     this.scope = null;
+    this.spec = o;
     this.extra = {};
     for (const key of Object.keys(o))
       if (!KNOWN_SPEC_KEYS.has(key))
         this.extra[key] = o[key];
   }
+  clone() {
+    return Component.fromSpec(this.spec);
+  }
   compile(ParseContext2) {
     for (const name in this.views)
       this.views[name].compile(new ParseContext2, this.scope, this.id);
-    for (const key in this._rawDynamic) {
-      const dinfo = this._rawDynamic[key];
-      if (isString(dinfo)) {
-        const val = vp.parseField(dinfo, this.views.main.ctx);
-        this.dynamic[key] = new Dynamic(key, val, Symbol(key));
-      } else if (isString(dinfo?.default) && isString(dinfo?.for)) {
-        const val = vp.parseField(dinfo.default, this.views.main.ctx);
-        const [compName, dynName] = dinfo.for.split(".");
-        if (isString(compName) && isString(dynName))
-          this.dynamic[key] = new DynamicAlias(key, val, compName, dynName);
-      }
-    }
+    const ctx = this.views.main.ctx;
+    for (const key in this._rawProvide) {
+      const val = vp.parseProvide(this._rawProvide[key], ctx);
+      if (val)
+        this.provide[key] = new ProvideInfo(key, val, Symbol(key));
+    }
+    for (const key in this._rawLookup) {
+      const linfo = this._rawLookup[key];
+      const forStr = isString(linfo) ? linfo : isString(linfo?.for) ? linfo.for : null;
+      const [compName, provideName] = forStr === null ? [] : forStr.split(".");
+      if (!isString(compName) || !isString(provideName))
+        continue;
+      const defStr = isString(linfo?.default) ? linfo.default : null;
+      const val = defStr === null ? null : vp.parseField(defStr, ctx);
+      this.lookup[key] = new LookupInfo(key, compName, provideName, val);
+    }
+    for (const key in this.lookup)
+      if (this.provide[key] !== undefined)
+        console.warn("name declared in both provide and lookup", this.name, key);
   }
   make(args, opts) {
     return this.Class.make(args, opts ?? { scope: this.scope });
@@ -2509,9 +2517,6 @@ class Component {
 `);
   }
 }
-function defaultOnStackEnter() {
-  return null;
-}
 
 // src/stack.js
 var STOP = Symbol("STOP");
@@ -2570,47 +2575,61 @@ class Stack {
     this.viewsId = viewsId;
     this.ctx = ctx;
   }
-  _enrichOnEnter() {
-    return this.withDynamicBinds(this.comps.getOnEnterFor(this.it).call(this.it));
+  _pushProvides() {
+    const provide = this.comps.getCompFor(this.it)?.provide;
+    if (provide == null)
+      return this;
+    const dynObj = {};
+    let has = false;
+    for (const k in provide) {
+      dynObj[provide[k].symbol] = provide[k].val.eval(this);
+      has = true;
+    }
+    if (!has)
+      return this;
+    const newDynBinds = [new ObjectFrame(dynObj), this.dynBinds];
+    const { comps, it, binds, views, viewsId, ctx } = this;
+    return new Stack(comps, it, binds, newDynBinds, views, viewsId, ctx);
   }
   static root(comps, it, ctx) {
     const binds = [new BindFrame(it, { it }, true), null];
     const dynBinds = [new ObjectFrame({}), null];
     const views = ["main", null];
-    return new Stack(comps, it, binds, dynBinds, views, "", ctx)._enrichOnEnter();
+    return new Stack(comps, it, binds, dynBinds, views, "", ctx)._pushProvides();
   }
   enter(it, bindings = {}, isFrame = true) {
     const { comps, binds, dynBinds, views, viewsId, ctx } = this;
     const newBinds = [new BindFrame(it, bindings, isFrame), binds];
     const stack = new Stack(comps, it, newBinds, dynBinds, views, viewsId, ctx);
-    return isFrame ? stack._enrichOnEnter() : stack;
+    return isFrame ? stack._pushProvides() : stack;
   }
   pushViewName(name) {
     const { comps, it, binds, dynBinds, views, ctx } = this;
     const newViews = [name, views];
     return new Stack(comps, it, binds, dynBinds, newViews, computeViewsId(newViews), ctx);
   }
-  withDynamicBinds(dynamics) {
-    if (dynamics == null || dynamics.length === 0)
-      return this;
-    const dynObj = {};
-    const comp = this.comps.getCompFor(this.it);
-    for (const dynName of dynamics)
-      comp.dynamic[dynName].evalAndBind(this, dynObj);
-    const newDynBinds = [new ObjectFrame(dynObj), this.dynBinds];
-    const { comps, it, binds, views, viewsId, ctx } = this;
-    return new Stack(comps, it, binds, newDynBinds, views, viewsId, ctx);
+  _pushDynBindValuesToArray(arr, comp) {
+    for (const k in comp.provide)
+      arr.push(this._lookupProvide(comp.provide[k]));
+    for (const k in comp.lookup)
+      arr.push(this._lookupAlias(comp.lookup[k]));
   }
-  _pushDynBindValuesToArray(arr, dyns) {
-    for (const k in dyns)
-      arr.push(this._lookupDynamicWithDynVal(dyns[k]));
+  _lookupProvide(p) {
+    return lookup(this.dynBinds, p.symbol) ?? p.val.eval(this) ?? null;
   }
-  _lookupDynamicWithDynVal(d) {
-    return lookup(this.dynBinds, d.getSymbol(this)) ?? d.val?.eval(this) ?? null;
+  _lookupAlias(lk) {
+    const sym = lk.getProducerSymbol(this);
+    return (sym != null ? lookup(this.dynBinds, sym) : null) ?? lk.val?.eval(this) ?? null;
   }
   lookupDynamic(name) {
-    const d = this.comps.getCompFor(this.it)?.dynamic[name];
-    return d ? this._lookupDynamicWithDynVal(d) : null;
+    const comp = this.comps.getCompFor(this.it);
+    if (comp == null)
+      return null;
+    const lk = comp.lookup[name];
+    if (lk !== undefined)
+      return this._lookupAlias(lk);
+    const p = comp.provide[name];
+    return p !== undefined ? this._lookupProvide(p) : null;
   }
   lookupBind(name) {
     return lookup(this.binds, name);
@@ -3380,7 +3399,7 @@ class Renderer {
   _rValComp(stack, val, comp, node, key, viewName) {
     const cacheKey = `${viewName ?? stack.viewsId ?? ""}-${key}`;
     const cachePath = [node, val];
-    stack._pushDynBindValuesToArray(cachePath, comp.dynamic);
+    stack._pushDynBindValuesToArray(cachePath, comp);
     const cachedNode = this.cache.get(cachePath, cacheKey);
     if (cachedNode)
       return cachedNode;
@@ -3920,7 +3939,8 @@ function classFromData(name, { fields = {}, methods, statics }) {
     b.statics(statics);
   return b.build();
 }
-var component = (opts) => new Component(classFromData(opts.name, opts), opts);
+Component.fromSpec = (opts) => new Component(classFromData(opts.name, opts), opts);
+var component = (opts) => Component.fromSpec(opts);
 
 // index.js
 var css = String.raw;