@supersoniks/concorde 5.1.0 → 5.1.2

package/src/docs/home/mach-stage.ts

@@ -0,0 +1,389 @@
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+
+/** The Concorde silhouette from the brand icon, nose up, in a 66 × 66 box centred on (33, 33). */
+const PLANE =
+  "M33.2499 62.03C33.8799 59.24 34.26 56.17 34.39 53.08C34.57 52.78 34.9099 52.6 35.2599 52.64H35.39C35.48 52.64 35.5799 52.64 35.6899 52.64H35.7599C35.7599 52.64 35.7999 52.64 35.8299 52.64C36.2499 52.62 36.6799 52.58 36.9099 52.56C36.9399 52.56 36.9599 52.56 36.9799 52.56C37.0099 52.56 37.0299 52.56 37.0499 52.56H37.0899L37.2099 51.93H37.4799L37.5799 52.4L37.6899 52.49H39.2699L39.39 52.38L39.5099 51.93H39.7899L39.8399 52.21L39.9999 52.29L45.2099 51.86L46.2799 51.29C46.2799 51.29 46.2799 50.85 46.2399 50.25V50.18C46.2399 50.18 46.2399 50.13 46.2399 50.11C46.2099 49.62 46.1399 49.13 46.0399 48.65C45.7899 47.45 45.29 46 42.2 41.58C39.11 37.16 38.04 35.52 35.89 27.63C35.85 27.48 35.8199 27.35 35.7899 27.2C35.1399 24.53 34.6899 22.95 34.5199 22.38V10.89C34.4999 9.60996 34.3999 8.33996 34.2099 7.07996C34.0499 5.97996 33.6099 4.89996 33.3499 3.95996H32.6299C32.3599 4.89996 31.9299 5.97996 31.7699 7.06996C31.5799 8.33996 31.4799 9.60996 31.4599 10.89V22.38C31.2899 22.95 30.8299 24.52 30.1899 27.2C30.1599 27.35 30.1199 27.49 30.0899 27.63C27.9499 35.52 26.8699 37.16 23.7799 41.58C20.6899 46 20.1899 47.45 19.9399 48.65C19.8399 49.13 19.7799 49.62 19.7399 50.11C19.7399 50.13 19.7399 50.16 19.7399 50.18V50.25C19.6999 50.85 19.7 51.29 19.7 51.29L20.7699 51.86L25.9799 52.29L26.14 52.21L26.1899 51.93H26.4799L26.5999 52.38L26.7299 52.49H28.2999L28.4099 52.4L28.5099 51.93H28.7699L28.89 52.56H28.9399C28.9399 52.56 28.9799 52.56 29.0099 52.56C29.0299 52.56 29.0499 52.56 29.0799 52.56C29.3099 52.58 29.7499 52.63 30.1599 52.64C30.1799 52.64 30.2099 52.64 30.2299 52.64H30.2999C30.4099 52.64 30.5099 52.64 30.5999 52.64H30.7299C31.0799 52.6 31.4299 52.77 31.6099 53.08C31.7299 56.17 32.1099 59.24 32.7399 62.03H33.2499Z";
+
+/** Speed of sound on the stage, in stage widths per second. */
+const SOUND = 0.19;
+/** Cruise: Concorde flew at Mach 2.02, 18 000 m up. */
+const CRUISE = 2.02;
+/** Grid cells across the field; every fourth line is heavier. */
+const GRID = 24;
+const WAVE_EVERY = 0.05;
+const WAVE_LIFE = 2.6;
+
+const clamp = (v: number, lo: number, hi: number) =>
+  Math.min(hi, Math.max(lo, v));
+const smooth = (a: number, b: number, v: number) => {
+  const t = clamp((v - a) / (b - a), 0, 1);
+  return t * t * (3 - 2 * t);
+};
+
+type Wave = { x: number; y: number; t: number };
+
+/**
+ * The hero's orange field as a Mach diagram: the aircraft drops a sound wave as it flies and,
+ * once it outruns them, the waves pile into the shock cone. On autopilot it accelerates through
+ * the barrier on every pass; a moving pointer steers it and moving fast
+ * enough breaks the barrier by hand. Reduced motion gets one still frame at cruise.
+ */
+@customElement("docs-mach-stage")
+export class DocsMachStage extends LitElement {
+  private canvas?: HTMLCanvasElement;
+  private ints: HTMLElement[] = [];
+  private decs: HTMLElement[] = [];
+  private plane = new Path2D(PLANE);
+  private waves: Wave[] = [];
+  private x = -0.3;
+  private y = 0.55;
+  private vx = 0.75 * SOUND;
+  private vy = 0;
+  private mach = 0;
+  private time = 0;
+  private lastWave = 0;
+  private pointer: { x: number; y: number; t: number } | null = null;
+  private boom = -10;
+  private frame = 0;
+  private last = 0;
+  private resize?: ResizeObserver;
+  private visible = true;
+  private io?: IntersectionObserver;
+
+  createRenderRoot() {
+    return this;
+  }
+
+  render() {
+    return html`<canvas class="mach-canvas" aria-hidden="true"></canvas>
+      <p class="mach-readout" aria-label="Concorde cruise speed: Mach 2.02">
+        <span class="mach-label">mach</span>
+        <span class="mach-value">
+          ${[
+            "mach-layer",
+            "mach-layer mach-ghost-a",
+            "mach-layer mach-ghost-b",
+          ].map(
+            (layer, i) =>
+              html`<span class=${layer} aria-hidden=${i ? "true" : "false"}
+                ><span class="mach-int">0</span><span class="mach-dot">.</span
+                ><span class="mach-dec">00</span></span
+              >`,
+          )}
+        </span>
+      </p>
+      <p class="mach-note">
+        cruise mach 2.02 · 18 000 m · paris – new york in 3 h 30
+      </p>`;
+  }
+
+  firstUpdated() {
+    this.canvas = this.querySelector("canvas")!;
+    this.ints = [...this.querySelectorAll<HTMLElement>(".mach-int")];
+    this.decs = [...this.querySelectorAll<HTMLElement>(".mach-dec")];
+    this.resize = new ResizeObserver(() => this.fit());
+    this.resize.observe(this);
+    this.io = new IntersectionObserver(
+      ([e]) => (this.visible = e.isIntersecting),
+    );
+    this.io.observe(this);
+    this.addEventListener("pointermove", this.onPointer);
+    this.addEventListener("pointerdown", this.onPointer);
+    this.addEventListener("pointerleave", this.onLeave);
+    this.fit();
+    if (matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      this.still();
+      return;
+    }
+    this.frame = requestAnimationFrame(this.tick);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    cancelAnimationFrame(this.frame);
+    this.resize?.disconnect();
+    this.io?.disconnect();
+  }
+
+  private onPointer = (e: PointerEvent) => {
+    const r = this.getBoundingClientRect();
+    this.pointer = {
+      x: (e.clientX - r.left) / r.width,
+      y: (e.clientY - r.top) / r.width,
+      t: this.time,
+    };
+  };
+
+  private onLeave = () => {
+    this.pointer = null;
+  };
+
+  private fit() {
+    const c = this.canvas!;
+    const dpr = Math.min(devicePixelRatio || 1, 2);
+    c.width = Math.round(this.clientWidth * dpr);
+    c.height = Math.round(this.clientHeight * dpr);
+    // publish the grid cell so the field's bevel can be cut along the grid
+    this.parentElement?.style.setProperty(
+      "--mach-cell",
+      `${this.clientWidth / GRID}px`,
+    );
+    if (matchMedia("(prefers-reduced-motion: reduce)").matches) this.still();
+  }
+
+  /** Height of the field in stage widths (positions are kept in widths so speed is uniform). */
+  private get aspect() {
+    return this.clientHeight / Math.max(1, this.clientWidth);
+  }
+
+  private tick = (now: number) => {
+    this.frame = requestAnimationFrame(this.tick);
+    const dt = Math.min(0.05, (now - (this.last || now)) / 1000);
+    this.last = now;
+    if (!this.visible || !dt) return;
+    this.time += dt;
+    this.fly(dt);
+    if (this.time - this.lastWave > WAVE_EVERY) {
+      this.lastWave = this.time;
+      this.waves.push({ x: this.x, y: this.y, t: this.time });
+    }
+    this.waves = this.waves.filter((w) => this.time - w.t < WAVE_LIFE);
+    this.draw();
+  };
+
+  private fly(dt: number) {
+    const h = this.aspect;
+    const before = this.mach;
+    // flown by heading and speed, never by position, so it always carries on along an arc
+    let speed = Math.hypot(this.vx, this.vy);
+    let heading = Math.atan2(this.vy, this.vx);
+    let wantSpeed: number;
+    let wantHeading: number;
+    let turn: number;
+    let throttle: number;
+    const steering = this.pointer && this.time - this.pointer.t < 0.4;
+    if (steering) {
+      // head for a moving pointer; the further ahead it runs, the faster the aircraft goes
+      const dx = this.pointer!.x - this.x;
+      const dy = this.pointer!.y - this.y;
+      wantHeading = Math.atan2(dy, dx);
+      wantSpeed = clamp(Math.hypot(dx, dy) * 2.5, 0.6 * SOUND, 2.4 * SOUND);
+      turn = 5;
+      throttle = 4;
+    } else {
+      // autopilot: endless passes, speeding up to cruise across the field and easing off
+      // while out of sight, so each pass hands over to the next without a cut
+      const up = smooth(-0.1, 0.65, this.x);
+      const down = smooth(1.0, 1.2, this.x);
+      wantSpeed = (0.6 + (CRUISE - 0.6) * up * (1 - down)) * SOUND;
+      const cy = h * 0.55 + Math.sin(this.time * 0.6) * h * 0.06;
+      wantHeading = Math.atan2(cy - this.y, 0.6);
+      turn = 2;
+      throttle = 2;
+    }
+    let delta = wantHeading - heading;
+    delta = Math.atan2(Math.sin(delta), Math.cos(delta));
+    heading += delta * Math.min(1, dt * turn);
+    speed += (wantSpeed - speed) * Math.min(1, dt * throttle);
+    this.vx = Math.cos(heading) * speed;
+    this.vy = Math.sin(heading) * speed;
+    this.x += this.vx * dt;
+    this.y += this.vy * dt;
+    // out of sight on the right, back in on the left; the old waves fade where they were left
+    if (!steering && this.x > 1.3) this.x -= 1.6;
+    this.mach = speed / SOUND;
+    if (before < 1 && this.mach >= 1) this.boom = this.time;
+  }
+
+  private colours() {
+    const s = getComputedStyle(this);
+    return { ink: s.color, field: s.backgroundColor };
+  }
+
+  private draw() {
+    const c = this.canvas!;
+    const g = c.getContext("2d")!;
+    const W = c.width;
+    const u = W; // one stage width in device pixels
+    const { ink } = this.colours();
+    g.clearRect(0, 0, c.width, c.height);
+    g.strokeStyle = ink;
+    g.fillStyle = ink;
+    const px = this.x * u;
+    const py = this.y * u;
+
+    // graph paper under the diagram: a fine square grid, every fourth line heavier
+    const cell = u / GRID;
+    g.lineWidth = Math.max(1, u * 0.0008);
+    for (let i = 0, x = 0; x <= c.width; i++, x += cell) {
+      g.globalAlpha = i % 4 ? 0.1 : 0.22;
+      g.beginPath();
+      g.moveTo(Math.round(x) + 0.5, 0);
+      g.lineTo(Math.round(x) + 0.5, c.height);
+      g.stroke();
+    }
+    for (let i = 0, y = 0; y <= c.height; i++, y += cell) {
+      g.globalAlpha = i % 4 ? 0.1 : 0.22;
+      g.beginPath();
+      g.moveTo(0, Math.round(y) + 0.5);
+      g.lineTo(c.width, Math.round(y) + 0.5);
+      g.stroke();
+    }
+
+    // the shock cone, filled, once supersonic
+    if (this.mach > 1.02) {
+      const mu = Math.asin(1 / this.mach);
+      const dir = Math.atan2(this.vy, this.vx);
+      const len = u * 2;
+      g.globalAlpha = Math.min(0.22, (this.mach - 1) * 0.35);
+      g.beginPath();
+      g.moveTo(px, py);
+      g.lineTo(px - Math.cos(dir - mu) * len, py - Math.sin(dir - mu) * len);
+      g.lineTo(px - Math.cos(dir + mu) * len, py - Math.sin(dir + mu) * len);
+      g.closePath();
+      g.fill();
+    }
+
+    // the waves: each one a circle growing at the speed of sound from where it was dropped
+    g.lineWidth = Math.max(2, u * 0.003);
+    for (const w of this.waves) {
+      const age = this.time - w.t;
+      const r = age * SOUND * u;
+      g.globalAlpha = Math.max(0, 1 - age / WAVE_LIFE) * 0.9;
+      g.beginPath();
+      g.arc(w.x * u, w.y * u, r, 0, Math.PI * 2);
+      g.stroke();
+    }
+
+    this.construct(g, u, px, py);
+
+    // the boom: one heavy ring when the barrier goes
+    const since = this.time - this.boom;
+    if (since >= 0 && since < 1.4) {
+      g.globalAlpha = 1 - since / 1.4;
+      g.lineWidth = u * 0.018 * (1 - since / 1.4) + 2;
+      g.beginPath();
+      g.arc(px, py, since * SOUND * u * 3.2, 0, Math.PI * 2);
+      g.stroke();
+    }
+
+    // the aircraft, pointing where it flies
+    g.globalAlpha = 1;
+    const size = u * 0.15;
+    g.save();
+    g.translate(px, py);
+    g.rotate(Math.atan2(this.vy, this.vx) + Math.PI / 2);
+    g.scale(size / 66, size / 66);
+    g.translate(-33, -33);
+    g.fill(this.plane);
+    g.restore();
+
+    const [int, dec] = this.mach.toFixed(2).split(".");
+    for (const el of this.ints) el.textContent = int;
+    for (const el of this.decs) el.textContent = dec;
+    // the readout splits and shakes for a moment as the barrier goes
+    this.toggleAttribute("data-boom", since >= 0 && since < 0.9);
+    this.toggleAttribute("data-supersonic", this.mach >= 1);
+  }
+
+  /**
+   * Construction lines, as on a textbook figure: the flight path, the Mach lines run out to the
+   * edges, a few radii dropped square onto them from the centres that made them, and the angle.
+   */
+  private construct(
+    g: CanvasRenderingContext2D,
+    u: number,
+    px: number,
+    py: number,
+  ) {
+    const c = this.canvas!;
+    const dir = Math.atan2(this.vy, this.vx);
+    const reach = Math.hypot(c.width, c.height) * 2;
+    const line = (x1: number, y1: number, x2: number, y2: number) => {
+      g.beginPath();
+      g.moveTo(x1, y1);
+      g.lineTo(x2, y2);
+      g.stroke();
+    };
+    g.lineWidth = Math.max(1, u * 0.0012);
+
+    // flight path, dashed, through the whole field
+    g.globalAlpha = 0.45;
+    g.setLineDash([u * 0.012, u * 0.008]);
+    line(
+      px - Math.cos(dir) * reach,
+      py - Math.sin(dir) * reach,
+      px + Math.cos(dir) * reach,
+      py + Math.sin(dir) * reach,
+    );
+    g.setLineDash([]);
+
+    // centre marks where the waves were dropped
+    const mark = u * 0.006;
+    g.globalAlpha = 0.5;
+    this.waves.forEach((w, i) => {
+      if (i % 6) return;
+      line(w.x * u - mark, w.y * u, w.x * u + mark, w.y * u);
+      line(w.x * u, w.y * u - mark, w.x * u, w.y * u + mark);
+    });
+
+    if (this.mach <= 1.02) return;
+    const mu = Math.asin(1 / this.mach);
+    for (const side of [-1, 1]) {
+      const ex = Math.cos(dir + Math.PI + side * mu);
+      const ey = Math.sin(dir + Math.PI + side * mu);
+      // the Mach line, run out past the cone to the edge
+      g.globalAlpha = 0.6;
+      line(px, py, px + ex * reach, py + ey * reach);
+      // radii, square to the Mach line, from a few of the centres
+      g.globalAlpha = 0.45;
+      this.waves.forEach((w, i) => {
+        if (i % 12 || this.time - w.t < 0.5) return;
+        const cx = w.x * u;
+        const cy = w.y * u;
+        const along = (cx - px) * ex + (cy - py) * ey;
+        if (along <= 0) return;
+        line(cx, cy, px + ex * along, py + ey * along);
+      });
+    }
+
+    // the angle, marked at the apex, its value set just outside the cone where no wave reaches
+    const r = u * 0.12;
+    g.globalAlpha = 1;
+    g.lineWidth = Math.max(2, u * 0.003);
+    g.beginPath();
+    g.arc(px, py, r, dir + Math.PI - mu, dir + Math.PI + mu);
+    g.stroke();
+    const edge = dir + Math.PI + mu;
+    const out = edge + Math.PI / 2;
+    const gap = u * 0.03;
+    g.font = `600 ${Math.round(u * 0.024)}px ${getComputedStyle(this).fontFamily}`;
+    g.textAlign = "center";
+    g.textBaseline = "middle";
+    const deg = ((mu * 180) / Math.PI).toFixed(1);
+    g.fillText(
+      `μ ${deg}°`,
+      px + Math.cos(edge) * r * 1.1 + Math.cos(out) * gap,
+      py + Math.sin(edge) * r * 1.1 + Math.sin(out) * gap,
+    );
+  }
+
+  /** Reduced motion: the field at cruise, waves laid out as they would be, nothing moving. */
+  private still() {
+    if (!this.canvas) return;
+    const h = this.aspect;
+    this.x = 0.68;
+    this.y = h * 0.55;
+    this.vx = CRUISE * SOUND;
+    this.vy = 0;
+    this.mach = CRUISE;
+    this.time = WAVE_LIFE;
+    this.boom = -10;
+    this.waves = [];
+    for (let t = 0; t < WAVE_LIFE; t += WAVE_EVERY * 2) {
+      this.waves.push({ x: this.x - this.vx * (WAVE_LIFE - t), y: this.y, t });
+    }
+    this.draw();
+  }
+}

