@djangocfg/ui-core 2.1.418 → 2.1.420

package/src/components/data/BalancedText/index.ts

@@ -0,0 +1,5 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { BalancedText } from './BalancedText';
+export type { BalancedTextProps, BalancedFont } from './types';
+export { DEFAULT_BALANCED_FONT, DEFAULT_BALANCED_MAX_WIDTH } from './types';

package/src/components/data/BalancedText/types.ts

@@ -0,0 +1,59 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+
+/**
+ * CSS font shorthand for Pretext measurement.
+ *
+ * Must match the actually rendered font, otherwise the balanced width will be
+ * off. When `font` is omitted, the component reads `getComputedStyle()` on the
+ * element after mount and falls back to {@link DEFAULT_BALANCED_FONT} on the
+ * server.
+ */
+export type BalancedFont = string;
+
+export interface BalancedTextOwnProps {
+  /** Text to balance. Required as a string — pretext measures runs of glyphs, not React trees. */
+  children: string;
+  /** CSS font shorthand (`'16px Inter, sans-serif'`). When omitted, reads `getComputedStyle`. */
+  font?: BalancedFont;
+  /**
+   * Hard cap on width in px. Balanced width never exceeds this. When omitted,
+   * the parent container's measured `clientWidth` is used. `maxLines` cannot
+   * make the text wider than this.
+   * @default 600
+   */
+  maxWidth?: number;
+  /**
+   * Cap on number of lines. When set, the balanced width is the *narrowest*
+   * width that still keeps ≤ `maxLines` lines (instead of preserving the
+   * natural line count at `maxWidth`). Useful for headings.
+   */
+  maxLines?: number;
+  /** Element to render as. @default 'span' */
+  as?: ElementType;
+}
+
+/** Props for {@link BalancedText}. */
+export type BalancedTextProps = BalancedTextOwnProps &
+  Omit<ComponentPropsWithoutRef<'span'>, keyof BalancedTextOwnProps | 'children'> & {
+    children: string;
+  };
+
+/** Fallback used on SSR and when `font` is not provided + measurement hasn't run. */
+export const DEFAULT_BALANCED_FONT: BalancedFont =
+  '16px ui-sans-serif, system-ui, -apple-system, sans-serif';
+
+export const DEFAULT_BALANCED_MAX_WIDTH = 600;
+
+/** Internal: BalancedText render shape (used by subcomponents). */
+export interface InternalRenderProps {
+  Tag: ElementType;
+  balancedWidth: number;
+  hasMeasured: boolean;
+  text: string;
+  className?: string;
+  style?: React.CSSProperties;
+  rest: Record<string, unknown>;
+  textNode: ReactNode;
+}

package/src/components/index.ts

