@ultimat3/ui 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -14,8 +14,16 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 - **No raw colours.** Only `t.role('<role>')` / `var(--color-*)`. Canonical roles live in `src/tokens/_colors.scss`; `tokens.ts` mirrors them and `tokens.test.ts` fails on drift.
 - **Logical properties only.** `margin-inline`, `inset-inline-start`, `text-align: start`. A `left`/`right` in a stylesheet is a bug.
 - **solid-js is a type-only import.** All reactive access goes through `src/theme/solid-adapter.ts`. Never `import { createSignal } from 'solid-js'`.
+- **The runtime SLOT is `src/theme/runtime-slot.ts`; the RULE is `solid-adapter.ts`, and the split is a byte measurement.** `solid()` throws `runtimeMissingError`, so it imports `../errors`, which `package.json` declares side-effectful (`registerErrorCodes()` runs at import) and no bundler may shake — so while the slot sat beside it, an island whose `mount` did nothing but `setSolidRuntime(solidRuntime)` carried @ultimat3/core's whole error registry: **5,719 B against 72 B**. One module owns `let runtime`, `solid()` reads it through `registeredSolidRuntime()`, and `barrel-bytes.test.ts` holds the ceiling at 1 kB — small enough that the registry re-entering the graph reds it.
+- **The barrel is the ONE import path, and component subpath exports are refused on measurement** (2026-08-23, issue #275). `import { Button } from '@ultimat3/ui'` and a deep path into `components/Button` emit the same chunk, to within the length of the entry's own module name; so do `useUi` (14 kB) and `moneyText` (25 kB). `@ultimat3/ui/button` would be a second idiom for zero bytes. The two subpaths that exist are not exceptions to that: `./icons/*` is 1,767 data modules no bundler can split, and `./jsx-probe` is test-only and deliberately absent from the barrel. `barrel-bytes.test.ts` compares the two paths, so the day the barrel stops shaking this argument reds instead of ageing.
 - **`solid()` always answers off-DOM.** No registered runtime and no DOM is a *server render*, and it gets `INERT_SOLID_RUNTIME` (`src/theme/inert-runtime.ts`) — signals hold, memos recompute on read, effects never run, `useContext` returns the default. No DOM means no reactivity to lose; a **DOM** with no runtime is still `X_UI_RUNTIME_MISSING`, because that one is the theme toggle that does nothing. Never widen this to "no runtime, never throw": that is the silent degradation the split exists to prevent.
 - **`useUi()` reads the request on the server**, via `ambientUiContext()` — `currentLocale()`, `currentTimeZone()`, `useI18n()`. Those two read **core's own `Ctx.locale` / `Ctx.tz`**, which `@ultimat3/http`'s `locale` stage writes once per request; `@ultimat3/i18n` and `@ultimat3/time` publish no field of their own. Never add a second ambient store here or there — `time` kept a `ctx['timeZone']` nothing wrote until 2026-08, and the whole cost was invisible: every server-rendered date formatted in UTC under a doc comment saying it did not. `theme`/`currency` deliberately have no ambient source at all.
+- **Every locale-sensitive call takes the locale as an ARGUMENT, `toLocaleUpperCase` included.**
+  `initialsOf(name, locale)` reads `useUi().locale`, exactly as `DateTime` does. A bare
+  `toLocaleUpperCase()` reads the RUNTIME's default — a server's `LANG`, a browser's UI language —
+  which is the ambient locale this package does not have; Turkish is where the absence shows,
+  because dotted `i` uppercases to `İ`, so a Turkish member's avatar read `I` on a server in
+  Ireland. **Breaking**: `initialsOf`'s second parameter is required.
 - **`UiProvider` is client-only and throws on the server** (`providerNeedsRuntimeError`, the same `X_UI_RUNTIME_MISSING`). A Provider in an inert tree reaches no descendant — the tree is built before the renderer walks it, so consumers are walked outside every owner and read the context default even with a real Solid runtime registered. Rendering the children anyway would drop its locale, zone, currency and translator silently. Making it work needs the *renderer* to scope a context around the walk; until then it refuses.
 - **A component may call `solid()` freely.** Its effects must stay DOM-only work — they simply never run on the server.
 - **No `{...rest}` prop spreading.** Splitting props reactively needs solid's `splitProps` (a value import), so components declare explicit props and read `props.x` inside JSX.
@@ -43,7 +51,8 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 |---|---|
 | `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers |
 | `src/tokens/theme.scss` | the only stylesheet that emits global custom properties |
-| `src/theme/solid-adapter.ts` | the runtime slot and the one rule that decides which runtime a render gets |
+| `src/theme/runtime-slot.ts` | the module-scope slot holding the app's Solid runtime — and nothing else, so registering one costs an island 72 B |
+| `src/theme/solid-adapter.ts` | the runtime's SHAPE, and the one rule that decides which runtime a render gets |
 | `src/theme/inert-runtime.ts` | `INERT_SOLID_RUNTIME` — what a server render IS, not a stub of what it lacks |
 | `src/theme/theme.ts` | resolution: stored choice → OS; all side effects via injected `ThemeEnv` |
 | `src/theme/inline-script.ts` | anti-flash `<head>` snippet + its CSP sha256 |
@@ -56,6 +65,7 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 | `src/roving.ts` | the pure rules of a keyboard group: navigable set, tab stop, who keeps their own arrows |
 | `src/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
 | `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reached from `@ultimat3/admin` at `@ultimat3/ui/jsx-probe`; the walkers stay internal |
+| `src/barrel-bytes.test.ts` | the build error behind the two byte claims above: the setter's ceiling, and barrel-vs-deep-path parity |
 | `src/components/style-classes.test.ts` | the build error behind "every `styles['x']` a component names is declared in its own `.module.scss`" — under `bun test` a `.module.scss` import resolves to the file PATH, so no render can catch a dead class |
 
 ## Assumed peer contracts

package/README.md

@@ -274,20 +274,28 @@ as text, because `t()`'s catalog does not cross the seam and neither does a call
 what is rendered. `UiProvider` sets `lang` + `dir` on `<html>` from `locale`, so
 `ar-EG` needs no second stylesheet and no second component.
 
-**An island pays for the barrel, not for the component it named.** Measured through
-`buildIslands` — minified, production Solid, `As of 2026-08-21`:
+**An island pays for what it names, and `import { … } from '@ultimat3/ui'` is the one way to
+name it.** Measured through `buildIslands` — minified, production Solid, `As of 2026-08-23`:
 
 | An island that imports | Chunk |
 |---|---|
 | nothing | 52 B |
-| `setSolidRuntime` alone | 5.7 kB |
-| `<UiProvider>` + one `<Button>` | 49.0 kB, of which Solid's own runtime is 12.2 kB |
-| `<UiProvider>` + `<Form>` + `<Input>` + `<Button>` | 54.8 kB |
-
-There are no component subpath exports, so `import { Button }` reaches the whole index —
-issue **#275**. `@ultimat3/ui/icons/*` is the one part of the package already shaped the
-other way, and is what the components want. Budget an island against these numbers, not
-against the component's own source.
+| `setSolidRuntime` alone | 74 B |
+| `<UiProvider>` + one `<Button>` | 49.4 kB, of which Solid's own runtime is 12.6 kB |
+| `<UiProvider>` + `<Form>` + `<Input>` + `<Button>` | 55.3 kB |
+
+**There are no component subpath exports, and there will not be** — measured, not asserted:
+`import { Button } from '@ultimat3/ui'` and a deep path into `components/Button` produce the
+same chunk to within the bytes of the entry's own name, and so do `useUi` (14 kB) and
+`moneyText` (25 kB). `@ultimat3/ui/button` would be a second way to import one name for zero
+bytes, which is axiom 1 for nothing. `src/barrel-bytes.test.ts` is the build error, and it will
+red the day the barrel stops shaking. `@ultimat3/ui/icons/*` is a subpath for the opposite
+reason: 1,767 glyph modules are data, and no bundler splits one module holding all of them.
+
+What a component's 49 kB actually is: Solid's runtime, `@ultimat3/i18n`'s translator and plural
+machinery reached through `useUi()`, and `@ultimat3/core`'s error registry reached through
+`errors.ts` — none of which a different export shape removes. Budget an island against these
+numbers, not against the component's own source.
 
 ## `<Text>` and `<Image>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "10.0.0",
+  "version": "11.1.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -44,10 +44,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "10.0.0",
-    "@ultimat3/i18n": "10.0.0",
-    "@ultimat3/money": "10.0.0",
-    "@ultimat3/time": "10.0.0"
+    "@ultimat3/core": "11.1.0",
+    "@ultimat3/i18n": "11.1.0",
+    "@ultimat3/money": "11.1.0",
+    "@ultimat3/time": "11.1.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/components/Avatar.tsx

@@ -5,6 +5,7 @@
 import { safeUrl } from '@ultimat3/core';
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
+import { useUi } from '../theme/context';
 import styles from './Avatar.module.scss';
 import type { Size } from './variants';
 
@@ -21,16 +22,24 @@ export interface AvatarProps {
 
 const PX: Readonly<Record<string, number>> = { xs: 20, sm: 24, md: 32, lg: 40, xl: 64 };
 
-/** First letters of the first two words — locale-safe, no ASCII assumptions. */
-export function initialsOf(name: string): string {
+/**
+ * First letters of the first two words — locale-safe, no ASCII assumptions.
+ *
+ * `locale` is REQUIRED, exactly as it is on `dateTimeView`: a bare `toLocaleUpperCase()` reads the
+ * RUNTIME's default locale, which is a server's `LANG` and a browser's UI language, and never the
+ * request's. Turkish is where the absence shows — dotted `i` uppercases to `İ` — and this package
+ * has no ambient locale to fall back on by rule.
+ */
+export function initialsOf(name: string, locale: string): string {
   const words = name.trim().split(/\s+/).filter(Boolean).slice(0, 2);
   return words
     .map((word) => [...word][0] ?? '')
     .join('')
-    .toLocaleUpperCase();
+    .toLocaleUpperCase(locale);
 }
 
 export function Avatar(props: AvatarProps): JSX.Element {
+  const ui = useUi();
   const px = (): number => PX[props.size ?? 'md'] ?? 32;
 
   return (
@@ -46,7 +55,7 @@ export function Avatar(props: AvatarProps): JSX.Element {
     >
       {props.src === undefined ? (
         <span aria-hidden="true" class={styles['initials']}>
-          {initialsOf(props.name)}
+          {initialsOf(props.name, ui.locale)}
         </span>
       ) : (
         <img

package/src/components/image-source.ts

@@ -116,8 +116,25 @@ export function assertNonEmptySrc(kind: string, value: unknown, src: string): st
   return trimmed;
 }
 
+/**
+ * `srcset` is a comma-separated list whose entries are split on WHITESPACE — so the two characters
+ * a src may not carry are whitespace anywhere and a comma at either end. Trimming the ends is not
+ * enough: `'/my file.webp 800w'` parses as the URL `/my` with the descriptor `file.webp`, which is
+ * not a descriptor, so the candidate is dropped and the `<img>` silently falls back to `src`. An
+ * INTERIOR comma is fine and is deliberately allowed — the parser reads a URL up to the first
+ * whitespace, so `/img/a,b.webp` round-trips.
+ */
+const SRCSET_UNSAFE = /\s|^,|,$/;
+
 function toCandidate(variant: ImageVariant): Candidate {
   const src = assertNonEmptySrc('Image', variant, variant.src);
+  if (SRCSET_UNSAFE.test(src)) {
+    throw invalidValueError(
+      'Image',
+      variant,
+      'a variant src with no whitespace and no leading or trailing comma — srcset splits on both, so such a src is dropped by the browser rather than reported',
+    );
+  }
 
   const width = variant.width;
   const density = variant.density;

package/src/index.ts

@@ -220,13 +220,11 @@ export {
 } from './theme/inline-script';
 export type { UiProviderProps } from './theme/provider';
 export { UiProvider } from './theme/provider';
+// The slot is its own module so that registering a runtime does not drag `errors.ts` — and with it
+// @ultimat3/core's error registry — into an island chunk. `barrel-bytes.test.ts` holds the ceiling.
+export { clearSolidRuntime, hasSolidRuntime, setSolidRuntime } from './theme/runtime-slot';
 export type { Accessor, Setter, SolidContext, SolidRuntime } from './theme/solid-adapter';
-export {
-  clearSolidRuntime,
-  hasSolidRuntime,
-  setSolidRuntime,
-  solid,
-} from './theme/solid-adapter';
+export { solid } from './theme/solid-adapter';
 export type { ThemeEnv } from './theme/theme';
 // --- theme -------------------------------------------------------------------
 export {

package/src/theme/context.ts

@@ -14,7 +14,8 @@ import {
 } from '@ultimat3/i18n';
 import { currentTimeZone, type TimeZone } from '@ultimat3/time';
 import type { Theme } from '../tokens/tokens';
-import { hasSolidRuntime, type SolidContext, type SolidRuntime, solid } from './solid-adapter';
+import { hasSolidRuntime } from './runtime-slot';
+import { type SolidContext, type SolidRuntime, solid } from './solid-adapter';
 
 export type { Direction };
 

package/src/theme/provider.tsx

@@ -14,7 +14,8 @@ import {
   type UiContextValue,
   uiContext,
 } from './context';
-import { hasSolidRuntime, solid } from './solid-adapter';
+import { hasSolidRuntime } from './runtime-slot';
+import { solid } from './solid-adapter';
 
 export interface UiProviderProps {
   theme?: Theme | undefined;

package/src/theme/runtime-slot.ts

@@ -0,0 +1,34 @@
+// The module-scope slot holding the app's Solid runtime, and nothing else.
+//
+// Split out of `solid-adapter.ts` because of what the neighbours cost: `solid()` throws
+// `runtimeMissingError`, so it imports `../errors`, which `package.json` declares side-effectful
+// (`registerErrorCodes()` runs at import) and no bundler may therefore shake. An island that only
+// REGISTERS the runtime paid @ultimat3/core's whole error registry for it — 5,719 B against 72 B,
+// measured in `barrel-bytes.test.ts`, which is the build error behind this file existing.
+
+import type { SolidRuntime } from './solid-adapter';
+
+let runtime: SolidRuntime | null = null;
+
+/** Register once, in the app entry, before the first render. */
+export function setSolidRuntime(next: SolidRuntime): void {
+  runtime = next;
+}
+
+export function hasSolidRuntime(): boolean {
+  return runtime !== null;
+}
+
+/** For tests: drop the registration so cases stay independent. */
+export function clearSolidRuntime(): void {
+  runtime = null;
+}
+
+/**
+ * The registered runtime or `null` — read only by `solid()`, which owns the rule about what a
+ * missing one MEANS. A component never reaches this: two answers to "which runtime does this
+ * render get" is the split this file is careful not to become.
+ */
+export function registeredSolidRuntime(): SolidRuntime | null {
+  return runtime;
+}

package/src/theme/solid-adapter.ts

@@ -1,10 +1,15 @@
-// Solid runtime adapter. @ultimat3/ui imports *types* from solid-js and nothing
-// else, so the package installs, typechecks, and tests with no reactive runtime
-// present. The CLIENT entry registers the real one once; a server render gets the inert one.
+// Solid runtime adapter: the shape of the runtime, and the ONE rule that decides which runtime a
+// render gets. @ultimat3/ui imports *types* from solid-js and nothing else, so the package
+// installs, typechecks, and tests with no reactive runtime present.
+//
+// The slot itself is `runtime-slot.ts`, not this file: `runtimeMissingError` below reaches
+// `../errors`, which is side-effectful and unshakeable, so an island that only registers a runtime
+// would pay the error registry for it (`barrel-bytes.test.ts`).
 
 import type { JSX } from 'solid-js';
 import { runtimeMissingError } from '../errors';
 import { INERT_SOLID_RUNTIME } from './inert-runtime';
+import { registeredSolidRuntime } from './runtime-slot';
 
 export type Accessor<T> = () => T;
 export type Setter<T> = (next: T) => void;
@@ -34,22 +39,6 @@ export interface SolidRuntime {
   onCleanup(fn: () => void): void;
 }
 
-let runtime: SolidRuntime | null = null;
-
-/** Register once, in the app entry, before the first render. */
-export function setSolidRuntime(next: SolidRuntime): void {
-  runtime = next;
-}
-
-export function hasSolidRuntime(): boolean {
-  return runtime !== null;
-}
-
-/** For tests: drop the registration so cases stay independent. */
-export function clearSolidRuntime(): void {
-  runtime = null;
-}
-
 /**
  * A DOM is the whole of the question. With one, a component that reaches for a runtime nobody
  * registered is a real bug — the theme toggle that does nothing — so it throws. Without one there
@@ -63,6 +52,7 @@ function hasDom(): boolean {
 }
 
 export function solid(): SolidRuntime {
+  const runtime = registeredSolidRuntime();
   if (runtime !== null) return runtime;
   if (hasDom()) {
     // Two lines to paste, and both are real: `x g resource` writes exactly them into the slice's