@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/core/components/ui/toast/toast.md

@@ -1,14 +1,12 @@
 # Toast
 
-Toasts surface **short-lived feedback** in a fixed stack (bottom-right in the main window). Queue messages with **`SonicToast.add()`** on the global **`SonicToast`** class—the host **`sonic-toast`** is created automatically. Prefer **`label`** for a heading; use **`preserve`** or interactive **`text`** when the user must read or act before dismiss.
+Toasts show short-lived feedback in a fixed stack at the bottom right of the page. Call **`SonicToast.add()`** (also `window.SonicToast`); the **`sonic-toast`** host is created on first use. Use **`label`** for a heading and **`preserve`** when the user must read or act before the toast goes away.
 
 ## Basic example
 
-Click the button to show a toast.
-
 <sonic-code>
   <template>
-    <sonic-button onclick="SonicToast.add({ text: 'Simple notification' })">
+    <sonic-button onclick="SonicToast.add({ text: 'Flight CN 001 is now boarding' })">
       Show toast
     </sonic-button>
   </template>
@@ -16,54 +14,37 @@ Click the button to show a toast.
 
 ## Status
 
-**`status`** drives color, icon, and live-region behavior. Omit **`status`** or pass an empty string for a neutral toast.
+**`status`** sets the color, the icon and the live-region role. With no `status`, the toast is neutral.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Default message', status: '' })">
-        Default
-      </sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">
-        Success
-      </sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">
-        Error
-      </sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">
-        Warning
-      </sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">
-        Info
-      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Default message' })">Default</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">Success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">Error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">Warning</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">Info</sonic-button>
     </div>
   </template>
 </sonic-code>
 
 ## Label
 
-Set **`label`** for a bold title above **`text`**. **`title`** still works but is deprecated—use **`label`** in new code.
+**`label`** adds a bold heading above **`text`**. `title` is a deprecated alias.
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button
-        onclick="SonicToast.add({ label: 'Success', text: 'Your request was processed.', status: 'success' })"
-      >
-        Toast with label
-      </sonic-button>
-      <sonic-button
-        onclick="SonicToast.add({ label: 'Error', text: 'Processing failed. Try again.', status: 'error' })"
-      >
-        Error with label
-      </sonic-button>
-    </div>
+    <sonic-button
+      onclick="SonicToast.add({ label: 'Gate change', text: 'Flight CN 001 now departs from gate B12.', status: 'warning' })"
+    >
+      Toast with label
+    </sonic-button>
   </template>
 </sonic-code>
 
 ## HTML in text
 
-**`text`** (and **`label`**) can include HTML strings. Links and controls in **`text`** automatically enable **`preserve`** so the toast does not auto-hide while the user interacts.
+**`text`** and **`label`** accept HTML strings. A link or form control in **`text`** turns on **`preserve`** automatically.
 
 <sonic-code>
   <template>
@@ -77,12 +58,12 @@ Set **`label`** for a bold title above **`text`**. **`title`** still works but i
 
 ## Preserve
 
-Without **`preserve`**, toasts auto-hide after about six seconds (timer pauses on hover or focus). Set **`preserve`** to keep the toast until the user closes it.
+Toasts hide after 6 seconds; the timer pauses on hover and focus. **`preserve`** keeps the toast until the user closes it.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ text: 'This toast stays until you dismiss it', status: 'info', preserve: true })"
+      onclick="SonicToast.add({ text: 'Turbulence ahead: please fasten your seat belt', status: 'info', preserve: true })"
     >
       Persistent toast
     </sonic-button>
@@ -91,12 +72,12 @@ Without **`preserve`**, toasts auto-hide after about six seconds (timer pauses o
 
 ## Dismiss forever
 
-With **`dismissForever`** and a stable **`id`**, closing the toast stores dismissal in **`localStorage`**—**`SonicToast.add`** skips it on later visits. Duplicate payloads (same fields, ignoring **`id`**) are not queued twice.
+With **`dismissForever`** and a stable **`id`**, closing the toast is stored in `localStorage` and later `add()` calls with that `id` are ignored. A toast identical to one already shown (ignoring `id`) is never added twice.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ id: 'unique-toast-id', text: 'Dismiss forever hides this across reloads', status: 'info', dismissForever: true })"
+      onclick="SonicToast.add({ id: 'welcome-toast', label: 'Welcome', text: 'Close me and I will not come back after a reload.', status: 'info', dismissForever: true })"
     >
       Dismiss forever
     </sonic-button>