@@ -187,6 +187,8 @@ export { CircularProgress, CircularProgressCombined, CircularProgressIndicator,
 export type { CircularProgressProps } from './data/circular-progress';
 export { RelativeTimeCard, relativeTimeCardVariants } from './data/relative-time-card';
 export type { RelativeTimeCardProps } from './data/relative-time-card';
+export { BalancedText, DEFAULT_BALANCED_FONT, DEFAULT_BALANCED_MAX_WIDTH } from './data/BalancedText';
+export type { BalancedTextProps, BalancedFont } from './data/BalancedText';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Chart Components

package/src/hooks/dom/index.ts

@@ -12,5 +12,7 @@ export {
 export type { ScrollSnapshot, ScrollDirection, ScrollTarget } from './useScroll';
 export { useLayoutEffect } from './useLayoutEffect';
 export { useSize } from './useSize';
+export { useResizeObserver } from './useResizeObserver';
+export type { Size } from './useResizeObserver';
 export { useFormReset } from './useFormReset';
 export type { UseFormResetParams } from './useFormReset';

package/src/hooks/dom/useResizeObserver.ts

@@ -0,0 +1,117 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Shared ResizeObserver store with refcounting.
+//
+// Why a shared observer (vs one per `useSize`/`useResizeObserver` call):
+//   - A single ResizeObserver instance is cheaper than N when many
+//     components subscribe (charts, sparklines, masonry items, …).
+//   - Avoids "ResizeObserver loop completed with undelivered notifications"
+//     warnings that pile up when many tiny observers fire in the same frame.
+//
+// The store keeps one global RO; per-element listener sets are reference
+// counted so the observer detaches from elements once nobody listens.
+//
+// Inspired by the pattern at activity-graph.tsx:180-188 in jalcoui.
+
+'use client';
+
+import * as React from 'react';
+import { useLayoutEffect } from './useLayoutEffect';
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+type Listener = (size: Size) => void;
+
+interface Entry {
+  listeners: Set<Listener>;
+  last: Size;
+}
+
+let sharedObserver: ResizeObserver | null = null;
+const entries = new WeakMap<Element, Entry>();
+// Mirror keyset so we can resolve elements from RO entries.
+const elementByEntry = new WeakMap<Element, Entry>();
+
+function getObserver(): ResizeObserver {
+  if (sharedObserver) return sharedObserver;
+  sharedObserver = new ResizeObserver((roEntries) => {
+    for (const roEntry of roEntries) {
+      const el = roEntry.target;
+      const entry = elementByEntry.get(el);
+      if (!entry) continue;
+
+      let width: number;
+      let height: number;
+      const box = (roEntry as ResizeObserverEntry).borderBoxSize;
+      if (box) {
+        const b = Array.isArray(box) ? box[0] : box;
+        width = b.inlineSize;
+        height = b.blockSize;
+      } else {
+        width = (el as HTMLElement).offsetWidth;
+        height = (el as HTMLElement).offsetHeight;
+      }
+
+      entry.last = { width, height };
+      for (const listener of entry.listeners) listener(entry.last);
+    }
+  });
+  return sharedObserver;
+}
+
+function subscribe(element: Element, listener: Listener): () => void {
+  const observer = getObserver();
+  let entry = entries.get(element);
+  if (!entry) {
+    entry = {
+      listeners: new Set<Listener>(),
+      last: {
+        width: (element as HTMLElement).offsetWidth ?? 0,
+        height: (element as HTMLElement).offsetHeight ?? 0,
+      },
+    };
+    entries.set(element, entry);
+    elementByEntry.set(element, entry);
+    observer.observe(element);
+  }
+  entry.listeners.add(listener);
+  // Deliver current size synchronously so consumers don't render with 0.
+  listener(entry.last);
+
+  return () => {
+    const e = entries.get(element);
+    if (!e) return;
+    e.listeners.delete(listener);
+    if (e.listeners.size === 0) {
+      observer.unobserve(element);
+      entries.delete(element);
+    }
+  };
+}
+
+/**
+ * Observe an element's border-box size via a shared ResizeObserver.
+ *
+ * Returns `{ width: 0, height: 0 }` until the first measurement lands.
+ * Pass either a ref or a callback-style ref result.
+ *
+ * @example
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const { width, height } = useResizeObserver(ref);
+ */
+export function useResizeObserver<T extends Element = Element>(
+  ref: React.RefObject<T | null>,
+): Size {
+  const [size, setSize] = React.useState<Size>({ width: 0, height: 0 });
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    return subscribe(el, setSize);
+  }, [ref]);
+
+  return size;
+}

package/src/lib/index.ts

@@ -15,3 +15,4 @@ export * from "./compose-refs";
 export * from "./get-element-ref";
 export * from "./compose-event-handlers";
 export { createContext } from "./create-context";
+export { getIntensity } from "./intensity";

package/src/lib/intensity.ts

