From efbb1a790b9a6eab80bcca0d4d2ecf5f82e40546 Mon Sep 17 00:00:00 2001
From: Dylan Piercey <pierceydylan@gmail.com>
Date: Fri, 3 Jul 2026 22:00:21 +0000
Subject: [PATCH] Optimize class attributes built from CSS module classes

A `class` value assembled from CSS module classes (a stylesheet import or a
`<style/name>` object) previously bailed to the runtime `classValue` walker,
since `styles.foo` is a member expression the constant folder can't resolve.

Recognize these as known class strings so the optimizer can treat them like
static tokens: HTML concatenates them directly, DOM applies constant classes
once at mount and toggles the conditional ones in place, and `_attr_class_item`
handles a class that resolves to multiple tokens (eg from `composes:`). In
development a class that resolves to a non-string logs a warning; the wrapper is
compiled away in optimized builds.
---
 .changeset/css-module-class-optimization.md   |   5 +
 .sizes.json                                   |   4 +-
 .sizes/dom.js                                 |  10 +-
 .../__snapshots__/dom.bundle.debug.js         |  16 +
 .../__snapshots__/html.bundle.debug.js        |  11 +
 .../__snapshots__/html.bundle.js              |   8 +
 .../attr-class-css-module-style/sizes.json    |   3 +
 .../template.marko                            |  10 +
 .../attr-class-css-module-style/test.ts       |   8 +
 .../__snapshots__/dom.bundle.debug.js         |  29 ++
 .../__snapshots__/html.bundle.debug.js        |  17 +
 .../__snapshots__/html.bundle.js              |  14 +
 .../fixtures/attr-class-css-module/sizes.json |   3 +
 .../attr-class-css-module/styles.module.css   |  12 +
 .../attr-class-css-module/template.marko      |  14 +
 .../fixtures/attr-class-css-module/test.ts    |   8 +
 .../define-tag-for-attribute-tag/sizes.json   |   4 +-
 packages/runtime-tags/src/common/helpers.ts   |  18 ++
 packages/runtime-tags/src/dom.ts              |   2 +-
 packages/runtime-tags/src/dom/dom.ts          |   9 +-
 packages/runtime-tags/src/html.ts             |   1 +
 .../runtime-tags/src/translator/core/style.ts |   9 +
 .../src/translator/util/css-module-class.ts   |  85 +++++
 .../src/translator/visitors/tag/native-tag.ts | 299 +++++++++++++++---
 24 files changed, 542 insertions(+), 57 deletions(-)
 create mode 100644 .changeset/css-module-class-optimization.md
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/dom.bundle.debug.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.debug.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/sizes.json
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/template.marko
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/test.ts
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/dom.bundle.debug.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.debug.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.js
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/sizes.json
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/styles.module.css
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/template.marko
 create mode 100644 packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/test.ts
 create mode 100644 packages/runtime-tags/src/translator/util/css-module-class.ts

