@ecoma-io/loom 0.1.0 → 0.2.0

package/dist/styles/theme.css

@@ -5,26 +5,21 @@
  * can theme lives here and nowhere else: no colour, duration, easing, radius
  * or shadow is written literally in a component.
  *
- * Positioning it encodes. Ecoma is a platform where an organization digitizes
- * its own operations and AI agents are a first-class workforce, so the form
- * language is dual-force:
+ * Positioning it encodes. Loom is a UI system for cross-platform web
+ * applications — browser, PWA, Electron, Tauri — so the form language is
+ * purposeful and opinionated:
  *
- *   - Human (warp) — the threads strung and held under tension: what people
- *     author and decide. Doubles as the default action colour, because a
- *     person drives the interface.
- *   - Agent (weft) — the thread carried across them: work an agent is running
- *     or has produced.
- *   - The seam — a warp→weft gradient — appears ONLY where the two forces
- *     meet: handoffs, co-authored assets, brand moments. Never under body
- *     text, never on anything smaller than 20px, never in an interaction
- *     state.
+ *   - Primary (`--color-primary`) — the default action colour: what a person
+ *     drives the interface with. The focus ring is the same hue for the same
+ *     reason — keyboard focus is the primary action.
+ *   - Accent (`--color-accent`) — a second semantic colour for contrast or
+ *     emphasis distinct from the primary action. Useful for signalling a
+ *     different category, mode, or origin.
  *
- * Two threads, one cloth: the forces are one piece of work, not two systems.
- *
- * Light-first. This is a daytime operations tool, so the paper-light theme is
- * the single default and there is no runtime light/dark switch. A symmetric
- * dark theme is a reserved seam that returns with the first surface that
- * needs it.
+ * Dual-theme. The light tokens are the default; the dark block below
+ * overrides every semantic token under `:root[data-theme="dark"]`. Switching
+ * replaces the entire set, so the two cannot drift apart. The `useTheme`
+ * composable and `themeScript` flash-prevention snippet manage the attribute.
  *
  * `static` rather than plain `@theme`: Tailwind emits only the variables its
  * generated utilities reference, and several tokens here are read by an