@@ -0,0 +1,40 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Quantize a numeric value into a discrete intensity bucket. Used by
+// heatmaps (activity-graph), gauges, and any thermal-style visualization
+// that needs N colored steps.
+//
+// `thresholds` are upper bounds in ascending order, expressed as fractions
+// of `max` or as absolute values — caller picks. The returned bucket index
+// is in `[0, thresholds.length]`.
+//
+// Inspired by `getIntensity` at activity-graph.tsx:72-80.
+
+/**
+ * @param value      Current value.
+ * @param thresholds Ascending upper bounds. The returned bucket is the
+ *                   index of the first threshold `value` does not exceed,
+ *                   or `thresholds.length` if it exceeds them all.
+ * @returns Bucket index in `[0, thresholds.length]`. `0` for non-positive
+ *          values (treated as "empty").
+ *
+ * @example
+ *   getIntensity(0, [0.25, 0.5, 0.75])     // 0  (empty)
+ *   getIntensity(0.1, [0.25, 0.5, 0.75])   // 1
+ *   getIntensity(0.5, [0.25, 0.5, 0.75])   // 2
+ *   getIntensity(0.8, [0.25, 0.5, 0.75])   // 3
+ *   getIntensity(1.0, [0.25, 0.5, 0.75])   // 3
+ *
+ * @example
+ *   // Quantize commits/day into 4 buckets relative to the busiest day:
+ *   const max = Math.max(...counts);
+ *   const ratio = count / max;
+ *   const step = getIntensity(ratio, [0.25, 0.5, 0.75]); // 0..3
+ */
+export function getIntensity(value: number, thresholds: number[]): number {
+  if (!(value > 0)) return 0;
+  for (let i = 0; i < thresholds.length; i++) {
+    if (value <= thresholds[i]) return i + 1;
+  }
+  return thresholds.length;
+}

package/src/lib/pretext/index.ts

@@ -0,0 +1,18 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export {
+  usePretext,
+  usePretextWithSegments,
+  usePretextLayout,
+  usePretextLines,
+  useShrinkwrap,
+  useBalancedWidth,
+} from './use-pretext';
+
+export type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+} from './use-pretext';

package/src/lib/pretext/pretext.types.ts

@@ -0,0 +1,72 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Local mirror of the @chenglou/pretext public API. The runtime dependency
+// is declared `optional` (see ui-tools/package.json), so consumers that
+// never use BalancedText / pretext-powered tools don't pay for it. To keep
+// `pnpm check` green without the dependency installed, we redeclare just
+// the types we touch — no `import type from '@chenglou/pretext'`.
+//
+// Mirrors the public surface as of @chenglou/pretext 0.0.7. If the upstream
+// types drift, update here.
+
+export interface PrepareOptions {
+  whiteSpace?: 'normal' | 'pre' | 'pre-wrap' | 'pre-line';
+}
+
+// Opaque handles — internal shape doesn't matter to consumers of the hooks.
+// We brand them so the two flavours don't get accidentally swapped.
+export interface PreparedText {
+  readonly __brand: 'PreparedText';
+}
+
+export interface PreparedTextWithSegments {
+  readonly __brand: 'PreparedTextWithSegments';
+}
+
+export interface LayoutResult {
+  lineCount: number;
+  height: number;
+}
+
+export interface LayoutLine {
+  text: string;
+  width: number;
+  start: number;
+  end: number;
+}
+
+export interface LayoutLinesResult {
+  lineCount: number;
+  height: number;
+  lines: LayoutLine[];
+}
+
+export interface WalkLineRange {
+  width: number;
+  start: number;
+  end: number;
+}
+
+export interface PretextModule {
+  prepare(text: string, font: string, options?: PrepareOptions): PreparedText;
+  prepareWithSegments(
+    text: string,
+    font: string,
+    options?: PrepareOptions,
+  ): PreparedTextWithSegments;
+  layout(
+    prepared: PreparedText,
+    maxWidth: number,
+    lineHeight: number,
+  ): LayoutResult;
+  layoutWithLines(
+    prepared: PreparedTextWithSegments,
+    maxWidth: number,
+    lineHeight: number,
+  ): LayoutLinesResult;
+  walkLineRanges(
+    prepared: PreparedTextWithSegments,
+    maxWidth: number,
+    visit: (line: WalkLineRange) => void,
+  ): void;
+}

package/src/lib/pretext/use-pretext.ts

