From 266bc3e55822c21df528a774273ddbb9b9e5d524 Mon Sep 17 00:00:00 2001 From: Koji Wakayama Date: Tue, 11 Aug 2026 21:55:38 +0200 Subject: [PATCH 1/2] fix(css): give the unminified-CSS warning a remedy that works The missing-optimizer warning told developers to run `deno add @veryfront/ext-css-lightning`. Following it changes nothing. `@veryfront/ext-css-lightning` declares `activation: "explicit"`, so installing the package registers no CSSOptimizationEngine on its own -- only a `veryfront.config.ts` `extensions` entry activates it. The hint was borrowed from `resolve()`, where it is correct because those contracts are satisfied by auto-activating extensions. `deno add` is also the wrong command for a scaffolded project, which is an npm project. So the warning read as actionable, the developer acted on it, and the build still shipped unminified CSS with the same warning. On the 0.1.1229 ai-agent scaffold: 90,684 bytes before, and 90,684 bytes after `npm install @veryfront/ext-css-lightning`. Installing *and* adding the factory to `extensions` drops it to 71,506 bytes and clears the warning. State the effect first, name the package, and name the second step. The contract name leaves the instruction -- it is an internal registration hook no guide mentions, and `component=css-compiler` already identifies the source. Reporting stays once per process, as before. --- .../css-provider-session.test.ts | 24 ++++++++++++++----- src/html/styles-builder/tailwind-compiler.ts | 18 ++++++++++---- 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/src/html/styles-builder/css-provider-session.test.ts b/src/html/styles-builder/css-provider-session.test.ts index 95bf131258..5e238a7c3e 100644 --- a/src/html/styles-builder/css-provider-session.test.ts +++ b/src/html/styles-builder/css-provider-session.test.ts @@ -208,12 +208,15 @@ describe("styles-builder CSS provider sessions", () => { assertEquals(generated.css, "missing-optimizer|sheet|alpha"); }); - it("reports a missing optimizer once, with the package that provides one", () => { + it("reports a missing optimizer once, with the steps that actually enable one", () => { // `regenerateCSSByHash` acquires a session per request, so warning on every // acquisition made this line the most frequent entry in a hosted project's - // logs -- once per render, at warn level, naming a registration hook with no - // documented way to act on it. State the package that registers an engine, - // and say it once while the engine stays absent. + // logs -- once per render, at warn level. Say it once while the engine stays + // absent, and give the whole recipe: `@veryfront/ext-css-lightning` declares + // `activation: "explicit"`, so installing the package registers nothing on + // its own. Only a `veryfront.config.ts` `extensions` entry activates it, and + // advice that stops at the install leaves the developer with unminified CSS + // and no next step. installProcessor(createProcessor("warn-rearm")); register(CSSOptimizationEngineName, createOptimizer("warn-rearm")); // Observing an engine re-arms the warning, so this test does not depend on @@ -236,10 +239,19 @@ describe("styles-builder CSS provider sessions", () => { __resetLogRecordEmitterForTests(); } - const reports = records.filter((entry) => entry.message.includes("CSSOptimizationEngine")); + const reports = records.filter((entry) => entry.message.includes("not minified")); assertEquals(reports.length, 1); + const report = reports[0]?.message ?? ""; assertEquals(reports[0]?.level, "warn"); - assertEquals(reports[0]?.message.includes("@veryfront/ext-css-lightning"), true); + assertEquals(report.includes("@veryfront/ext-css-lightning"), true); + assertEquals(report.includes("veryfront.config.ts"), true); + assertEquals(report.includes("extensions"), true); + // `deno add` is wrong twice over: scaffolded projects are npm projects, and + // no package manager can activate an explicit-activation extension. + assertEquals(report.includes("deno add"), false); + // The contract name is an internal registration hook the guides never + // mention, so it cannot appear as the developer-facing instruction. + assertEquals(report.includes("CSSOptimizationEngine"), false); }); it("keeps minified and unminified output in separate cache identities", async () => { diff --git a/src/html/styles-builder/tailwind-compiler.ts b/src/html/styles-builder/tailwind-compiler.ts index 3964895a73..c5e8485eda 100644 --- a/src/html/styles-builder/tailwind-compiler.ts +++ b/src/html/styles-builder/tailwind-compiler.ts @@ -149,14 +149,24 @@ export function acquireCSSGenerationSession(minify: boolean): CSSGenerationSessi // // Once per process, not once per acquisition: regenerateCSSByHash acquires // a session on every cold-cache request, which made this the single most - // frequent line in a hosted project's logs. Name the package that registers - // an engine, or the message asks for a hook with no way to reach it. + // frequent line in a hosted project's logs. + // + // State the effect and the whole remedy. An earlier revision borrowed + // `resolve()`'s "install it with: deno add " hint, which is only + // true for an auto-activating extension: `@veryfront/ext-css-lightning` + // declares `activation: "explicit"`, so installing it registers nothing + // until a `veryfront.config.ts` `extensions` entry activates it, and + // scaffolded projects are npm projects where `deno add` is the wrong + // command besides. Advice that stops at the install reads as actionable and + // leaves the CSS exactly as unminified as before. The contract name stays + // out of the instruction: it is an internal registration hook the guides + // never mention, and `component=css-compiler` already identifies the source. reportedMissingOptimizationEngine = true; const recommendation = getRecommendation(CSSOptimizationEngineName); logger.warn( recommendation === undefined - ? "No CSSOptimizationEngine registered; emitting unminified CSS" - : `No CSSOptimizationEngine registered; emitting unminified CSS. Install one with: deno add ${recommendation}`, + ? "CSS is not minified: no CSS optimizer is active" + : `CSS is not minified: no CSS optimizer is active. Install ${recommendation}, then add it to "extensions" in veryfront.config.ts`, ); } const optimizationEngine = optimizationProvider === undefined From aabf75f452fd4736dc224969364e8c2160fe617f Mon Sep 17 00:00:00 2001 From: Koji Wakayama Date: Tue, 11 Aug 2026 22:06:59 +0200 Subject: [PATCH 2/2] fix(css): put the unminified-CSS warning in active voice AGENTS.md "Public copy rules" require present tense and active voice for warnings exposed to users, and name the product as "Veryfront". "CSS is not minified" is passive. Name the actor. Re-verified on the 0.1.1229 ai-agent scaffold: 90,740 bytes and the warning without the config entry, 71,506 bytes and no warning with it. --- src/html/styles-builder/css-provider-session.test.ts | 2 +- src/html/styles-builder/tailwind-compiler.ts | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/html/styles-builder/css-provider-session.test.ts b/src/html/styles-builder/css-provider-session.test.ts index 5e238a7c3e..27e2614b6b 100644 --- a/src/html/styles-builder/css-provider-session.test.ts +++ b/src/html/styles-builder/css-provider-session.test.ts @@ -239,7 +239,7 @@ describe("styles-builder CSS provider sessions", () => { __resetLogRecordEmitterForTests(); } - const reports = records.filter((entry) => entry.message.includes("not minified")); + const reports = records.filter((entry) => entry.message.includes("unminified CSS")); assertEquals(reports.length, 1); const report = reports[0]?.message ?? ""; assertEquals(reports[0]?.level, "warn"); diff --git a/src/html/styles-builder/tailwind-compiler.ts b/src/html/styles-builder/tailwind-compiler.ts index c5e8485eda..c57c7025f1 100644 --- a/src/html/styles-builder/tailwind-compiler.ts +++ b/src/html/styles-builder/tailwind-compiler.ts @@ -165,8 +165,8 @@ export function acquireCSSGenerationSession(minify: boolean): CSSGenerationSessi const recommendation = getRecommendation(CSSOptimizationEngineName); logger.warn( recommendation === undefined - ? "CSS is not minified: no CSS optimizer is active" - : `CSS is not minified: no CSS optimizer is active. Install ${recommendation}, then add it to "extensions" in veryfront.config.ts`, + ? "Veryfront emits unminified CSS because no CSS optimizer is active" + : `Veryfront emits unminified CSS because no CSS optimizer is active. Install ${recommendation}, then add it to "extensions" in veryfront.config.ts`, ); } const optimizationEngine = optimizationProvider === undefined