marko 6.3.31 → 6.3.33

package/cheatsheet.md

@@ -4,18 +4,20 @@ Marko 6 = HTML superset. NOT JSX, NOT old Marko 4/5. `.marko` files are componen
 
 ## Golden rules
 
-1. Text interpolation: `${expr}` inside tag bodies. A bare line like `Welcome aboard` at the root of the template parses as a TAG named `Welcome` (concise mode) and fails to compile. Wrap it in an element (`<p>Welcome aboard</p>`) or prefix the line with `-- ` to mark it as text (`-- Welcome ${name}` works at the top level). Attributes take raw JS after `=` with NO braces/quotes needed: `<div title=user.name data-n=1 + 1>` (parenthesize if the value contains `>`).
-2. State: `<let/name=initial>` (slash then var name!). Update by plain assignment in an event handler: `count++`, `text = "hi"`. No setState, no hooks.
-3. Derived values: `<const/total=items.length * price>` — auto-recomputes. Never use an effect to derive state. Updates batch: mid-handler a reassigned `<let>` reads current but its derived `<const>` reads stale — recompute from the `<let>`.
-4. NEVER mutate state in place. `items.push(x)` will NOT update the UI. Always reassign:
+1. Text interpolation: `${expr}` inside tag bodies. A bare line at the template root parses as a TAG (concise mode): `Welcome aboard` fails to compile, but `p is a tag` compiles SILENTLY to `<p is a tag></p>` — any line starting with a real tag name loses its words to attributes. Wrap text in an element (`<p>Welcome aboard</p>`) or prefix the line with `--` and a space (`-- Welcome ${name}`). Attributes take raw JS after `=` with NO braces/quotes: `<div title=user.name data-n=1 + 1>`.
+2. A top-level `>` in an attribute value **ENDS THE TAG**: the value truncates there, the rest of the line becomes body text, and it usually still compiles clean. `<button disabled=count>=8 onClick() {…}>More</button>` is `disabled=count` plus the TEXT `=8 onClick() {…}>`, so the handler never binds; spaces don't help (`disabled=a > b` closes too). Parenthesize the value — `disabled=(count >= 8)`, `hidden=(a > b)`, and for a TS type argument `<let/s=(new Set<string>())>`. Do NOT move the type onto the tag variable instead: `<let/s:Set<string>=new Set()>` compiles but fails type-check with TS2322 (the annotation does not flow into the initializer). A `>` nested inside `(…)`/`{…}`/`[…]` is safe (`class={ big: n > 1 }`, `of=list.filter(x => x > 1)`), but an arrow BODY is not nested: `<const/f=(a, b) => a > b>` truncates to `(a, b) => a`. `<` never closes a tag (`disabled=count<=1` is fine).
+3. State: `<let/name=initial>` (slash then var name!). Update by plain assignment in an event handler: `count++`, `text = "hi"`. No setState, no hooks.
+4. Derived values: `<const/total=items.length * price>` — auto-recomputes. Never use an effect to derive state. `<let>` is deliberately different: its value is an INITIAL value, so `<let/draft=input.text>` seeds from a reactive value and then de-syncs — that de-sync is the point of an editable copy. So pick by intent: recomputes → `<const>`, seeds then diverges → `<let>`. A `<let>` you never assign is just a frozen `<const>`. Updates batch: mid-handler a reassigned `<let>` reads current but its derived `<const>` reads stale — recompute from the `<let>`.
+5. NEVER mutate state in place. `items.push(x)` will NOT update the UI. Always reassign:
    - add: `items = items.concat(x)`
    - remove: `items = items.toSpliced(i, 1)`
    - update: `items = items.toSpliced(i, 1, { ...item, done: true })`
    - object: `user = { ...user, name }`