@@ -0,0 +1,211 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// React hooks wrapping @chenglou/pretext for DOM-free text measurement.
+// Provides prepare/layout lifecycle management, shrinkwrap search,
+// and line-balanced width computation.
+//
+// Powered by Pretext by Cheng Lou — github.com/chenglou/pretext
+//
+// `@chenglou/pretext` is declared as an optionalDependency in
+// `packages/ui-tools/package.json` — consumers that never use BalancedText
+// (or other pretext-based tools) can install ui-tools without it. The
+// `getPretext()` helper uses a CommonJS `require()` so the optional
+// dependency is resolved lazily at first use; if it is missing, the
+// `require` throws at call site, never at module-load.
+
+'use client';
+
+import * as React from 'react';
+import type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+  PretextModule,
+} from './pretext.types';
+
+export type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+};
+
+const isBrowser = typeof window !== 'undefined';
+
+let cachedPretext: PretextModule | null = null;
+
+function getPretext(): PretextModule {
+  if (cachedPretext) return cachedPretext;
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  cachedPretext = require('@chenglou/pretext') as PretextModule;
+  return cachedPretext;
+}
+
+const EMPTY_LAYOUT: LayoutResult = { lineCount: 0, height: 0 };
+const EMPTY_LINES: LayoutLinesResult = { lineCount: 0, height: 0, lines: [] };
+
+/**
+ * Prepare text for Pretext measurement. Runs `prepare()` once and caches
+ * the result until `text`, `font`, or `options` change.
+ *
+ * The returned handle is opaque — pass it to `usePretextLayout`.
+ */
+export function usePretext(
+  text: string,
+  font: string,
+  options?: PrepareOptions,
+): PreparedText | null {
+  const whiteSpace = options?.whiteSpace ?? 'normal';
+
+  return React.useMemo(() => {
+    if (!isBrowser) return null;
+    return getPretext().prepare(text, font, options);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, font, whiteSpace]);
+}
+
+/**
+ * Prepare text with segment data for advanced layout (line-by-line rendering,
+ * shrinkwrap, balancing). Same as `usePretext` but returns the richer handle.
+ */
+export function usePretextWithSegments(
+  text: string,
+  font: string,
+  options?: PrepareOptions,
+): PreparedTextWithSegments | null {
+  const whiteSpace = options?.whiteSpace ?? 'normal';
+
+  return React.useMemo(() => {
+    if (!isBrowser) return null;
+    return getPretext().prepareWithSegments(text, font, options);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, font, whiteSpace]);
+}
+
+/**
+ * Layout prepared text at a given width and line height. Pure arithmetic —
+ * no DOM reads. Returns line count and total height.
+ *
+ * Re-runs on every `maxWidth` or `lineHeight` change (~0.0002ms).
+ */
+export function usePretextLayout(
+  prepared: PreparedText | null,
+  maxWidth: number,
+  lineHeight: number,
+): LayoutResult {
+  return React.useMemo(() => {
+    if (!prepared) return EMPTY_LAYOUT;
+    return getPretext().layout(prepared, maxWidth, lineHeight);
+  }, [prepared, maxWidth, lineHeight]);
+}
+
+/**
+ * Layout prepared text and return full line data (text, width, cursors).
+ * Heavier than `usePretextLayout` — use when you need per-line info
+ * for custom rendering.
+ */
+export function usePretextLines(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+  lineHeight: number,
+): LayoutLinesResult {
+  return React.useMemo(() => {
+    if (!prepared) return EMPTY_LINES;
+    return getPretext().layoutWithLines(prepared, maxWidth, lineHeight);
+  }, [prepared, maxWidth, lineHeight]);
+}
+
+/**
+ * Find the tightest width that produces the same line count as `maxWidth`.
+ * Binary-searches widths using `walkLineRanges` — no DOM measurement.
+ *
+ * Returns the shrinkwrapped width in pixels.
+ */
+export function useShrinkwrap(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+): number {
+  return React.useMemo(() => {
+    if (!prepared || maxWidth <= 0) return 0;
+
+    const { walkLineRanges } = getPretext();
+
+    let baseLineCount = 0;
+    walkLineRanges(prepared, maxWidth, () => {
+      baseLineCount++;
+    });
+    if (baseLineCount <= 1) {
+      let singleLineWidth = 0;
+      walkLineRanges(prepared, maxWidth, (line) => {
+        singleLineWidth = line.width;
+      });
+      return Math.ceil(singleLineWidth) || 0;
+    }
+
+    let lo = 1;
+    let hi = Math.ceil(maxWidth);
+
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      let midLineCount = 0;
+      walkLineRanges(prepared, mid, () => {
+        midLineCount++;
+      });
+
+      if (midLineCount <= baseLineCount) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
+      }
+    }
+
+    return lo;
+  }, [prepared, maxWidth]);
+}
+
+/**
+ * Find the width where all lines are roughly equal length (balanced text).
+ * Binary-searches for the narrowest width that keeps the same line count
+ * as `maxWidth`, then returns that width.
+ *
+ * CSS `text-wrap: balance` only works up to ~6 lines and is inconsistent
+ * cross-browser. This works on any length and is deterministic.
+ */
+export function useBalancedWidth(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+): number {
+  return React.useMemo(() => {
+    if (!prepared || maxWidth <= 0) return 0;
+
+    const { walkLineRanges } = getPretext();
+
+    let baseLineCount = 0;
+    walkLineRanges(prepared, maxWidth, () => {
+      baseLineCount++;
+    });
+    if (baseLineCount <= 1) return maxWidth;
+
+    let lo = 1;
+    let hi = Math.ceil(maxWidth);
+
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      let midLineCount = 0;
+      walkLineRanges(prepared, mid, () => {
+        midLineCount++;
+      });
+
+      if (midLineCount <= baseLineCount) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
+      }
+    }
+
+    return lo;
+  }, [prepared, maxWidth]);
+}

