@lumencast/runtime 0.4.0 → 0.6.0

package/src/render/bundle.ts

@@ -48,6 +48,17 @@ export interface RenderNode {
    *  the primitive applies no `initial` and the prior no-mount-play
    *  behaviour holds (backward compatible). */
   animate_initial?: Record<string, number | string>;
+  /** LSML 1.1 §6.3 — animation targets bound to leaf paths
+   *  (`bindAnimate`). Keys are the spec property names (`opacity`,
+   *  `transform.translate`, `transform.scale`, `transform.rotate`,
+   *  `filter.blur`, `filter.brightness`, plus the kind's colour-typed
+   *  property per §6.5 : `style.color` / `fill` / `background`) ; values
+   *  are LeafPaths. The runtime subscribes each path's leaf-grain signal
+   *  and retargets a Framer motion value on change — continuous
+   *  interpolation toward the live value, no remount. Deltas are
+   *  coalesced per frame (one retarget max per rAF per binding,
+   *  ADR 001 RC#13). */
+  animateBindings?: Record<string, string>;
   /** LSML 1.1 §6.6 — multi-step keyframe sequence played on mount or
    *  whenever `keyframes.key` (LeafPath) changes. Coexists with
    *  `transitions` ; the runtime applies whichever was last triggered
@@ -102,9 +113,11 @@ export interface RenderBundle {
   external_adapters?: ExternalAdapter[];
   assets?: Asset[];
   /** LSML 1.1 §17.3 — capability profiles required for correct rendering.
-   * Each entry is a `<vendor>.<name>-<version>` string. The runtime
-   * checks every entry against its supported list ; an unrecognised
-   * profile raises BUNDLE_INCOMPATIBLE per §17.3.1. */
+   * Each entry is an `x-<vendor>.<name>/<version>` string. The runtime
+   * checks every behavioural entry against its supported list ; an
+   * unrecognised behavioural profile raises BUNDLE_INCOMPATIBLE per
+   * §17.3.1. Authoring profiles (`x-<vendor>.authoring/<major>`, §17.5.1)
+   * are advisory : ignored at render time, never a rejection cause. */
   profiles?: string[];
 }
 
@@ -123,6 +136,44 @@ export const SUPPORTED_PROFILES: ReadonlySet<string> = new Set<string>([
   "x-lumencast.color-srgb-1.0",
 ]);
 
