agent-feedback: marko@next install, custom element semantics and ctx.body

agent-feedback/items/2026-07-30-script-tag-run-order.md

@@ -10,3 +10,7 @@ site: docs/reference/core-tag.md › ## <script>
 The `<script>` section says the body "is executed first when the template has finished rendering and is mounted in the browser" and re-runs when a referenced tag variable changes, which leaves source order as the only ordering a reader can infer between two `<script>` tags. Marko compiles a `<script>` that reads a tag variable into that variable's own setup, so it first runs when the variable initializes, ahead of an earlier-in-source `<script>` that reads nothing. Given `<let/board=DEFAULT/>`, a first script that only assigns `board` from `localStorage`, and a second that reads `board` and writes it back, the second runs first with `DEFAULT` and overwrites the saved value before the restore reads it: the compiled dom output puts the persist effect inside `_let(...)` while the restore stays a separate `$setup__script`. The page's own `<script=remember/>` example already persists `input.collapsed` to `sessionStorage` without saying when it first fires, so the rule belongs there, stated positively: reading a tag variable ties the effect to that variable's initialization. The paired restore-and-persist idiom belongs under `## <lifecycle>`, whose `onMount`/`onUpdate` handlers already model "set up once, then follow the value".
 
 Check: `grep -n "finished rendering" docs/reference/core-tag.md` is the page's only ordering statement and `grep -rn "localStorage" docs/` returns nothing, so neither the rule nor the idiom is documented; the clobber reproduces in the local playground (`pnpm run dev`).
+
+Which reads count needs the same statement. A read anywhere in the body subscribes, including from a closure that runs long after the effect returned, while an assignment alone does not: a `<script>` registering `document.addEventListener("keydown", (e) => { if (e.key === "?") helpOpen = !helpOpen }, { signal: $signal })` compiles into `helpOpen`'s own `_let` signal, so every toggle aborts `$signal`, tears the listener down and registers a fresh one, whereas the same body writing `helpOpen = true` stays a one-time `$setup__script`. The qualification belongs on `docs/reference/language.md` › ### `$signal` too, which teaches this idiom with an empty listener body, the one variant that does not churn, and says `$signal` aborts when "The expression is invalidated" without saying what invalidates it. Scope the sentence to a read of a reactive tag variable rather than of any identifier, since marko `translator/util/references.ts` › `resolveReferencedBindingsInFunction` skips getter, hoisted and dom reads, so the `myButton()` element reference in the section's own example does not subscribe; and cross-link `## <lifecycle>`, whose `onMount` is the run-once tool for registering a listener that reads state.
+
+Check: in the marko checkout, `pnpm run compile -- -o dom -d` on `<let/helpOpen=false><script>document.addEventListener("keydown", (e) => { if (e.key === "?") helpOpen = !helpOpen; }, { signal: $signal });</script><div>${helpOpen}</div>` emits `_let("helpOpen/1", $scope => { _$signalReset($scope, 0); _text(...); $helpOpen__script($scope); })`, while the same body writing `helpOpen = true` leaves `$setup__script($scope)` in `$setup`. Mounted, three `?` presses take the read version's run counter from 1 to 4 and add three `document.addEventListener` calls; the write-only body and a `<lifecycle onMount>` rewrite stay at 1 with none.

agent-feedback/items/2026-08-20-compiler-api-docs.md

@@ -10,3 +10,7 @@ site: docs/guide/low-level-apis.md › ## Writing a Migrator
 `docs/guide/low-level-apis.md` is 379 bytes: one intro paragraph, then `## Writing a Migrator` and `## Writing a Translator` with nothing under either, and it is the only entry `public/llms.txt` offers for the compiler ("Advanced low-level APIs"). Nothing else on the site names the API those sections need. `grep -rniE 'compileSync|compileFile|@marko/compiler|babel-utils' docs/` matches one newsletter sentence, and the generated `/docs/reference-full.md` bundle contains none of it, so an agent asked to write a codemod, a migrator or a bundler integration reverse-engineers `@marko/compiler`'s `index.d.ts`, which exports `compile`, `compileSync`, `compileFile`, `compileFileSync`, `configure`, `getRuntimeEntryFiles` and a `taglib` namespace. The version relationship is unstated too: `marko@6.3.44` depends on `@marko/compiler@^5.42.2`, so a search for the installed compiler's documentation lands on the Marko 5 site, and no page says that pairing is expected. Fill the two sections against the `migrator` and `translator` hooks the taglib loader reads from `marko.json`, and give the compiler entry points a reference page indexed in `llms.txt`.
 
 Check: `grep -rniE 'compileSync|compileFile|@marko/compiler' docs/ | grep -v newsletter` returns nothing and `wc -c docs/guide/low-level-apis.md` prints 379; expect both sections to have bodies and the compiler entry points and their output modes to be documented somewhere under `docs/`.