package/src/docs/layout.ts

@@ -1,18 +1,19 @@
-const onLocationChange = (location: Location) => {
-  if (location.pathname === "/" && location.hash === "") {
+import LocationHandler from "@supersoniks/concorde/core/utils/LocationHandler";
+import { parseDocsLocation } from "./docs-location";
+
+const onLocationChange = (locationHref: string) => {
+  const { url } = parseDocsLocation(locationHref);
+  // No markdown path → home.
+  if (!url) {
     document.documentElement.setAttribute("data-home", "");
   } else {
     document.documentElement.removeAttribute("data-home");
   }
 };
-const getCurrentLocation = () => document.location;
-const currentLocation: Location = getCurrentLocation();
-onLocationChange(currentLocation);
-window.addEventListener("popstate", (event) => {
-  onLocationChange(getCurrentLocation());
-});
 
-// Listen for changes in the URL hash
-window.addEventListener("hashchange", () => {
-  onLocationChange(getCurrentLocation());
+// LocationHandler polls document.location (covers pushState; popstate alone does not).
+LocationHandler.onChange({
+  set location(value: string) {
+    onLocationChange(value);
+  },
 });

package/src/docs/misc/api-configuration.md

@@ -0,0 +1,79 @@
+# API configuration
+
+`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get](/docs/decorators/get) / [@post](/docs/decorators/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.
+
+> **Mock service:** same [Local API demos](/docs/misc/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.
+
+## Attribute map
+
+| Attribute (ancestor) | `APIConfiguration` field | Role |
+|---------------------|---------------------------|------|
+| `serviceURL` | `serviceURL` | Base URL (e.g. `/docs-mock-api`) |
+| `token` | `token` | Static Bearer sent on REST calls |
+| `userName` / `password` | `userName` / `password` | Basic auth for **tokenProvider** fetch only |
+| `eventsApiToken` | `authToken` | Bearer for **tokenProvider** when no Basic |
+| `tokenProvider` | `tokenProvider` | Path to GET a new token (`{ token }` JSON) |
+| `wordingProvider` | — (read by `wording()`) | Base path + query for label batch GET |
+| `wordingVersionProvider` | — | Publisher id; bump version → reload wordings |
+| `credentials` | `credentials` | `fetch` credentials mode |
+| `addHTTPResponse` | `addHTTPResponse` | Attach `_sonic_http_response_` on result |
+| `cache` | `cache` | `fetch` cache mode |
+| `blockUntilDone` | `blockUntilDone` | Serialize calls per `serviceURL` |
+| `keepAlive` | `keepAlive` | `fetch` keepalive |
+
+**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](/docs/misc/dataProviderKey)).
+
+## Bearer token (static)
+
+Publisher `docsApiConfBearerKey` (`set(docsApiConfBearerKey, { token: "docs-mock-valid-token", … })`) — mock returns the protected payload.
+
+<docs-lit-demo for="docs-api-config-bearer-demo"></docs-lit-demo>
+
+## tokenProvider + Basic auth
+
+No static `token`: `API.auth()` calls `GET /docs-mock-api/auth/token` with Basic **demo** / **secret**, stores `token`, then calls the protected route.
+
+<docs-lit-demo for="docs-api-config-token-provider-demo"></docs-lit-demo>
+
+## HTTP 498 — stale token refresh
+
+Initial `token="docs-mock-stale-token"` → mock responds **498** → Concorde invalidates the token, runs `auth()` again (same `tokenProvider` + Basic), retries with `docs-mock-fresh-token`.
+
+<docs-lit-demo for="docs-api-config-stale-token-demo"></docs-lit-demo>
+
+## eventsApiToken
+
+Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config (used as Bearer when calling `tokenProvider`, instead of Basic).
+
+<docs-lit-demo for="docs-api-config-events-token-demo"></docs-lit-demo>
+
+## Wording API
+
+`wordingProvider` and `wordingVersionProvider` are read by the translation directive: see [t()](/docs/directives/t).
+
+## Scoped attributes (HTML / sonic-scope)
+
+Attributes on **`sonic-scope`** (or any ancestor) are visible to descendants via `getAncestorAttributeValue`.
+
+<docs-lit-demo for="docs-api-config-scoped-attrs-demo"></docs-lit-demo>
+
+## API config routes
+
+| Route | Demo |
+|-------|------|
+| `GET /docs-mock-api/auth/token` | tokenProvider, eventsApiToken |
+| `GET /docs-mock-api/api/config/protected` | Bearer / Basic / 498 |
+| `GET /docs-mock-api/wording/labels?labels[]=…&lang=fr` | `wording()` |
+
+Mock tokens (doc only): `docs-mock-valid-token`, `docs-mock-stale-token` (498), `docs-mock-fresh-token` (after refresh). Basic: **demo** / **secret**. Events token: `docs-mock-events-token`.
+
+Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service Worker with `router.ts`).
+
+## See also
+
+- [@get](/docs/decorators/get) — `APIConfiguration` + `Endpoint`
+- [@post](/docs/decorators/post) — same configuration model for POST
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH
+- [Endpoint](/docs/misc/endpoint) — typed path
+- [Local API demos](/docs/misc/docs-mock-api) — offline `serviceURL`
+- [Fetch](/core/components/functional/fetch) — attribute table (legacy sonic-fetch)

package/src/docs/misc/dataProviderKey.md

@@ -0,0 +1,168 @@
+# DataProviderKey
+
+The `DataProviderKey<T>` utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via `toString()` or the `path` property.
+
+For a **single HTTP path string** (no dot-syntax), see [Endpoint](/docs/misc/endpoint). For **`DataProviderKey<APIConfiguration>`**, see [API configuration](/docs/misc/api-configuration).
+
+## Principle
+
+`DataProviderKey` uses a Proxy to intercept property access and build a cumulative path string. TypeScript infers the nested type at each level, so `myKey.items[0]` is correctly typed as `DataProviderKey<Item>` when `items` is `Item[]`.
+
+In Lit demos, bind HTML attributes from a key’s **`.path`** (single source of truth), and use **`get` / `set` / `dp`** instead of `PublisherManager.get("…")`:
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
+
+export const myFormKey = new DataProviderKey&lt;{ email: string }&gt;("myForm");
+set(myFormKey, { email: "a@b.c" });
+
+// template: formDataProvider=${myFormKey.path}
+  </template>
+</sonic-code>
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+### Basic example
+
+<sonic-code language="typescript">
+  <template>
+type Item = { id: string; name: string };
+//
+type Data = {
+  items: Item[];
+  count: number;
+};
+//
+const myKey = new DataProviderKey&lt;Data&gt;("data").items[0];
+// Equivalent to: new DataProviderKey&lt;Item&gt;("data.items.0")
+myKey.toString();  // "data.items.0"
+myKey.path;        // same value
+// myKey is typed as DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Object property access
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data");
+const countKey = key.count;
+countKey.path;        // "data.count"
+countKey.toString();  // "data.count"
+  </template>
+</sonic-code>
+
+### Array index access
+
+<sonic-code language="typescript">
+  <template>
+const itemsKey = new DataProviderKey&lt;Data&gt;("data").items;
+itemsKey.path;  // "data.items"
+// itemsKey is DataProviderKey&lt;Item[]&gt;
+//
+const firstItem = itemsKey[0];
+firstItem.path;  // "data.items.0"
+// firstItem is DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Dynamic paths
+
+Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. See [Dynamic path placeholders](/docs/misc/dynamic-path) for resolution rules and `skipEmptyPlaceholder`. The type remains declarative:
+
+<sonic-code language="typescript">
+  <template>
+type User = { name: string; email: string };
+//
+// Path resolved from component.userIndex at runtime
+@subscribe(new DataProviderKey&lt;User&gt;("users.${userIndex}"))
+@state()
+user: User | null = null;
+  </template>
+</sonic-code>
+
+Dynamic keys are **not** supported by `get`, `set`, or `dp` — those APIs take a snapshot at call time with no component context. For dynamic paths use decorators (`@subscribe`, `@publish`, `@handle`) or **`sub(key)`** in Lit templates (resolves `${…}` from the host component). See [sub()](/docs/directives/sub).
+
+### get / set / dp with static keys
+
+For programmatic access, pass a `DataProviderKey` or a static path string. Dynamic placeholders are rejected:
+
+<sonic-code language="typescript">
+  <template>
+import { dp, get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+const counterKey = new DataProviderKey&lt;{ count: number }&gt;("myCounter");
+//
+set(counterKey, { count: 0 });
+dp(counterKey.count).set(1);
+get(counterKey);  // snapshot: { count: 1 }
+  </template>
+</sonic-code>
+
+## Path retrieval
+
+The final path is built by concatenating each accessed property with a dot:
+
+- `new DataProviderKey<T>("base")` → `"base"`
+- `key.prop` → `"base.prop"`
+- `key.items[0]` → `"base.items.0"`
+
+Use `toString()` or `path` to get the full path string:
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data").count;
+const pathString = key.toString();  // "data.count"
+const pathProp = key.path;           // "data.count"
+  </template>
+</sonic-code>
+
+## Use cases
+
+- **Type-safe bindings**: paths for `@bind`, `@subscribe`, `@publish`, `@handle`
+- **Dynamic paths**: reusable keys with `${...}` placeholders
+- **Form fields**: form data paths with compile-time checking
+
+## Integration with @subscribe, @publish and @handle
+
+Use `DataProviderKey` with `@subscribe` (read-only), `@publish` (write-only), or `@handle` (method callback on assign). With `@subscribe` / `@publish`, the decorated property **must** match the key’s value type. With `@handle`, the method receives `(value: T)`.
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+type FormData = { email: string };
+const formKey = new DataProviderKey&lt;FormData&gt;("formData");
+//
+@customElement("user-form")
+export class UserForm extends LitElement {
+  @subscribe(formKey.email)
+  @state()
+  email = "";
+//
+  render() {
+    return html`&lt;input .value=${this.email} @input=${(e) => this.email = (e.target as HTMLInputElement).value}&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path). See [@handle](/docs/decorators/handle) for method callbacks.
+
+## Notes
+
+- Function properties are excluded from navigation (no `key.method()` chaining)
+- Primitives have no navigable properties
+- The `path` property and `toString()` are equivalent for retrieving the key