cursedbelt 2.3.0 → 2.5.1

package/dist/styles-static.css

@@ -6,32 +6,54 @@
  * This `@source` makes Tailwind v4 scan cursedbelt's source files so the utility
  * classes used by its components are generated in the app's stylesheet.
  *
- * ── Two entry points, and which one an app wants ─────────────────────────────
+ * ── Two ways in, and which one an app wants ──────────────────────────────────
  * `@source "."` is the expensive half: it points Tailwind's JIT at cursedbelt's
  * ENTIRE source tree, so the app emits the union of the whole design system
- * (113 KB / 846 selectors, measured in the previous generation) whether it
- * renders three components or eighty. Everything else in this file is CSS the
- * components genuinely need and no app can do without.
+ * whether it renders three components or eighty, and its own build walks 827
+ * files it does not own. Everything else in this file is CSS the components
+ * genuinely need and no app can do without.
  *
- * A CSS `@import` takes the whole file, so the split is a second subpath:
+ * A CSS `@import` takes the whole file, so the split is two more subpaths:
  *
- *   cursedbelt/styles.css         this file — the real CSS + the `@source` scan
- *   cursedbelt/styles-static.css  the same file MINUS the `@source` line
+ *   cursedbelt/styles.css            this file — the real CSS + the `@source` scan
+ *   cursedbelt/styles-static.css     the same file MINUS the `@source` line
+ *   cursedbelt/styles-utilities.css  the utilities that `@source` line would have
+ *                                    produced, precompiled at cursedbelt's build
  *
- * The static one is for an app that pays for its own scanning — it gets the
- * tooltip pointer-events fix, the Progress keyframes, the lightbox bridge, the
- * ambient/glass layer and `tw-animate-css`, and emits none of cursedbelt's
- * utility classes, so whatever component utilities it needs must come from
- * sources IT registers. Do not hand-list cursedbelt's component files to get
- * them back: a relative `@source` reaching into this package's source tree is a
- * `file:` dependency wearing a stylesheet's clothes, and it is the thing the
- * previous generation's 29-line-per-app arrangement is remembered for.
+ * The second two are a PAIR and neither is usable alone — `styles-static.css` on
+ * its own gets the tooltip pointer-events fix, the Progress keyframes, the
+ * lightbox bridge, the ambient/glass layer and `tw-animate-css`, and emits none
+ * of cursedbelt's utility classes, i.e. an unstyled app:
  *
- * 🔴 This header is in BOTH files, because one is generated from the other and a
- * test holds them byte-identical apart from the `@source` line. Always edit
- * `src/styles.css`; never `src/styles-static.css`, which
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-utilities.css";
+ *   @import "cursedbelt/theme.css";
+ *
+ * 🔴 Do NOT hand-list cursedbelt's component files to get the utilities back.
+ * Tailwind v4 resolves every `@source` to a DIRECTORY and scans it recursively —
+ * a file path and a glob are both silently widened to their parent — and
+ * `VirtualList`/`VirtualCardGrid` live at the root of `src/react/`, so the finest
+ * grain an app can write is the whole design system. A relative `@source` reaching
+ * into this package's source tree is also a `file:` dependency wearing a
+ * stylesheet's clothes, and it buys nothing: it is the thing the previous
+ * generation's 29-line-per-app arrangement is remembered for, and those 29 lines
+ * were never file-level scoping either.
+ *
+ * The pair is not SMALLER than this file — measured, both routes emit the same
+ * rules within 54 bytes. What it buys is a build that scans nothing of another
+ * package's source tree, and a `styles-static.css` that finally has a correct
+ * use. The measurements, and what would actually shrink a consumer, are in the
+ * header of `scripts/generateUtilityStyles.ts`.
+ *
+ * 🔴 This header is in BOTH of the first two files, because one is generated from
+ * the other and a test holds them byte-identical apart from the `@source` line.
+ * Always edit `src/styles.css`; never `src/styles-static.css`, which
  * `scripts/generateStaticStyles.ts` rewrites on every `bun run build` and
- * `src/stylesStaticMatches.spec.ts` fails on when it is stale.
+ * `src/stylesStaticMatches.spec.ts` fails on when it is stale. Editing this file
+ * invalidates `src/styles-utilities.css` too — it is compiled against the static
+ * variant, `scripts/generateUtilityStyles.ts` rewrites it in the same build step,
+ * and `src/stylesUtilitiesMatches.spec.ts` is what fails when it is stale.
  */
 
 /* Animation utilities (animate-in/out, fade/zoom/slide-in-from-*) consumed by the