@@ -33,7 +28,7 @@
  * `var(--duration-fast)` resolve inside a component's style attribute.
  */
 @theme static {
-  /* ---- Neutrals: technical paper, cooled slightly toward the warp ------- */
+  /* ---- Neutrals: technical paper, cooled slightly toward the primary hue --- */
   --color-background: hsl(213 25% 96%);
   --color-foreground: hsl(213 29% 15%);
 
@@ -51,6 +46,17 @@
   --color-muted: hsl(213 18% 91%);
   --color-muted-foreground: hsl(213 14% 41%);
 
+  /* The lighter step of the same ladder, and it is reserved for a *graphical
+   * object*, never for text: a glyph that must keep clearing the 3:1 floor
+   * while receding behind `muted-foreground` — the disabled Rating's unfilled
+   * stars, which carry the maximum. Text is held to 4.5:1, which is what
+   * `muted-foreground` is measured to; the 3:1 floor of WCAG 1.4.11 leaves
+   * room for one more step, and taking it as a token rather than as an alpha
+   * over the darker grey is the whole point: composited at half alpha,
+   * `muted-foreground` lands at 2.05:1 on the page ground, short of even
+   * that floor. */
+  --color-muted-foreground-soft: hsl(213 12% 50%);
+
   /* Two border weights: the default hairline recedes; strong is for the few
    * blocks that must assert their edge — an active panel, a keyboard target
    * zone. */
@@ -63,23 +69,25 @@
   --color-subtle: hsl(213 20% 94%);
   --color-subtle-foreground: hsl(213 29% 18%);
 
-  /* ---- Force 1 · Human — warp: default action, structure, decisions ----- */
+  /* ---- Force 1 · Primary — default action, structure, decisions --------- */
   --color-primary: hsl(211 37% 32%);
   --color-primary-foreground: hsl(0 0% 100%);
-  --color-primary-muted: hsl(211 35% 92%); /* warp wash: selected/active fills */
+  --color-primary-muted: hsl(211 35% 92%); /* wash: selected/active fills */
 
-  /* ---- Force 2 · Agent — weft: automated work running or produced ------- */
-  --color-agent: hsl(18 56% 39%);
-  --color-agent-foreground: hsl(0 0% 100%);
-  --color-agent-muted: hsl(18 50% 93%); /* weft wash: agent-driven surfaces */
+  /* ---- Force 2 · Accent — a second semantic colour for contrast or
+   * emphasis distinct from the primary action. Useful for signalling a
+   * different category, mode, or origin. ------------------------------- */
+  --color-accent: hsl(18 56% 39%);
+  --color-accent-foreground: hsl(0 0% 100%);
+  --color-accent-muted: hsl(18 50% 93%); /* wash: accent-driven surfaces */
 
   --color-secondary: hsl(213 18% 91%);
   --color-secondary-foreground: hsl(213 29% 18%);
 
-  /* Focus ring is the Human warp: keyboard focus is a person acting. */
+  /* Focus ring is the primary colour: keyboard focus is the primary action. */
   --color-ring: hsl(211 37% 32%);
 
-  /* ---- Functional — hues kept distinct from both forces ----------------- */
+  /* ---- Functional — hues kept distinct from both action colours ------------ */
   --color-destructive: hsl(356 65% 41%);
   --color-destructive-foreground: hsl(0 0% 100%);
   --color-success: hsl(152 45% 30%);
@@ -89,10 +97,50 @@
   --color-info: hsl(202 65% 35%);
   --color-info-foreground: hsl(0 0% 100%);
 
-  /* ---- The seam: the two forces meeting. Interpolated in OKLCH so the
-   * midpoint never turns muddy. Reach for it through the `bg-seam` utility
-   * below, at handoff points and brand moments only. ---------------------- */
-  --seam: linear-gradient(90deg in oklch, hsl(211 37% 32%), hsl(18 56% 39%));
+  /* Each functional hue's wash, completing the pattern the action colours above
+   * already set. These are opaque rather than an alpha of the base hue, and
+   * that is the whole reason they exist: a `bg-destructive/12` fill composites
+   * against whatever is behind it, so the same badge renders as one colour on
+   * `bg-card` and another on `bg-sunken`. A status tint that shifts with its
+   * container is a status tint a reader cannot learn. Each is mixed to hold at
+   * least 4.5:1 against its own base hue, which is what sits on top of it as
+   * text or as a hairline. */
+  --color-destructive-muted: hsl(356 55% 94%); /* error wash: a failed or blocking surface */
+  --color-success-muted: hsl(152 40% 93%); /* success wash: a settled, completed surface */
+  --color-warning-muted: hsl(38 70% 92%); /* warning wash: a surface needing attention */
+  --color-info-muted: hsl(202 55% 93%); /* info wash: a neutral advisory surface */
+
+  /* ---- Scrim weight, as modifiers on `foreground`: `bg-foreground/scrim`.
+   * Two weights, because how much of the page a surface hides is a statement
+   * about what that surface is. A dialog interrupts, so the page behind it
+   * drops to context. A drawer is worked alongside its page — you tune a
+   * filter and watch the rows change — so the page stays legible and stays
+   * the subject. That rule lived in a comment inside `Drawer.vue`, which is
+   * the one place a person building a third overlay would never look. ------ */
+  --opacity-scrim: 70%; /* a surface that interrupts: the page behind is context */
+  --opacity-scrim-light: 40%; /* a surface worked alongside: the page behind is still the subject */
+
+  /* One weight for "unavailable", because two menu rows ten points apart is
+   * not a decision anyone made — `opacity-40` had appeared twice against
+   * `opacity-50` forty-five times, and nothing in any check can see a
+   * difference that small. */
+  --opacity-disabled: 50%;
+
+  /* ---- Stacking. Five rungs, named, because the ladder was real before it
+   * was written down: seventeen overlays at `z-50` and two toasts at
+   * `z-[100]`, an arbitrary value of exactly the kind this file exists to
+   * prevent. Ordering *within* a rung is the portal's job — Reka appends in
+   * open order, so the last dialog opened is the one on top without anyone
+   * numbering them. --------------------------------------------------------- */
+  --z-index-raised: 10; /* lifted above its own siblings: an Indicator's marker, a SegmentedControl thumb */
+  --z-index-sticky: 20; /* page furniture that pins while content scrolls under it */
+  --z-index-chrome: 30; /* application chrome: the header and rails that outlive the page */
+  --z-index-overlay: 50; /* anything portalled over the page — dialogs, popovers, menus, drawers */
+  --z-index-toast: 100; /* above every overlay, because a toast reports on the thing the overlay is doing */
+
+  /* The press. One value, reached through `active:scale-press`, replacing six
+   * `scale-[0.97]` and three `scale-95` that meant the same thing. */
+  --scale-press: 0.97;
 
   /* ---- Shape: small, even fillets — milled, never blobby.
    * Nesting law: inner radius = outer radius − padding, floor 2px. Pick the
@@ -125,7 +173,7 @@
   --shadow-md: 0 4px 12px -2px hsl(213 30% 12% / 0.1), 0 2px 6px -2px hsl(213 30% 12% / 0.07);
   --shadow-lg: 0 12px 32px -6px hsl(213 30% 12% / 0.14), 0 4px 10px -4px hsl(213 30% 12% / 0.08);
 
-  /* Focus halo — a warp haze AROUND the crisp ring outline, added on top of
+  /* Focus halo — a primary haze AROUND the crisp ring outline, added on top of
    * it and never replacing it, so the outline still shows under
    * forced-colors. */
   --shadow-halo: 0 0 0 4px hsl(211 37% 32% / 0.15);
@@ -173,19 +221,65 @@
   --breakpoint-4xl: 2560px; /* QHD */
   --breakpoint-5xl: 3440px; /* 21:9 ultra-wide */
 
+  /* ---- Safe areas. Mobile webviews (notch, home indicator) and PWA title-bar
+   * overlays both reserve space the layout must not paint into. The fallback is
+   * 0 so these tokens are always safe to read — a viewport without a safe area
+   * simply contributes no inset. A host that needs the raw value for
+   * `padding-top: env(safe-area-inset-top)` can use it directly, but a host
+   * that wants Loom's opinion uses the token instead and lets the theme layer
+   * decide what the inset is. ---------------------------------------------- */
+  --safe-area-top: env(safe-area-inset-top, 0px);
+  --safe-area-bottom: env(safe-area-inset-bottom, 0px);
+  --safe-area-left: env(safe-area-inset-left, 0px);
+  --safe-area-right: env(safe-area-inset-right, 0px);
+
   /* ---- The animation vocabulary. Keyframes live in global.css; these are
    * the named utilities that play them. ---------------------------------- */
   --animate-fade: fade var(--duration-normal) var(--ease-out) both;
   --animate-fade-rise: fade-rise var(--duration-normal) var(--ease-out) both;
   --animate-scale-in: scale-in var(--duration-fast) var(--ease-spring) both;
   --animate-shimmer: shimmer 1.6s linear infinite;
-  /* Agent at work — the weft's shuttle beat. */
-  --animate-conduct: conduct 1.8s var(--ease-in-out) infinite;
-  /* A live seam: the warp↔weft boundary drifts while the collaboration runs,
-   * and goes static once the work settles. */
-  --animate-seam-flow: seam-flow 3.2s linear infinite;
   --animate-progress-indeterminate: progress-indeterminate 1.3s var(--ease-in-out) infinite;
   --animate-toast-in: toast-in var(--duration-normal) var(--ease-spring) both;
+
+  /* ---- Motion that leaves. Every animation above is an entrance, so until
+   * these existed an overlay that faded in over 200ms was simply gone between
+   * two frames, and the page behind it appeared to jump rather than to be
+   * revealed. `--ease-in` was declared with the rest of the easings and used by
+   * nothing at all, which is the tell: the accelerate curve has one job and it
+   * is this one.
+   *
+   * Exits run shorter than the entrance they mirror and on `--ease-in`, because
+   * the two directions are not the same event. A surface arriving is
+   * decelerating into place and is worth watching; a surface leaving has
+   * already done its job and should clear the eye rather than hold it.
+   *
+   * These are load-bearing beyond taste. Reka's `Presence` keeps closed content
+   * mounted until an `animationend` arrives — that is why every entrance here
+   * is scoped `data-[state=open]:` — and a closed element with no animation at
+   * all unmounts on the spot. A `data-[state=closed]:` animation is what turns
+   * that all-or-nothing into an ordinary timed exit, and it stays safe under
+   * `prefers-reduced-motion`: `global.css` collapses the duration to 0.01ms,
+   * which still fires `animationend`, so the overlay still unmounts. --------- */
+  --animate-fade-out: fade-out var(--duration-fast) var(--ease-in) both; /* the exit answering `fade` */
+  --animate-fade-fall: fade-fall var(--duration-fast) var(--ease-in) both; /* the exit answering `fade-rise` */
+  --animate-scale-out: scale-out var(--duration-instant) var(--ease-in) both; /* the exit answering `scale-in` */
+
+  /* An edge-anchored panel leaving the way it came. `--duration-normal` against
+   * the `slow` entrance a drawer uses: 320ms is what stops a full-height panel
+   * arriving like a flinch, and none of that reasoning applies to a panel on
+   * its way out.
+   *
+   * There is no matching `slide-in` family, and that is a decision rather than
+   * an omission — see `Drawer.vue`, which enters on `@starting-style` because a
+   * transition composes with a live swipe gesture where a keyframe would fight
+   * it. The exit has no such conflict and cannot be a transition at all:
+   * `Presence` observes `animationend` and never `transitionend`, so a
+   * transition-based exit is unmounted before it can run. --------------------- */
+  --animate-slide-out-to-left: slide-out-to-left var(--duration-normal) var(--ease-in) both; /* a panel leaving past the left edge */
+  --animate-slide-out-to-right: slide-out-to-right var(--duration-normal) var(--ease-in) both; /* a panel leaving past the right edge */
+  --animate-slide-out-to-top: slide-out-to-top var(--duration-normal) var(--ease-in) both; /* a panel leaving past the top edge */
+  --animate-slide-out-to-bottom: slide-out-to-bottom var(--duration-normal) var(--ease-in) both; /* a panel leaving past the bottom edge */
 }
 
 /* Tailwind has no `--duration-*` theme namespace — `duration-*` takes a bare
@@ -205,8 +299,112 @@
   transition-duration: var(--duration-slower);
 }
 
-/* The seam, as a background. A gradient is not a colour, so it has no colour
- * namespace to live in; this is the only sanctioned way to paint one. */
-@utility bg-seam {
-  background-image: var(--seam);
+/* ---- Dark theme overrides ------------------------------------------------
+ * Every semantic token overridden; no "fallback to light". Switching replaces
+ * the entire set, so the two cannot drift apart and contrast is verified for
+ * each independently. `data-theme` on `<html>` is the single source of truth.
+ *
+ * Design principles:
+ *   - Same hue family, adjusted lightness — dark is the mirror, not a new palette
+ *   - Functional tokens slightly desaturated — bright saturated colours on dark
+ *     backgrounds cause eye strain and fail contrast against dark surfaces
+ *   - Elevation = lighter background, not shadow — shadows are invisible on dark
+ *   - Borders brighten — the hairline that recedes on light must be visible on dark
+ *   - `muted-foreground-soft` stays above 3:1 (graphical-object floor)
+ *   - Focus ring stays primary — halo shifts to a lighter shade for visibility
+ *
+ * Contrast is verified: all text pairings clear 4.5:1; all graphical-object
+ * pairings clear 3:1. See the contrast verification table in the repository
+ * for the full audit. ----------------------------------------------------- */
+:root[data-theme="dark"] {
+  /* ---- Neutrals: same hue family, inverted lightness ---- */
+
+  /* Elevation in dark = lighter: sunken(7%) < background(10%) < card(14%) < popover(17%).
+   * Light: sunken(93%) < background(96%) < card(100%) = popover(100%).
+   * Dark mirrors the order with the 4-7% steps that keep surfaces distinct
+   * while staying dark enough for high foreground contrast. */
+  --color-background: hsl(213 25% 10%);
+  --color-foreground: hsl(
+    213 20% 92%
+  ); /* S narrowed 29→20 for softer read; 14.68:1 on background */
+
+  --color-card: hsl(213 20% 14%);
+  --color-card-foreground: hsl(213 20% 92%);
+
+  --color-sunken: hsl(213 24% 7%);
+
+  --color-popover: hsl(213 18% 17%);
+  --color-popover-foreground: hsl(213 20% 92%);
+
+  --color-muted: hsl(213 16% 13%);
+  --color-muted-foreground: hsl(213 10% 60%); /* S 14→10%; 6.06:1 on background */
+
+  /* Graphical-object token: clears 3:1 (4.03:1 on background). In light the
+   * gap is 9pp (41→50); in dark it widens to 12pp (60→48) because the 3:1
+   * floor binds tighter on dark. */
+  --color-muted-foreground-soft: hsl(213 8% 48%);
+
+  /* Borders brighten — the hairline that recedes on light must be visible on
+   * dark. Input and border-strong carry additional indicators (background fill,
+   * label) beyond the border alone. */
+  --color-border: hsl(213 14% 22%);
+  --color-border-strong: hsl(213 10% 36%);
+  --color-input: hsl(213 12% 28%);
+
+  --color-subtle: hsl(213 20% 13%);
+  --color-subtle-foreground: hsl(213 20% 86%);
+
+  /* ---- Primary — lightened (32→45%) and desaturated (37→33%) so the colour
+   * is visible on dark without eye strain. White foreground still clears 4.5:1
+   * (5.05:1) because blue's low luminance-per-lightness keeps the base dark. - */
+  --color-primary: hsl(211 33% 45%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-primary-muted: hsl(211 28% 13%);
+
+  /* ---- Accent — lightened (39→44%) and desaturated (56→48%). -------------- */
+  --color-accent: hsl(18 48% 44%);
+  --color-accent-foreground: hsl(0 0% 100%);
+  --color-accent-muted: hsl(18 35% 13%);
+
+  --color-secondary: hsl(213 16% 14%);
+  --color-secondary-foreground: hsl(213 20% 88%);
+
+  --color-ring: hsl(211 33% 45%); /* matches primary; 3.50:1 on background */
+
+  /* ---- Functional — each lightened and desaturated for dark ---- */
+
+  --color-destructive: hsl(356 55% 48%);
+  --color-destructive-foreground: hsl(0 0% 100%);
+  --color-success: hsl(152 38% 36%);
+  --color-success-foreground: hsl(0 0% 100%);
+  /* Amber has very high luminance-per-lightness; white text fails, so the
+   * foreground is near-black. Dark text on amber is the universal pattern. */
+  --color-warning: hsl(38 80% 50%);
+  --color-warning-foreground: hsl(0 0% 5%);
+  --color-info: hsl(202 55% 40%);
+  --color-info-foreground: hsl(0 0% 100%);
+
+  /* Functional-muted surfaces. In light each wash holds 4.5:1 against its base
+   * hue (dark text on light wash). In dark the luminance range of dark surfaces
+   * is too compressed for that — a surface dark enough for 4.5:1 base-as-text
+   * would be indistinguishable from the background. Each base hue instead
+   * clears the 3:1 graphical-object floor on its muted surface (icons,
+   * indicators), and text uses the foreground token (12-14:1 on every surface). */
+  --color-destructive-muted: hsl(356 40% 13%);
+  --color-success-muted: hsl(152 28% 13%);
+  --color-warning-muted: hsl(38 45% 13%);
+  --color-info-muted: hsl(202 35% 13%);
+
+  /* ---- Elevation: shadow recedes, background lightness ascends ----
+   * Shadows are nearly invisible on dark; elevation is communicated through
+   * the background lightness gradient (sunken through popover). The shadow
+   * tokens use a near-black colour with raised opacity so they remain faintly
+   * perceptible on the lightest dark surfaces (card, popover). */
+  --shadow-sm: 0 1px 2px 0 hsl(213 30% 2% / 0.18);
+  --shadow-md: 0 4px 12px -2px hsl(213 30% 2% / 0.22), 0 2px 6px -2px hsl(213 30% 2% / 0.16);
+  --shadow-lg: 0 12px 32px -6px hsl(213 30% 2% / 0.28), 0 4px 10px -4px hsl(213 30% 2% / 0.18);
+
+  /* Focus halo — shifts to the lighter dark-primary and raises opacity for
+   * visibility on dark surfaces. */
+  --shadow-halo: 0 0 0 4px hsl(211 33% 45% / 0.35);
 }

package/dist/theme.js

@@ -0,0 +1,171 @@
+import { computed, onScopeDispose, ref, watch } from "vue";
+//#region src/lib/theme.ts
+/**
+* Theme switching for Loom.
+*
+* The single source of truth is the `data-theme` attribute on `<html>`.
+* This composable reads and writes it, persists the preference to
+* `localStorage`, and resolves `"system"` mode from the OS preference.
+*
+* SSR-safe: every DOM access is guarded. On the server, `theme` returns
+* the persisted or default preference, `resolvedTheme` resolves `"system"`
+* to `"light"` (the only safe default without a DOM), and the setter and
+* toggler are no-ops.
+*
+* Flash prevention: `themeScript` is a string of inline JavaScript that
+* reads `localStorage` and sets `data-theme` before the first paint.
+* Consumers rendering SSR inject it into `<head>`:
+*
+*   <script>${themeScript}<\/script>
+*/
+var STORAGE_KEY = "loom:theme";
+var DATA_ATTR = "data-theme";
+var MEDIA_QUERY = "(prefers-color-scheme: dark)";
+/** Default preference when nothing is stored and no OS signal exists. */
+var DEFAULT_PREFERENCE = "system";
+/**
+* Reactive shared state, lazily initialised on the first `useTheme()` call
+* and torn down with the effect scope that owns it. Multiple components
+* calling `useTheme()` in the same app share the same refs and the same
+* `matchMedia` listener.
+*/
+var sharedState = null;
+/**
+* Reset the shared state. Intended for test isolation only — a real app
+* never needs this because the state lives for the app's lifetime.
+*/
+function _resetThemeState() {
+	if (sharedState?.mediaQuery && sharedState.listener) sharedState.mediaQuery.removeEventListener("change", sharedState.listener);
+	sharedState = null;
+}
+function getSharedState() {
+	if (sharedState) {
+		sharedState.scopeCount++;
+		return sharedState;
+	}
+	let stored = DEFAULT_PREFERENCE;
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === "light" || raw === "dark" || raw === "system") stored = raw;
+	} catch {}
+	applyToDOM(resolveTheme(stored, getSystemIsDark()));
+	const preference = ref(stored);
+	const systemIsDark = ref(getSystemIsDark());
+	let mediaQuery = null;
+	let listener = null;
+	try {
+		mediaQuery = window.matchMedia(MEDIA_QUERY);
+		listener = (e) => {
+			systemIsDark.value = e.matches;
+		};
+		mediaQuery.addEventListener("change", listener);
+	} catch {}
+	sharedState = {
+		preference,
+		systemIsDark,
+		mediaQuery,
+		listener,
+		scopeCount: 1
+	};
+	return sharedState;
+}
+function releaseSharedState() {
+	if (!sharedState) return;
+	sharedState.scopeCount--;
+	if (sharedState.scopeCount > 0) return;
+	if (sharedState.mediaQuery && sharedState.listener) sharedState.mediaQuery.removeEventListener("change", sharedState.listener);
+	sharedState = null;
+}
+function getSystemIsDark() {
+	try {
+		return window.matchMedia(MEDIA_QUERY).matches;
+	} catch {
+		return false;
+	}
+}
+function resolveTheme(pref, systemDark) {
+	return pref === "system" ? systemDark ? "dark" : "light" : pref;
+}
+function applyToDOM(theme) {
+	try {
+		document.documentElement.setAttribute(DATA_ATTR, theme);
+	} catch {}
+}
+function persist(preference) {
+	try {
+		localStorage.setItem(STORAGE_KEY, preference);
+	} catch {}
+}
+/**
+* Read and control the active Loom theme.
+*
+* @example
+* ```vue
+* <script setup>
+* import { useTheme } from "@ecoma-io/loom/theme"
+* const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme()
+* <\/script>
+*
+* <template>
+*   <button @click="toggleTheme">
+*     {{ resolvedTheme === "dark" ? "☀️" : "🌙" }}
+*   </button>
+* </template>
+* ```
+*/
+function useTheme() {
+	const state = getSharedState();
+	onScopeDispose(releaseSharedState);
+	/** The user's preference — `"system"` defers to the OS. */
+	const theme = computed({
+		get: () => state.preference.value,
+		set: (value) => {
+			state.preference.value = value;
+		}
+	});
+	/** The actual active theme, with `"system"` resolved to `"light"` or `"dark"`. */
+	const resolvedTheme = computed(() => resolveTheme(state.preference.value, state.systemIsDark.value));
+	watch([() => state.preference.value, () => state.systemIsDark.value], () => {
+		applyToDOM(resolvedTheme.value);
+		persist(state.preference.value);
+	});
+	/** Set the theme preference explicitly. */
+	function setTheme(preference) {
+		state.preference.value = preference;
+	}
+	/** Toggle between light and dark. System preference stays system. */
+	function toggleTheme() {
+		if (state.preference.value === "system") state.preference.value = resolvedTheme.value === "dark" ? "light" : "dark";
+		else state.preference.value = state.preference.value === "dark" ? "light" : "dark";
+	}
+	return {
+		theme,
+		resolvedTheme,
+		setTheme,
+		toggleTheme
+	};
+}
+/**
+* Inline script to prevent flash-of-wrong-theme on SSR pages.
+*
+* Paste it into `<head>` before any stylesheet links:
+*
+* ```html
+* <script><%= themeScript %><\/script>
+* ```
+*
+* It reads `localStorage` and sets `data-theme` on `<html>` synchronously,
+* before the browser paints, so the first frame is already in the right
+* theme. When no preference is stored, it follows the OS preference.
+*
+* The script is deliberately tiny and has no dependencies.
+*/
+var themeScript = `(() => {
+  const t = localStorage.getItem("${STORAGE_KEY}");
+  const d = window.matchMedia("${MEDIA_QUERY}").matches;
+  document.documentElement.setAttribute("${DATA_ATTR}", (t === "dark" || (!t && d)) ? "dark" : "light");
+})()`;
+//#endregion
+export { _resetThemeState, themeScript, useTheme };
+
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","names":[],"sources":["../src/lib/theme.ts"],"sourcesContent":["/**\n * Theme switching for Loom.\n *\n * The single source of truth is the `data-theme` attribute on `<html>`.\n * This composable reads and writes it, persists the preference to\n * `localStorage`, and resolves `\"system\"` mode from the OS preference.\n *\n * SSR-safe: every DOM access is guarded. On the server, `theme` returns\n * the persisted or default preference, `resolvedTheme` resolves `\"system\"`\n * to `\"light\"` (the only safe default without a DOM), and the setter and\n * toggler are no-ops.\n *\n * Flash prevention: `themeScript` is a string of inline JavaScript that\n * reads `localStorage` and sets `data-theme` before the first paint.\n * Consumers rendering SSR inject it into `<head>`:\n *\n *   <script>${themeScript}</script>\n */\n\nimport { type Ref, computed, onScopeDispose, ref, watch } from \"vue\";\n\n/** The preference a user expresses — `\"system\"` defers to the OS. */\nexport type ThemePreference = \"light\" | \"dark\" | \"system\";\n\n/** The actual theme applied — `\"system\"` is resolved away. */\nexport type ResolvedTheme = \"light\" | \"dark\";\n\nconst STORAGE_KEY = \"loom:theme\";\nconst DATA_ATTR = \"data-theme\";\nconst MEDIA_QUERY = \"(prefers-color-scheme: dark)\";\n\n/** Default preference when nothing is stored and no OS signal exists. */\nconst DEFAULT_PREFERENCE: ThemePreference = \"system\";\n\n// --- Shared state (one per Vue app, not one per composable call) ---------\n\ninterface ThemeState {\n  preference: Ref<ThemePreference>;\n  systemIsDark: Ref<boolean>;\n  mediaQuery: MediaQueryList | null;\n  listener: ((e: MediaQueryListEvent) => void) | null;\n  scopeCount: number;\n}\n\n/**\n * Reactive shared state, lazily initialised on the first `useTheme()` call\n * and torn down with the effect scope that owns it. Multiple components\n * calling `useTheme()` in the same app share the same refs and the same\n * `matchMedia` listener.\n */\nlet sharedState: ThemeState | null = null;\n\n/**\n * Reset the shared state. Intended for test isolation only — a real app\n * never needs this because the state lives for the app's lifetime.\n */\nexport function _resetThemeState(): void {\n  if (sharedState?.mediaQuery && sharedState.listener) {\n    sharedState.mediaQuery.removeEventListener(\"change\", sharedState.listener);\n  }\n  sharedState = null;\n}\n\nfunction getSharedState(): ThemeState {\n  if (sharedState) {\n    sharedState.scopeCount++;\n    return sharedState;\n  }\n\n  // Read the stored preference, defaulting to \"system\".\n  let stored: ThemePreference = DEFAULT_PREFERENCE;\n  try {\n    const raw = localStorage.getItem(STORAGE_KEY);\n    if (raw === \"light\" || raw === \"dark\" || raw === \"system\") {\n      stored = raw;\n    }\n  } catch {\n    // localStorage may be unavailable (SSR, private browsing).\n  }\n\n  // Apply the initial theme to the DOM so the very first render is correct.\n  const initial = resolveTheme(stored, getSystemIsDark());\n  applyToDOM(initial);\n\n  const preference = ref<ThemePreference>(stored);\n  const systemIsDark = ref<boolean>(getSystemIsDark());\n\n  // Listen for OS dark-mode changes.\n  let mediaQuery: MediaQueryList | null = null;\n  let listener: ((e: MediaQueryListEvent) => void) | null = null;\n\n  try {\n    mediaQuery = window.matchMedia(MEDIA_QUERY);\n    listener = (e: MediaQueryListEvent) => {\n      systemIsDark.value = e.matches;\n    };\n    mediaQuery.addEventListener(\"change\", listener);\n  } catch {\n    // matchMedia may be unavailable.\n  }\n\n  sharedState = {\n    preference,\n    systemIsDark,\n    mediaQuery,\n    listener,\n    scopeCount: 1,\n  };\n\n  return sharedState;\n}\n\nfunction releaseSharedState(): void {\n  if (!sharedState) return;\n  sharedState.scopeCount--;\n  if (sharedState.scopeCount > 0) return;\n\n  // Last consumer gone — tear down the listener.\n  if (sharedState.mediaQuery && sharedState.listener) {\n    sharedState.mediaQuery.removeEventListener(\"change\", sharedState.listener);\n  }\n  sharedState = null;\n}\n\n// --- DOM helpers --------------------------------------------------------\n\nfunction getSystemIsDark(): boolean {\n  try {\n    return window.matchMedia(MEDIA_QUERY).matches;\n  } catch {\n    return false;\n  }\n}\n\nfunction resolveTheme(pref: ThemePreference, systemDark: boolean): ResolvedTheme {\n  return pref === \"system\" ? (systemDark ? \"dark\" : \"light\") : pref;\n}\n\nfunction applyToDOM(theme: ResolvedTheme): void {\n  try {\n    document.documentElement.setAttribute(DATA_ATTR, theme);\n  } catch {\n    // document may be unavailable (SSR).\n  }\n}\n\nfunction persist(preference: ThemePreference): void {\n  try {\n    localStorage.setItem(STORAGE_KEY, preference);\n  } catch {\n    // localStorage may be unavailable.\n  }\n}\n\n// --- Public API ---------------------------------------------------------\n\n/**\n * Read and control the active Loom theme.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useTheme } from \"@ecoma-io/loom/theme\"\n * const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme()\n * </script>\n *\n * <template>\n *   <button @click=\"toggleTheme\">\n *     {{ resolvedTheme === \"dark\" ? \"☀️\" : \"🌙\" }}\n *   </button>\n * </template>\n * ```\n */\nexport function useTheme(): {\n  readonly theme: Ref<ThemePreference>;\n  readonly resolvedTheme: Readonly<Ref<ResolvedTheme>>;\n  readonly setTheme: (preference: ThemePreference) => void;\n  readonly toggleTheme: () => void;\n} {\n  const state = getSharedState();\n\n  // Clean up the shared listener when the consuming scope disposes.\n  onScopeDispose(releaseSharedState);\n\n  /** The user's preference — `\"system\"` defers to the OS. */\n  const theme = computed<ThemePreference>({\n    get: () => state.preference.value,\n    set: (value: ThemePreference) => {\n      state.preference.value = value;\n    },\n  });\n\n  /** The actual active theme, with `\"system\"` resolved to `\"light\"` or `\"dark\"`. */\n  const resolvedTheme = computed<ResolvedTheme>(() =>\n    resolveTheme(state.preference.value, state.systemIsDark.value),\n  );\n\n  // Whenever the preference or the OS signal changes, apply the resolved\n  // theme to the DOM and persist the preference.\n  watch([() => state.preference.value, () => state.systemIsDark.value], () => {\n    applyToDOM(resolvedTheme.value);\n    persist(state.preference.value);\n  });\n\n  /** Set the theme preference explicitly. */\n  function setTheme(preference: ThemePreference): void {\n    state.preference.value = preference;\n  }\n\n  /** Toggle between light and dark. System preference stays system. */\n  function toggleTheme(): void {\n    if (state.preference.value === \"system\") {\n      // Toggle the resolved theme and lock to it, so the user can override\n      // the OS preference with one click.\n      state.preference.value = resolvedTheme.value === \"dark\" ? \"light\" : \"dark\";\n    } else {\n      state.preference.value = state.preference.value === \"dark\" ? \"light\" : \"dark\";\n    }\n  }\n\n  return { theme, resolvedTheme, setTheme, toggleTheme } as const;\n}\n\n/**\n * Inline script to prevent flash-of-wrong-theme on SSR pages.\n *\n * Paste it into `<head>` before any stylesheet links:\n *\n * ```html\n * <script><%= themeScript %></script>\n * ```\n *\n * It reads `localStorage` and sets `data-theme` on `<html>` synchronously,\n * before the browser paints, so the first frame is already in the right\n * theme. When no preference is stored, it follows the OS preference.\n *\n * The script is deliberately tiny and has no dependencies.\n */\nexport const themeScript = `(() => {\n  const t = localStorage.getItem(\"${STORAGE_KEY}\");\n  const d = window.matchMedia(\"${MEDIA_QUERY}\").matches;\n  document.documentElement.setAttribute(\"${DATA_ATTR}\", (t === \"dark\" || (!t && d)) ? \"dark\" : \"light\");\n})()`;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA2BA,IAAM,cAAc;AACpB,IAAM,YAAY;AAClB,IAAM,cAAc;;AAGpB,IAAM,qBAAsC;;;;;;;AAkB5C,IAAI,cAAiC;;;;;AAMrC,SAAgB,mBAAyB;CACvC,IAAI,aAAa,cAAc,YAAY,UACzC,YAAY,WAAW,oBAAoB,UAAU,YAAY,QAAQ;CAE3E,cAAc;AAChB;AAEA,SAAS,iBAA6B;CACpC,IAAI,aAAa;EACf,YAAY;EACZ,OAAO;CACT;CAGA,IAAI,SAA0B;CAC9B,IAAI;EACF,MAAM,MAAM,aAAa,QAAQ,WAAW;EAC5C,IAAI,QAAQ,WAAW,QAAQ,UAAU,QAAQ,UAC/C,SAAS;CAEb,QAAQ,CAER;CAIA,WADgB,aAAa,QAAQ,gBAAgB,CAC1C,CAAO;CAElB,MAAM,aAAa,IAAqB,MAAM;CAC9C,MAAM,eAAe,IAAa,gBAAgB,CAAC;CAGnD,IAAI,aAAoC;CACxC,IAAI,WAAsD;CAE1D,IAAI;EACF,aAAa,OAAO,WAAW,WAAW;EAC1C,YAAY,MAA2B;GACrC,aAAa,QAAQ,EAAE;EACzB;EACA,WAAW,iBAAiB,UAAU,QAAQ;CAChD,QAAQ,CAER;CAEA,cAAc;EACZ;EACA;EACA;EACA;EACA,YAAY;CACd;CAEA,OAAO;AACT;AAEA,SAAS,qBAA2B;CAClC,IAAI,CAAC,aAAa;CAClB,YAAY;CACZ,IAAI,YAAY,aAAa,GAAG;CAGhC,IAAI,YAAY,cAAc,YAAY,UACxC,YAAY,WAAW,oBAAoB,UAAU,YAAY,QAAQ;CAE3E,cAAc;AAChB;AAIA,SAAS,kBAA2B;CAClC,IAAI;EACF,OAAO,OAAO,WAAW,WAAW,CAAC,CAAC;CACxC,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,aAAa,MAAuB,YAAoC;CAC/E,OAAO,SAAS,WAAY,aAAa,SAAS,UAAW;AAC/D;AAEA,SAAS,WAAW,OAA4B;CAC9C,IAAI;EACF,SAAS,gBAAgB,aAAa,WAAW,KAAK;CACxD,QAAQ,CAER;AACF;AAEA,SAAS,QAAQ,YAAmC;CAClD,IAAI;EACF,aAAa,QAAQ,aAAa,UAAU;CAC9C,QAAQ,CAER;AACF;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,WAKd;CACA,MAAM,QAAQ,eAAe;CAG7B,eAAe,kBAAkB;;CAGjC,MAAM,QAAQ,SAA0B;EACtC,WAAW,MAAM,WAAW;EAC5B,MAAM,UAA2B;GAC/B,MAAM,WAAW,QAAQ;EAC3B;CACF,CAAC;;CAGD,MAAM,gBAAgB,eACpB,aAAa,MAAM,WAAW,OAAO,MAAM,aAAa,KAAK,CAC/D;CAIA,MAAM,OAAO,MAAM,WAAW,aAAa,MAAM,aAAa,KAAK,SAAS;EAC1E,WAAW,cAAc,KAAK;EAC9B,QAAQ,MAAM,WAAW,KAAK;CAChC,CAAC;;CAGD,SAAS,SAAS,YAAmC;EACnD,MAAM,WAAW,QAAQ;CAC3B;;CAGA,SAAS,cAAoB;EAC3B,IAAI,MAAM,WAAW,UAAU,UAG7B,MAAM,WAAW,QAAQ,cAAc,UAAU,SAAS,UAAU;OAEpE,MAAM,WAAW,QAAQ,MAAM,WAAW,UAAU,SAAS,UAAU;CAE3E;CAEA,OAAO;EAAE;EAAO;EAAe;EAAU;CAAY;AACvD;;;;;;;;;;;;;;;;AAiBA,IAAa,cAAc;oCACS,YAAY;iCACf,YAAY;2CACF,UAAU"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ecoma-io/loom",
-  "version": "0.1.0",
-  "description": "Design system & components for the Ecoma ecosystem.",
+  "version": "0.2.0",
+  "description": "Opinionated UI system and composition library for cross-platform web applications.",
   "keywords": [
     "design-system",
     "component-library",
@@ -16,7 +16,10 @@
     "wcag",
     "theming",
     "dark-mode",
-    "ecoma"
+    "cross-platform",
+    "desktop",
+    "responsive",
+    "composition"
   ],
   "homepage": "https://github.com/ecoma-io/loom#readme",
   "repository": {
@@ -47,6 +50,10 @@
       "types": "./dist/a11y.d.ts",
       "default": "./dist/a11y.js"
     },