+
+The `./register` subpath belongs in the same reference. `@marko/compiler/register` self-installs a `require.extensions[".marko"]` hook on require (`packages/compiler/src/register.cjs` › `register`, typed by `register.d.ts`, pinned by `compiler/test/register.test.js`) that compiles each template with `compileFileSync` and forces `modules: "cjs"`, so `require("./hello.marko").default.render(input)` renders a template from a plain Node process with no bundler, and an ESM entry bridges through `createRequire` because the hook does not serve `import("./hello.marko")`. It is the one bundler-free render path the site could describe: `docs/introduction/installation.md` › ## Manual Setup starts from "your preferred bundler", `docs/introduction/integrations.md` › Bundlers lists Vite, Webpack, Rollup and Lasso, and `docs/reference/template.md`'s Node `http.createServer` examples import `./template.marko` without saying what loads it. Document the hook, its CommonJS output and its `output`, `sourceMaps` and `extensions` options alongside the entry points.
+
+Check: `grep -rn -i 'compiler/register\|require.extensions\|node-require' docs public/llms.txt` exits 1. In a scratch dir with a package.json (the compiler resolves `marko/translator` from the nearest package root above `process.cwd()`, and without one the hook throws `Cannot find module 'marko/translator'`) and node_modules resolving marko 6.3.46 with @marko/compiler 5.42.3, with `hello.marko` = `<h1>Hello ${input.name}</h1>`, `node -e 'require("@marko/compiler/register")({output:"html",sourceMaps:false});require("./hello.marko").default.render({name:"Ada"}).then(h=>console.log(String(h)))'` prints `<h1>Hello Ada</h1>`, while `import "@marko/compiler/register"; await import("./hello.marko")` from an `.mjs` throws `ERR_UNKNOWN_FILE_EXTENSION` and the same file's `createRequire(import.meta.url)("./hello.marko").default.render({ name: "Ada" })` prints the same HTML.

agent-feedback/items/2026-08-28-browser-only-setup.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/introduction/installation.md › ## Manual Setup
+---
+
+# Document the browser-only setup (`marko({ linked: false })`, `index.html`, `Template.mount`) under Manual Setup
+
+`docs/introduction/installation.md` › ## Manual Setup walks through Vite plus `marko()` plus an express SSR server, and the browser-only alternative survives as a parenthetical on the "Add a server" step ("this can be disabled with the Marko plugin's `linked` option"). `linked` appears in one other place under `docs/`, the `docs/reference/lazy-loading.md` note that `linked: false` cannot code-split; `docs/introduction/integrations.md` covers bundlers with no browser build; and `docs/reference/template.md` › ## `Template.mount(input, node, position?)` documents the API, warning that it is "primarily intended to be used in exclusively client rendered environments", without tying it to a build setup. Following Manual Setup and dropping the server file without also passing `linked: false` fails the build with `[marko-vite:pre] You must run the "ssr" build before the "browser" build.`, an error the docs do not explain. Add a Manual Setup subsection assembling the three files a client-only app needs, a `vite.config.ts` with `marko({ linked: false })`, an `index.html` holding a mount node and a module script, and an entry module calling `Template.mount`; carry the lazy-loading note that `linked: false` cannot code-split and link the `Template.mount` section. The site already runs this mode itself in the playground (`src/util/workspace.ts`).
+
+Check: `grep -rn '\blinked\b' docs` prints only `docs/introduction/installation.md:88` (the parenthetical) and `docs/reference/lazy-loading.md:180`, and `grep -rni 'client-only\|SPA' docs` prints nothing. In a scratch dir with marko 6.3.46, @marko/vite 6.1.11 and vite 8.2.2, with `vite.config.ts` = `export default defineConfig({ plugins: [marko({ linked: false })] })`, `index.html` = `<div id="app"></div><script type="module" src="/src/main.ts"></script>`, `src/app.marko` = `<let/count=input.start ?? 0><button onClick() { count++ }>Clicked ${count}</button>` and `src/main.ts` = `App.mount({ start: 3 }, document.getElementById("app")!)`, `npx vite build` prints `✓ 7 modules transformed` plus `dist/assets/index-*.js 4.76 kB` and `npx vite preview` serves a page whose button goes from `Clicked 3` to `Clicked 4` with no server file. The same project with plain `marko()` fails `npx vite build` with `You must run the "ssr" build before the "browser" build.`