diff --git a/.changeset/css-module-class-optimization.md b/.changeset/css-module-class-optimization.md
new file mode 100644
index 00000000000..5c0a7199aa8
--- /dev/null
+++ b/.changeset/css-module-class-optimization.md
@@ -0,0 +1,5 @@
+---
+"@marko/runtime-tags": patch
+---
+
+Optimize `class` attributes built from CSS module classes. A member access on a CSS module - a default/namespace import from a stylesheet, or a `<style/name>` tag's object - is now treated as a known class string, so `class=[styles.card, { [styles.active]: on }]` no longer falls back to the runtime `class` walker. Constant classes are folded into the concatenated string on the server and applied once at mount on the client, while toggles update in place. `_attr_class_item` now also handles a class that resolves to multiple space-separated tokens (eg from `composes:`). In development, a CSS module class that resolves to a non-string (a typo or a class missing from the stylesheet) logs a warning; this assertion is compiled away in optimized builds.
diff --git a/.sizes.json b/.sizes.json
index 3d97219db90..faeb661f068 100644
--- a/.sizes.json
+++ b/.sizes.json
@@ -7,8 +7,8 @@
     {
       "name": "*",
       "total": {
-        "min": 25867,
-        "brotli": 9506
+        "min": 25968,
+        "brotli": 9546
       }
     },
     {
diff --git a/.sizes/dom.js b/.sizes/dom.js
index 721fb89d245..81174262885 100644
--- a/.sizes/dom.js
+++ b/.sizes/dom.js
@@ -1,4 +1,4 @@
-// size: 25867 (min) 9506 (brotli)
+// size: 25968 (min) 9546 (brotli)
 //#region packages/runtime-tags/dist/dom.mjs
 let empty = [],
   rest = Symbol(),
@@ -327,6 +327,9 @@ function _call(fn, v) {
 function stringifyClassObject(name, value) {
   return value ? name : "";
 }
+function _class_module_value(value, name) {
+  return value;
+}
 function stringifyStyleObject(name, value) {
   return value || value === 0 ? name + ":" + value : "";
 }
@@ -1449,7 +1452,10 @@ function _attr_class_items(element, items) {
   for (let key in items) _attr_class_item(element, key, items[key]);
 }
 function _attr_class_item(element, name, value) {
-  element.classList.toggle(name, !!value);
+  let { classList } = element;
+  if (~name.indexOf(" "))
+    for (let token of name.split(" ")) classList.toggle(token, !!value);
+  else classList.toggle(name, !!value);
 }
 function _attr_style(element, value) {
   setAttribute(
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/dom.bundle.debug.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/dom.bundle.debug.js
new file mode 100644
index 00000000000..2db05b90292
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/dom.bundle.debug.js
@@ -0,0 +1,16 @@
+// template.marko
+const $template = "<div></div><div></div>";
+const $walks = " b b";
+function $setup($scope) {
+	_attr_class_item($scope["#div/0"], _class_module_value(void 0, "card"), 1);
+	_attr_class_item($scope["#div/1"], _class_module_value(void 0, "card"), 1);
+}
+const $active = /* @__PURE__ */ _const("active", ($scope) => {
+	_attr_class_item($scope["#div/0"], _class_module_value(void 0, "on"), $scope.active);
+	_attr_class_item($scope["#div/1"], _class_module_value(void 0, "on"), $scope.active);
+});
+const $input = ($scope, input) => $active($scope, input.active);
+var template_default = /* @__PURE__ */ _template("__tests__/template.marko", $template, $walks, $setup, $input);
+
+// v:template.marko.module.css
+var v_template_marko_module_default = "\n  .card { color: green }\n  .on { color: blue }\n";
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.debug.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.debug.js
new file mode 100644
index 00000000000..ea5103bfd74
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.debug.js
@@ -0,0 +1,11 @@
+// v:template.marko.module.css
+var v_template_marko_module_default = "\n  .card { color: green }\n  .on { color: blue }\n";
+
+// template.marko
+var template_default = _template("__tests__/template.marko", (input) => {
+	const $scope0_reason = _scope_reason(), $sg__input_active = _serialize_guard($scope0_reason, 0);
+	const $scope0_id = _scope_id();
+	const { active } = input;
+	_html(`<div${_attr_class(`${_class_module_value(void 0, "card")}${active ? " " + _class_module_value(void 0, "on") : ""}`)}></div>${_el_resume($scope0_id, "#div/0", $sg__input_active)}<div${_attr_class(`${_class_module_value(void 0, "card")}${active ? " " + _class_module_value(void 0, "on") : ""}`)}></div>${_el_resume($scope0_id, "#div/1", $sg__input_active)}`);
+	_serialize_if($scope0_reason, 0) && writeScope($scope0_id, {}, "__tests__/template.marko", 0);
+}, 1);
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.js
new file mode 100644
index 00000000000..8bcf7951c19
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/__snapshots__/html.bundle.js
@@ -0,0 +1,8 @@
+// template.marko
+var template_default = _template("a", (input) => {
+	const $scope0_reason = _scope_reason(), $sg__input_active = _serialize_guard($scope0_reason, 0);
+	const $scope0_id = _scope_id();
+	const { active } = input;
+	_html(`<div${_attr_class(`${void 0}${active ? " " + void 0 : ""}`)}></div>${_el_resume($scope0_id, "a", $sg__input_active)}<div${_attr_class(`${void 0}${active ? " " + void 0 : ""}`)}></div>${_el_resume($scope0_id, "b", $sg__input_active)}`);
+	_serialize_if($scope0_reason, 0) && writeScope($scope0_id, {});
+}, 1);
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/sizes.json b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/sizes.json
new file mode 100644
index 00000000000..6fb6860b420
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/sizes.json
@@ -0,0 +1,3 @@
+{
+  "dom": {}
+}
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/template.marko b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/template.marko
new file mode 100644
index 00000000000..9e903fed140
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/template.marko
@@ -0,0 +1,10 @@
+<style/styles>
+  .card { color: green }
+  .on { color: blue }
+</style>
+
+<const/{ active }=input/>
+
+// A `<style/var>` object resolves classes the same way a module import does.
+<div class=[styles.card, { [styles.on]: active }]/>
+<div class=[styles.card, active && styles.on]/>
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/test.ts b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/test.ts
new file mode 100644
index 00000000000..8d039fc48a0
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module-style/test.ts
@@ -0,0 +1,8 @@
+import type { TestConfig } from "../../main.test";
+
+// CSS module class values are supplied by the bundler, not this harness (which
+// loads `.css` as text), so this fixture asserts on the compiled output only.
+export const config: TestConfig = {
+  skip_csr: true,
+  skip_ssr: true,
+};
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/dom.bundle.debug.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/dom.bundle.debug.js
new file mode 100644
index 00000000000..5c01c160047
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/dom.bundle.debug.js
@@ -0,0 +1,29 @@
+// template.marko
+const $template = "<div></div><div></div><div></div><div></div><div class=base></div>";
+const $walks = " b b b b b";
+function $setup($scope) {
+	_attr_class_item($scope["#div/0"], _class_module_value(styles_module_default.card, "card"), 1);
+	_attr_class_item($scope["#div/3"], _class_module_value(styles_module_default.card, "card"), 1);
+	_attr_class_item($scope["#div/4"], _class_module_value(styles_module_default.card, "card"), 1);
+}
+const $active = /* @__PURE__ */ _const("active", ($scope) => {
+	_attr_class_item($scope["#div/0"], _class_module_value(styles_module_default.on, "on"), $scope.active);
+	_attr_class_item($scope["#div/1"], _class_module_value(styles_module_default.on, "on"), $scope.active);
+	_attr_class_item($scope["#div/3"], _class_module_value(styles_module_default.on, "on"), $scope.active);
+	_attr_class_item($scope["#div/4"], _class_module_value(styles_module_default.on, "on"), $scope.active);
+});
+const $input_x__OR__input_y = /* @__PURE__ */ _or(10, ($scope) => _attr_class_items($scope["#div/2"], {
+	[_class_module_value(styles_module_default.a, "a")]: $scope.x,
+	[_class_module_value(styles_module_default.b, "b")]: $scope.y
+}));
+const $x = /* @__PURE__ */ _const("x", $input_x__OR__input_y);
+const $y = /* @__PURE__ */ _const("y", $input_x__OR__input_y);
+const $input = ($scope, input) => {
+	$active($scope, input.active);
+	$x($scope, input.x);
+	$y($scope, input.y);
+};
+var template_default = /* @__PURE__ */ _template("__tests__/template.marko", $template, $walks, $setup, $input);
+
+// styles.module.css
+var styles_module_default = ".card {\n  color: green;\n}\n.on {\n  color: blue;\n}\n.a {\n  color: red;\n}\n.b {\n  color: teal;\n}\n";
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.debug.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.debug.js
new file mode 100644
index 00000000000..d624b53eb50
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.debug.js
@@ -0,0 +1,17 @@
+// styles.module.css
+var styles_module_default = ".card {\n  color: green;\n}\n.on {\n  color: blue;\n}\n.a {\n  color: red;\n}\n.b {\n  color: teal;\n}\n";
+
+// template.marko
+var template_default = _template("__tests__/template.marko", (input) => {
+	const $scope0_reason = _scope_reason(), $sg__input_active = _serialize_guard($scope0_reason, 2);
+	const $scope0_id = _scope_id();
+	const { active, x, y } = input;
+	_html(`<div${_attr_class(`${_class_module_value(styles_module_default.card, "card")}${active ? " " + _class_module_value(styles_module_default.on, "on") : ""}`)}></div>${_el_resume($scope0_id, "#div/0", $sg__input_active)}<div${_attr_class(active ? _class_module_value(styles_module_default.on, "on") : "")}></div>${_el_resume($scope0_id, "#div/1", $sg__input_active)}<div${_attr_class([x && _class_module_value(styles_module_default.a, "a"), y && _class_module_value(styles_module_default.b, "b")])}></div>${_el_resume($scope0_id, "#div/2", _serialize_guard($scope0_reason, 0))}<div${_attr_class(`${_class_module_value(styles_module_default.card, "card")}${active ? " " + _class_module_value(styles_module_default.on, "on") : ""}`)}></div>${_el_resume($scope0_id, "#div/3", $sg__input_active)}<div${_attr_class(`base ${_class_module_value(styles_module_default.card, "card")}${active ? " " + _class_module_value(styles_module_default.on, "on") : ""}`)}></div>${_el_resume($scope0_id, "#div/4", $sg__input_active)}`);
+	_serialize_if($scope0_reason, 1) && writeScope($scope0_id, {
+		x: _serialize_if($scope0_reason, 4) && x,
+		y: _serialize_if($scope0_reason, 3) && y
+	}, "__tests__/template.marko", 0, {
+		x: "3:18",
+		y: "3:21"
+	});
+}, 1);
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.js b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.js
new file mode 100644
index 00000000000..a797c5be2e4
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/__snapshots__/html.bundle.js
@@ -0,0 +1,14 @@
+// styles.module.css
+var styles_module_default = ".card {\n  color: green;\n}\n.on {\n  color: blue;\n}\n.a {\n  color: red;\n}\n.b {\n  color: teal;\n}\n";
+
+// template.marko
+var template_default = _template("a", (input) => {
+	const $scope0_reason = _scope_reason(), $sg__input_active = _serialize_guard($scope0_reason, 2);
+	const $scope0_id = _scope_id();
+	const { active, x, y } = input;
+	_html(`<div${_attr_class(`${styles_module_default.card}${active ? " " + styles_module_default.on : ""}`)}></div>${_el_resume($scope0_id, "a", $sg__input_active)}<div${_attr_class(active ? styles_module_default.on : "")}></div>${_el_resume($scope0_id, "b", $sg__input_active)}<div${_attr_class([x && styles_module_default.a, y && styles_module_default.b])}></div>${_el_resume($scope0_id, "c", _serialize_guard($scope0_reason, 0))}<div${_attr_class(`${styles_module_default.card}${active ? " " + styles_module_default.on : ""}`)}></div>${_el_resume($scope0_id, "d", $sg__input_active)}<div${_attr_class(`base ${styles_module_default.card}${active ? " " + styles_module_default.on : ""}`)}></div>${_el_resume($scope0_id, "e", $sg__input_active)}`);
+	_serialize_if($scope0_reason, 1) && writeScope($scope0_id, {
+		i: _serialize_if($scope0_reason, 4) && x,
+		j: _serialize_if($scope0_reason, 3) && y
+	});
+}, 1);
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/sizes.json b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/sizes.json
new file mode 100644
index 00000000000..6fb6860b420
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/sizes.json
@@ -0,0 +1,3 @@
+{
+  "dom": {}
+}
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/styles.module.css b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/styles.module.css
new file mode 100644
index 00000000000..7a2570568b7
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/styles.module.css
@@ -0,0 +1,12 @@
+.card {
+  color: green;
+}
+.on {
+  color: blue;
+}
+.a {
+  color: red;
+}
+.b {
+  color: teal;
+}
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/template.marko b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/template.marko
new file mode 100644
index 00000000000..5443af1d8aa
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/template.marko
@@ -0,0 +1,14 @@
+import styles from "./styles.module.css";
+
+<const/{ active, x, y }=input/>
+
+// always-applied member + toggle
+<div class=[styles.card, { [styles.on]: active }]/>
+// single toggle
+<div class={ [styles.on]: active }/>
+// pure multi-toggle
+<div class={ [styles.a]: x, [styles.b]: y }/>
+// array-boolean idiom
+<div class=[styles.card, active && styles.on]/>
+// static literal mixed with a css module class
+<div class=["base", styles.card, { [styles.on]: active }]/>
diff --git a/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/test.ts b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/test.ts
new file mode 100644
index 00000000000..8d039fc48a0
--- /dev/null
+++ b/packages/runtime-tags/src/__tests__/fixtures/attr-class-css-module/test.ts
@@ -0,0 +1,8 @@
+import type { TestConfig } from "../../main.test";
+
+// CSS module class values are supplied by the bundler, not this harness (which
+// loads `.css` as text), so this fixture asserts on the compiled output only.
+export const config: TestConfig = {
+  skip_csr: true,
+  skip_ssr: true,
+};
diff --git a/packages/runtime-tags/src/__tests__/fixtures/define-tag-for-attribute-tag/sizes.json b/packages/runtime-tags/src/__tests__/fixtures/define-tag-for-attribute-tag/sizes.json
index 2813f6a0546..2a2d1247865 100644
--- a/packages/runtime-tags/src/__tests__/fixtures/define-tag-for-attribute-tag/sizes.json
+++ b/packages/runtime-tags/src/__tests__/fixtures/define-tag-for-attribute-tag/sizes.json
@@ -2,8 +2,8 @@
   "dom": {
     "template.marko.page.mjs": {
       "total": {
-        "min": 13430,
-        "brotli": 5130
+        "min": 13505,
+        "brotli": 5152
       },
       "files": {
         "tags/child.marko": 413,
diff --git a/packages/runtime-tags/src/common/helpers.ts b/packages/runtime-tags/src/common/helpers.ts
index a56ef0f7c8a..8f589753b84 100644
--- a/packages/runtime-tags/src/common/helpers.ts
+++ b/packages/runtime-tags/src/common/helpers.ts
@@ -57,6 +57,24 @@ export function stringifyClassObject(name: string, value: unknown) {
   return value ? name : "";
 }
 
+// Dev-only guard the translator wraps around CSS module class accesses (eg
+// `styles.foo`) in the optimized `class` attribute paths. A typo resolves to
+// `undefined`, which would otherwise fold silently into the class string; here
+// it surfaces as a warning. Compiled away in optimized builds (the translator
+// emits the bare access), so this is never on the production hot path.
+export function _class_module_value(value: unknown, name?: string) {
+  if (MARKO_DEBUG && typeof value !== "string") {
+    console.warn(
+      `Expected the CSS module class ${
+        name ? `\`${name}\`` : "access"
+      } to resolve to a string, but received ${
+        value === undefined ? "undefined" : `a ${typeof value}`
+      }. It may be a typo or missing from the stylesheet.`,
+    );
+  }
+  return value;
+}
+
 export function stringifyStyleObject(name: string, value: unknown) {
   return value || value === 0 ? name + ":" + value : "";
 }
diff --git a/packages/runtime-tags/src/dom.ts b/packages/runtime-tags/src/dom.ts
index 9872fe29744..861056c75ea 100644
--- a/packages/runtime-tags/src/dom.ts
+++ b/packages/runtime-tags/src/dom.ts
@@ -1,7 +1,7 @@
 export { attrTag, attrTags } from "./common/attr-tag";
 export { _assert_hoist } from "./common/errors";
 export { forIn, forOf, forTo, forUntil } from "./common/for";
-export { _call } from "./common/helpers";
+export { _call, _class_module_value } from "./common/helpers";
 export { $signal, $signalReset } from "./dom/abort-signal";
 export { compat } from "./dom/compat";
 export {
diff --git a/packages/runtime-tags/src/dom/dom.ts b/packages/runtime-tags/src/dom/dom.ts
index a5779024fa6..9bad45932d1 100644
--- a/packages/runtime-tags/src/dom/dom.ts
+++ b/packages/runtime-tags/src/dom/dom.ts
@@ -92,7 +92,14 @@ export function _attr_class_item(
   name: string,
   value: unknown,
 ) {
-  element.classList.toggle(name, !!value);
+  const { classList } = element;
+  // Only pay for a split when a CSS module class resolves to multiple tokens
+  // (eg `composes:`), which `classList.toggle` would reject as a single token.
+  if (~name.indexOf(" ")) {
+    for (const token of name.split(" ")) classList.toggle(token, !!value);
+  } else {
+    classList.toggle(name, !!value);
+  }
 }
 
 export function _attr_style(element: Element, value: unknown) {
diff --git a/packages/runtime-tags/src/html.ts b/packages/runtime-tags/src/html.ts
index 52367140091..3b141643215 100644
--- a/packages/runtime-tags/src/html.ts
+++ b/packages/runtime-tags/src/html.ts
@@ -4,6 +4,7 @@ export {
   _el_read_error,
   _hoist_read_error,
 } from "./common/errors";
+export { _class_module_value } from "./common/helpers";
 export { _flush_head, withLoadAssets, withPageAssets } from "./html/assets";
 export {
   _attr,
diff --git a/packages/runtime-tags/src/translator/core/style.ts b/packages/runtime-tags/src/translator/core/style.ts
index f87e9dbcb66..e41265a553c 100644
--- a/packages/runtime-tags/src/translator/core/style.ts
+++ b/packages/runtime-tags/src/translator/core/style.ts
@@ -16,6 +16,7 @@ import path from "path";
 
 import { WalkCode } from "../../common/types";
 import { addAssetImport } from "../util/asset-imports";
+import { registerStyleModuleVar } from "../util/css-module-class";
 import { isCoreTagName } from "../util/is-core-tag";
 import { isOutputDOM } from "../util/marko-config";
 import normalizeStringExpression from "../util/normalize-string-expression";
@@ -91,6 +92,14 @@ export default {
       addAssetImport(file, importPath);
     }
 
+    // Record the `var` name (eg `<style/styles>`) so the `class` attribute
+    // optimizer recognizes `styles.foo` as a CSS module class. Done in analyze
+    // because translate removes this tag and emits the backing import late,
+    // after which the name is no longer resolvable as a binding.
+    if (t.isIdentifier(node.var)) {
+      registerStyleModuleVar(node.var.name);
+    }
+
     if (names) {
       analyzeDynamicStyle(tag, names);
       // Dynamic styles write their shell statement in setup.
diff --git a/packages/runtime-tags/src/translator/util/css-module-class.ts b/packages/runtime-tags/src/translator/util/css-module-class.ts
new file mode 100644
index 00000000000..e25072834b5
--- /dev/null
+++ b/packages/runtime-tags/src/translator/util/css-module-class.ts
@@ -0,0 +1,85 @@
+import { types as t } from "@marko/compiler";
+import { getProgram } from "@marko/compiler/babel-utils";
+
+// A member access whose object is a CSS module resolves to a class string at
+// runtime (the bundler fills in the value). We can't know the string, but
+// knowing it *is* a string lets the `class` attribute optimizer treat it like a
+// static token instead of an opaque value handed to the runtime walker.
+const CSS_MODULE_SOURCE_REG = /\.(css|less|s[ac]ss|styl|stylus|p?css)($|\?)/i;
+
+declare module "@marko/compiler/dist/types" {
+  export interface NodeExtra {
+    styleModuleVars?: Set<string>;
+  }
+}
+
+/**
+ * Records that a `<style/name>` tag introduces `name` as a CSS module object.
+ * Called from the `<style>` tag's analyze so the name is known before any
+ * translate runs (translate removes the tag and emits the backing import, at
+ * which point the binding is no longer inspectable).
+ */
+export function registerStyleModuleVar(name: string) {
+  const program = getProgram().node;
+  ((program.extra ??= {}).styleModuleVars ??= new Set()).add(name);
+}
+
+/**
+ * True when `expr` is `obj.prop` / `obj["prop"]` with a statically known key and
+ * `obj` is a CSS module: either a default/namespace import from a stylesheet
+ * source, or the `var` of a `<style>` tag (which compiles to such an import).
+ */
+export function isCSSModuleClass(
+  expr: t.Expression | t.PrivateName,
+  scope: {
+    getBinding(name: string): { kind: string; path: t.NodePath } | void;
+  },
+): expr is t.MemberExpression {
+  if (!t.isMemberExpression(expr) || !t.isIdentifier(expr.object)) {
+    return false;
+  }
+
+  // Require a statically known property (`styles.foo` / `styles["foo"]`) so the
+  // access is a constant class string with no reactive dependency of its own.
+  if (
+    expr.computed
+      ? !t.isStringLiteral(expr.property)
+      : !t.isIdentifier(expr.property)
+  ) {
+    return false;
+  }
+
+  // A `<style/var>` matches by name in both phases. Checked before the binding
+  // because analyze still sees the tag's local binding while translate (which
+  // has removed the tag) sees none - relying on the binding would disagree.
+  if (getProgram().node.extra?.styleModuleVars?.has(expr.object.name)) {
+    return true;
+  }
+
+  const binding = scope.getBinding(expr.object.name);
+  if (!binding || binding.kind !== "module") {
+    return false;
+  }
+
+  const specifier = binding.path.node;
+  const decl = binding.path.parent;
+  return (
+    t.isImportDeclaration(decl) &&
+    (t.isImportDefaultSpecifier(specifier) ||
+      t.isImportNamespaceSpecifier(specifier)) &&
+    CSS_MODULE_SOURCE_REG.test(decl.source.value)
+  );
+}
+
+/** The accessed class name, when statically known, for dev diagnostics. */
+export function cssModuleClassName(
+  expr: t.MemberExpression,
+): string | undefined {
+  if (!expr.computed && t.isIdentifier(expr.property)) {
+    return expr.property.name;
+  }
+  if (expr.computed && t.isStringLiteral(expr.property)) {
+    return expr.property.value;
+  }
+  return undefined;
+}
diff --git a/packages/runtime-tags/src/translator/visitors/tag/native-tag.ts b/packages/runtime-tags/src/translator/visitors/tag/native-tag.ts
index 7f63b96e3ed..109f7456285 100644
--- a/packages/runtime-tags/src/translator/visitors/tag/native-tag.ts
+++ b/packages/runtime-tags/src/translator/visitors/tag/native-tag.ts
@@ -18,13 +18,21 @@ import {
 } from "../../../common/helpers";
 import { WalkCode } from "../../../common/types";
 import { bodyToTextLiteral } from "../../util/body-to-text-literal";
+import {
+  cssModuleClassName,
+  isCSSModuleClass,
+} from "../../util/css-module-class";
 import evaluate from "../../util/evaluate";
 import { generateUidIdentifier } from "../../util/generate-uid";
 import { getAccessorProp } from "../../util/get-accessor-char";
 import { getTagName } from "../../util/get-tag-name";
 import { isEventOrChangeHandler } from "../../util/is-event-or-change-handler";
 import { isTextOnlyNativeTag } from "../../util/is-non-html-text";
-import { getMarkoOpts, isOutputHTML } from "../../util/marko-config";
+import {
+  getMarkoOpts,
+  isOptimize,
+  isOutputHTML,
+} from "../../util/marko-config";
 import normalizeStringExpression from "../../util/normalize-string-expression";
 import { includes, type Opt, push } from "../../util/optional";
 import {
@@ -319,6 +327,17 @@ export default {
             !evaluate(attr.value).confident
           ) {
             addSetupExpr(tagSection, attr.value);
+
+            // Constant CSS module classes are applied once in setup (see the DOM
+            // `class` codegen). Their extras merge into the reactive value, so
+            // force setup here to match, or analysis mis-predicts an empty setup.
+            if (name === "class") {
+              const meta = emptyDelimitedAttrMeta(tag.scope);
+              trackDelimitedAttrValue(attr.value, meta);
+              if (!meta.dynamicItems && meta.stringItems) {
+                addSetupStatement(tagSection);
+              }
+            }
           }
         }
 
@@ -472,7 +491,8 @@ export default {
                     },
                     (branch) =>
                       buildStringAttrAnd(helper, branch) ||
-                      (name === "class" && buildClassAttrExpression(branch)) ||
+                      (name === "class" &&
+                        buildClassAttrExpression(branch, tag.scope)) ||
                       callRuntime(helper, branch),
                   ),
                 )}`;
@@ -763,57 +783,91 @@ export default {
                 write`${getHTMLRuntime()[helper](computed)}`;
               } else {
                 const nodeExpr = createScopeReadExpression(nodeBinding!);
-                const meta: DelimitedAttrMeta = {
-                  staticItems: undefined,
-                  dynamicItems: undefined,
-                  dynamicValues: undefined,
-                };
-                let stmt: undefined | t.Statement;
+                const meta = emptyDelimitedAttrMeta(
+                  name === "class" ? tag.scope : undefined,
+                );
                 trackDelimitedAttrValue(value, meta);
 
                 if (meta.dynamicItems) {
-                  stmt = t.expressionStatement(
-                    callRuntime(helper, nodeExpr, value),
+                  addStatement(
+                    "render",
+                    tagSection,
+                    valueReferences,
+                    t.expressionStatement(callRuntime(helper, nodeExpr, value)),
+                    undefined,
+                    true,
                   );
-                } else {
-                  if (meta.staticItems) {
-                    write`${getHTMLRuntime()[helper](meta.staticItems)}`;
-                  }
+                  break;
+                }
 
-                  if (meta.dynamicValues) {
-                    const keys = Object.keys(meta.dynamicValues);
+                // Static literals fold into the SSR'd attribute.
+                if (meta.staticItems) {
+                  write`${getHTMLRuntime()[helper](meta.staticItems)}`;
+                }
 
-                    if (keys.length === 1) {
-                      const [key] = keys;
-                      const value = meta.dynamicValues[key];
-                      stmt = t.expressionStatement(
+                // Always-applied CSS module classes are constant, so `classList`
+                // them on once at mount rather than inside a reactive signal.
+                if (meta.stringItems) {
+                  for (const item of meta.stringItems) {
+                    addStatement(
+                      "render",
+                      tagSection,
+                      undefined,
+                      t.expressionStatement(
                         callRuntime(
                           `_attr_${name}_item`,
                           nodeExpr,
-                          t.stringLiteral(key),
-                          value,
+                          classModuleValue(item),
+                          t.numericLiteral(1),
                         ),
-                      );
-                    } else {
-                      const props: t.ObjectExpression["properties"] = [];
-                      for (const key of keys) {
-                        const value = meta.dynamicValues[key];
-                        props.push(
-                          t.objectProperty(toPropertyName(key), value),
-                        );
-                      }
-
-                      stmt = t.expressionStatement(
-                        callRuntime(
-                          `_attr_${name}_items`,
-                          nodeExpr,
-                          t.objectExpression(props),
-                        ),
-                      );
-                    }
+                      ),
+                      undefined,
+                      false,
+                    );
                   }
                 }
 
+                // Toggles (static keys and CSS module keys) update reactively.
+                const toggles: [t.Expression, t.Expression][] = [];
+                if (meta.dynamicValues) {
+                  for (const key in meta.dynamicValues) {
+                    toggles.push([
+                      t.stringLiteral(key),
+                      meta.dynamicValues[key],
+                    ]);
+                  }
+                }
+                if (meta.stringToggles) {
+                  for (const [key, condition] of meta.stringToggles) {
+                    toggles.push([classModuleValue(key), condition]);
+                  }
+                }
+
+                let stmt: undefined | t.Statement;
+                if (toggles.length === 1) {
+                  const [key, condition] = toggles[0];
+                  stmt = t.expressionStatement(
+                    callRuntime(`_attr_${name}_item`, nodeExpr, key, condition),
+                  );
+                } else if (toggles.length > 1) {
+                  stmt = t.expressionStatement(
+                    callRuntime(
+                      `_attr_${name}_items`,
+                      nodeExpr,
+                      t.objectExpression(
+                        toggles.map(([key, condition]) =>
+                          key.type === "StringLiteral"
+                            ? t.objectProperty(
+                                toPropertyName(key.value),
+                                condition,
+                              )
+                            : t.objectProperty(key, condition, true),
+                        ),
+                      ),
+                    ),
+                  );
+                }
+
                 if (stmt) {
                   addStatement(
                     "render",
@@ -821,7 +875,7 @@ export default {
                     valueReferences,
                     stmt,
                     undefined,
-                    !!meta.dynamicItems,
+                    false,
                   );
                 }
               }
@@ -1421,18 +1475,25 @@ function buildStringAttrAnd(
 // toggle once: 1 toggle picks a precomputed literal; a few index a hoisted table
 // packed from the toggles; more concatenate the string for `_attr_class`.
 const MAX_PRECOMPUTED_CLASS_TOGGLES = 4;
-function buildClassAttrExpression(value: t.Expression) {
+function buildClassAttrExpression(
+  value: t.Expression,
+  cssScope: CSSModuleScope,
+) {
   if (value.type !== "ObjectExpression" && value.type !== "ArrayExpression") {
     return;
   }
 
-  const meta: DelimitedAttrMeta = {
-    staticItems: undefined,
-    dynamicItems: undefined,
-    dynamicValues: undefined,
-  };
+  const meta = emptyDelimitedAttrMeta(cssScope);
   trackDelimitedAttrValue(value, meta);
-  if (meta.dynamicItems || !meta.staticItems || !meta.dynamicValues) {
+  if (meta.dynamicItems) {
+    return;
+  }
+
+  if (meta.stringItems || meta.stringToggles) {
+    return buildCSSModuleClassExpression(meta);
+  }
+
+  if (!meta.staticItems || !meta.dynamicValues) {
     return;
   }
 
@@ -1519,11 +1580,126 @@ function buildClassAttrExpression(value: t.Expression) {
   return callRuntime("_attr_class", classes);
 }
 
+// HTML codegen for a `class` value whose parts are known class strings (static
+// literals + CSS module accesses). Concatenates them directly - `_attr_class`
+// still trims/escapes - instead of allocating the array/object and walking it.
+function buildCSSModuleClassExpression(meta: DelimitedAttrMeta) {
+  // Always-applied parts, in source order: the folded static base then each
+  // CSS module class. All are non-empty strings, so they need no guard.
+  const always: (string | t.Expression)[] = [];
+  const base = meta.staticItems
+    ? toDelimitedString(meta.staticItems, " ", stringifyClassObject)
+    : "";
+  if (base) always.push(base);
+  if (meta.stringItems) {
+    for (const item of meta.stringItems) always.push(classModuleValue(item));
+  }
+
+  // Toggles, as `[classExpression, condition]`. Static keys are literals; CSS
+  // module keys carry the dev assertion wrapper.
+  const toggles: [t.Expression, t.Expression][] = [];
+  if (meta.dynamicValues) {
+    for (const key in meta.dynamicValues) {
+      toggles.push([t.stringLiteral(key), meta.dynamicValues[key]]);
+    }
+  }
+  if (meta.stringToggles) {
+    for (const [key, condition] of meta.stringToggles) {
+      toggles.push([classModuleValue(key), condition]);
+    }
+  }
+
+  if (always.length) {
+    // A non-empty always-part seeds the string, so each toggle can safely
+    // prepend its own separator space when present.
+    const parts: (string | t.Expression)[] = [];
+    always.forEach((part, i) => {
+      if (i) parts.push(" ");
+      parts.push(part);
+    });
+    for (const [key, condition] of toggles) {
+      parts.push(
+        t.conditionalExpression(
+          condition,
+          prefixSpace(key),
+          t.stringLiteral(""),
+        ),
+      );
+    }
+    return callRuntime("_attr_class", normalizeStringExpression(parts)!);
+  }
+
+  if (toggles.length === 1) {
+    const [key, condition] = toggles[0];
+    return callRuntime(
+      "_attr_class",
+      t.conditionalExpression(condition, key, t.stringLiteral("")),
+    );
+  }
+
+  // Multiple toggles with no always-part: a leading separator would depend on
+  // which toggles are on, so hand the walker an array of `condition && class`
+  // and let it drop the falsy entries.
+  return callRuntime(
+    "_attr_class",
+    t.arrayExpression(
+      toggles.map(([key, condition]) =>
+        t.logicalExpression("&&", condition, key),
+      ),
+    ),
+  );
+}
+
+// Prepend a separating space to a class expression, folding it into the literal
+// when the class itself is a literal.
+function prefixSpace(value: t.Expression): t.Expression {
+  return value.type === "StringLiteral"
+    ? t.stringLiteral(" " + value.value)
+    : t.binaryExpression("+", t.stringLiteral(" "), value);
+}
+
+// Wrap a CSS module class access so a non-string (typo/missing class) warns in
+// development. Optimized builds emit the bare access - no runtime cost.
+function classModuleValue(access: t.MemberExpression): t.Expression {
+  if (isOptimize()) {
+    return access;
+  }
+  const name = cssModuleClassName(access);
+  return callRuntime(
+    "_class_module_value",
+    access,
+    name && t.stringLiteral(name),
+  );
+}
+
 interface DelimitedAttrMeta {
   staticItems: undefined | unknown[];
   dynamicItems: undefined | (t.Expression | t.SpreadElement)[];
   dynamicValues: undefined | Record<string, t.Expression>;
+  // Set only for `class` attributes: `cssScope` enables CSS module detection.
+  // `stringItems` are always-applied CSS module classes (eg `styles.foo`);
+  // `stringToggles` are `[classAccess, condition]` pairs from `{ [styles.x]: c }`
+  // or `c && styles.x`. Both hold expressions known to be class strings, so the
+  // optimizer can concatenate them instead of deferring to the runtime walker.
+  cssScope: undefined | CSSModuleScope;
+  stringItems: undefined | t.MemberExpression[];
+  stringToggles: undefined | [t.MemberExpression, t.Expression][];
+}
+type CSSModuleScope = Parameters<typeof isCSSModuleClass>[1];
+
+function emptyDelimitedAttrMeta(
+  cssScope: CSSModuleScope | undefined,
+): DelimitedAttrMeta {
+  return {
+    staticItems: undefined,
+    dynamicItems: undefined,
+    dynamicValues: undefined,
+    cssScope,
+    stringItems: undefined,
+    stringToggles: undefined,
+  };
 }
+
 function trackDelimitedAttrValue(expr: t.Expression, meta: DelimitedAttrMeta) {
   switch (expr.type) {
     case "ObjectExpression":
@@ -1533,6 +1709,8 @@ function trackDelimitedAttrValue(expr: t.Expression, meta: DelimitedAttrMeta) {
       trackDelimitedAttrArrayItems(expr, meta);
       break;
     default:
+      // A lone value (eg `class=styles.foo`) is already applied in one call, so
+      // there is nothing to split out - only array/object shapes benefit.
       (meta.dynamicItems ||= []).push(expr);
       break;
   }
@@ -1564,6 +1742,16 @@ function trackDelimitedAttrArrayItems(
           const evalItem = evaluate(item);
           if (evalItem.confident) {
             (meta.staticItems ||= []).push(evalItem.computed);
+          } else if (meta.cssScope && isCSSModuleClass(item, meta.cssScope)) {
+            (meta.stringItems ||= []).push(item);
+          } else if (
+            // The array-boolean idiom `condition && styles.foo`.
+            item.type === "LogicalExpression" &&
+            item.operator === "&&" &&
+            meta.cssScope &&
+            isCSSModuleClass(item.right, meta.cssScope)
+          ) {
+            (meta.stringToggles ||= []).push([item.right, item.left]);
           } else {
             (meta.dynamicItems ||= []).push(item);
           }
@@ -1581,11 +1769,24 @@ function trackDelimitedAttrObjectProperties(
   let staticProps: Record<string, unknown> | undefined;
   let dynamicProps: t.ObjectExpression["properties"] | undefined;
   for (const prop of obj.properties) {
-    if (prop.type !== "ObjectProperty" || prop.computed) {
+    if (prop.type !== "ObjectProperty") {
       (dynamicProps ||= []).push(prop);
       continue;
     }
 
+    if (prop.computed) {
+      // `{ [styles.foo]: condition }` - a toggle keyed by a CSS module class.
+      if (meta.cssScope && isCSSModuleClass(prop.key, meta.cssScope)) {
+        (meta.stringToggles ||= []).push([
+          prop.key,
+          prop.value as t.Expression,
+        ]);
+      } else {
+        (dynamicProps ||= []).push(prop);
+      }
+      continue;
+    }
+
     let key: string;
     if (prop.key.type === "Identifier") {
       key = prop.key.name;