-5. Events: method shorthand `onClick() { ... }` or `onClick=fn`. Handler gets the DOM event: `onSubmit(e) { e.preventDefault(); save() }`. Don't sync input values through `onInput`/`onChange` listeners — that's what change handlers (next rule) are for, and they make the data's owner explicit.
-6. Native inputs are UNCONTROLLED by default: `value=` only sets the initial value. Adding the matching `*Change` handler is what makes them controlled — `valueChange` on `<input>`/`<textarea>`/`<select>`, `checkedChange` on checkboxes/radios, `openChange` on `<details>`/`<dialog>`. `value:=text` is the shorthand for `value=text valueChange(v) { text = v }`. (`<textarea value:=text/>` — value attribute, not body.)
-7. Transform in the handler when needed — number inputs give STRINGS: `<input type="number" value=n valueChange(v) { n = +v }>`, or `value:parseFloat:=n`.
-8. Radio/checkbox groups: `checkedValue:=picked` on each input (shared var, distinct `value=`) — the match is checked; array var for multi-checkbox. Dropdown: `<select value:=picked>`.
+6. Events: method shorthand `onClick() { ... }` or `onClick=fn`. Handler gets the DOM event: `onSubmit(e) { e.preventDefault(); save() }`. Don't sync input values through `onInput`/`onChange` — that's what the change handlers below are for.
+7. Native inputs are UNCONTROLLED by default: `value=` only sets the initial value. Adding the matching `*Change` handler is what makes them controlled — `valueChange` on `<input>`/`<textarea>`/`<select>`, `checkedChange` on checkboxes/radios, `openChange` on `<details>`/`<dialog>`. `value:=text` is the shorthand for `value=text valueChange(v) { text = v }`. (`<textarea value:=text/>` — value attribute, not body.)
+8. Transform in the handler when needed — number inputs give STRINGS: `<input type="number" value=n valueChange(v) { n = +v }>`, or `value:parseFloat:=n`.
+9. Radio/checkbox groups: `checkedValue:=picked` on each input (shared var, distinct `value=`) — the match is checked; array var for multi-checkbox. Dropdown: `<select value:=picked>`.
+10. Module-level values and helpers need `static`: `static const LIMIT = 10`, `static function fmt(n) {…}`. Without it `function fmt(n) {` parses as a TAG — ``Unable to find entry point for custom tag `<function>` ``, an error that never says `static`. Prefer it to `<const>` for anything that never changes: `<const/LIMIT=10>` emits a per-instance signal plus a `$setup` call.
 
 ## Canonical component (copy this shape)
 
@@ -61,7 +63,7 @@ Marko 6 = HTML superset. NOT JSX, NOT old Marko 4/5. `.marko` files are componen
 <else> C </else>
 
 <for|item, index| of=list by="id"> ${item.name} </for>   // by keys the loop (no key= attr!)
-<for|city| of=cities by=(city) => city> ${city} </for>    // primitives: by takes a FUNCTION — by=city would be an undefined variable (the loop param is not in scope in by=)
+<for|city| of=cities by=(city) => city> ${city} </for>    // primitives: by takes a FUNCTION — the loop param is not in scope in by=, so by=city is an undefined variable
 <for|i| from=0 until=5> ${i} </for>                       // 0..4
 
 <show=open> stays mounted, keeps state (form drafts) when hidden </show>