@@ -105,112 +86,62 @@ With **`dismissForever`** and a stable **`id`**, closing the toast stores dismis
 
 ## Ghost
 
-**`ghost`** renders a semi-transparent, non-interactive toast—useful for loading or background states. **`SonicToast.removeAll`** leaves ghost toasts in place.
+**`ghost`** renders a semi-transparent, non-interactive toast, for example for a background task.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ text: 'Ghost toast (non-interactive)', status: 'info', ghost: true })"
+      onclick="SonicToast.add({ text: 'Syncing in the background', status: 'info', ghost: true })"
     >
       Ghost toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Dismissal
-
-Use static helpers to clear the stack from app logic (for example after navigation).
+## Removing toasts
 
-### Remove all
-
-Removes every toast except **`ghost`** items.
+Static helpers clear the stack from script, for example after navigation. **`removeAll()`** keeps ghost toasts; **`removeTemporaryItems()`** keeps preserved ones.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Toast 1', status: 'info' })">Add toast 1</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Toast 2', status: 'success' })">Add toast 2</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Toast 3', status: 'warning' })">Add toast 3</sonic-button>
-      <sonic-button onclick="SonicToast.removeAll()">Remove all</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary success', status: 'success' })">Add success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary error', status: 'error' })">Add error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Persistent info', status: 'info', preserve: true })">Add persistent</sonic-button>
     </div>
-  </template>
-</sonic-code>
-
-### Remove by status
-
-<sonic-code>
-  <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Success toast', status: 'success' })">Success</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Error toast', status: 'error' })">Error</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Warning toast', status: 'warning' })">Warning</sonic-button>
-      <sonic-button onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
-      <sonic-button onclick="SonicToast.removeItemsByStatus('error')">Remove error</sonic-button>
-    </div>
-  </template>
-</sonic-code>
-
-### Remove temporary items
-
-Removes toasts that are not **`preserve`**.
-
-<sonic-code>
-  <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Temporary toast', status: 'info' })">Temporary</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Persistent toast', status: 'success', preserve: true })">
-        Persistent
-      </sonic-button>
-      <sonic-button onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
+    <div class="flex flex-wrap gap-2 mt-3">
+      <sonic-button variant="outline" onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
+      <sonic-button variant="outline" onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
+      <sonic-button variant="outline" onclick="SonicToast.removeAll()">Remove all</sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## Combined options
-
-<sonic-code>
-  <template>
-    <sonic-button
-      onclick="SonicToast.add({
-      id: 'welcome-toast',
-      label: 'Welcome',
-      text: 'Welcome to the platform. Explore the docs to get started.',
-      status: 'success',
-      dismissForever: true
-    })"
-    >
-      Full example
-    </sonic-button>
-  </template>
-</sonic-code>
-
-## Accessibility
-
-Each toast uses **`role="alert"`** for **`error`** and **`role="status"`** otherwise (with **`aria-live="polite"`** when applicable). Status icons are decorative (**`aria-hidden`**). The close control has an i18n **`aria-label`**. When there is no **`label`**, a truncated string **`aria-label`** may be derived from plain **`text`**.
+Inside an iframe, toasts are forwarded to the parent window's stack when the parent also loads Concorde.
 
 ## API reference
 
-Options passed to **`SonicToast.add(conf)`**:
+Options of **`SonicToast.add(options)`**:
 
 | Option | Values | Description |
 |----------|---------|-------------|