agent-feedback/items/2026-08-28-catch-scope-render-errors.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/core-tag.md › ### `@catch`
+---
+
+# Scope `@catch` to errors thrown while rendering the `<try>` content
+
+`docs/reference/core-tag.md` › ### `@catch` says "When a runtime error occurs in the content of the `<try>` or its `@placeholder` attribute tag, the content is replaced", which a reader takes to include the event handlers and effects written in that content. The runtime scopes it to the render path: marko `dom/catch.feat.ts` wraps `runRender` alone, with a comment recording that an error thrown from a `<script>` or `<lifecycle>` body deliberately escapes the flush, and `dom/event.ts` › `handleDelegated` invokes handlers bare. Clicking a `<button onClick() { throw new Error("event boom") }>` inside a `<try>` leaves `@catch` unrendered, leaves the sibling content in place and surfaces one uncaught page error; a `<script>` that throws behaves the same on its first mount and on an update, while a throw during render, initial or on update, and a rejected `<await>` are both caught. Restate the section as the positive rule, that `@catch` covers errors thrown while rendering the content including a rejected `<await>`, and point handler and effect errors at the ordinary window error path.
+
+Check: mount `<try><widget mode=mode/><@catch|err|><div class="caught">caught: ${err.message}</div></@catch></try>`, where widget is `<const/status=health(input.mode)><div class="status">Status: ${status}</div><button onClick() { throw new Error("event boom") }>Poke</button>` and `health` throws for `mode === "render"`. Clicking Poke gives `{ caughtCount: 0, status: "Status: healthy", pageErrors: ["event boom"] }`; flipping `mode` to `"render"` gives `{ caughtCount: 1, caughtText: "caught: render boom", statusCount: 0 }`; a `<try>`-wrapped child whose `<script>` throws gives `{ caughtCount: 0, errs: ["effect boom"] }` with its sibling content still rendered; `<try><await|v|=Promise.reject(new Error("await boom"))>` renders `@catch` with an empty `pageErrors`.

agent-feedback/items/2026-08-28-controllable-counter-optional-count.md

@@ -0,0 +1,12 @@
+---
+type: bug
+impact: med
+effort: low
+site: docs/explanation/controllable-components.md › ### Controllable `<let>`
+---
+
+# Give the controllable `<counter>` example an optional `count` and a `?? 0` default
+
+The counter.marko block under `docs/explanation/controllable-components.md` › ### Controllable `<let>` declares `count: number` as required and binds `<let/count=input.count valueChange=input.countChange>`, while the parent block on the same page renders a bare `<counter/>` labelled "This one holds its own state". `mtc` rejects that usage with TS2345 (`Property 'count' is missing in type '{}' but required in type 'Input'`), and silencing the error does not rescue it: `input.count` is undefined, so the server renders `Count: ` where the page's own bullet promises the behavior of its first example, and the first click makes it NaN. The shape that keeps the uncontrolled, seeded and controlled usages all valid is `count?: number` with `<let/count=input.count ?? 0 valueChange=input.countChange>`, which type-checks for `<counter/>`, `<counter count=5/>`, `<counter count=parentCount countChange(count) {...}/>` and `<counter count:=parentCount/>`. Note in the section that the explicit handler form is required once a default is involved, since `<let/count:=input.count ?? 0>` is a compile error; `docs/reference/core-tag.md` › ### Controllable Let is self-consistent and needs no change.
+
+Check: copy the two blocks under ### Controllable `<let>` verbatim into a project with `@marko/type-check` 3.2.0 as `src/tags/counter.marko` and `src/parent.marko` and run `npx mtc`: it reports `error TS2345` on `<counter/>` in `src/parent.marko` with `Property 'count' is missing in type '{}' but required in type 'Input'`, unchanged with `strict: false`. In the marko checkout, `pnpm run compile -- -o html -d <parent.marko>` and rendering the result gives `<button>Count: <!>0<!--...--></button><button>Count: <!><!--...--></button>`, the second button carrying no number. With `count?: number` and `?? 0`, `npx mtc` reports nothing for the four usages above, while `<let/count:=input.count ?? 0>` fails `pnpm run compile -- -o dom -d` with "Attributes may only be bound to identifiers or member expressions".