@@ -84,14 +86,29 @@ import { getUser } from "../data.js";
 </try>
 ```
 
-`@placeholder`/`@catch` go on `<try>`, never on `<await>`. On the server this streams (placeholder flushes first, content follows). It works in the browser too: hand `<await>` a new promise (e.g. a `<const>` derived from state) and it shows the placeholder again, then the new result. `@catch` can't recover in place — usually it redirects (a `<script>` setting `location`) for a full reload, otherwise re-render the `<try>` (bump a key on a wrapping `<for>`).
+`@placeholder`/`@catch` go on `<try>`, never on `<await>`. On the server this streams (placeholder flushes first, content follows). It works in the browser too: hand `<await>` a new promise (e.g. a `<const>` derived from state) and it shows the placeholder again, then the new result. `@catch` can't recover in place: redirect (a `<script>` setting `location`), or re-render the `<try>` by bumping a key on a wrapping `<for>`.
 
 Don't fetch while rendering: start data loads early, pass the PROMISE through the template, and `<await>` it where the data is rendered. Fetching inside each component that renders the data serializes the requests (waterfalls). Under @marko/run, load in the route handler — `return next({ user: getUser() })`, no await — and render with `<await|user|=$global.data.user>`.
 
 ## Components
 
 - File `src/tags/product-card.marko` is auto-discovered as `<product-card>` from any template (no import needed). Attributes arrive as `input`: `${input.title}`.
-- Body content passed by the parent renders with `<${input.content}/>`.
+- Body content renders where the child places `<${input.content}/>`, and the child can hand it values — `<${input.content}(x, y)/>` in the child, `<my-tag|count, total|>${count}</my-tag>` in the parent. Placement is the child's: put it inside a `<for>` and the body appears once per item, each with its own values (`<for|...args| to=input.to><${input.content}(...args)/></>`). Those values exist ONLY inside that body.
+- `<return=value>` publishes ONE value into the PARENT's scope, named by a tag variable; from there it is an ordinary value in that template. A native tag variable's value is itself a function returning the element, so `<div/el>` is read as `el()`. So: body parameters when the value belongs to the nested markup, including one set per item where the child loops; a tag variable when the parent needs one value outside the body. A tag var on a child that never returns is `undefined`.
+
+```marko
+/* src/tags/toggle-section.marko */
+<let/open=input.startExpanded ?? false>
+<button onClick() { open = !open }>${input.title}</button>
+<if=open><div><${input.content}/></div></if>
+<return=open>
+
+/* parent */
+<toggle-section/aOpen title="A" startExpanded=true>one</toggle-section>
+<toggle-section/bOpen title="B">two</toggle-section>
+<const/openCount=(aOpen ? 1 : 0) + (bOpen ? 1 : 0)>   // recomputes on every toggle
+```
+
 - Named sections use attribute tags:
 
 ```marko
@@ -115,9 +132,9 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 
 ## Sharing data (`$global`)
 
-- No provider/consumer context API. Prop-drill through `input`, or read request-scoped `$global` from any template with no threading: `${$global.messages.title}`.
+- Read request-scoped `$global` from any template, no threading: `${$global.messages.title}`. Otherwise prop-drill through `input` — there is no provider/consumer context API.
 - Populate at the render call: `template.render({ $global: { messages } })`. Under @marko/run a middleware's `return next({ messages })` merges into `$global.data`.
-- `$global` is NOT serialized by default, so client-reactive reads (`<const>`, `<let>` init, handlers) throw after resume even though SSR looked fine. Allow-list first: `$global.serializedGlobals = { messages: true }` (@marko/run ships only `params`/`url`; add `context.serializedGlobals.data = true`). SSR-only markup needs no opt-in.
+- `$global` is NOT serialized to the client by default. Mark any key the BROWSER itself evaluates — an event handler, a `<script>`, markup the browser (re)creates, a `<const>` that recomputes from state: `$global.serializedGlobals = { messages: true }` at the render call (under @marko/run, `context.serializedGlobals.data = true`; it ships `params`/`url` already). What the server already rendered needs no opt-in.
 
 ## Client-side effects (rare — prefer state/const)
 
@@ -125,7 +142,7 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 <div/el/>
 <script>
   // Browser-only. Runs after mount and re-runs when referenced state changes.
-  el().focus();                                  // element refs are getter FUNCTIONS
+  el().focus();                                  // NATIVE element refs are getter FUNCTIONS
   const id = setInterval(tick, 1000);
   $signal.onabort = () => clearInterval(id);     // cleanup
 </script>