-| `text` | string · Lit template | Main body; HTML strings are supported |
-| `label` | string · Lit template | Optional heading above **`text`** |
-| `title` | string · Lit template | Deprecated alias for **`label`** |
-| `status` | `success` · `error` · `warning` · `info` · `` (empty) | Semantic styling and live region behavior |
-| `id` | string · number | Stable id for deduplication and **`dismissForever`** (defaults to timestamp) |
-| `preserve` | boolean | Skip auto-hide; forced when **`text`** contains interactive markup |
-| `ghost` | boolean | Semi-transparent and non-interactive; kept by **`removeAll`** |
-| `dismissForever` | boolean | Persist dismissal in **`localStorage`** when closed (requires stable **`id`**) |
-| `styleSheet` | modal style input | Extra adopted styles on the toast item shadow root |
-| `useSlot` | boolean | Legacy: project **`text`** into the light DOM slot |
+| `text` | string · Lit template | Body, required; HTML strings allowed |
+| `label` | string · Lit template | Heading above `text` |
+| `title` | string · Lit template | Deprecated alias of `label` |
+| `status` | `success` · `error` · `warning` · `info` (default neutral) | Color and icon; `error` gets `role="alert"`, others `role="status"` |
+| `id` | string · number (default timestamp) | Identifier for `removeItemById` and `dismissForever` |
+| `preserve` | boolean | No auto-hide; forced when `text` contains a link or control |
+| `ghost` | boolean | Semi-transparent and non-interactive; kept by `removeAll` |
+| `dismissForever` | boolean | Remember the dismissal in `localStorage`; needs a stable `id` |
+| `styleSheet` | `CSSResult` · `CSSStyleSheet` · array | Extra styles adopted by the toast |
+| `useSlot` | boolean | Legacy: render `text` in the light DOM |
 
 | Method | Description |
 |--------|-------------|
-| `SonicToast.add(conf)` | Append a toast; returns the config or **`null`** if skipped (dismissed forever or duplicate) |
-| `SonicToast.removeAll()` | Remove all non-**`ghost`** toasts |
-| `SonicToast.removeItemsByStatus(status)` | Remove toasts matching **`status`** |
-| `SonicToast.removeItemById(id)` | Remove a single toast by **`id`** |
-| `SonicToast.removeTemporaryItems()` | Remove toasts without **`preserve`** |
+| `SonicToast.add(options)` | Show a toast; returns the stored config, or `null` when skipped |
+| `SonicToast.removeAll()` | Remove every toast except ghosts |
+| `SonicToast.removeItemsByStatus(status)` | Remove toasts with this `status` |
+| `SonicToast.removeItemById(id)` | Remove one toast |
+| `SonicToast.removeTemporaryItems()` | Remove toasts without `preserve` |
 
-**`sonic-toast`** is mounted automatically; **`sonic-toast-item`** is internal. In iframes, toasts can delegate to the parent window via **`postMessage`**.
+`sonic-toast` and `sonic-toast-item` are created by `add()`; do not write them in markup. `sonic-toast-message-subscriber` shows a toast for each `{ type: "public", content, status }` entry of its `messages` property.

package/src/core/components/ui/tooltip/tooltip.md

@@ -1,12 +1,12 @@
 # Tooltip
 
-Tooltip shows a short **`label`** on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default **`placement`** is **`top`** (center-aligned). An empty **`label`** hides the bubble the same way as **`disabled`**.
+**`sonic-tooltip`** shows a short `label` in a bubble when the trigger in the default slot is hovered or receives focus. With no `placement`, the bubble sits on `top`, centered. An empty `label` hides the bubble, like `disabled`.
 
 ## Basic example
 
 <sonic-code>
   <template>
-    <sonic-tooltip label="Additional context on hover">
+    <sonic-tooltip label="Cruising at Mach 2.04">
       <sonic-button variant="outline">Hover me</sonic-button>
     </sonic-tooltip>
   </template>
