@homebound/truss 2.14.0 → 2.15.1

package/build/plugin/index.d.ts

@@ -41,7 +41,8 @@ interface TrussEsbuildPluginOptions {
     outputCss?: string;
 }
 /**
- * esbuild plugin that transforms `Css.*.$` expressions and emits a `truss.css` file.
+ * esbuild plugin that transforms `Css.*.$` expressions, collects `.css.ts` blocks,
+ * and emits a `truss.css` file.
  *
  * Designed for library builds using tsup/esbuild. Transforms source files
  * during the build and writes an annotated `truss.css` alongside the output
@@ -101,6 +102,7 @@ interface TrussVitePlugin {
     transformIndexHtml?: (html: string) => string;
     handleHotUpdate?: (ctx: any) => void;
     generateBundle?: (options: any, bundle: any) => void;
+    writeBundle?: (options: any, bundle: any) => void;
 }
 /**
  * Vite plugin that transforms `Css.*.$` expressions from truss's CssBuilder DSL
@@ -111,7 +113,7 @@ interface TrussVitePlugin {
  * while imports are supplemented with a virtual CSS side-effect module.
  *
  * In dev mode, serves CSS via a virtual endpoint that the injected runtime keeps in sync.
- * In production, emits a single `truss.css` asset with all atomic rules.
+ * In production, emits a content-hashed CSS asset (e.g. `assets/truss-abc123.css`) for long-term caching.
  */
 declare function trussPlugin(opts: TrussPluginOptions): TrussVitePlugin;
 /** Load a truss mapping file synchronously (for tests). */

package/build/plugin/index.js

@@ -1,6 +1,7 @@
 // src/plugin/index.ts
-import { readFileSync as readFileSync3, existsSync } from "fs";
-import { resolve as resolve2, dirname, isAbsolute } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync, readdirSync } from "fs";
+import { resolve as resolve2, dirname, isAbsolute, join as join2 } from "path";
+import { createHash } from "crypto";
 
 // src/plugin/emit-truss.ts
 import * as t from "@babel/types";
