cssints 0.34.0 → 0.35.0

package/dist/vite.mjs

@@ -672,6 +672,7 @@ function cssints({ inner = false, exclude, devtools = false, opencode = false, e
 	const siteOf = /* @__PURE__ */ new Map();
 	let buildMap = false;
 	const callsOf = /* @__PURE__ */ new Map();
+	const sheetEdits = {};
 	const sheet = Effect.fnUntraced(function* (ids = [...usedBy.keys()]) {
 		return yield* renderSheet(ids.flatMap((id) => usedBy.get(id)?.split("\n") ?? []));
 	});
@@ -912,6 +913,7 @@ function cssints({ inner = false, exclude, devtools = false, opencode = false, e
 			yield* drop(file);
 		}
 		yield* Effect.sync(() => forgetWarnings([file]));
+		yield* Effect.sync(() => sheetEdits.last = file);
 		const graph = env.moduleGraph;
 		const affected = [.../* @__PURE__ */ new Set([...depsOf.get(file) ?? [], ...inflight])].flatMap((id) => graph.getModuleById(id) ?? []);
 		yield* Effect.sync(() => affected.forEach((m) => {
@@ -959,6 +961,9 @@ function cssints({ inner = false, exclude, devtools = false, opencode = false, e
 			server = s;
 			if (inner) return;
 			evaluator.server = evaluator.needed ? void 0 : s;
+			s.environments.client.hot.on("cssints:edits:get", (_, client) => {
+				if (sheetEdits.measured) client.send("cssints:edits", sheetEdits.measured);
+			});
 			s.environments.client.hot.on("cssints:sheet", (v) => {
 				if (!s.environments.client.moduleGraph.getModuleById(SHEET)?.transformResult?.code.includes(v)) Effect.runSync(reloadSheet());
 			});
@@ -983,6 +988,15 @@ function cssints({ inner = false, exclude, devtools = false, opencode = false, e
 			if (id === SHEET) {
 				if (build) return LAYERS;
 				const code = runSync(hook("vite.load", id, sheet()));
+				if (this.environment.name === "client" && server) {
+					const classes = new Set([...usedBy.values()].flatMap((v) => v.split("\n"))).size;
+					sheetEdits.measured = {
+						file: sheetEdits.last ? relative(root, sheetEdits.last) : "",
+						bytes: code.length,
+						classes
+					};
+					server.environments.client.hot.send("cssints:edits", sheetEdits.measured);
+				}
 				return {
 					code,
 					map: sheetMap(code, siteOf)

package/docs/API.md

@@ -4397,6 +4397,74 @@ TOKENS
 - **Its own styles do not touch yours.** The overlay is a custom element with a shadow root and its own cssints sheet, built with the package: the page's rules do not reach it, and its classes are not in your sheet or in the table.
 - **Limits.** The proximity of `@scope` is not ranked (no two looks set one property on one element), and a logical and a physical property (`margin-inline-start`, `margin-left`) are two properties, as `cn()` treats them; an element inside another shadow root is picked as its host; a page that Vite does not serve as HTML (server rendering) gets no entry.
 
+#### Vitals in the console (`@cssints/devtools/vitals`, 2026-11-07, cssints-0p4d)
+
+The panel inspects an element; this entry inspects the page, and prints to the console rather than drawing a DOM panel —
+the only surface a page that draws to a canvas has. No dev server, no overlay chunk and no cssints dependency of its own: a
+plain ES module (about 30 kB, 9.5 kB gzip) any page imports in dev.
+
+```ts
+// the app's entry, dev only
+import { observe, vitals } from "@cssints/devtools/vitals";
+observe(); // long tasks and long animation frames are not buffered: observe before the work
+
+// later, from the console:
+vitals(); // or window.vitals(): prints the report and returns it
+```
+
+```text skip
+cssints vitals
+265 ms · 214 nodes · 1 sheet · 380 classes
+vitals   FCP 412 ms · LCP 1.20 s (h1.hero) · CLS 0.002
+         INP 96 ms (button.primary) · 8+40+48 · TTFB 38 ms
+frames   p50 16.7 ms · p95 33.4 ms · max 51.2 ms · 3 dropped  ▁▂▃▅▇▆▃▂▁▂▃▅
+main     7 long tasks · 412 ms · max 120 ms · style+layout 41 ms · 0 errors · heap 42.1 MB
+sheet    64.4 kB · +29 B on src/registry/button/button.tsx · 3 loads · 81 B a class  ▁▁█
+load     2 sheets · 1 render-blocking · 66 ms to last · slow.css 65 ms (327 B)
+history  12 loads · LCP 1.20 s (−180 ms) (−312 B)  ▁▂▃▅▆▇▆▅
+CSS      41.2 kB · 380 rules · 1 902 decls · 0 blocked · specificity 0,3,2 (._1t8gqy5:hover)
+layer    _.k       ████████████████████ 22.4 kB
+tokens   14 colours · 2 fonts · 1 !important · custom props 12 declared / 9 used / 3 orphaned · keyframes 2 / 1 unused
+coverage 41 / 380 classes unused (11%)  cs-Landing-hero …
+```
+
+- **Web vitals** come from [web-vitals](https://github.com/GoogleChrome/web-vitals) (MIT), the reference implementation:
+  CLS is the largest session window of shifts (not their sum), INP is the ~98th percentile of interactions (not the worst),
+  and each metric names its culprit — the LCP element and render delay, the interaction's target with input / processing /
+  presentation, the frames it covered. `!` is needs-improvement and `!!` poor, the library's thresholds. It reads the same
+  APIs, so CLS is Chromium only and the other four come from Chromium, Firefox and Safari. Long animation frames are ours,
+  and `render` sums the style and layout time — the part CSS pays for.
+- **The sheet's numbers** come from the CSSOM, not a parser: bytes, rules, declarations, layer bytes, the worst
+  specificity, colours, fonts, `!important`, custom properties declared / read / orphaned / undeclared, keyframes declared
+  / used / unused, and coverage — the classes of the sheet that no element carries now. On a cssints sheet this should be
+  clean by construction, so a drift names what bypassed the engine; it is Project Wallace's x-ray pointed at a generated
+  sheet.
+- **The sheet's growth** is the dev server's measurement, over the HMR channel (`cssints:edits`; a late subscriber asks
+  with `cssints:edits:get`): each load reports its size, its class count and the file that changed, so an edit reads
+  `+29 B on src/registry/button/button.tsx`, with a sparkline of the last thirty loads and the bytes a class costs. Off a
+  dev server the row is absent. These bytes are `renderSheet`'s, not the CSSOM's, so they differ a little from the `CSS`
+  row.
+- **Long animation frames** also name their scripts: the top sources by script time (a source is the last two path
+  segments), the invokers (`timer`, `message handler`, an event listener), and the _forced_ style and layout time — the
+  read-after-write that makes a script pay for layout.
+- **The history** of the last twenty loads of a path lives in `sessionStorage` (`cssints-vitals`): LCP and the sheet's
+  bytes as deltas against the previous load of the same page; `reset()` clears it, and a store that throws (a private
+  window) is simply absent.
+- **The cost by call** needs the devtools table (`cssints({ devtools: true })`): bytes of each class at the call that made
+  it, the total and the number of calls, and how many of the call's classes the page carries; without the table the row is
+  absent.
+- **The CSS files' arrival** is the resource timeline: each `.css`, its duration, Chrome's `renderBlockingStatus`, the
+  slowest and the last.
+- **Frames** are sampled by a rAF loop: p50 / p95 / max, the dropped frames, a sparkline and a heatmap of the timeline
+  (green under 16.7 ms, amber to 33.4, orange to 50, red above).
+- **Limits.** Long animation frames are not buffered entries, so a report from a cold console sees only the work after
+  `observe()`; the five vitals are buffered but arrive a task after the module loads, so the first report can be early.
+  A cross-origin sheet throws on `cssRules` and is counted as `blocked`. Coverage asks the DOM now: a class used only in a
+  state is used if an element carries it.
+
+`report()` returns the numbers, `print(report)` prints them, `reset()` forgets the history and the sheet's measurements,
+`stop()` ends the frame loop.
+
 ### Debugging: traces of the engine (`CSSINTS_TRACE`, cssints-r2qq)
 
 Opt-in. Set `CSSINTS_TRACE=otlp` (or `otlp:http://host:port`; the default is `http://localhost:4318`) before `vite dev` or `vite build`, and the plugin sends one trace per Vite hook to an OpenTelemetry backend over OTLP/HTTP (JSON). Unset, nothing is loaded and nothing runs: the hooks use Effect's own `runSync` and `runPromiseExit`, no tracer, no exporter, no HTTP client. The variable is read once, when the plugin loads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -72,7 +72,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.34.0",
+    "@cssints/css-grammar": "^0.35.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.6",

package/skills/cssints-plugin/references/table.md

@@ -114,7 +114,7 @@ shade: fn({
 - `value` runs at build time, once per call; the call is replaced by its CSS text. It throws for values the grammar
   cannot reject (units it cannot compute, a failed accessibility rule): `fluid` rejects `em` and fails WCAG 1.4.4.
 - What `value` returns must be a string or a Typed OM value (`cssints: tint() value must return a string or a Typed OM
-value`). A result that does not fit the property is that property's error at the same site.
+  value`). A result that does not fit the property is that property's error at the same site.
 
 ## Identity and HMR