+    "./theme": {
+      "types": "./dist/lib/theme.d.ts",
+      "default": "./dist/theme.js"
+    },
     "./styles/global.css": "./dist/styles/global.css",
     "./styles/theme.css": "./dist/styles/theme.css",
     "./styles/fonts.css": "./dist/styles/fonts.css",
@@ -64,7 +71,7 @@
     "prepare": "lefthook install",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "lint": "eslint . --max-warnings 0 && node tools/check-component-artifacts.ts",
+    "lint": "eslint . --cache --cache-strategy content --cache-location node_modules/.cache/eslint --max-warnings 0 && node tools/check-component-artifacts.ts",
     "typecheck": "vue-tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -73,6 +80,7 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:stage": "node tools/stage-docs.ts",
+    "docs:check-route": "node tools/stage-docs.ts --check",
     "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
@@ -87,6 +95,7 @@
     "@vitest/coverage-v8": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.26",
     "@vue/test-utils": "^2.4.11",
+    "@vue/typescript-plugin": "3.3.9",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-playwright": "^2.11.0",
@@ -111,6 +120,7 @@
     "wrangler": "^4.118.0"
   },
   "dependencies": {
+    "@internationalized/date": "^3.12.3",
     "@lucide/vue": "^1.28.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/dist/icons/BrandMark.d.ts

@@ -1,18 +0,0 @@
-/**
- * BrandMark — one face, two forces. The left half is human (an almond eye),
- * the right half is the agent (a rectangular eye), and the dividing line is a
- * nose bridge: both halves belong to the same face, which is the
- * organization.
- *
- * Built with `createLucideIcon` so it takes exactly the props any Lucide icon
- * takes — size, strokeWidth, color — and a consumer cannot tell a custom icon
- * from a stock one. Custom icons live in this folder and follow the same
- * recipe: 24-unit grid geometry, stroke through `currentColor`.
- *
- * The duotone treatment, where the warp and weft halves carry their own
- * colours, is a brand asset rather than an icon. An icon stays monochrome so
- * it can inherit whatever colour it is dropped into.
- */
-declare const BrandMark: import("@lucide/vue").LucideIcon;
-export default BrandMark;
-//# sourceMappingURL=BrandMark.d.ts.map

package/dist/icons/BrandMark.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BrandMark.d.ts","sourceRoot":"","sources":["../../src/icons/BrandMark.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,SAAS,kCAgBb,CAAC;AAEH,eAAe,SAAS,CAAC"}