@marko/runtime-tags 6.3.5 → 6.3.7

package/cheatsheet.md

@@ -14,7 +14,8 @@ Marko 6 = HTML superset. NOT JSX, NOT old Marko 4/5. `.marko` files are componen
    - 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. Write the change handler yourself when updates need transforming — number inputs give STRINGS: `<input type="number" value=n valueChange(v) { n = +v }>`.
+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>`.
 
 ## Canonical component (copy this shape)
 
@@ -109,7 +110,8 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 
 - Repeated attr tags (many `<@tab ...>`) arrive as the SINGULAR prop `input.tab`, which is iterable but NOT an array: `input.tab[i]` and `input.tab.length` are undefined. To index or count, spread first: `<const/tabs=[...input.tab ?? []]>` then `tabs[active]`/`tabs.length`. Looping directly is fine: `<for|tab| of=input.tab>`.
 - Conditional attrs: `false`/`null` attrs are omitted from HTML. `aria-selected` etc. want strings: `aria-selected=(i === active && "true")`.
-- `class=` / `style=` accept strings, objects, arrays: `class=["btn", { active }]`, `style={ color }` (single braces).
+- `class=` / `style=` accept strings, objects, arrays: `class=["btn", { active }]`, `style={ color }` (single braces). `style=` keys are kebab-case CSS names (`{ "background-color": c }`), not camelCase.
+- `<id/x>` mints a collision-free id for label/input wiring (`<label for=x>`/`<input id=x>`) — don't hardcode ids in reusable tags; `<id/x=input.id>` reuses a caller's.
 
 ## Client-side effects (rare — prefer state/const)
 
@@ -125,6 +127,26 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 
 `<style>` = real CSS, extracted & global. `<script>` = reactive effect, NOT an HTML script tag.
 
+Imperative libs (charts, maps) needing mount/update/destroy: use `<lifecycle>`, not a hand-wired `<script>`. `this` persists across all three; return an object from `onMount` to stash the instance:
+
+```marko
+<canvas/canvas/>
+<lifecycle
+  onMount() { return { chart: new Chart(canvas(), data) } }
+  onUpdate() { this.chart.setData(data) }         // re-runs when `data` changes
+  onDestroy() { this.chart.destroy() }
+/>
+```
+
+## Lazy loading
+
+Defer a tag's JS into its own bundle until a trigger fires: `render`, `visible#sel`, `idle`, `media(...)`, `on-click#sel` (combine with `|`). Server HTML renders immediately; `<try>` shows a `@placeholder` while loading. Don't hand-roll an `IntersectionObserver`.
+
+```marko
+import PriceChart from "<price-chart>" with { load: "visible#chart" }
+<div#chart><PriceChart symbol=input.symbol/></div>
+```
+
 ## DON'T (these are errors or silently wrong)
 
 | Wrong (React/Vue/Marko5 habit)                              | Right                                                                                |
@@ -144,3 +166,9 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 | `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>`                                                    |
+| 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)             |

package/dist/debug/dom.js

@@ -68,7 +68,12 @@ function _call(fn, v) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/debug/dom.mjs

@@ -66,7 +66,12 @@ function _call(fn, v) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/debug/html.js