+// LSML 1.1 §17.5.1 + ADR 001 RC#14 — authoring-profile detection.
+//
+// An authoring profile is advisory : a runtime that does not support it
+// MUST NOT reject the bundle and renders the underlying primitives as if
+// the profile were absent. Detection matches the COMPLETE identifier form
+// `x-<vendor>.authoring/<major>` :
+//
+//   - `x-` prefix, then one or more lowercase name segments separated by
+//     dots, where `.authoring` is the EXACT TERMINAL segment before `/` ;
+//   - `<major>` is a bare integer (no `.minor`) ;
+//   - never a substring test : a behavioural profile whose name merely
+//     *contains* `.authoring` in a non-terminal position is NOT exempted
+//     and keeps §17.3.1 hard-rejection semantics.
+//
+// Anti-ReDoS note : both regexes below are anchored and unambiguous —
+// the character classes exclude the `.` and `/` separators, so there is
+// exactly one possible parse per input (linear time, no backtracking).
+const AUTHORING_NAME_RE = /^x-[a-z0-9-]+(?:\.[a-z0-9-]+)*$/;
+const AUTHORING_MAJOR_RE = /^(?:0|[1-9][0-9]*)$/;
+const AUTHORING_SUFFIX = ".authoring";
+
+/** True when `id` has the complete authoring-profile form
+ * `x-<vendor>.authoring/<major>` (LSML 1.1 §17.5.1, ADR 001 RC#14).
+ * Such profiles are advisory : ignored at render time, never rejected. */
+export function isAuthoringProfile(id: string): boolean {
+  const slash = id.indexOf("/");
+  if (slash < 0) return false;
+  const name = id.slice(0, slash);
+  const major = id.slice(slash + 1);
+  if (!AUTHORING_MAJOR_RE.test(major)) return false;
+  if (!name.endsWith(AUTHORING_SUFFIX)) return false;
+  // `name` minus the terminal `.authoring` segment must still be a valid
+  // `x-<vendor>[.<segment>...]` prefix — this is what makes `.authoring`
+  // a real terminal segment rather than a substring of another one
+  // (e.g. `x-evilauthoring/1` or `x-evil.authoring.fx/1` do not match).
+  return AUTHORING_NAME_RE.test(name.slice(0, -AUTHORING_SUFFIX.length));
+}
+
 export class BundleIncompatibleError extends Error {
   public readonly code = "BUNDLE_INCOMPATIBLE" as const;
   public readonly unsupportedProfiles: string[];
@@ -139,14 +190,33 @@ export class BundleIncompatibleError extends Error {
 
 /** Validate a bundle's `profiles[]` against the runtime's supported
  * set. Throws `BundleIncompatibleError` listing every offending entry
- * when at least one is not supported. */
+ * when at least one behavioural profile is not supported.
+ *
+ * Authoring profiles (`x-<vendor>.authoring/<major>`, LSML 1.1 §17.5.1)
+ * are advisory and skipped : their absence from the supported set is
+ * never a rejection cause. Every other (behavioural) unsupported profile
+ * keeps the hard §17.3.1 `BUNDLE_INCOMPATIBLE` rejection.
+ *
+ * Malformed-shape guard : `bundle` may come from an unchecked
+ * `json as RenderBundle` cast on untrusted server JSON
+ * (`FetcherImpl.get`). A non-array `profiles` or a non-string entry is
+ * therefore reachable at runtime and is rejected as
+ * `BundleIncompatibleError` (typed, code BUNDLE_INCOMPATIBLE) — never a
+ * raw TypeError. The diagnostic never echoes the malformed value, only a
+ * shape placeholder. */
 export function validateBundleProfiles(
   bundle: { profiles?: string[] },
   supported: ReadonlySet<string> = SUPPORTED_PROFILES,
 ): void {
-  const profiles = bundle.profiles;
-  if (!profiles || profiles.length === 0) return;
-  const missing = profiles.filter((p) => !supported.has(p));
+  const profiles: unknown = bundle.profiles;
+  if (!profiles) return;
+  if (!Array.isArray(profiles)) {
+    throw new BundleIncompatibleError(["<malformed: profiles is not an array>"]);
+  }
+  if (profiles.length === 0) return;
+  const missing = profiles
+    .filter((p) => typeof p !== "string" || (!isAuthoringProfile(p) && !supported.has(p)))
+    .map((p) => (typeof p === "string" ? p : "<malformed: non-string profile entry>"));
   if (missing.length > 0) {
     throw new BundleIncompatibleError(missing);
   }
@@ -162,12 +232,33 @@ export interface BundleFetcher {
   preload(bundle: RenderBundle): void;
 }
 
+/** Resolves the absolute URL of a scene's render bundle. Supplied by the
+ *  host (`MountOptions.resolveBundleUrl`) when the server is not at the
+ *  default host-root LSDP/1 layout — e.g. reached through a gateway prefix
+ *  (`https://gw/orion/api/v1/scenes/{id}/render-bundle?v={hash}`). */
+export type BundleUrlResolver = (sceneId: string, sceneVersion: string) => string;
+
 export interface BundleFetcherOptions {
   /** Base URL of the server. The fetcher constructs
-   *  `${baseUrl}/lsdp/v1/scenes/{id}/bundle?v={hash}`. */
+   *  `${baseUrl}/lsdp/v1/scenes/{id}/bundle?v={hash}`. Ignored when
+   *  `resolveUrl` is provided. */
   baseUrl: string;
-  /** Path prefix for bundle resolution. Defaults to `/lsdp/v1/scenes`. */
+  /** Path prefix for bundle resolution. Defaults to `/lsdp/v1/scenes`.
+   *  Ignored when `resolveUrl` is provided. */
   pathPrefix?: string;
+  /** When set, takes full control of URL construction — the host owns the
+   *  whole URL (base, path prefix and `/bundle` vs `/render-bundle` suffix).
+   *  Lets a gateway-prefixed server be addressed without changing the
+   *  host-root default. */
+  resolveUrl?: BundleUrlResolver;
+  /** Resolve the bearer token used to authenticate each bundle GET. The
+   *  render-bundle endpoint is auth-gated identically to the LSDP/1 WS
+   *  subscription, so the fetch carries the same session token as
+   *  `Authorization: Bearer <token>`. Resolved per request so a token swap
+   *  (`setToken`) takes effect on the next fetch ; a `LumencastTokenProvider`
+   *  is awaited. When omitted — or when it resolves to an empty/undefined
+   *  value — no `Authorization` header is sent (v0.5.0 behaviour). */
+  getAuthToken?: () => string | undefined | Promise<string | undefined>;
   fetchImpl?: typeof fetch;
 }
 
@@ -175,14 +266,35 @@ class FetcherImpl implements BundleFetcher {
   private readonly cache = new Map<string, RenderBundle>();
   private readonly baseUrl: string;
   private readonly pathPrefix: string;
+  private readonly resolveUrl: BundleUrlResolver | undefined;
+  private readonly getAuthToken: BundleFetcherOptions["getAuthToken"];
   private readonly fetchImpl: typeof fetch;
 
   constructor(opts: BundleFetcherOptions) {
     this.baseUrl = opts.baseUrl.replace(/\/$/, "");
     this.pathPrefix = (opts.pathPrefix ?? "/lsdp/v1/scenes").replace(/\/$/, "");
+    this.resolveUrl = opts.resolveUrl;
+    this.getAuthToken = opts.getAuthToken;
     this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
   }
 
+  /** Build the request init carrying the bearer token, if any. Returns
+   *  `undefined` when no token is available — the fetch stays header-less,
+   *  preserving v0.5.0 behaviour. */
+  private async buildInit(): Promise<RequestInit | undefined> {
+    if (!this.getAuthToken) return undefined;
+    const token = await this.getAuthToken();
+    if (!token) return undefined;
+    return { headers: { Authorization: `Bearer ${token}` } };
+  }
+
+  private buildUrl(sceneId: string, sceneVersion: string): string {
+    if (this.resolveUrl) {
+      return this.resolveUrl(sceneId, sceneVersion);
+    }
+    return `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(sceneId)}/bundle?v=${encodeURIComponent(sceneVersion)}`;
+  }
+
   preload(bundle: RenderBundle): void {
     // LSML 1.1 §17.3.1 — reject early if any declared profile is
     // unsupported by this runtime. Authors get an actionable error
@@ -194,8 +306,9 @@ class FetcherImpl implements BundleFetcher {
   async get(sceneId: string, sceneVersion: string): Promise<RenderBundle> {
     const cached = this.cache.get(sceneVersion);
     if (cached) return cached;
-    const url = `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(sceneId)}/bundle?v=${encodeURIComponent(sceneVersion)}`;
-    const response = await this.fetchImpl(url);
+    const url = this.buildUrl(sceneId, sceneVersion);
+    const init = await this.buildInit();
+    const response = init ? await this.fetchImpl(url, init) : await this.fetchImpl(url);
     if (!response.ok) {
       throw new Error(`bundle fetch failed: ${response.status} ${response.statusText}`);
     }

package/src/render/color-interp.ts

@@ -0,0 +1,303 @@
+// sRGB colour interpolation (LSML 1.1 §6.5) — issue #33.
+//
+// Both endpoints of a colour animation are first CANONICALISED through
+// the strict shared parser (`parseCssColor`, css-color.ts — ADR 001
+// RC#11/RC#12, never a raw string), then converted to RGBA channels in
+// [0, 1] and interpolated component-wise :
+//
+//   out_c = a_c + t * (b_c - a_c)   for c ∈ {r, g, b, a}
+//
+// with `t` produced by the easing curve. The output is serialised back
+// to `rgba()` form — which itself round-trips through `parseCssColor`
+// at the consuming primitive (belt and braces).
+//
+// All conversions are constant-time per value (the parser already
+// bounds inputs to 64 chars) ; the named-colour table is a flat map
+// lookup.
+
+import { parseCssColor } from "./css-color";
+
+/** RGBA channels, each in [0, 1]. */
+export type Rgba = readonly [number, number, number, number];
+
+// CSS Color 4 §6.1 named colours → packed 0xRRGGBB. Kept numeric (not
+// hex strings) to minimise bundle weight ; the set of NAMES here is
+// exactly the set accepted by css-color.ts (`transparent` and
+// `currentcolor` are handled separately — `currentcolor` cannot be
+// interpolated without computed-style context and is rejected).
+const NAMED_RGB: Record<string, number> = {
+  aliceblue: 0xf0f8ff,
+  antiquewhite: 0xfaebd7,
+  aqua: 0x00ffff,
+  aquamarine: 0x7fffd4,
+  azure: 0xf0ffff,
+  beige: 0xf5f5dc,
+  bisque: 0xffe4c4,
+  black: 0x000000,
+  blanchedalmond: 0xffebcd,
+  blue: 0x0000ff,
+  blueviolet: 0x8a2be2,
+  brown: 0xa52a2a,
+  burlywood: 0xdeb887,
+  cadetblue: 0x5f9ea0,
+  chartreuse: 0x7fff00,
+  chocolate: 0xd2691e,
+  coral: 0xff7f50,
+  cornflowerblue: 0x6495ed,
+  cornsilk: 0xfff8dc,
+  crimson: 0xdc143c,
+  cyan: 0x00ffff,
+  darkblue: 0x00008b,
+  darkcyan: 0x008b8b,
+  darkgoldenrod: 0xb8860b,
+  darkgray: 0xa9a9a9,
+  darkgreen: 0x006400,
+  darkgrey: 0xa9a9a9,
+  darkkhaki: 0xbdb76b,
+  darkmagenta: 0x8b008b,
+  darkolivegreen: 0x556b2f,
+  darkorange: 0xff8c00,
+  darkorchid: 0x9932cc,
+  darkred: 0x8b0000,
+  darksalmon: 0xe9967a,
+  darkseagreen: 0x8fbc8f,
+  darkslateblue: 0x483d8b,
+  darkslategray: 0x2f4f4f,
+  darkslategrey: 0x2f4f4f,
+  darkturquoise: 0x00ced1,
+  darkviolet: 0x9400d3,
+  deeppink: 0xff1493,
+  deepskyblue: 0x00bfff,
+  dimgray: 0x696969,
+  dimgrey: 0x696969,
+  dodgerblue: 0x1e90ff,
+  firebrick: 0xb22222,
+  floralwhite: 0xfffaf0,
+  forestgreen: 0x228b22,
+  fuchsia: 0xff00ff,
+  gainsboro: 0xdcdcdc,
+  ghostwhite: 0xf8f8ff,
+  gold: 0xffd700,
+  goldenrod: 0xdaa520,
+  gray: 0x808080,
+  green: 0x008000,
+  greenyellow: 0xadff2f,
+  grey: 0x808080,
+  honeydew: 0xf0fff0,
+  hotpink: 0xff69b4,
+  indianred: 0xcd5c5c,
+  indigo: 0x4b0082,
+  ivory: 0xfffff0,
+  khaki: 0xf0e68c,
+  lavender: 0xe6e6fa,
+  lavenderblush: 0xfff0f5,
+  lawngreen: 0x7cfc00,
+  lemonchiffon: 0xfffacd,
+  lightblue: 0xadd8e6,
+  lightcoral: 0xf08080,
+  lightcyan: 0xe0ffff,
+  lightgoldenrodyellow: 0xfafad2,
+  lightgray: 0xd3d3d3,
+  lightgreen: 0x90ee90,
+  lightgrey: 0xd3d3d3,
+  lightpink: 0xffb6c1,
+  lightsalmon: 0xffa07a,
+  lightseagreen: 0x20b2aa,
+  lightskyblue: 0x87cefa,
+  lightslategray: 0x778899,
+  lightslategrey: 0x778899,
+  lightsteelblue: 0xb0c4de,
+  lightyellow: 0xffffe0,
+  lime: 0x00ff00,
+  limegreen: 0x32cd32,
+  linen: 0xfaf0e6,
+  magenta: 0xff00ff,
+  maroon: 0x800000,
+  mediumaquamarine: 0x66cdaa,
+  mediumblue: 0x0000cd,
+  mediumorchid: 0xba55d3,
+  mediumpurple: 0x9370db,
+  mediumseagreen: 0x3cb371,
+  mediumslateblue: 0x7b68ee,
+  mediumspringgreen: 0x00fa9a,
+  mediumturquoise: 0x48d1cc,
+  mediumvioletred: 0xc71585,
+  midnightblue: 0x191970,
+  mintcream: 0xf5fffa,
+  mistyrose: 0xffe4e1,
+  moccasin: 0xffe4b5,
+  navajowhite: 0xffdead,
+  navy: 0x000080,
+  oldlace: 0xfdf5e6,
+  olive: 0x808000,
+  olivedrab: 0x6b8e23,
+  orange: 0xffa500,
+  orangered: 0xff4500,
+  orchid: 0xda70d6,
+  palegoldenrod: 0xeee8aa,
+  palegreen: 0x98fb98,
+  paleturquoise: 0xafeeee,
+  palevioletred: 0xdb7093,
+  papayawhip: 0xffefd5,
+  peachpuff: 0xffdab9,
+  peru: 0xcd853f,
+  pink: 0xffc0cb,
+  plum: 0xdda0dd,
+  powderblue: 0xb0e0e6,
+  purple: 0x800080,
+  rebeccapurple: 0x663399,
+  red: 0xff0000,
+  rosybrown: 0xbc8f8f,
+  royalblue: 0x4169e1,
+  saddlebrown: 0x8b4513,
+  salmon: 0xfa8072,
+  sandybrown: 0xf4a460,
+  seagreen: 0x2e8b57,
+  seashell: 0xfff5ee,
+  sienna: 0xa0522d,
+  silver: 0xc0c0c0,
+  skyblue: 0x87ceeb,
+  slateblue: 0x6a5acd,
+  slategray: 0x708090,
+  slategrey: 0x708090,
+  snow: 0xfffafa,
+  springgreen: 0x00ff7f,
+  steelblue: 0x4682b4,
+  tan: 0xd2b48c,
+  teal: 0x008080,
+  thistle: 0xd8bfd8,
+  tomato: 0xff6347,
+  turquoise: 0x40e0d0,
+  violet: 0xee82ee,
+  wheat: 0xf5deb3,
+  white: 0xffffff,
+  whitesmoke: 0xf5f5f5,
+  yellow: 0xffff00,
+  yellowgreen: 0x9acd32,
+};
+
+/**
+ * Canonicalise + convert an untrusted colour value to RGBA channels in
+ * [0, 1]. The value passes through `parseCssColor` FIRST — anything the
+ * strict parser rejects converts to `null` here (never interpolate a
+ * raw string, §6.5 step 1 / RC#11). `currentcolor` is also rejected :
+ * it has no concrete channels without computed-style context.
+ */
+export function cssColorToRgba(value: unknown): Rgba | null {
+  const v = parseCssColor(value);
+  if (v === null) return null;
+
+  if (v.startsWith("#")) return hexToRgba(v);
+
+  if (v.startsWith("rgb")) {
+    const body = v.slice(v.indexOf("(") + 1, -1);
+    const parts = body.split(",").map((p) => p.trim());
+    if (parts.length < 3) return null;
+    const pct = parts[0]!.endsWith("%");
+    const scale = pct ? 100 : 255;
+    const r = channel(parts[0]!, scale);
+    const g = channel(parts[1]!, scale);
+    const b = channel(parts[2]!, scale);
+    const a = parts.length > 3 ? alphaChannel(parts[3]!) : 1;
+    if (r === null || g === null || b === null || a === null) return null;
+    return [r, g, b, a];
+  }
+
+  if (v.startsWith("hsl")) {
+    const body = v.slice(v.indexOf("(") + 1, -1);
+    const parts = body.split(",").map((p) => p.trim());
+    if (parts.length < 3) return null;
+    const h = Number(parts[0]!.replace("deg", ""));
+    const s = Number(parts[1]!.replace("%", "")) / 100;
+    const l = Number(parts[2]!.replace("%", "")) / 100;
+    const a = parts.length > 3 ? alphaChannel(parts[3]!) : 1;
+    if (![h, s, l].every(Number.isFinite) || a === null) return null;
+    const [r, g, b] = hslToRgb(h, s, l);
+    return [r, g, b, a];
+  }
+
+  if (v === "transparent") return [0, 0, 0, 0];
+  if (v === "currentcolor") return null;
+
+  const packed = NAMED_RGB[v];
+  if (packed === undefined) return null;
+  return [((packed >> 16) & 0xff) / 255, ((packed >> 8) & 0xff) / 255, (packed & 0xff) / 255, 1];
+}
+
+function hexToRgba(v: string): Rgba | null {
+  const h = v.slice(1);
+  if (h.length === 3 || h.length === 4) {
+    const r = parseInt(h[0]! + h[0]!, 16);
+    const g = parseInt(h[1]! + h[1]!, 16);
+    const b = parseInt(h[2]! + h[2]!, 16);
+    const a = h.length === 4 ? parseInt(h[3]! + h[3]!, 16) : 255;
+    return [r / 255, g / 255, b / 255, a / 255];
+  }
+  if (h.length === 6 || h.length === 8) {
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) : 255;
+    return [r / 255, g / 255, b / 255, a / 255];
+  }
+  return null;
+}
+
+function channel(token: string, scale: number): number | null {
+  const n = Number(token.replace("%", ""));
+  if (!Number.isFinite(n)) return null;
+  return clamp01(n / scale);
+}
+
+function alphaChannel(token: string): number | null {
+  const pct = token.endsWith("%");
+  const n = Number(token.replace("%", ""));
+  if (!Number.isFinite(n)) return null;
+  return clamp01(pct ? n / 100 : n);
+}
+
+/** Standard HSL → RGB (CSS Color 4 §7.1). h in degrees, s/l in [0,1]. */
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  const hue = ((h % 360) + 360) % 360;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const hp = hue / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  if (hp < 1) [r, g, b] = [c, x, 0];
+  else if (hp < 2) [r, g, b] = [x, c, 0];
+  else if (hp < 3) [r, g, b] = [0, c, x];
+  else if (hp < 4) [r, g, b] = [0, x, c];
+  else if (hp < 5) [r, g, b] = [x, 0, c];
+  else [r, g, b] = [c, 0, x];
+  const m = l - c / 2;
+  return [clamp01(r + m), clamp01(g + m), clamp01(b + m)];
+}
+
+/** Component-wise sRGB lerp (§6.5 step 2). `t` may overshoot (springs) ;
+ *  channels clamp back into [0, 1] after mixing. */
+export function mixRgba(a: Rgba, b: Rgba, t: number): Rgba {
+  return [
+    clamp01(a[0] + t * (b[0] - a[0])),
+    clamp01(a[1] + t * (b[1] - a[1])),
+    clamp01(a[2] + t * (b[2] - a[2])),
+    clamp01(a[3] + t * (b[3] - a[3])),
+  ];
+}
+
+/** Serialise RGBA back to `rgba()` form (§6.5 step 3). The output is
+ *  always re-accepted by `parseCssColor` (integer channels, alpha with
+ *  at most 4 decimals). */
+export function serializeRgba(rgba: Rgba): string {
+  const r = Math.round(clamp01(rgba[0]) * 255);
+  const g = Math.round(clamp01(rgba[1]) * 255);
+  const b = Math.round(clamp01(rgba[2]) * 255);
+  // 4 decimals max so the alpha token matches the strict grammar.
+  const a = Math.round(clamp01(rgba[3]) * 10000) / 10000;
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function clamp01(n: number): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}

package/src/render/css-color.ts

@@ -0,0 +1,145 @@
+// Strict CSS colour parser — the ONLY gate through which untrusted
+// colour values (bundle props AND live LSDP deltas, see `resolveProps`
+// in tree.tsx) may reach an inline CSS style.
+//
+// ADR 001 §6 RC#11 (CSS strict) + RC#12 (anti-ReDoS), threat model
+// Bastion 2026-06-10, issue #35. Sites #30/#31/#33 must reuse this
+// module — never re-implement colour validation locally.
+//
+// Accepted grammar (LSML 1.1 §6.5 colour forms, nothing more) :
+//   - hex      : #RGB | #RGBA | #RRGGBB | #RRGGBBAA
+//   - rgb()    : rgb(R, G, B) | rgba(R, G, B, A) — 0-255 or percentages
+//   - hsl()    : hsl(H, S%, L%) | hsla(H, S%, L%, A)
+//   - named    : canonical CSS named colours + `transparent` + `currentcolor`
+// Anything else — including `url(`, `;`, `}`, `expression(`, var(),
+// calc(), whitespace tricks — is REJECTED (null). Never passthrough.
+//
+// ── Linear-time justification (RC#12, written per Bastion) ──────────
+// 1. Inputs longer than MAX_LEN (64) are rejected before any regex
+//    runs, so every step below operates on a bounded string.
+// 2. The charset pre-scan is a single O(n) pass over one character
+//    class — it rejects `;`, `}`, `:`, `/`, quotes, backslashes and
+//    control characters outright, so no later step ever sees them.
+// 3. Every regex is anchored (`^…$`) and built exclusively from
+//    literals, character classes and BOUNDED quantifiers ({m,n}, ?).
+//    There are no nested unbounded quantifiers ((a+)+ style), no
+//    overlapping alternations under a quantifier — i.e. no input can
+//    trigger super-linear backtracking. Combined with the 64-char cap,
+//    total work is O(64) per value regardless of payload shape.
+// ─────────────────────────────────────────────────────────────────────
+
+import { emitDiagnostic } from "./diagnostics";
+
+const MAX_LEN = 64;
+
+// Single-pass charset allowlist. Only characters that can appear in
+// the accepted grammar. Notably ABSENT : `;` `}` `{` `:` `/` `"` `'`
+// `\` `<` `>` `-` and all control chars — the injection metacharacters.
+const CHARSET_RE = /^[#a-zA-Z0-9(),.% ]{1,64}$/;
+
+// hex — 3/4/6/8 hex digits. Alternation of fixed-width character-class
+// runs : strictly linear.
+const HEX_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+// Number tokens. All quantifiers bounded ; `(?:\.\d{1,4})?` is an
+// optional bounded group — one possible match per position, no
+// ambiguity, no backtracking blow-up.
+const NUM = String.raw`\d{1,3}(?:\.\d{1,4})?`; // 0 … 999.9999
+const ALPHA = String.raw`(?:0|1|0?\.\d{1,4}|${NUM}%)`; // 0-1 or %
+const SP = String.raw`[ ]{0,4}`; // bounded optional spaces
+
+// rgb(R, G, B[, A]) — channels all plain numbers or all percentages
+// are both accepted (range-checked numerically after the match).
+const RGB_RE = new RegExp(
+  `^rgba?\\(${SP}(${NUM})(%?)${SP},${SP}(${NUM})(%?)${SP},${SP}(${NUM})(%?)${SP}` +
+    `(?:,${SP}${ALPHA}${SP})?\\)$`,
+);
+
+// hsl(H[deg], S%, L%[, A])
+const HSL_RE = new RegExp(
+  `^hsla?\\(${SP}(${NUM})(?:deg)?${SP},${SP}(${NUM})%${SP},${SP}(${NUM})%${SP}` +
+    `(?:,${SP}${ALPHA}${SP})?\\)$`,
+);
+
+// Canonical CSS named colours (CSS Color 4 §6.1) + the two keywords
+// that behave like colours in every site we render.
+const NAMED = new Set(
+  (
+    "aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue " +
+    "blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk " +
+    "crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki " +
+    "darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen " +
+    "darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue " +
+    "dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite " +
+    "gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki " +
+    "lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan " +
+    "lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen " +
+    "lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen " +
+    "linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple " +
+    "mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred " +
+    "midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab " +
+    "orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip " +
+    "peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue " +
+    "saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue " +
+    "slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet " +
+    "wheat white whitesmoke yellow yellowgreen transparent currentcolor"
+  ).split(" "),
+);
+
+/**
+ * Validate an untrusted colour value against the strict grammar above.
+ *
+ * Returns the validated string (trimmed ; named colours lowercased) or
+ * `null` on rejection. A `null` MUST be handled as "omit the style /
+ * use the primitive's safe default" — never interpolate the raw input.
+ */
+export function parseCssColor(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  if (v.length === 0 || v.length > MAX_LEN) return null;
+  // Contractual explicit rejects (Bastion RC#11) — redundant with the
+  // charset scan below, kept as belt-and-braces so the contract holds
+  // even if the grammar is ever extended.
+  const lower = v.toLowerCase();
+  if (lower.includes("url(") || v.includes(";") || v.includes("}")) return null;
+  // Single-pass charset allowlist (kills every CSS metacharacter).
+  if (!CHARSET_RE.test(v)) return null;
+
+  if (v.startsWith("#")) return HEX_RE.test(v) ? v : null;
+
+  if (lower.startsWith("rgb")) {
+    const m = RGB_RE.exec(lower);
+    if (!m) return null;
+    // Range check : percent channels ≤ 100, plain channels ≤ 255, no mixing.
+    const pct = [m[2], m[4], m[6]];
+    if (!(pct.every((p) => p === "%") || pct.every((p) => p === ""))) return null;
+    const max = pct[0] === "%" ? 100 : 255;
+    for (const ch of [m[1], m[3], m[5]]) {
+      if (Number(ch) > max) return null;
+    }
+    return lower;
+  }
+
+  if (lower.startsWith("hsl")) {
+    const m = HSL_RE.exec(lower);
+    if (!m) return null;
+    if (Number(m[1]) > 360 || Number(m[2]) > 100 || Number(m[3]) > 100) return null;
+    return lower;
+  }
+
+  return NAMED.has(lower) ? lower : null;
+}
+
+/**
+ * Diagnostic for a rejected value. Bastion R9 (ADR 001 §5.1) : the
+ * rejected VALUE is never logged nor forwarded — only `node.id` (RC#7,
+ * issue #34), the field name and a static reason. Routed through the
+ * structured diagnostics channel (events, no logs in `broadcast`).
+ */
+export function warnRejectedColor(field: string, nodeId?: string): void {
+  emitDiagnostic(
+    nodeId,
+    field,
+    "rejected unsafe colour : not a strict hex/rgb()/hsl()/named colour",
+  );
+}