@@ -3357,11 +3358,14 @@ function toVirtualCssSpecifier(source) {
 import { readFileSync } from "fs";
 var RULE_ANNOTATION_RE = /^\/\* @truss p:([\d.]+) c:(\S+) \*\/$/;
 var PROPERTY_ANNOTATION_RE = /^\/\* @truss @property \*\/$/;
+var ARBITRARY_START_RE = /^\/\* @truss arbitrary:start \*\/$/;
+var ARBITRARY_END_RE = /^\/\* @truss arbitrary:end \*\/$/;
 var PROPERTY_VAR_RE = /^@property\s+(--\S+)/;
 function parseTrussCss(cssText) {
   const lines = cssText.split("\n");
   const rules = [];
   const properties = [];
+  const arbitraryCssBlocks = [];
   let i = 0;
   while (i < lines.length) {
     const line = lines[i].trim();
@@ -3390,19 +3394,43 @@ function parseTrussCss(cssText) {
       i++;
       continue;
     }
+    if (ARBITRARY_START_RE.test(line)) {
+      i++;
+      const blockLines = [];
+      while (i < lines.length && !ARBITRARY_END_RE.test(lines[i].trim())) {
+        blockLines.push(lines[i]);
+        i++;
+      }
+      const blockText = blockLines.join("\n").trim();
+      if (blockText.length > 0) {
+        arbitraryCssBlocks.push({ cssText: blockText });
+      }
+      if (i < lines.length && ARBITRARY_END_RE.test(lines[i].trim())) {
+        i++;
+      }
+      continue;
+    }
     i++;
   }
-  return { rules, properties };
+  return { rules, properties, arbitraryCssBlocks };
 }
 function readTrussCss(filePath) {
   const content = readFileSync(filePath, "utf8");
   return parseTrussCss(content);
 }
+function annotateArbitraryCssBlock(cssText) {
+  const trimmed = cssText.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+  return ["/* @truss arbitrary:start */", trimmed, "/* @truss arbitrary:end */"].join("\n");
+}
 function mergeTrussCss(sources) {
   const seenClasses = /* @__PURE__ */ new Set();
   const allRules = [];
   const seenProperties = /* @__PURE__ */ new Set();
   const allProperties = [];
+  const allArbitraryCssBlocks = [];
   for (const source of sources) {
     for (const rule of source.rules) {
       if (!seenClasses.has(rule.className)) {
@@ -3416,6 +3444,7 @@ function mergeTrussCss(sources) {
         allProperties.push(prop);
       }
     }
+    allArbitraryCssBlocks.push(...source.arbitraryCssBlocks ?? []);
   }
   allRules.sort((a, b) => {
     const diff = a.priority - b.priority;
@@ -3431,6 +3460,9 @@ function mergeTrussCss(sources) {
     lines.push(`/* @truss @property */`);
     lines.push(prop.cssText);
   }
+  for (const block of allArbitraryCssBlocks) {
+    lines.push(annotateArbitraryCssBlock(block.cssText));
+  }
   return lines.join("\n");
 }
 
@@ -3439,6 +3471,7 @@ import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
 import { resolve, join } from "path";
 function trussEsbuildPlugin(opts) {
   const cssRegistry = /* @__PURE__ */ new Map();
+  const arbitraryCssRegistry = /* @__PURE__ */ new Map();
   let mapping = null;
   let outDir;
   return {
@@ -3447,6 +3480,18 @@ function trussEsbuildPlugin(opts) {
       outDir = build.initialOptions.outdir ?? build.initialOptions.outdir;
       build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
         const code = readFileSync2(args.path, "utf8");
+        if (args.path.endsWith(".css.ts")) {
+          if (!mapping) {
+            mapping = loadMapping(resolve(process.cwd(), opts.mapping));
+          }
+          const css = annotateArbitraryCssBlock(transformCssTs(code, args.path, mapping));
+          if (css.length > 0) {
+            arbitraryCssRegistry.set(args.path, css);
+          } else {
+            arbitraryCssRegistry.delete(args.path);
+          }
+          return { contents: code, loader: loaderForPath(args.path) };
+        }
         if (!code.includes("Css") && !code.includes("css=")) return void 0;
         if (!mapping) {
           mapping = loadMapping(resolve(process.cwd(), opts.mapping));
@@ -3463,8 +3508,11 @@ function trussEsbuildPlugin(opts) {
         return { contents: result.code, loader: loaderForPath(args.path) };
       });
       build.onEnd(() => {
-        if (cssRegistry.size === 0) return;
-        const css = generateCssText(cssRegistry);
+        if (cssRegistry.size === 0 && arbitraryCssRegistry.size === 0) return;
+        const cssParts = [generateCssText(cssRegistry), ...arbitraryCssRegistry.values()].filter(
+          (part) => part.length > 0
+        );
+        const css = cssParts.join("\n");
         const cssFileName = opts.outputCss ?? "truss.css";
         const cssPath = resolve(outDir ?? join(process.cwd(), "dist"), cssFileName);
         mkdirSync(resolve(cssPath, ".."), { recursive: true });
@@ -3483,6 +3531,7 @@ function loaderForPath(filePath) {
 // src/plugin/index.ts
 var VIRTUAL_CSS_PREFIX = "\0truss-css:";
 var CSS_TS_QUERY = "?truss-css";
+var TRUSS_CSS_PLACEHOLDER = "__TRUSS_CSS_HASH__";
 var VIRTUAL_CSS_ENDPOINT = "/virtual:truss.css";
 var VIRTUAL_RUNTIME_ID = "virtual:truss:runtime";
 var RESOLVED_VIRTUAL_RUNTIME_ID = "\0" + VIRTUAL_RUNTIME_ID;
@@ -3495,6 +3544,7 @@ function trussPlugin(opts) {
   let isTest = false;
   let isBuild = false;
   const libraryPaths = opts.libraries ?? [];
+  let emittedCssFileName = null;
   const cssRegistry = /* @__PURE__ */ new Map();
   let cssVersion = 0;
   let lastSentVersion = 0;
@@ -3562,8 +3612,9 @@ function trussPlugin(opts) {
     },
     transformIndexHtml(html) {
       if (isBuild) {
-        const link = `<link rel="stylesheet" href="./truss.css">`;
-        return html.replace("</head>", `    ${link}
+        const stripped = html.replace(/\s*<link[^>]*href=["'][^"']*virtual:truss\.css["'][^>]*\/?>/g, "").replace(/\s*<link[^>]*href=["'][^"']*__TRUSS_CSS_HASH__["'][^>]*\/?>/g, "").replace(/\s*<link[^>]*href=["'][^"']*\/assets\/truss-[0-9a-f]+\.css["'][^>]*\/?>/g, "");
+        const link = `<link rel="stylesheet" href="${TRUSS_CSS_PLACEHOLDER}">`;
+        return stripped.replace("</head>", `    ${link}
   </head>`);
       }
       const tag = `<script type="module" src="/${VIRTUAL_RUNTIME_ID}"></script>`;
@@ -3680,11 +3731,27 @@ __injectTrussCSS(${JSON.stringify(css)});
       if (!isBuild) return;
       const css = collectCss();
       if (!css) return;
+      const hash = createHash("sha256").update(css).digest("hex").slice(0, 8);
+      const fileName = `assets/truss-${hash}.css`;
+      emittedCssFileName = fileName;
       this.emitFile({
         type: "asset",
-        fileName: "truss.css",
+        fileName,
         source: css
       });
+    },
+    /** Patch HTML files on disk to replace the CSS placeholder with the hashed filename. */
+    writeBundle(options, _bundle) {
+      if (!emittedCssFileName) return;
+      const outDir = options.dir || join2(projectRoot, "dist");
+      for (const entry of readdirSync(outDir)) {
+        if (!entry.endsWith(".html")) continue;
+        const htmlPath = join2(outDir, entry);
+        const html = readFileSync3(htmlPath, "utf8");
+        if (html.includes(TRUSS_CSS_PLACEHOLDER)) {
+          writeFileSync2(htmlPath, html.replace(TRUSS_CSS_PLACEHOLDER, `/${emittedCssFileName}`), "utf8");
+        }
+      }
     }
   };
 }