@@ -173,28 +190,32 @@ export interface Input<T> {
 
 | Wrong (React/Vue/Marko5 habit)                              | Right                                                                                |
 | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `disabled=n>=8` / `hidden=a > b` (top-level `>` in a value) | `disabled=(n >= 8)` — a bare `>` closes the tag; the rest of the line becomes text   |
+| `<let/s=new Set<string>()>` (type argument in a value)      | `<let/s=(new Set<string>())>` — a tag-var annotation fails type-check                |
 | `{expr}` in markup, `className`, `key=`, `style={{...}}`    | `${expr}`, `class`, `by=` on `<for>`, `style={...}`                                  |
 | `onClick={() => ...}` / `@click` / `on-click("name")`       | `onClick() { ... }`                                                                  |
 | `const [x, setX] = useState()` / `state` / `class {}` block | `<let/x=0>` then `x = 1`                                                             |
 | `$ const y = x * 2;` (scriptlets are removed)               | `<const/y=x * 2>`                                                                    |
+| `<let/n=a + b>` when you want it to recompute               | `<const/n=a + b>` — `<let>` seeds an initial value, then de-syncs by design          |
+| `function fmt(n) {…}` / `const LIMIT = 10` at module level  | `static function fmt(n) {…}` / `static const LIMIT = 10`                             |
 | `<let x=0>`                                                 | `<let/x=0>`                                                                          |
 | `<if(cond)>`                                                | `<if=cond>`                                                                          |
 | `items.push(x)`                                             | `items = items.concat(x)`                                                            |
-| `input.renderBody`                                          | `input.content`                                                                      |
+| `input.renderBody` (renders nothing, no error)              | `input.content`                                                                      |
 | `<await>` with `@placeholder`/`@catch`                      | wrap in `<try>`                                                                      |
 | `el.focus()` on a ref                                       | `el().focus()` inside `<script>`/handler                                             |
 | `input.tab[0]` / `input.tab.length`                         | `[...input.tab ?? []]` first (attr tags are iterables, not arrays)                   |
-| bare text on its own line at template root                  | wrap in an element (`<p>...`), or prefix the line with `-- `                         |
+| bare text on its own line at template root                  | wrap in an element (`<p>...`), or prefix the line with `--` and a space              |
 | `by=item` using the loop variable                           | `by="propName"` or `by=(item) => key` — `by=` is evaluated outside the loop          |
 | `onInput(e) { q = e.target.value }` to sync an input        | `value:=q` — the change handler owns the value                                       |
 | fetching inside the component that renders the data         | start the promise early (route handler / top of template), pass it down to `<await>` |
 | `style={ backgroundColor: c }` (camelCase keys)             | `style={ "background-color": c }` (kebab-case)                                       |
 | `this.querySelector` / `this.getRootNode()` in `<script>`   | element ref getter: `<div/el>` then `el()` (there is no `this`)                      |
-| `<div/my-el>` / `<input/card-input>` (hyphen in tag var)    | valid JS identifier: `<div/myEl>`                                                    |
+| `<div/my-el>` / `<input/card-input>` (hyphen in tag var)    | valid JS identifier: `<div/myEl>` (the error won't name the hyphen)                  |
 | hand-rolled radios `checked=x checkedChange(v){…}`          | `checkedValue:=picked` on each radio (shared var, distinct `value=`)                 |
 | hand-rolled `IntersectionObserver` to defer a widget's JS   | `import W from "<w>" with { load: "visible#sel" }`                                   |
 | imperative lib wired through `<script>` mount + cleanup     | `<lifecycle onMount/onUpdate/onDestroy>` (keeps `this` across all three)             |
 | `createContext`/provider to share data                      | `input` (prop drilling) or request-scoped `$global`                                  |
-| `$global.x` in client-reactive code, not allow-listed       | `$global.serializedGlobals = { x: true }` first, or it throws after resume           |
+| `$global.x` in client-reactive code, not allow-listed       | `$global.serializedGlobals = { x: true }` first — otherwise the read is `undefined`  |
 | hand-namespaced global classes (`.my-card-title`)           | `<style/styles>` + `class=styles.card` (scoped CSS modules)                          |
 | `tsc --noEmit` to type check templates                      | `mtc` — `tsc` skips `.marko` files and exits 0                                       |

package/dist/common/helpers.d.ts

@@ -13,3 +13,5 @@ export declare function isNotVoid(value: unknown): boolean;
 export declare function isPromise(value: unknown): value is Promise<unknown>;
 export declare function normalizeDynamicRenderer<Renderer>(value: any): Renderer | string | undefined;
 export declare const decodeAccessor: (num: number) => string;
+export declare let branchesEnabled: undefined | 1;
+export declare function withBranches<T>(runtime?: T): T;

package/dist/debug/dom/catch.feat.js

@@ -0,0 +1,38 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+//#region src/dom/catch.feat.ts
+const handlePendingTry = (fn, scope, branch) => {
+	while (branch) {
+		if (branch["#AwaitCounter"]?.i) return (branch[require_control_flow.PendingEffects] ||= []).push(fn, scope);
+		branch = branch[require_control_flow.ParentBranch];
+	}
+};
+require_control_flow.installCatch((runEffects) => (effects, checkPending = require_control_flow.placeholderShown.has(effects)) => {
+	if (checkPending || require_control_flow.caughtError.has(effects)) {
+		let i = 0;
+		let fn;
+		let scope;
+		let branch;
+		for (; i < effects.length;) {
+			fn = effects[i++];
+			scope = effects[i++];
+			if ((branch = scope["#ClosestBranch"])?.["#Gen"] !== 0 && !(checkPending && handlePendingTry(fn, scope, branch))) fn(scope);
+		}
+	} else runEffects(effects);
+}, (runRender) => (render) => {
+	try {
+		let branch = render[require_control_flow.Scope][require_control_flow.ClosestBranch];
+		while (branch) {
+			if (branch["#PendingRenders"]) {
+				render[require_control_flow.Pending] = 1;
+				return branch[require_control_flow.PendingRenders].push(render);
+			}
+			branch = branch[require_control_flow.ParentBranch];
+		}
+		render[require_control_flow.Pending] = 0;
+		runRender(render);
+	} catch (error) {
+		require_control_flow.renderCatch(render[require_control_flow.Scope], error);
+	}
+});
+//#endregion

package/dist/debug/dom/catch.feat.mjs

@@ -0,0 +1,37 @@
+import { Cn as PendingRenders, Jt as caughtError, Sn as PendingEffects, Xt as placeholderShown, Yt as installCatch, gn as ClosestBranch, h as renderCatch, mn as Scope, pn as Pending, xn as ParentBranch } from "../dom-BJ93mcSe.mjs";
+//#region src/dom/catch.feat.ts
+const handlePendingTry = (fn, scope, branch) => {
+	while (branch) {
+		if (branch["#AwaitCounter"]?.i) return (branch[PendingEffects] ||= []).push(fn, scope);
+		branch = branch[ParentBranch];
+	}
+};
+installCatch((runEffects) => (effects, checkPending = placeholderShown.has(effects)) => {
+	if (checkPending || caughtError.has(effects)) {
+		let i = 0;
+		let fn;
+		let scope;
+		let branch;
+		for (; i < effects.length;) {
+			fn = effects[i++];
+			scope = effects[i++];
+			if ((branch = scope["#ClosestBranch"])?.["#Gen"] !== 0 && !(checkPending && handlePendingTry(fn, scope, branch))) fn(scope);
+		}
+	} else runEffects(effects);
+}, (runRender) => (render) => {
+	try {
+		let branch = render[Scope][ClosestBranch];
+		while (branch) {
+			if (branch["#PendingRenders"]) {
+				render[Pending] = 1;
+				return branch[PendingRenders].push(render);
+			}
+			branch = branch[ParentBranch];
+		}
+		render[Pending] = 0;
+		runRender(render);
+	} catch (error) {
+		renderCatch(render[Scope], error);
+	}
+});
+//#endregion

package/dist/debug/dom/controllable-input.feat.js

@@ -0,0 +1,7 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+//#region src/dom/controllable-input.feat.ts
+require_control_flow.controllableScripts[0] = require_control_flow._attr_input_checked_script;
+require_control_flow.controllableScripts[1] = require_control_flow._attr_input_checkedValue_script;
+require_control_flow.controllableScripts[2] = require_control_flow._attr_input_value_script;
+//#endregion

package/dist/debug/dom/controllable-input.feat.mjs

@@ -0,0 +1,6 @@
+import { R as controllableScripts, S as _attr_input_checkedValue_script, k as _attr_input_value_script, w as _attr_input_checked_script } from "../dom-BJ93mcSe.mjs";
+//#region src/dom/controllable-input.feat.ts
+controllableScripts[0] = _attr_input_checked_script;
+controllableScripts[1] = _attr_input_checkedValue_script;
+controllableScripts[2] = _attr_input_value_script;
+//#endregion

package/dist/debug/dom/controllable-open.feat.js

@@ -0,0 +1,5 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+//#region src/dom/controllable-open.feat.ts
+require_control_flow.controllableScripts[4] = require_control_flow._attr_details_or_dialog_open_script;
+//#endregion

package/dist/debug/dom/controllable-open.feat.mjs

@@ -0,0 +1,4 @@
+import { R as controllableScripts, v as _attr_details_or_dialog_open_script } from "../dom-BJ93mcSe.mjs";
+//#region src/dom/controllable-open.feat.ts
+controllableScripts[4] = _attr_details_or_dialog_open_script;
+//#endregion

package/dist/debug/dom/controllable-select.feat.js

@@ -0,0 +1,5 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+//#region src/dom/controllable-select.feat.ts
+require_control_flow.controllableScripts[3] = require_control_flow._attr_select_value_script;
+//#endregion

package/dist/debug/dom/controllable-select.feat.mjs

@@ -0,0 +1,4 @@
+import { M as _attr_select_value_script, R as controllableScripts } from "../dom-BJ93mcSe.mjs";
+//#region src/dom/controllable-select.feat.ts
+controllableScripts[3] = _attr_select_value_script;
+//#endregion

package/dist/debug/dom/controllable-textarea.feat.js

@@ -0,0 +1,5 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+//#region src/dom/controllable-textarea.feat.ts
+require_control_flow.controllableScripts[2] = require_control_flow._attr_input_value_script;
+//#endregion

package/dist/debug/dom/controllable-textarea.feat.mjs

@@ -0,0 +1,4 @@
+import { R as controllableScripts, k as _attr_input_value_script } from "../dom-BJ93mcSe.mjs";
+//#region src/dom/controllable-textarea.feat.ts
+controllableScripts[2] = _attr_input_value_script;
+//#endregion

package/dist/debug/dom/controllable.feat.js

@@ -0,0 +1,11 @@
+"use strict";
+const require_control_flow = require("../dom-CiFITSPN.js");
+require("./controllable-input.feat.js");
+require("./controllable-open.feat.js");
+require("./controllable-select.feat.js");
+//#region src/dom/controllable.feat.ts
+require_control_flow.controllableRenders.INPUT = require_control_flow._controllable_input;
+require_control_flow.controllableRenders.TEXTAREA = require_control_flow._controllable_textarea;
+require_control_flow.controllableRenders.SELECT = require_control_flow._controllable_select;
+require_control_flow.controllableRenders.DETAILS = require_control_flow.controllableRenders.DIALOG = require_control_flow._controllable_open;
+//#endregion

package/dist/debug/dom/controllable.feat.mjs

@@ -0,0 +1,10 @@
+import { F as _controllable_select, I as _controllable_textarea, L as controllableRenders, N as _controllable_input, P as _controllable_open } from "../dom-BJ93mcSe.mjs";
+import "./controllable-input.feat.mjs";
+import "./controllable-open.feat.mjs";
+import "./controllable-select.feat.mjs";
+//#region src/dom/controllable.feat.ts
+controllableRenders.INPUT = _controllable_input;
+controllableRenders.TEXTAREA = _controllable_textarea;
+controllableRenders.SELECT = _controllable_select;
+controllableRenders.DETAILS = controllableRenders.DIALOG = _controllable_open;
+//#endregion