tutuca 0.13.2 → 0.14.0

package/skill/tutuca/advanced.md

@@ -79,14 +79,38 @@ it: whoever is nearest above and provides that name answers, and a
 `*name` that names the component's own `provide` resolves to that
 (including its own).
 
-Because a lookup does not name its producer, **one provide name has one
-producer per scope chain** — two components providing `color` is a lint
-error (`PROVIDE_NAME_COLLISION`), not a last-one-wins surprise. That is
-also what lets the render-target teleport below find the producer.
+More than one component may provide the same name. The live render stack
+is a normal shadowing stack, so the **nearest rendered provider wins** —
+a `Theme` nested inside another `Theme` overrides it for its own subtree,
+and nothing has to name a producer.
 
 A lookup name starting with an **uppercase** letter is a component
 **type** rather than a value; see *Looking up component types*.
 
+### Ambient names without a provider
+
+A name can also be registered **lexically**, as an absolute path from the
+app state root — for a session, a theme, or anything host-owned that no
+component in the tree should have to publish:
+
+```js
+import { path } from "tutuca";
+
+app.registerComponents([Workspace, Toolbar], {
+  paths: { session: path().field("session"), theme: path().field("ui").field("theme") },
+});
+```
+
+`path()` is the same address builder `ctx.at` hands a handler — `.field(name)`,
+`.index(name, i)`, `.key(name, k)`, chained freely from the state root.
+
+Descendants declare `lookup: ["session", "theme"]` and read or render
+`*session` / `*theme` as usual. The mounted root does not have to publish
+them, and no wrapper component needs to exist solely to. Register on a
+nested scope (`scope.registerPaths({…})`) to narrow a name; nearest
+registration wins. The order is still `dyn lex`, so a rendered provider
+answers before a registered path.
+
 ### Looking up component types
 
 The same two environments answer a **type** name, and a handler asks with
@@ -139,11 +163,14 @@ component-render target and an iteration source:
 ```
 
 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:
+seq-access, nothing else. It is both read as `*name` *and* used as the
+path a render target resumes at, so a method or constant — which has no
+path — is a lint error (`PROVIDE_NOT_ADDRESSABLE`), and the bad provide is
+dropped: `*name` then reads its `default`, or `null`. If a dynamic binding
+reads as its fallback everywhere, lint first and suspect the producer's
+expression. 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({
@@ -160,14 +187,18 @@ There is **no `*name[.key]` form** — a consumer never indexes a dynamic
 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">`
-physically lives at the producer (e.g. `Root.items`), not under the
-consumer. When an event fires inside that dynamically-rendered subtree,
-the runtime expands the *render* path (consumer → … → the rendered
-node) to reconstruct the handler, but the *transaction* is teleported:
-the mutation skips the intermediate components and lands on the
-producer's data. Editing the entry in the consumer and the same entry
-in the producer's own view update in lock-step.
+A published **type** is not a render target: it has no path, so
+`<x render="*Cell">` stays unresolvable by construction.
+
+**Resuming at the value's path.** The component rendered via
+`<x render="*selected">` physically lives at the producer (e.g.
+`Root.items`), not under the consumer. A provider publishes the value
+*and* the absolute path it lives at, and rendering pushes that path as a
+continuation frame. So an event inside that subtree mutates the selected
+value where it really is, while bubbling pops back out to the visual
+caller that wrote the `*name` and continues through its ancestry. Editing
+the entry in the consumer and the same entry in the producer's own view
+update in lock-step.
 
 ## Pseudo-`x` (`@x`)
 

package/skill/tutuca/component-design.md