package/src/styles/README.md

@@ -6,7 +6,8 @@ CSS architecture for `@djangocfg/ui-core` — **Tailwind v4** with semantic toke
 
 ```
 styles/
-├── index.css              # Main entry — imports the chain below
+├── full.css               # Golden path (recommended) — Tailwind + tokens + base + utilities, cascade-layer-safe
+├── index.css              # Plain entry (no Tailwind, unlayered) — you own layer ordering
 ├── theme.css              # Imports tokens.css → animations → light → dark
 ├── base.css               # Resets + `*` border-color + body bg/color
 ├── utilities.css          # Custom utilities (.glass-*, .step, animations)
@@ -155,18 +156,55 @@ Each requires a **non-transparent parent** (something for the blur to chew on).
 
 ## App setup
 
-In your consuming app's `globals.css`:
+### Golden path (recommended) — one import, layer-safe
 
 ```css
-/* 1. ui-core theme tokens FIRST (they define every --color-*) */
-@import "@djangocfg/ui-core/styles";
+/* Single line. Imports Tailwind + tokens + base + utilities in the
+   correct cascade layers. Put it FIRST; other package CSS after. */
+@import "@djangocfg/ui-core/styles/full";
 
-/* 2. Other package styles after */
 @import "@djangocfg/layouts/styles";
 @import "@djangocfg/ui-tools/styles";