@@ -64,7 +64,12 @@ function getWrongAttrSuggestion(name) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {
@@ -1169,25 +1174,39 @@ function writeGenerator(state, iter, ref) {
 		state.buf.push("(function*(){}())");
 		return true;
 	}
-	let sep = "";
-	state.buf.push("(function*(){");
+	const yields = [];
+	let returnValue;
+	let needsId;
 	while (true) {
 		const { value, done } = iter.next();
 		if (done) {
-			if (value !== void 0) {
-				state.buf.push(sep + "return ");
-				writeProp(state, value, ref, "");
-			}
+			returnValue = value;
 			break;
 		}
-		if (value === void 0) state.buf.push(sep + "yield");
-		else {
-			state.buf.push(sep + "yield ");
-			writeProp(state, value, ref, "");
+		needsId ||= isDedupedMember(value);
+		yields.push(value);
+	}
+	if (returnValue === void 0 && !yields.length) {
+		state.buf.push("(function*(){})()");
+		return true;
+	}
+	state.buf.push(returnValue === void 0 ? "(function*(a){yield*a})(" : "(function*(a,r){yield*a;return r})(");
+	if (needsId) {
+		const arrayRef = new Reference(ref, null, state.flush, null, nextRefAccess(state));
+		state.buf.push(arrayRef.id + "=");
+		writeArray(state, yields, arrayRef);
+	} else writeArray(state, yields, new Reference(ref, null, state.flush, state.buf.length));
+	if (returnValue !== void 0) {
+		const sepIndex = state.buf.push(",") - 1;
+		if (writeProp(state, returnValue, ref, "") && isDedupedMember(returnValue)) {
+			const retRef = typeof returnValue === "string" ? state.strs.get(returnValue) : state.refs.get(returnValue);
+			if (retRef && !retRef.id && retRef.scopeId === void 0) {
+				retRef.id = nextRefAccess(state);
+				state.buf[sepIndex] = "," + retRef.id + "=";
+			}
 		}
-		sep = ";";
 	}
-	state.buf.push("})()");
+	state.buf.push(")");
 	return true;
 }
 function writeAsyncGenerator(state, iter, ref) {
@@ -1322,9 +1341,12 @@ function toObjectKey(name) {
 	const c0 = name.charCodeAt(0);
 	if (c0 >= 48 && c0 <= 57) if (c0 === 48) {
 		if (len !== 1) return quote(name, 1);
-	} else for (let i = 1; i < len; i++) {
-		const c = name.charCodeAt(i);
-		if (c < 48 || c > 57) return quote(name, i);
+	} else {
+		for (let i = 1; i < len; i++) {
+			const c = name.charCodeAt(i);
+			if (c < 48 || c > 57) return quote(name, i);
+		}
+		if (len > 15 && "" + +name !== name) return quote(name, 0);
 	}
 	else if (c0 >= 97 && c0 <= 122 || c0 >= 65 && c0 <= 90 || c0 === 95 || c0 === 36) for (let i = 1; i < len; i++) {
 		const c = name.charCodeAt(i);

package/dist/debug/html.mjs

@@ -62,7 +62,12 @@ function getWrongAttrSuggestion(name) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {
@@ -1167,25 +1172,39 @@ function writeGenerator(state, iter, ref) {
 		state.buf.push("(function*(){}())");
 		return true;
 	}
-	let sep = "";
-	state.buf.push("(function*(){");
+	const yields = [];
+	let returnValue;
+	let needsId;
 	while (true) {
 		const { value, done } = iter.next();
 		if (done) {
-			if (value !== void 0) {
-				state.buf.push(sep + "return ");
-				writeProp(state, value, ref, "");
-			}
+			returnValue = value;
 			break;
 		}
-		if (value === void 0) state.buf.push(sep + "yield");
-		else {
-			state.buf.push(sep + "yield ");
-			writeProp(state, value, ref, "");
+		needsId ||= isDedupedMember(value);
+		yields.push(value);
+	}
+	if (returnValue === void 0 && !yields.length) {
+		state.buf.push("(function*(){})()");
+		return true;
+	}
+	state.buf.push(returnValue === void 0 ? "(function*(a){yield*a})(" : "(function*(a,r){yield*a;return r})(");
+	if (needsId) {
+		const arrayRef = new Reference(ref, null, state.flush, null, nextRefAccess(state));
+		state.buf.push(arrayRef.id + "=");
+		writeArray(state, yields, arrayRef);
+	} else writeArray(state, yields, new Reference(ref, null, state.flush, state.buf.length));
+	if (returnValue !== void 0) {
+		const sepIndex = state.buf.push(",") - 1;
+		if (writeProp(state, returnValue, ref, "") && isDedupedMember(returnValue)) {
+			const retRef = typeof returnValue === "string" ? state.strs.get(returnValue) : state.refs.get(returnValue);
+			if (retRef && !retRef.id && retRef.scopeId === void 0) {
+				retRef.id = nextRefAccess(state);
+				state.buf[sepIndex] = "," + retRef.id + "=";
+			}
 		}
-		sep = ";";
 	}
-	state.buf.push("})()");
+	state.buf.push(")");
 	return true;
 }
 function writeAsyncGenerator(state, iter, ref) {
@@ -1320,9 +1339,12 @@ function toObjectKey(name) {
 	const c0 = name.charCodeAt(0);
 	if (c0 >= 48 && c0 <= 57) if (c0 === 48) {
 		if (len !== 1) return quote(name, 1);
-	} else for (let i = 1; i < len; i++) {
-		const c = name.charCodeAt(i);
-		if (c < 48 || c > 57) return quote(name, i);
+	} else {
+		for (let i = 1; i < len; i++) {
+			const c = name.charCodeAt(i);
+			if (c < 48 || c > 57) return quote(name, i);
+		}
+		if (len > 15 && "" + +name !== name) return quote(name, 0);
 	}
 	else if (c0 >= 97 && c0 <= 122 || c0 >= 65 && c0 <= 90 || c0 === 95 || c0 === 36) for (let i = 1; i < len; i++) {
 		const c = name.charCodeAt(i);

package/dist/html.js

@@ -823,16 +823,28 @@ function writeReadableStream(state, val, ref) {
 }
 function writeGenerator(state, iter, ref) {
 	if (iter[kTouchedIterator]) return state.buf.push("(function*(){}())"), !0;
-	let sep = "";
-	for (state.buf.push("(function*(){");;) {
+	let yields = [], returnValue, needsId;
+	for (;;) {
 		let { value, done } = iter.next();
 		if (done) {
-			value !== void 0 && (state.buf.push(sep + "return "), writeProp(state, value, ref, ""));
+			returnValue = value;
 			break;
 		}
-		value === void 0 ? state.buf.push(sep + "yield") : (state.buf.push(sep + "yield "), writeProp(state, value, ref, "")), sep = ";";
+		needsId ||= isDedupedMember(value), yields.push(value);
+	}
+	if (returnValue === void 0 && !yields.length) return state.buf.push("(function*(){})()"), !0;
+	if (state.buf.push(returnValue === void 0 ? "(function*(a){yield*a})(" : "(function*(a,r){yield*a;return r})("), needsId) {
+		let arrayRef = new Reference(ref, null, state.flush, null, nextRefAccess(state));
+		state.buf.push(arrayRef.id + "="), writeArray(state, yields, arrayRef);
+	} else writeArray(state, yields, new Reference(ref, null, state.flush, state.buf.length));
+	if (returnValue !== void 0) {
+		let sepIndex = state.buf.push(",") - 1;
+		if (writeProp(state, returnValue, ref, "") && isDedupedMember(returnValue)) {
+			let retRef = typeof returnValue == "string" ? state.strs.get(returnValue) : state.refs.get(returnValue);
+			retRef && !retRef.id && retRef.scopeId === void 0 && (retRef.id = nextRefAccess(state), state.buf[sepIndex] = "," + retRef.id + "=");
+		}
 	}
-	return state.buf.push("})()"), !0;
+	return state.buf.push(")"), !0;
 }
 function writeAsyncGenerator(state, iter, ref) {
 	if (iter[kTouchedIterator]) return state.buf.push("(async function*(){}())"), !0;
@@ -902,9 +914,12 @@ function toObjectKey(name) {
 	let len = name.length, c0 = name.charCodeAt(0);
 	if (c0 >= 48 && c0 <= 57) if (c0 === 48) {
 		if (len !== 1) return quote(name, 1);
-	} else for (let i = 1; i < len; i++) {
-		let c = name.charCodeAt(i);
-		if (c < 48 || c > 57) return quote(name, i);
+	} else {
+		for (let i = 1; i < len; i++) {
+			let c = name.charCodeAt(i);
+			if (c < 48 || c > 57) return quote(name, i);
+		}
+		if (len > 15 && "" + +name !== name) return quote(name, 0);
 	}
 	else if (c0 >= 97 && c0 <= 122 || c0 >= 65 && c0 <= 90 || c0 === 95 || c0 === 36) for (let i = 1; i < len; i++) {
 		let c = name.charCodeAt(i);

package/dist/html.mjs

@@ -822,16 +822,28 @@ function writeReadableStream(state, val, ref) {
 }
 function writeGenerator(state, iter, ref) {
 	if (iter[kTouchedIterator]) return state.buf.push("(function*(){}())"), !0;
-	let sep = "";
-	for (state.buf.push("(function*(){");;) {
+	let yields = [], returnValue, needsId;
+	for (;;) {
 		let { value, done } = iter.next();
 		if (done) {
-			value !== void 0 && (state.buf.push(sep + "return "), writeProp(state, value, ref, ""));
+			returnValue = value;
 			break;
 		}
-		value === void 0 ? state.buf.push(sep + "yield") : (state.buf.push(sep + "yield "), writeProp(state, value, ref, "")), sep = ";";
+		needsId ||= isDedupedMember(value), yields.push(value);
+	}
+	if (returnValue === void 0 && !yields.length) return state.buf.push("(function*(){})()"), !0;
+	if (state.buf.push(returnValue === void 0 ? "(function*(a){yield*a})(" : "(function*(a,r){yield*a;return r})("), needsId) {
+		let arrayRef = new Reference(ref, null, state.flush, null, nextRefAccess(state));
+		state.buf.push(arrayRef.id + "="), writeArray(state, yields, arrayRef);
+	} else writeArray(state, yields, new Reference(ref, null, state.flush, state.buf.length));
+	if (returnValue !== void 0) {
+		let sepIndex = state.buf.push(",") - 1;
+		if (writeProp(state, returnValue, ref, "") && isDedupedMember(returnValue)) {
+			let retRef = typeof returnValue == "string" ? state.strs.get(returnValue) : state.refs.get(returnValue);
+			retRef && !retRef.id && retRef.scopeId === void 0 && (retRef.id = nextRefAccess(state), state.buf[sepIndex] = "," + retRef.id + "=");
+		}
 	}
-	return state.buf.push("})()"), !0;
+	return state.buf.push(")"), !0;
 }
 function writeAsyncGenerator(state, iter, ref) {
 	if (iter[kTouchedIterator]) return state.buf.push("(async function*(){}())"), !0;
@@ -901,9 +913,12 @@ function toObjectKey(name) {
 	let len = name.length, c0 = name.charCodeAt(0);
 	if (c0 >= 48 && c0 <= 57) if (c0 === 48) {
 		if (len !== 1) return quote(name, 1);
-	} else for (let i = 1; i < len; i++) {
-		let c = name.charCodeAt(i);
-		if (c < 48 || c > 57) return quote(name, i);
+	} else {
+		for (let i = 1; i < len; i++) {
+			let c = name.charCodeAt(i);
+			if (c < 48 || c > 57) return quote(name, i);
+		}
+		if (len > 15 && "" + +name !== name) return quote(name, 0);
 	}
 	else if (c0 >= 97 && c0 <= 122 || c0 >= 65 && c0 <= 90 || c0 === 95 || c0 === 36) for (let i = 1; i < len; i++) {
 		let c = name.charCodeAt(i);

package/dist/translator/index.d.ts

@@ -1,5 +1,6 @@
 import type { Config } from "@marko/compiler";
 export { version } from "../../package.json";
+export declare const cheatsheet = "../../cheatsheet.md";
 export declare const tagDiscoveryDirs: string[];
 export { default as internalEntryBuilder } from "./util/entry-builder";
 export declare const preferAPI = "tags";

package/dist/translator/index.js

@@ -3802,6 +3802,8 @@ var for_default = {
 			default: throw tag.buildCodeFrameError("The [`<for>` tag](https://markojs.com/docs/reference/core-tag#for) requires an `of=`, `in=`, or `to=` attribute.");
 		}
 		if (!isAttrTag) allowAttrs.push("by");
+		const keyAttr = tag.node.attributes.find((attr) => attr.type === "MarkoAttribute" && attr.name === "key");
+		if (keyAttr) throw tag.hub.buildError(keyAttr, `The [\`<for>\` tag](https://markojs.com/docs/reference/core-tag#for) keys items with the \`by=\` attribute, not \`key=\`. ${forType === "of" ? "Use `by=\"propName\"` or `by=(item, index) => key`" : forType === "in" ? "Use `by=(key, value) => key`" : "Use `by=(num) => key`"}.`);
 		(0, _marko_compiler_babel_utils.assertAllowedAttributes)(tag, allowAttrs);
 		if (isAttrTag) return;
 		const byAttr = getKnownAttrValues(tag.node).by;
@@ -4359,6 +4361,7 @@ var native_tag_default = {
 				seen[attr.name] = attr;
 				assertValidNativeAttrName(tag, attr);
 				assertNativeAttrValueType(tag, attr);
+				if (attr.name === "style") warnCamelCaseStyleKeys(tag, attr);
 				if (injectNonce && attr.name === "nonce") injectNonce = false;
 				if (isEventOrChangeHandler(attr.name)) assertNativeHandlerAttr(tag, attr);
 				if (isEventHandler(attr.name)) {
@@ -4810,6 +4813,19 @@ function assertNativeAttrValueType(tag, attr) {
 	if (_marko_compiler.types.isFunction(attr.value)) throw tag.hub.buildError(attr, `The \`${name}\` attribute cannot be a function.`, Error);
 	if (_marko_compiler.types.isObjectExpression(attr.value)) throw tag.hub.buildError(attr, `The \`${name}\` attribute cannot be a plain object (it would render as \`[object Object]\`).`, Error);
 }
+function warnCamelCaseStyleKeys(tag, attr) {
+	const { value } = attr;
+	const objects = value.type === "ObjectExpression" ? [value] : value.type === "ArrayExpression" ? value.elements.filter((el) => el?.type === "ObjectExpression") : [];
+	for (const object of objects) for (const prop of object.properties) {
+		if (prop.type !== "ObjectProperty" || prop.computed) continue;
+		const { key } = prop;
+		const name = key.type === "Identifier" ? key.name : key.type === "StringLiteral" ? key.value : void 0;
+		if (name && !name.startsWith("--") && !name.includes("-") && /[A-Z]/.test(name)) (0, _marko_compiler_babel_utils.diagnosticWarn)(tag, {
+			label: `\`${name}\` is not a CSS property name; the [\`style=\` object](https://markojs.com/docs/reference/native-tag#style) writes keys out verbatim (unlike the camelCased DOM style API), so this renders as invalid CSS the browser ignores. Use the kebab-case name \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`,
+			loc: key.loc ?? void 0
+		});
+	}
+}
 function assertNativeHandlerAttr(tag, attr) {
 	if (_marko_compiler.types.isObjectExpression(attr.value)) throw tag.hub.buildError(attr.value, `The \`${attr.name}\` ${isEventHandler(attr.name) ? "event handler" : "change handler"} on a [native tag](https://markojs.com/docs/reference/native-tag) must be a function. Attribute values in Marko are plain JavaScript expressions, not JSX; remove the wrapping \`{ }\` (e.g. \`${attr.name}=myHandler\` or \`${attr.name}() { ... }\`).`, Error);
 	if ((0, _marko_compiler_babel_utils.computeNode)(attr.value)?.value) throw tag.hub.buildError(attr.value, `The \`${attr.name}\` ${isEventHandler(attr.name) ? "event handler" : "change handler"} on a [native tag](https://markojs.com/docs/reference/native-tag) must be a function or a falsey value (\`null\`, \`undefined\`, \`false\`, \`0\`, …).`, Error);
@@ -9356,13 +9372,36 @@ function tagNotFoundError(tag) {
 	if (tagName && tag.scope.hasBinding(tagName)) return tag.get("name").buildCodeFrameError(`Local variables must be in a [dynamic tag](https://markojs.com/docs/reference/language#dynamic-tags) unless they are PascalCase. Use \`<\${${tagName}}/>\` or rename to \`${tagName.charAt(0).toUpperCase() + tagName.slice(1)}\`.`);
 	let didYouMean = "";
 	const knownWrongTagHint = tagName && knownWrongTags.get(tagName);
+	const proseText = tagName && getProseText(tag);
 	if (knownWrongTagHint) didYouMean = ` ${knownWrongTagHint}`;
+	else if (proseText) didYouMean = ` If this line is meant to be text, prefix it with \`--\` (e.g. \`-- ${proseText}\`) or wrap it in an element such as \`<p>${proseText}</p>\`.`;
 	else if (tagName) {
 		const closestTag = (0, fastest_levenshtein.closest)(tagName, Object.keys((0, _marko_compiler_babel_utils.getTaglibLookup)(tag.hub.file).merged.tags));
 		if ((0, fastest_levenshtein.distance)(tagName, closestTag) < 4) didYouMean = ` Did you mean \`<${closestTag}>\`?`;
 	}
 	return tag.get("name").buildCodeFrameError(`Unable to find entry point for [custom tag](https://markojs.com/docs/reference/custom-tag#relative-custom-tags) \`<${tagName}>\`.${didYouMean}`);
 }
+const wordReg = /^[A-Za-z]+$/;
+function getProseText(tag) {
+	const { node } = tag;
+	const tagName = getTagName(tag);
+	if (!tagName || !wordReg.test(tagName) || node.var || node.body.params.length || node.body.body.length || !node.attributes.length || !isConciseModeTag(node)) return;
+	return collectProseWords(node, tagName);
+}
+function isConciseModeTag(node) {
+	const tagLoc = node.loc;
+	const nameLoc = node.name.loc;
+	if (!tagLoc || !nameLoc) return false;
+	return tagLoc.start.line === nameLoc.start.line && tagLoc.start.column === nameLoc.start.column;
+}
+function collectProseWords(node, tagName) {
+	let text = tagName;
+	for (const attr of node.attributes) {
+		if (attr.type !== "MarkoAttribute" || attr.default || !wordReg.test(attr.name) || attr.value.type !== "BooleanLiteral" || attr.value.value !== true) return;
+		text += " " + attr.name;
+	}
+	return text;
+}
 function importOrSelfReferenceName(file, request, name, nameHint) {
 	if (isCircularRequest(file, request)) return _marko_compiler.types.identifier(name);
 	return (0, _marko_compiler_babel_utils.importNamed)(file, request, name, nameHint);
@@ -9984,6 +10023,7 @@ function getVisitorExit(visit) {
 }
 //#endregion
 //#region src/translator/index.ts
+const cheatsheet = "../../cheatsheet.md";
 const visitors = extractVisitors({
 	Program: program_default,
 	Function: function_default,
@@ -10010,6 +10050,7 @@ function getRuntimeEntryFiles(output, optimize) {
 }
 //#endregion
 exports.analyze = analyze;
+exports.cheatsheet = cheatsheet;
 exports.createInteropTranslator = createInteropTranslator;
 exports.getRuntimeEntryFiles = getRuntimeEntryFiles;
 exports.internalEntryBuilder = entry_builder_default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marko/runtime-tags",
-  "version": "6.3.5",
+  "version": "6.3.7",
   "description": "Optimized runtime for Marko templates.",
   "keywords": [
     "api",
@@ -51,7 +51,7 @@
     "build": "node -r ~ts ./scripts/bundle.mts"
   },
   "dependencies": {
-    "@marko/compiler": "^5.41.0",
+    "@marko/compiler": "^5.41.1",
     "csstype": "^3.2.3",
     "fastest-levenshtein": "^1.0.16",
     "magic-string": "^0.30.21"