@@ -160,8 +160,8 @@ A compact worked version of the first three (`method`, `send`/`receive`, and
 - [messages-and-intents.md](./messages-and-intents.md) — the channels in depth
   (`send`/`receive`, `intent` and its routes, `sendAtRoot`) and integrating
   with the outside world.
-- [advanced.md](./advanced.md) — `provide` / `lookup` / `*name` and the
-  clean-namespace boundary.
+- [advanced.md](./advanced.md) — `provide` / `lookup` / `*name`, lexically
+  registered paths, and the clean-namespace boundary.
 - [patterns/coordinate-components.md](./patterns/coordinate-components.md),
   [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md),
   [patterns/render-a-child-component.md](./patterns/render-a-child-component.md) —

package/skill/tutuca/core.md

@@ -381,6 +381,12 @@ native `Map`, and native `Set` stay native. Wrap nested component data with
 | `new Map()` | map | `draft.x.set(key, value)` |
 | `new Set()` | set | `draft.x.add(value)`, `draft.x.delete(value)` |
 
+**Every numeric default is a float, whole numbers included** — `count: 0` is a
+float field, not an int, because a JS literal can't say which one it means
+(`0.0` IS `0`). Ask for int explicitly when you want the truncation:
+`count: { type: "int", defaultValue: 0 }` turns a later `3.14` into `3`, while
+the plain `count: 0` keeps it.
+
 Fields do not generate setters or collection mutators. Define only the named
 handlers your view/API needs; the linter reports a field/method name collision.
 
@@ -915,7 +921,7 @@ storybook in your own page — see [storybook.md](./storybook.md).
 - [margaui.md](./margaui.md) — setting up MargaUI styling: install
   (CDN / npm / vendoring), theme CSS, and `compileClassesToStyleText`.
 - [semantics.md](./semantics.md) — runtime semantics: path steps, the
-  transaction lifecycle, dyn-var teleporting, and async key pinning
+  transaction lifecycle, located continuations, and async key pinning
   (`livePath`).
 - [testing.md](./testing.md) — `getTests` shape and the handler calling
   convention for tests.

package/skill/tutuca/messages-and-intents.md

@@ -409,7 +409,7 @@ rules are in [semantics.md](./semantics.md).
   blocks overview, and *Conventional Module Exports*.
 - [component-design.md](./component-design.md) — which channel to reach for when.
 - [semantics.md](./semantics.md) — the path/transaction model behind these
-  channels: path steps, the transaction lifecycle, teleporting, and the
+  channels: path steps, the transaction lifecycle, continuation frames, and the
   key-pinning rules `livePath` toggles.
 - [testing.md](./testing.md) — driving message and intent flows from tests.
 - [cli.md](./cli.md) — the full linter rule list, exit codes, and

package/skill/tutuca/patterns/README.md

@@ -26,7 +26,7 @@ task.
 ## Context & dynamic bindings
 
 - [Share state across the tree](share-state-across-the-tree.md) — `provide` / `lookup` and reading `*name`.
-- [Edit through a dynamic target](edit-through-a-dynamic-target.md) — render `*name` and teleport edits back to the owner.
+- [Edit through a dynamic target](edit-through-a-dynamic-target.md) — render `*name` and edit the owner's value in place.
 
 ## Composition
 

package/skill/tutuca/patterns/edit-through-a-dynamic-target.md

@@ -19,9 +19,14 @@ const Toolbar = component({
 });
 ```
 
-Because `*active` resolves to a real **path** (not a copied value), the event
-fired inside the rendered child is *teleported*: the mutation skips the
-intermediate components and lands on `Workspace.sheet`, so the owner and any
-other view of the same value update in lock-step. A `provide` can even point at
-a seq-access (`.items[.selectedKey]`) to expose "the selected item". This is
-the **edit** counterpart of the share-state-across-the-tree recipe.
+Because `*active` carries a real **path** alongside its value (not a copy),
+rendering it *resumes* there: the render site pushes `Workspace.sheet` as the
+active position, so an event fired inside the rendered child mutates
+`Workspace.sheet` itself, and the owner and any other view of the same value
+update in lock-step. Bubbling still returns to the `Toolbar` that wrote the
+`*active`, so an unhandled message keeps walking the visual ancestry.
+
+A `provide` can point at a seq-access (`.items[.selectedKey]`) to expose "the
+selected item", and a nested provider of the same name shadows an outer one for
+its own subtree. This is the **edit** counterpart of the
+share-state-across-the-tree recipe.

package/skill/tutuca/patterns/share-state-across-the-tree.md

@@ -19,7 +19,7 @@ const Producer = component({
   provide: { entries: ".items" },
 });
 
-// consumer — forwards to the producer's binding by "Component.name"
+// consumer — names what it WANTS, never who provides it
 const Consumer = component({
   name: "Selector",
   lookup: [{ name: "entries", default: ".items" }],
@@ -32,7 +32,22 @@ const Consumer = component({
 ```
 
 `provide` publishes a field under a name; a descendant's `lookup` resolves
-`*name` to the nearest matching producer, falling back to `default` when none
-is in scope. `*name` works wherever a `.field` does for iteration/rendering.
+`*name` to the nearest matching producer in the live render ancestry, falling
+back to `default` when none is above it. Several components may publish one
+name — the nearest rendered one wins. `*name` works wherever a `.field` does
+for iteration/rendering.
+
+For a value nothing in the tree should have to publish — a session, a theme —
+register it on the scope instead, as an absolute path from the state root:
+
+```js
+import { path } from "tutuca";
+
+app.registerComponents(comps, { paths: { theme: path().field("theme") } });
+```
+
+Consumers still declare `lookup: ["theme"]` and read `*theme`; a rendered
+provider of the same name still wins over it.
+
 This is the **read** side; to edit the producer's value through the dynamic,
 see the edit-through-a-dynamic-target recipe.

package/skill/tutuca/semantics.md

@@ -31,26 +31,29 @@ references* in [core.md](./core.md)). The step kinds:
 | `SeqStep`           | a sequence entry by **literal** key/index | `.items[2]`       |
 | `SeqAccessStep`     | a sequence entry whose key is **read from another field** | `.sheets[.selId]` |
 | `EachRenderItStep`  | an iterated `render-it` item       | `<x render-it>` per iter |