agent-feedback/items/2026-08-28-custom-element-attributes-setattribute.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/typescript.md › ### Registering a new native tag (e.g. for custom elements)
+---
+
+# State that attributes on a registered custom element are written with `setAttribute`, never as properties
+
+Every attribute on a `marko.json`-registered custom element goes through marko `packages/runtime-tags/src/dom/dom.ts` › `_attr`, which is `setAttribute(element, name, normalizeAttrValue(value))` with no `name in element` or `customElements.get` branch, and the translator special-cases controllable properties for input, select, textarea, details and dialog alone, so a same-named property setter on the element class is never called. The example under `docs/reference/typescript.md` › ### Registering a new native tag (e.g. for custom elements) reads the other way: it declares `class RangeSliderElement extends HTMLElement { value = 0 }` beside `<range-slider/sliderEl value=threshold step=5 .../>`, so the class field holds its initial value while `getAttribute("value")` tracks the binding, and the class declares no `observedAttributes`, so as printed nothing in it picks the attribute up. State the positive rule on that section and on `docs/reference/native-tag.md`, and show the element-reference idiom for writing a property, `<x-datepicker/picker value=newDate/>` with `picker().value = newDate` from a `<script>` body. `docs/guide/library-integration.md` › ### Consuming in Marko and ### Using Marko in a Web Component are empty headings and are the natural second home for it.
+
+Check: `sed -n '/export function _attr(/,/^}/p' packages/runtime-tags/src/dom/dom.ts` in the marko checkout shows the `setAttribute` call as the whole body. In a `linked: false` Vite page with `marko.json` = `{"<x-datepicker>":{"html":true}}` and an `x-datepicker` class defining `static get observedAttributes(){return["value"]}` plus a counting `set value(v)` and `attributeChangedCallback`, rendering `<let/newDate="2025-06-15"/><x-datepicker value=newDate/>` and then reassigning `newDate` reports `{ propertySets: 0, attributeSets: 2, setterCalls: [] }` with `outerHTML` `<x-datepicker value="2026-01-01"></x-datepicker>`. Rendering the typescript.md example with its class registered leaves `el.value` at its class-field value while `el.getAttribute("value")` goes `20` then `42`.

agent-feedback/items/2026-08-28-custom-event-handler-typing.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: docs/reference/typescript.md › ### Registering a new native tag (e.g. for custom elements)
+---
+
+# Show how to declare a custom element's `CustomEvent` handler in the native tag registration
+
+`AttrEventHandler` (marko `packages/runtime-tags/tags-html.d.ts`) brands a handler's event as `Event` intersected with a `currentTarget` string literal carrying the delegation guidance, deliberate since #3817. Any `currentTarget` brand makes that type non-comparable with `CustomEvent<T>`, so a handler inherited from `Marko.HTMLAttributes` cannot reach a custom element's `detail` the ordinary way: `(e as CustomEvent<string>).detail` is TS2352, annotating the parameter is TS2322, and re-declaring `onChange` in an interface that extends `Marko.HTMLAttributes<T>` is TS2430; only a widening double cast compiles. The supported route is to declare the event on the attributes interface, which for a custom name needs nothing extra (`interface XAttrs extends Marko.HTMLAttributes<T> { onDatepickerChange?: (e: CustomEvent<string>, target: T) => void }`) and for a name colliding with a standard DOM event needs `extends Omit<Marko.HTMLAttributes<T>, "onChange">`. Add both spellings, and the collision rule, to the registration section, which today shows `onChange(evt, target) { target.value }` alone.
+
+Check: in a project with `@marko/type-check` 3.2.0 and `marko.json` `{ "<x-datepicker>": { "html": true } }`, `npx mtc -p tsconfig.json -d condensed` over `<div onChange(e) { const d: string = (e as CustomEvent<string>).detail }/>` reports `error TS2352 Conversion of type 'Event & { currentTarget: "Marko delegates events, ..."; }' to type 'CustomEvent<string>' may be a mistake`, and over `<div onChange(e: CustomEvent<string>) { console.log(e.detail) }/>` reports `error TS2322 Type '(e: CustomEvent<string>) => void' is not assignable to type 'AttrEventHandler<Event, HTMLDivElement>'`, while `e as Event as CustomEvent<string>` and `e as unknown as CustomEvent<string>` report nothing. Registering `interface DatepickerAttributes extends Omit<Marko.HTMLAttributes<DatepickerElement>, "onChange"> { value?: string; onChange?: (e: CustomEvent<string>, target: DatepickerElement) => void }` as `Marko.NativeTags["x-datepicker"]` leaves `<x-datepicker value=picked onChange(e, target) { const d: string = e.detail } onClick(e, target) { console.log(e.clientX, target.value) }/>` clean, while `e.clientX` inside `onChange` still reports TS2339.