@@ -14,67 +14,34 @@ Tooltip shows a short **`label`** on hover (and on focus when the trigger can re
 
 ## Placement
 
-Use **`top`** · **`bottom`** · **`left`** · **`right`** for the main axis. Add **`-start`** or **`-end`** to align the bubble along the anchor edge.
+`top` · `bottom` · `left` · `right` set the side. Add `-start` or `-end` to align the bubble with an edge of the trigger instead of its center. The bubble is repositioned while open to stay in the viewport.
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-tooltip placement="top" label="Top">
-        <sonic-button>Top</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="bottom" label="Bottom">
-        <sonic-button>Bottom</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="right" label="Right">
-        <sonic-button>Right</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="left" label="Left">
-        <sonic-button>Left</sonic-button>
-      </sonic-tooltip>
+    <div class="flex flex-wrap gap-3">
+      <sonic-tooltip placement="top" label="top"><sonic-button minWidth="9rem">top</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="top-start" label="top-start"><sonic-button minWidth="9rem">top-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="top-end" label="top-end"><sonic-button minWidth="9rem">top-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom" label="bottom"><sonic-button minWidth="9rem">bottom</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom-start" label="bottom-start"><sonic-button minWidth="9rem">bottom-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom-end" label="bottom-end"><sonic-button minWidth="9rem">bottom-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left" label="left"><sonic-button minWidth="9rem">left</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left-start" label="left-start"><sonic-button minWidth="9rem">left-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left-end" label="left-end"><sonic-button minWidth="9rem">left-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right" label="right"><sonic-button minWidth="9rem">right</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right-start" label="right-start"><sonic-button minWidth="9rem">right-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right-end" label="right-end"><sonic-button minWidth="9rem">right-end</sonic-button></sonic-tooltip>
     </div>
   </template>
 </sonic-code>
 
-### Aligned placements
+## Multiline label
 
-<sonic-code>
-  <template>
-    <div class="flex gap-3 flex-wrap">
-      <sonic-tooltip placement="top-start" label="Top start">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="top-end" label="Top end">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="bottom-start" label="Bottom start">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="bottom-end" label="Bottom end">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="right-start" label="Right start">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="right-end" label="Right end">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="left-start" label="Left start">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="left-end" label="Left end">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left end</sonic-button>
-      </sonic-tooltip>
-    </div>
-  </template>
-</sonic-code>
-
-## Label formatting
-
-**`label`** supports line breaks (`\n` in markup or multiline text). Lines are trimmed; **`&nbsp;`** is normalized to spaces. **`white-space: pre-line`** preserves breaks in the bubble (max width **18rem**).
+Line breaks in `label` (a real newline or `&#10;`) are kept. Each line is trimmed and the bubble wraps at `18rem`.
 
 <sonic-code>
   <template>
-    <sonic-tooltip label="First line&#10;Second line">
+    <sonic-tooltip label="Gate B12&#10;Boarding at 08:15">
       <sonic-button variant="outline">Multiline label</sonic-button>
     </sonic-tooltip>
   </template>
@@ -82,7 +49,7 @@ Use **`top`** · **`bottom`** · **`left`** · **`right`** for the main axis. Ad
 
 ## Focusable
 
-On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0"`** and the tooltip opens on keyboard focus as well as hover.
+Set `focusable` when the trigger is not focusable itself (text, icon): the host gets `tabindex="0"` so keyboard users can open the tooltip. The bubble uses `popover="hint"`; without Popover API support, the label falls back to a native `title` on one line.
 
 <sonic-code>
   <template>
@@ -98,6 +65,8 @@ On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0
 
 ## Disabled
 
+`disabled` never shows the bubble and sets `tabindex="-1"` on the host.
+
 <sonic-code>
   <template>
     <sonic-tooltip disabled label="Not shown">
@@ -106,19 +75,15 @@ On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0
   </template>
 </sonic-code>
 
-## Accessibility
-
-The bubble uses **`popover="hint"`** (non-modal, no pointer capture). Prefer **`focusable`** when the slotted content is not already focusable. When the Popover API is unavailable, the host falls back to the native **`title`** attribute with a single-line label. Opacity transitions respect **`prefers-reduced-motion`**.
-
 ## API reference
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `label` | string | Tooltip copy; whitespace-only values suppress the bubble |
-| `placement` | `top` (default) · `bottom` · `left` · `right` · `top-start` · `top-end` · `bottom-start` · `bottom-end` · `left-start` · `left-end` · `right-start` · `right-end` | Position relative to the trigger; repositions while open |
-| `disabled` | boolean | Suppress show/hide; sets **`tabindex="-1"`** on the host |
-| `focusable` | boolean | Add **`tabindex="0"`** on the host for keyboard access |
+| `label` | string | Tooltip text; empty or whitespace-only hides the bubble |
+| `placement` | `top` (default) · `bottom` · `left` · `right`, each with optional `-start` · `-end` | Side and alignment relative to the trigger |
+| `disabled` | boolean | Never show the bubble; sets `tabindex="-1"` on the host |
+| `focusable` | boolean | Sets `tabindex="0"` on the host so the tooltip opens on keyboard focus |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Trigger content (hover target) |
+| *(default)* | Trigger content |

package/src/core/decorators/subscriber/bind.ts

@@ -189,28 +189,23 @@ function bindImpl(
   };
 }
 