-| `DynStep` / `DynEachStep` | a dynamic-var (`*x`) render target — a teleport marker | `<x render="*x">` |
 | `BindStep` / `EachBindStep` | nothing — frame-only (carry scope binds, no addressing) | `@each`, `@enrich-with` |
 
 `SeqAccessStep` is the important one for async correctness: it stores the
 field *names* `seqField` and `keyField`, and resolves the key from the
 live data each time it runs — see *Key resolution & async races* below.
 
-### Two derived paths
+### A dispatch path is a stack of continuation frames
 
-The reconstructed path is transformed two ways depending on use:
+What reconstruction actually returns is a `DispatchPath`: a list of frames,
+each `{ base, items }`. Ordinary rendering extends the top frame's `items`;
+rendering a located binding (`<x render="*sel">`) pushes a NEW frame based
+at the value's own absolute path — see *Rendering with a resumed path*
+below. Two projections come off it:
 
-- **`compact()` → the dispatch path.** Drops frame-only steps, keeps one
-  step per crossed component (including `DynStep`s). `popStep()` over it
-  walks every component. Used to drive `ctx.send` / `ctx.intent` and to
-  locate handlers.
-- **`toTransactionPath()` → the transaction path.** Teleports every
-  `DynStep` (drops the steps interior to its producer..consumer span and
-  splices in the producer's own steps) so a mutation lands on the data's
-  real location. A path with no `DynStep` is returned unchanged. Used by
-  `lookup` / `setValue` to read and write state.
+- **`compact()` → the dispatch path.** Drops frame-only steps inside every
+  frame independently, keeping one step per crossed component. `popStep()`
+  over it walks every component, and at the top of a frame returns to the
+  visual caller. Used to drive `ctx.send` / `ctx.intent` and to locate
+  handlers.
+- **`toTransactionPath()` → the transaction path.** The ACTIVE frame alone:
+  its absolute base followed by its own steps, so a mutation lands on the
+  data's real location. The saved caller frames affect bubbling only. Used
+  by `lookup` / `setValue` to read and write state.
 
 ## Reconstructing a path from the DOM
 
@@ -111,21 +114,32 @@ The walk object is shared across hops on purpose: that is what makes the
 one-shot **per intent** rather than per hop, so a second `ctx.reply` — from this
 handler or one three hops up — finds the walk already ended.
 
-## Dynamic-var teleporting
+## Rendering with a resumed path
 
 A component rendered through `<x render="*sel">` *physically lives* at the
 producer that declared `provide: { sel: … }`, not under the consumer that
-wrote the render. The reconstructed dispatch path keeps every intermediate
-component (so a walk visits them), but `toTransactionPath()` teleports
-the `DynStep`: it pops the steps tagged with the marker's `interiorCids`
-and splices in the producer's own steps (`DynStep.teleportSteps()`). The
-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 `provide` value is a seq-access (`.sheets[.selId]`),
-the teleported steps include a `SeqAccessStep` — which is where async key
-races come from.
+wrote the render. A provider evaluates both halves of a lowercase binding:
+its value, and the absolute path of that value. A descendant retrieves the
+nearest pair and renders the value after pushing its path as a continuation
+frame; the frame's base is recorded in the DOM (`base` in the `§Comp§` meta,
+`data-rp` on a fragment-rooted body) so reconstruction can rebuild it.
+
+Consequently:
+
+- mutation uses the ACTIVE frame, so an event inside the resumed component
+  updates the provider's data, and the consumer's view of it updates in
+  lock-step;
+- bubbling reaches the top of that frame and pops directly back to the
+  visual caller, then continues through the caller's ancestry.
+
+There is no producer search, producer id, interior list, or path rewriting
+at dispatch. Nested providers therefore shadow by live render ancestry: the
+nearest one that actually rendered wins. Authoring view: *Resuming at the
+value's path* in [advanced.md](./advanced.md).
+
+When the producer's `provide` value is a seq-access (`.sheets[.selId]`), the
+frame's base ends in a `SeqAccessStep` — which is where async key races come
+from.
 
 ## Key resolution & async races
 
@@ -143,8 +157,9 @@ path — each `SeqAccessStep(seq, keyField)` becomes a literal
 `SeqStep(seq, resolvedKey)`. The pinned path is stored on the
 `IntentWalk`, so the answer updates the item that raised the intent
 regardless of later key changes. (Pinning runs on the transaction path,
-after teleporting, because the `SeqAccessStep` may have come from a
-`DynStep`.)
+because the `SeqAccessStep` may have come from a resumed frame's base. The
+answer still DISPATCHES at the raiser's position, frames and all; the pinned
+path only decides where its mutation lands.)
 
 **Opt out per intent with `livePath: true`:**
 
@@ -191,5 +206,5 @@ things per step kind:
 - [messages-and-intents.md](./messages-and-intents.md) — the dispatch **API**:
   addressed `send`-`receive` vs routed `intent`, `ctx.at`, `$unknown`,
   intent-handler registration, and the `livePath` option.
-- [advanced.md](./advanced.md) — dynamic bindings (`*x`) and the authoring
-  view of teleporting.
+- [advanced.md](./advanced.md) — dynamic bindings (`*x`), lexically
+  registered paths, and the authoring view of resuming at a value's path.