gofront 1.6.1 → 1.8.0

package/src/backend/js/templ.js

@@ -2,9 +2,6 @@
 // Mounts an HTML/expression tree onto a parent DOM node by emitting plain
 // document.createElement / appendChild / setAttribute calls.
 
-import { Parser } from "../../parser/index.js";
-import { T, Token } from "../../tokens.js";
-
 /** @typedef {import('./index.js').CodeGen} CodeGen */
 
 /** @type {ThisType<CodeGen>} */
@@ -17,6 +14,12 @@ export const templGenMethods = {
 			.join(", ");
 		this.line(`function ${decl.name}(${params}) {`);
 		this.indented(() => {
+			// `@W(xs...)` passes `{ __sp: xs }` like any Go variadic call.
+			const last = decl.params[decl.params.length - 1];
+			if (last?.variadic && last.name && last.name !== "_") {
+				this.useHelper("va");
+				this.line(`${last.name} = __va(${last.name});`);
+			}
 			this.line(`return {Mount(___p, ___refs) {`);
 			this.indented(() => {
 				this._genTemplNodes(decl.body, "___p");
@@ -79,7 +82,7 @@ export const templGenMethods = {
 				);
 			case "TemplExpr":
 				return this.line(
-					`${p}.appendChild(document.createTextNode(String(${this._genTemplTokenExpr(node.tokens)})));`,
+					`${p}.appendChild(document.createTextNode(String(${this._genTemplExpr(node, '""')})));`,
 				);
 			case "TemplComponent":
 				return this._genTemplComponentMount(node, p);
@@ -101,20 +104,12 @@ export const templGenMethods = {
 
 	_genTemplComponentMount(node, p) {
 		// Special case: @templ.Raw(expr) → insertAdjacentHTML
-		const toks = node.tokens;
-		if (
-			toks.length >= 4 &&
-			toks[0]?.value === "templ" &&
-			toks[1]?.type === T.DOT &&
-			toks[2]?.value === "Raw" &&
-			toks[3]?.type === T.LPAREN
-		) {
-			const argTokens = toks.slice(4, toks.length - 1);
-			const argJs = this._genTemplTokenExpr(argTokens);
+		if (node.raw) {
+			const argJs = this._genTemplExpr(node, '""');
 			return this.line(`${p}.insertAdjacentHTML("beforeend", ${argJs});`);
 		}
 		return this.line(
-			`(${this._genTemplTokenCallExpr(node.tokens)}).Mount(${p}, ___refs);`,
+			`(${this._genTemplExpr(node, "null")}).Mount(${p}, ___refs);`,
 		);
 	},
 
@@ -160,7 +155,7 @@ export const templGenMethods = {
 				);
 			}
 		} else if (attr.kind === "expr") {
-			const exprJs = this._genTemplTokenExpr(attr.tokens);
+			const exprJs = this._genTemplExpr(attr, '""');
 			if (name === "class") {
 				this.line(setClass(exprJs));
 			} else {
@@ -171,7 +166,7 @@ export const templGenMethods = {
 		} else if (attr.kind === "bool") {
 			this.line(`${el}.setAttribute(${JSON.stringify(name)}, "");`);
 		} else if (attr.kind === "cond-bool") {
-			const exprJs = this._genTemplTokenExpr(attr.tokens);
+			const exprJs = this._genTemplExpr(attr, '""');
 			this.line(
 				`if(${exprJs})${el}.setAttribute(${JSON.stringify(name)}, "");`,
 			);
@@ -179,7 +174,7 @@ export const templGenMethods = {
 	},
 
 	_genTemplIf(node, p) {
-		const condJs = this._genTemplCondTokens(node.condTokens);
+		const condJs = this._genTemplExpr(node, "false");
 		this.line(`if (${condJs}) {`);
 		this.indented(() => this._genTemplNodes(node.then, p));
 		this._genTemplIfElse(node.else_, p);
@@ -192,7 +187,7 @@ export const templGenMethods = {
 		}
 		if (else_.length === 1 && else_[0].kind === "TemplIf") {
 			const elseIf = else_[0];
-			this.line(`} else if (${this._genTemplCondTokens(elseIf.condTokens)}) {`);
+			this.line(`} else if (${this._genTemplExpr(elseIf, "false")}) {`);
 			this.indented(() => this._genTemplNodes(elseIf.then, p));
 			this._genTemplIfElse(elseIf.else_, p);
 		} else {
@@ -203,16 +198,16 @@ export const templGenMethods = {
 	},
 
 	_genTemplSwitch(node, p) {
-		const { exprTokens, cases } = node;
+		const { cases } = node;
 		if (cases.length === 0) return;
-		const exprJs = this._genTemplTokenExpr(exprTokens);
+		const exprJs = this._genTemplExpr(node, '""');
 		this.line(`switch (${exprJs}) {`);
 		this.indented(() => {
 			for (const c of cases) {
 				const label =
 					c.caseTokens === null
 						? "default"
-						: `case ${this._genTemplTokenExpr(c.caseTokens)}`;
+						: `case ${this._genTemplExpr(c, '""')}`;
 				this.line(`${label}: {`);
 				this.indented(() => this._genTemplNodes(c.body, p));
 				this.line(`break; }`);
@@ -222,35 +217,10 @@ export const templGenMethods = {
 	},
 
 	_genTemplFor(node, p) {
-		// stmtTokens include the `for` keyword plus the range clause (no body).
-		// Strip any trailing semicolons (inserted by the Go lexer on newlines),
-		// then add a fake empty body `{ }` so the parser can complete the ForStmt.
-		let tokens = node.stmtTokens;
-		while (tokens.length > 0 && tokens[tokens.length - 1].type === T.SEMICOLON)
-			tokens = tokens.slice(0, -1);
-		const eofTok = new Token(T.EOF, "", 1, 1);
-		const lbrace = new Token(T.LBRACE, "{", 1, 1);
-		const rbrace = new Token(T.RBRACE, "}", 1, 1);
-		const semi = new Token(T.SEMICOLON, ";", 1, 1);
-		const withFor =
-			tokens[0]?.type === T.FOR
-				? [...tokens, lbrace, rbrace, semi, eofTok]
-				: [
-						new Token(T.FOR, "for", 1, 1),
-						...tokens,
-						lbrace,
-						rbrace,
-						semi,
-						eofTok,
-					];
-		try {
-			const p2 = new Parser(withFor);
-			const forStmt = p2.parseFor();
-			this._genTemplRangeFor(forStmt, node.body, p);
-		} catch {
-			// Fallback for non-range loops: emit a comment + skip
-			this.line(`/* templ for: ${this._tokensToSource(tokens)} */`);
-		}
+		if (node.forError) throw node.forError;
+		if (!node.forStmt)
+			throw new Error("templ for header was not parsed by TemplParser");
+		this._genTemplRangeFor(node.forStmt, node.body, p);
 	},
 
 	_genTemplRangeFor(forStmt, templBody, mountParent) {
@@ -290,37 +260,29 @@ export const templGenMethods = {
 		return `for (const [${keyName}, ${valName}] of __s(${iterJs}).entries()) {`;
 	},
 
-	// Parse a token array as a Go expression and emit JS.
-	_genTemplTokenExpr(tokens) {
-		if (!tokens || tokens.length === 0) return '""';
-		const eofTok = new Token(T.EOF, "", 1, 1);
-		const p = new Parser([...tokens, eofTok]);
-		const ast = p.parseExpr();
-		return this.genExpr(ast);
+	// Emit JS for the Go expression TemplParser parsed onto `node`. `emptyJs` is
+	// the value when the node holds no tokens. A parse error is raised here,
+	// not in the parser, so it surfaces at the same point as it always did.
+	_genTemplExpr(node, emptyJs) {
+		if (node.exprError) throw node.exprError;
+		if (node.expr === undefined)
+			throw new Error("templ expression was not parsed by TemplParser");
+		return node.expr ? this.genExpr(node.expr) : emptyJs;
 	},
 
-	// Parse a token array as a Go call expression and emit JS.
-	_genTemplTokenCallExpr(tokens) {
-		if (!tokens || tokens.length === 0) return "null";
-		const eofTok = new Token(T.EOF, "", 1, 1);
-		const p = new Parser([...tokens, eofTok]);
-		const ast = p.parseExpr();
-		return this.genExpr(ast);
+	// Rename handlers for `_renameReservedIdents`: templ bodies keep their Go
+	// expressions in non-enumerable props (see parser/templ.js), which its
+	// generic walk does not visit, so `class` in `{ class }` would stay unsafe.
+	_renameTemplExprNode(node) {
+		this._renameReservedIdents(node.expr);
 	},
 
-	// Extract condition JS from condTokens (which may start with `if`).
-	_genTemplCondTokens(tokens) {
-		if (!tokens || tokens.length === 0) return "false";
-		let toks = tokens;
-		if (toks[0]?.type === T.IF) toks = toks.slice(1); // skip `if` keyword
-		const eofTok = new Token(T.EOF, "", 1, 1);
-		const p = new Parser([...toks, eofTok]);
-		const ast = p.parseExpr();
-		return this.genExpr(ast);
+	_renameTemplForNode(node) {
+		this._renameReservedIdents(node.forStmt);
 	},
 
-	_tokensToSource(tokens) {
-		return tokens.map((t) => t.value).join(" ");
+	_renameTemplElementNode(node) {
+		for (const attr of node.attrs ?? []) this._renameReservedIdents(attr.expr);
 	},
 
 	// Fresh variable name counter

package/src/backend/js/type-info.js

@@ -0,0 +1,272 @@
+// src/backend/js/type-info.js
+// Run-time type information for erased generics.  A generic function (or the
+// instance of a generic type) receives one zero-value factory per type
+// parameter; when its body needs to know the instantiated type (type
+// assertions to a type parameter, conversions to it, `==` on it, building an
+// instance of another generic type from it) the factory also carries the
+// type's kind, identity and a type test (see `__ti` in HELPER_GENERICS).
+
+import { forEachChild } from "../../lower/index.js";
+import { isAny, typeStr } from "../../typechecker/types.js";
+import { mentionsTypeParam } from "./expressions.js";
+
+// True when type node `node` names one of the type parameters `names`.
+function typeNodeMentions(node, names) {
+	if (Array.isArray(node)) return node.some((n) => typeNodeMentions(n, names));
+	if (!node || typeof node !== "object") return false;
+	if (
+		(node.kind === "TypeName" || node.kind === "Ident") &&
+		names.has(node.name)
+	)
+		return true;
+	let found = false;
+	forEachChild(node, (c) => {
+		if (!found && typeNodeMentions(c, names)) found = true;
+	});
+	return found;
+}
+
+function typeArgsMention(node) {
+	const args = node._typeArgs ?? node._type?.typeArgs;
+	return Array.isArray(args) && args.some((t) => mentionsTypeParam(t));
+}
+
+export const typeInfoGenMethods = {
+	// Whether the body of generic `decl` (a function or method declaration)
+	// needs the instantiated types of `names`.
+	_declNeedsTypeInfo(decl, names) {
+		this._typeInfoMemo ??= new Map();
+		this._typeInfoActive ??= new Set();
+		if (this._typeInfoMemo.has(decl)) return this._typeInfoMemo.get(decl);
+		if (this._typeInfoActive.has(decl)) {
+			this._typeInfoCycle = true; // answer depends on an unfinished scan
+			return false;
+		}
+		const outer = this._typeInfoCycle;
+		this._typeInfoCycle = false;
+		this._typeInfoActive.add(decl);
+		const result = this._scanTypeInfoUse(decl.body, new Set(names));
+		this._typeInfoActive.delete(decl);
+		// A false that leaned on an in-progress scan is provisional: only cache
+		// it once no scan is in progress, otherwise a mutually recursive
+		// function would keep a stale answer.
+		if (result || !this._typeInfoCycle || this._typeInfoActive.size === 0)
+			this._typeInfoMemo.set(decl, result);
+		this._typeInfoCycle = outer || this._typeInfoCycle;
+		return result;
+	},
+
+	_scanTypeInfoUse(node, names) {
+		if (Array.isArray(node))
+			return node.some((n) => this._scanTypeInfoUse(n, names));
+		if (!node || typeof node !== "object") return false;
+		if (this._nodeUsesTypeInfo(node, names)) return true;
+		let found = false;
+		forEachChild(node, (c) => {
+			if (!found && this._scanTypeInfoUse(c, names)) found = true;
+		});
+		return found;
+	},
+
+	_nodeUsesTypeInfo(node, names) {
+		if (node._ifaceKeyDyn && names.has(node._ifaceKeyParam)) return true;
+		switch (node.kind) {
+			case "TypeAssertExpr":
+				return typeNodeMentions(node.type, names);
+			case "TypeSwitchStmt":
+				return node.cases.some((c) => typeNodeMentions(c.types, names));
+			case "TypeConversion":
+				return typeNodeMentions(node.targetType, names);
+			case "BinaryExpr":
+				return (
+					(node.op === "==" || node.op === "!=") &&
+					node.left._type?.kind === "typeParam"
+				);
+			case "CallExpr":
+				return this._callUsesTypeInfo(node);
+			case "CompositeLit":
+			case "GenericTypeName":
+				return typeArgsMention(node);
+			default:
+				return false;
+		}
+	},
+
+	_callUsesTypeInfo(call) {
+		if (call._isTypeConversion)
+			return call._conversionTargetType?.kind === "typeParam";
+		// A fmt operand of a type parameter type is formatted by its instantiated
+		// type (a Stringer type argument), see _fmtArgJs.
+		if (
+			call.func?.kind === "SelectorExpr" &&
+			call.func.expr?.name === "fmt" &&
+			call.args.some((a) => a?._type?.kind === "typeParam")
+		)
+			return true;
+		const site = call._genericFnType ? call : call.func;
+		if (!site?._genericFnType) return false;
+		if (!site._typeArgs?.some((t) => mentionsTypeParam(t))) return false;
+		return this._genericFnNeedsTypeInfo(site._genericFnType);
+	},
+
+	// Whether callers of generic function `generic` pass type information.
+	_genericFnNeedsTypeInfo(generic) {
+		const decl = generic?.declNode;
+		if (!decl) return false;
+		return this._declNeedsTypeInfo(
+			decl,
+			(decl.typeParams ?? []).map((tp) => tp.name),
+		);
+	},
+
+	// Whether instances of generic type `named` carry type information: any
+	// of its methods needs it.
+	_genericTypeNeedsTypeInfo(named) {
+		const generic = named?._generic;
+		if (!generic?.methods) return false;
+		const names = generic.typeParams.map((tp) => tp.name);
+		for (const m of generic.methods.values())
+			if (m?._decl && this._declNeedsTypeInfo(m._decl, names)) return true;
+		return false;
+	},
+
+	// The factory a generic callee receives for type argument `t`, carrying
+	// the type's kind, identity and type test.
+	_typeInfoFactory(t) {
+		if (t?.kind === "typeParam") {
+			const bound = this._typeParamZeroFactory(t.name);
+			if (bound) return bound;
+		}
+		this.useHelper("generics");
+		const base = this.zeroFactoryFor(t);
+		const u = this._underlyingOf(t);
+		let k = "";
+		if (isAny(u) || u?.kind === "interface") k = "iface";
+		else if (u?.kind === "basic") k = u.name;
+		const check = this._typeCheckForType(t, "__v");
+		const is = check ? `(__v) => ${check}` : "null";
+		const unbox = this._boxesInInterface(t) ? "true" : "false";
+		const box = this._ifaceKeyBox(t);
+		const fmtBox = this._fmtBoxFor(t);
+		const tail = fmtBox
+			? `, ${box ?? "null"}, ${fmtBox}`
+			: box
+				? `, ${box}`
+				: "";
+		return `__ti(${base}, ${JSON.stringify(k)}, ${JSON.stringify(typeStr(t))}, ${is}, ${unbox}${tail})`;
+	},
+
+	// A function boxing a plain value of named basic type `t`, as converting
+	// it to an interface does; null when `t` is not boxed.
+	_ifaceKeyBox(t) {
+		if (!this._boxesInInterface(t) || t?.kind !== "named") return null;
+		return `(__v) => ${this._genNamedIfaceBox("__v", t, false)}`;
+	},
+
+	// A function giving a plain value of type `t` the type information fmt
+	// needs once it is an `any` operand (see _fmtDesc); null when it needs none.
+	_fmtBoxFor(t) {
+		if (!t || t.kind === "typeParam" || mentionsTypeParam(t)) return null;
+		if (this._ifaceKeyBox(t)) return null; // boxed by the key box already
+		const u = this._underlyingOf(t);
+		if (t.kind === "pointer" && this._underlyingOf(t.base)?.kind === "struct") {
+			this.useHelper("ifaceBox");
+			return "(__v) => __ifp(__v)";
+		}
+		const desc = this._fmtDesc(t);
+		if (desc) this.useHelper("ifd");
+		const tagged = (v) => (desc ? `__ifd(${v}, ${desc})` : v);
+		if (u?.kind === "map") {
+			this.useHelper("ifaceBox");
+			return `(__v) => __ifm(${tagged("__v")})`;
+		}
+		if (u?.kind === "slice") return `(__v) => ${tagged("(__v ?? [])")}`;
+		return desc ? `(__v) => ${tagged("__v")}` : null;
+	},
+
+	_underlyingOf(t) {
+		let u = t;
+		for (let i = 0; i < 8 && u?.kind === "named"; i++) u = u.underlying;
+		return u;
+	},
+
+	// A named non-struct value (or pointer to one) is boxed in an interface.
+	_boxesInInterface(t) {
+		const base = t?.kind === "pointer" ? t.base : t;
+		return Boolean(this._namedBoxInfo(base));
+	},
+
+	// JS test that `val` holds a value of type `t`, or null when it cannot be
+	// told at run time.
+	_typeCheckForType(t, val) {
+		switch (t?.kind) {
+			case "basic":
+				return this._typeNameCheckExpr(t.name, val);
+			case "named":
+				return this._namedTypeCheck(t, val);
+			case "pointer":
+				return this._pointerTypeCheck(t.base, val);
+			case "interface":
+				return t.methods?.size
+					? this._ifaceMethodCheck(
+							val,
+							[...t.methods.keys()],
+							this._unwrapIsMulti(t.methods.get("Unwrap")),
+						)
+					: null;
+			case "typeParam": {
+				const f = this._typeParamZeroFactory(t.name);
+				return f ? `(${f}?.is?.(${val}) ?? true)` : null;
+			}
+			default:
+				return null;
+		}
+	},
+
+	_namedTypeCheck(t, val) {
+		if (t.typeArgs?.length) {
+			const generic = this._genericInstanceCheck(
+				{ kind: "GenericTypeName", name: t.name, _typeArgs: t.typeArgs },
+				val,
+			);
+			if (generic) return generic;
+		}
+		const u = this._underlyingOf(t);
+		if (u?.kind === "interface" && t.name !== "error")
+			return this._ifaceMethodCheck(
+				val,
+				[...(u.methods?.keys() ?? [])],
+				this._unwrapIsMulti(u.methods?.get("Unwrap")),
+			);
+		return this._typeNameCheckExpr(t.name, val);
+	},
+
+	_pointerTypeCheck(base, val) {
+		if (base?.kind !== "named") return null;
+		const node = base.typeArgs?.length
+			? { kind: "GenericTypeName", name: base.name, _typeArgs: base.typeArgs }
+			: { kind: "TypeName", name: base.name };
+		const check = this._typeCheckExpr({ kind: "PointerType", base: node }, val);
+		return check === "true" ? null : check;
+	},
+
+	// Runtime instance id of a generic type's instantiation `typeArgs` that
+	// mention type parameters: the callee's type arguments joined as
+	// `instanceId` prints them; null when it cannot be built.
+	_runtimeInstanceId(typeArgs) {
+		if (!typeArgs?.length) return null;
+		const parts = [];
+		for (const t of typeArgs) {
+			if (!mentionsTypeParam(t)) {
+				parts.push(JSON.stringify(typeStr(t)));
+				continue;
+			}
+			const f =
+				t.kind === "typeParam" ? this._typeParamZeroFactory(t.name) : null;
+			if (!f) return null;
+			parts.push(`${f}?.id`);
+		}
+		this.useHelper("generics");
+		return `__tid(${parts.join(", ")})`;
+	},
+};

package/src/backend/shared/fmt-types.js

@@ -0,0 +1,188 @@
+// Static type descriptors for `fmt` (Task 3.1c), shared by the JS and WASM
+// backends.  `%T` and `%#v` need the Go type of an operand, which the runtime
+// values do not carry (an `int` and a `float64` holding 3 are both the number
+// 3, a `Color` is a raw number inside a slice).  Where a format string is a
+// literal that needs them (`fmtWantsTypes`), codegen passes the operand's
+// static type next to its value as a plain JSON-compatible tree, which
+// `__sprintf` reads (`__ft` on JS, `fmt_arg_type` on WASM).
+//
+// Descriptor shapes (`k`): `b` basic `{ n }`, `named` `{ n, u }` (a named
+// non-struct type, `u` its underlying type), `struct` `{ n, f: [[name, T]] }`
+// (`n` is "" for an anonymous struct), `ptr` `{ e }`, `slice` `{ e }`,
+// `array` `{ e, len }`, `map` `{ key, val }`, `i` an interface `{ n }`,
+// `func` `{ p, r }`, `chan` `{ e }`.  A type that is too deep or unknown is
+// `null`; the runtime then derives a best-effort type from the value.
+
+const MAX_DEPTH = 4;
+const FLAGS = "#+\\- 0";
+const VERBS = "vTtcdoObxXUeEfFgGsqp";
+
+const qualify = (name) => (name.includes(".") ? name : `main.${name}`);
+
+/**
+ * @param {any} t checker type
+ * @param {(t: any) => any} [resolve] resolves a type reference
+ * @param {number} [depth]
+ * @returns {object | null}
+ */
+export function fmtTypeDesc(t, resolve = (x) => x, depth = 0) {
+	t = resolve(t) ?? t;
+	if (!t) return null;
+	const sub = (x) => fmtTypeDesc(x, resolve, depth + 1);
+	switch (t.kind) {
+		case "basic":
+			if (t.name === "any") return { k: "i", n: "interface {}" };
+			if (t.name === "nil" || t.name === "void") return null;
+			return { k: "b", n: t.name };
+		case "untyped":
+			return { k: "b", n: t.base };
+		case "interface":
+			return { k: "i", n: t.name ? qualify(t.name) : "interface {}" };
+		case "named":
+			return namedDesc(t, resolve, depth, sub);
+		case "struct":
+			return depth > MAX_DEPTH ? null : structDesc("", t, sub);
+		case "pointer":
+			return depth > MAX_DEPTH ? null : { k: "ptr", e: sub(t.base) };
+		case "slice":
+			return depth > MAX_DEPTH ? null : { k: "slice", e: sub(t.elem) };
+		case "array":
+			return depth > MAX_DEPTH
+				? null
+				: { k: "array", e: sub(t.elem), len: t.size ?? 0 };
+		case "map":
+			return depth > MAX_DEPTH
+				? null
+				: { k: "map", key: sub(t.key), val: sub(t.value) };
+		case "func":
+			return {
+				k: "func",
+				p: (t.params ?? []).map(sub),
+				r: (t.returns ?? []).map(sub),
+				v: Boolean(t.variadic),
+			};
+		case "chan":
+			return { k: "chan", e: sub(t.elem) };
+		default:
+			return null;
+	}
+}
+
+/**
+ * The fields a struct declares itself, in declaration order: named fields and
+ * one entry per embedded type.  Fields promoted from an embedded struct are
+ * not listed (`fields` also holds them for selector lookup).
+ * @param {any} st checker struct type
+ * @returns {[string, any][]}
+ */
+export function structOwnFields(st) {
+	if (!st._structFields) return [...(st.fields ?? [])];
+	const own = [];
+	for (const sf of st._structFields) {
+		if (!sf.embedded) {
+			for (const n of sf.names) own.push([n, st.fields.get(n)]);
+			continue;
+		}
+		const inner = sf.type?.kind === "pointer" ? sf.type.base : sf.type;
+		const name = (
+			sf.embeddedName ??
+			sf.astType?.name ??
+			sf.type?.name ??
+			sf.type?.base?.name ??
+			(inner?.kind === "named" ? inner.name : "")
+		)
+			.split(".")
+			.pop();
+		if (name) own.push([name, st.fields.get(name) ?? sf.type]);
+	}
+	return own;
+}
+
+function structDesc(n, st, sub) {
+	const f = [];
+	for (const [name, ft] of structOwnFields(st)) f.push([name, sub(ft)]);
+	return { k: "struct", n, f };
+}
+
+function namedDesc(t, resolve, depth, sub) {
+	const n = qualify(t.name ?? "");
+	const u = resolve(t.underlying) ?? t.underlying;
+	if (!u) return { k: "named", n, u: null };
+	if (u.kind === "struct")
+		return depth > MAX_DEPTH
+			? { k: "struct", n, f: null }
+			: structDesc(n, u, sub);
+	if (u.kind === "interface") return { k: "i", n };
+	return { k: "named", n, u: depth > MAX_DEPTH ? null : sub(u) };
+}
+
+/**
+ * Whether a type descriptor mentions a float32 or float64.  Such operands
+ * travel with their static type: a number alone cannot tell `float64(1e6)`
+ * (Go prints 1e+06) from an `int`, or a float32 from the float64 holding the
+ * same bits.
+ * @param {any} desc result of fmtTypeDesc
+ * @returns {boolean}
+ */
+export function fmtDescHasFloat(desc) {
+	if (!desc || typeof desc !== "object") return false;
+	switch (desc.k) {
+		case "b":
+			return desc.n === "float32" || desc.n === "float64";
+		case "named":
+			return fmtDescHasFloat(desc.u);
+		case "struct":
+			return (desc.f ?? []).some(([, ft]) => fmtDescHasFloat(ft));
+		case "ptr":
+		case "slice":
+		case "array":
+			return fmtDescHasFloat(desc.e);
+		case "map":
+			return fmtDescHasFloat(desc.key) || fmtDescHasFloat(desc.val);
+		default:
+			return false;
+	}
+}
+
+/**
+ * Whether a type descriptor is a slice or array (possibly named).  `%s`, `%q`
+ * and `%x` read a byte slice as text, which a plain list of numbers cannot
+ * tell from any other slice of small numbers.
+ * @param {any} desc result of fmtTypeDesc
+ * @returns {boolean}
+ */
+export function fmtDescIsSeq(desc) {
+	let d = desc;
+	while (d?.k === "named") d = d.u;
+	return d?.k === "slice" || d?.k === "array";
+}
+
+/**
+ * Whether a call with this literal format string needs operand types: `%T`,
+ * `%#v`, an unknown verb (`%!z(int=5)`), or more operands than verbs
+ * (`%!(EXTRA int=1)`).
+ * @param {unknown} format
+ * @param {number} nargs operand count, -1 when not known statically
+ * @param {boolean} [seqArgs] some operand is a slice or array, whose element
+ *   type decides how `%s`, `%q`, `%x` and `%X` read it
+ */
+export function fmtWantsTypes(format, nargs, seqArgs = false) {
+	if (typeof format !== "string") return false;
+	const re = new RegExp(
+		`%([${FLAGS}]*)((?:\\[\\d+\\])?(?:\\*|\\d+)?(?:\\.(?:\\[\\d+\\])?(?:\\*|\\d*))?(?:\\[\\d+\\])?)([^]?)`,
+		"g",
+	);
+	let count = 0;
+	let indexed = false;
+	for (const m of format.matchAll(re)) {
+		const verb = m[3];
+		if (verb === "%") continue;
+		if (verb === "T" || verb === "p") return true;
+		if (verb === "v" && m[1].includes("#")) return true;
+		if (seqArgs && "sqxX".includes(verb)) return true;
+		if (verb !== "" && !VERBS.includes(verb) && verb !== "w") return true;
+		if (/[[*]/.test(m[2])) indexed = true;
+		count++;
+	}
+	return nargs >= 0 && !indexed && nargs > count;
+}