+/** @deprecated Pass a `DataProviderKey<T>` instead of a string path (typed, refactor-safe). */
+export function bind(
+  path: string,
+  options?: BindOptions,
+): (target: unknown, propertyKey: string) => void;
 /**
- * Bidirectional binding to a publisher path. Subscribes to changes and optionally reflects writes back.
- * Accepts either a string path (legacy) or DataProviderKey&lt;T&gt; for type-safe binding.
- * Supports dynamic paths: use placeholders like "users.${userIndex}" in the path or DataProviderKey.
+ * Bidirectional binding to a publisher path: subscribes to changes and, with
+ * `reflect: true`, writes local assignments back. For one direction only, use
+ * `@subscribe` (read) or `@publish` (write).
+ * Supports dynamic paths: use placeholders like "users.${userIndex}" in the DataProviderKey.
  *
  * @example
- * // String path (legacy):
- * @bind("demoData.firstName")
- * @state()
- * firstName = "";
- *
- * @example
- * // DataProviderKey with type validation:
  * const dataKey = new DataProviderKey<Data>("data");
  * @bind(dataKey.count, { reflect: true })
  * @state()
  * count: number = 0;
  */
-export function bind(
-  path: string,
-  options?: BindOptions,
-): (target: unknown, propertyKey: string) => void;
 export function bind<T, U = any>(
   key: DataProviderKey<T, U>,
   options?: BindOptions,

package/src/core/decorators/subscriber/subscribe.ts

@@ -2,31 +2,37 @@ import type {
   DataProviderKey,
   DataProviderKeyHost,
 } from "../../utils/dataProviderKey";
+import type { Frozen } from "../../utils/deepReadonly";
 import { bind } from "./bind";
 
 /**
- * Read-only subscription to a publisher path via DataProviderKey<T>. No reflect.
- * The decorated property is typed as `T` (or optional / `| null` / `| undefined` for Lit / TS 5).
- * Supports dynamic paths: use placeholders like "users.${userIndex}" in the DataProviderKey.
+ * Read-only subscription to a publisher path via `DataProviderKey<T>`. No reflect.
+ * The decorated property **must** be typed {@link Frozen}`<T>` (runtime = owned
+ * frozen store ref). Primitives: `Frozen<number>` ≡ `number`.
+ * Use `@publish` / `@bind({ reflect: true })` to write.
  *
  * @example
- * const dataKey = new DataProviderKey<Data>("data");
  * @subscribe(dataKey.count)
- * @state()
  * count: number;
  *
- * // Dynamic path:
+ * @subscribe(dataKey.cities)
+ * cities?: Frozen<City[]>;
+ *
  * @subscribe(new DataProviderKey<User>("users.${userIndex}"))
- * user: User | null;
+ * user: Frozen<User> | null;
  */
 export function subscribe<T, U = any>(
   key: DataProviderKey<T, U>,
 ): <K extends string>(
-  target: DataProviderKeyHost<U> & { [P in K]?: T | null | undefined },
+  target: DataProviderKeyHost<U> & {
+    [P in K]?: Frozen<T> | null | undefined;
+  },
   propertyKey: K,
 ) => void {
   return bind(key) as <K extends string>(
-    target: DataProviderKeyHost<U> & { [P in K]?: T | null | undefined },
+    target: DataProviderKeyHost<U> & {
+      [P in K]?: Frozen<T> | null | undefined;
+    },
     propertyKey: K,
   ) => void;
 }

package/src/core/decorators/subscriber/subscribe.type-test.ts

@@ -1,32 +1,41 @@
 /**
- * Type tests for subscribe — ensures property type must match DataProviderKey<T>.
+ * Type tests for subscribe — property must be Frozen<T>.
  * Excluded from build. To verify: temporarily remove from exclude and run build.
- * Expected: InvalidUsage and InvalidUsage2 should produce type errors.
+ * Expected: InvalidUsage* should produce type errors.
  */
 import { DataProviderKey } from "../../utils/dataProviderKey";
+import type { Frozen } from "../../utils/deepReadonly";
 import { subscribe } from "./subscribe";
 
 type ControlStats = {
   gauge: number;
   label: string;
+  cities: { nom: string }[];
 };
 
 const statsKey = new DataProviderKey<ControlStats>("stats");
 
-// OK: gauge is number, matches DataProviderKey<number>
 class ValidUsage {
   @subscribe(statsKey.gauge)
   gauge = 0;
 }
 
-// Should error: gauge should be number, not string
+class ValidFrozenArray {
+  @subscribe(statsKey.cities)
+  cities?: Frozen<{ nom: string }[]>;
+}
+
 class InvalidUsage {
   @subscribe(statsKey.gauge)
   gauge: string = "";
 }
 
-// Should error: label should be string, not number
 class InvalidUsage2 {
   @subscribe(statsKey.label)
   label: number = 0;
 }
+
+class InvalidMutableArray {
+  @subscribe(statsKey.cities)
+  cities?: { nom: string }[];
+}

package/src/core/utils/LocationHandler.spec.ts

@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import LocationHandler from "./LocationHandler";
+
+describe("LocationHandler.changeFromComponent pushState", () => {
+  const pushState = vi.fn();
+
+  beforeEach(() => {
+    pushState.mockClear();
+    vi.stubGlobal("history", {
+      pushState,
+      replaceState: vi.fn(),
+      state: null,
+      length: 1,
+    });
+    vi.stubGlobal("document", {
+      location: {
+        href: "https://concorde.supersoniks.org/",
+        origin: "https://concorde.supersoniks.org",
+        pathname: "/",
+        search: "",
+        hash: "",
+      },
+      title: "Concorde",
+    });
+  });
+
+  function el(attrs: Record<string, string>) {
+    return {
+      getAttribute: (k: string) => (k in attrs ? attrs[k] : null),
+      hasAttribute: (k: string) => k in attrs,
+      href: attrs.href || "",
+      goBack: null,
+      autoActive: "disabled",
+    } as never;
+  }
+
+  it("pushState keeps a single leading slash (no protocol-relative //path)", () => {
+    LocationHandler.changeFromComponent(
+      el({ href: "/docs/getting-started/start", pushState: "" }),
+    );
+    expect(pushState).toHaveBeenCalledTimes(1);
+    expect(pushState.mock.calls[0][2]).toBe("/docs/getting-started/start");
+  });
+
+  it("preserves hash fragments on pathname routes", () => {
+    LocationHandler.changeFromComponent(
+      el({
+        href: "/core/components/functional/router#departures",
+        pushState: "",
+      }),
+    );
+    expect(pushState.mock.calls[0][2]).toBe(
+      "/core/components/functional/router#departures",
+    );
+  });
+
+  it("keeps pretty component paths without inventing a trailing duplicate", () => {
+    LocationHandler.changeFromComponent(
+      el({
+        href: "/core/components/functional/router",
+        pushState: "",
+      }),
+    );
+    expect(pushState.mock.calls[0][2]).toBe(
+      "/core/components/functional/router",
+    );
+  });
+
+  it("collapses empty segments from double slashes", () => {
+    LocationHandler.changeFromComponent(
+      el({ href: "/docs//getting-started//start", pushState: "" }),
+    );
+    expect(pushState.mock.calls[0][2]).toBe("/docs/getting-started/start");
+  });
+
+  it("navigates to / for the homepage", () => {
+    LocationHandler.changeFromComponent(el({ href: "/", pushState: "" }));
+    expect(pushState.mock.calls[0][2]).toBe("/");
+  });
+});