+```
 
-/* 3. Tailwind v4 core LAST so it sees the @theme tokens */
-@import "tailwindcss";
+`…/styles/full` (`full.css`) pins ui-core's base resets to `@layer base`
+and its custom utilities to `@layer utilities` via `@import "…" layer(name)`.
+A `layer()`-qualified import is folded into that layer **regardless of
+import order or build tool**, so you cannot get the ordering wrong, and
+you do not need to import `tailwindcss` yourself.
+
+### The cascade-layer rule (why ordering matters)
+
+Tailwind v4 emits its utilities inside `@layer utilities`. **Unlayered
+CSS beats any layered rule** in the cascade. So if a package's base
+resets (here `* { border-color }` and the `body` background/font rules in
+`base.css`) are emitted *unlayered*, they sit above `@layer utilities`
+and silently defeat layout utilities (`gap`, `space-y`, `divide`, `flex`,
+`border`, `padding`). Colors usually survive because they flow through
+CSS vars (no cascade conflict), so the breakage is invisible in Chrome
+but shows up in stricter engines (WKWebView).
+
+Whether a *plain*, unlayered `@import` lands in a layer depends on its
+position relative to `@import "tailwindcss"` **and** on the build tool
+(Vite vs Next.js resolve `@import` differently). `full.css` removes that
+dependency by binding each file to a layer explicitly. **Use `…/styles/full`
+and this whole class of bug cannot occur.**
+
+### Manual ordering (only if you manage layers yourself)
+
+The plain `@djangocfg/ui-core/styles` entry imports `theme.css` +
+`sources.css` + `base.css` + `utilities.css` **unlayered** (it does not
+import Tailwind). If you use it, you own the layer ordering. The Next.js
+demo does this and works because PostCSS folds the trailing
+`@import "tailwindcss"` such that the resets still end up benign — but a
+Vite consumer that puts `@import "tailwindcss"` last hit exactly the bug
+above. If you must hand-order, import `tailwindcss` **first**:
+
+```css
+@import "tailwindcss";              /* establishes the layers first */
+@import "@djangocfg/ui-core/styles";
+@import "@djangocfg/layouts/styles";
+@import "@djangocfg/ui-tools/styles";
 ```
 
 > **No `@plugin "tailwindcss-animate"` needed** in v4 — the keyframes ship via `theme/animations.css`. Use `tw-animate-css` instead if you need extra utilities.

package/src/styles/full.css

@@ -0,0 +1,52 @@
+/**
+ * @djangocfg/ui-core — golden-path style entry (cascade-layer-safe)
+ *
+ * Import THIS file (`@djangocfg/ui-core/styles/full`) as the SINGLE,
+ * FIRST style import in a consumer app and Tailwind cascade-layer
+ * ordering cannot go wrong — regardless of build tool (Vite or Next.js)
+ * or where the consumer's own `@import "tailwindcss"` ends up.
+ *
+ * Why this file exists — the cascade-layer trap it removes
+ * --------------------------------------------------------
+ * Tailwind v4 emits its utilities inside `@layer utilities`. Any CSS
+ * that lands OUTSIDE a cascade layer beats every layered rule, because
+ * unlayered styles always win over layered ones in the cascade. So if a
+ * package's base resets (e.g. ui-core's `* { border-color }` and the
+ * `body` background/font rules in base.css) are emitted unlayered, they
+ * sit above `@layer utilities` and silently defeat layout utilities
+ * (gap, space-y, divide, flex, border, padding). Colors usually survive
+ * because they resolve through CSS vars, which have no cascade conflict,
+ * so the breakage is invisible until a stricter engine (WKWebView) shows
+ * it. The plain `@djangocfg/ui-core/styles` entry imports base.css and
+ * utilities.css unlayered, which means their position relative to
+ * `@import "tailwindcss"` decides whether they get folded into a layer —
+ * a footgun for consumers.
+ *
+ * This entry removes the footgun by binding each package file to an
+ * explicit cascade layer at import time via `@import "..." layer(name)`.
+ * A `layer()`-qualified import is folded into that named layer no matter
+ * the import order or build tool, so the consumer can put their own
+ * `@import "tailwindcss"` anywhere (or omit it — this file imports it
+ * first) and the resets stay in `@layer base`, the custom utilities stay
+ * in `@layer utilities`, both correctly under Tailwind's own emissions.
+ *
+ * theme.css and sources.css are intentionally NOT layered: `@theme`
+ * token blocks and the `:root` / `.dark` CSS variables must stay global
+ * so Tailwind collects the tokens and the variables apply everywhere,
+ * and `@source` is a build directive, not a style rule.
+ */
+
+/* Tailwind v4 core first — establishes the properties/theme/base/components/utilities layer order. */
+@import "tailwindcss";
+
+/* Theme tokens + CSS variables — must stay global (unlayered) so Tailwind reads @theme and :root/.dark apply everywhere. */
+@import "./theme.css";
+
+/* @source directives for monorepo class detection — build directive, not a style rule. */
+@import "./sources.css";
+
+/* Base resets pinned to @layer base so they never escape above Tailwind's utilities. */
+@import "./base.css" layer(base);
+
+/* Custom utilities pinned to @layer utilities to sit alongside Tailwind's own. */
+@import "./utilities.css" layer(utilities);