@lumencast/runtime 0.4.0 → 0.6.0

package/src/render/primitives/shape.tsx

@@ -2,41 +2,66 @@ import { motion } from "framer-motion";
 import type { ReactElement } from "react";
 import type { PrimitiveProps } from "./index";
 import { toFramer, mountPlay, resolveTransition } from "../../animate/transitions";
-import { parseFills, renderFill } from "../fill";
+import { parseFills, renderFill, sanitizeFills } from "../fill";
+import { parseCssColor, warnRejectedColor } from "../css-color";
+import { parseShapePaths, type SubPath } from "../svg-path";
 
 interface StrokeSpec {
   color?: string;
   width?: number;
 }
 
-/** Rectangle / circle / line. Renders as SVG so stroke + fill behave
- *  predictably across hosts. Opacity animatable.
+/** Rectangle / circle / line / path. Renders as SVG so stroke + fill
+ *  behave predictably across hosts. Opacity animatable.
  *
  *  LSML 1.1 §4.6 + §4.12 add `fills[]` / `strokes[]` arrays as the
  *  preferred way to declare multi-layer fills with linear/radial
  *  gradients. The legacy single `fill` / `stroke` props remain
  *  accepted for 1.0 bundles ; when both are present the array form
  *  wins (the spec forbids mixing, but we tolerate to ease migration).
+ *
+ *  Security (ADR 001 §6 RC#10 + RC#11, issue #30) : every colour that
+ *  reaches an SVG `fill`/`stroke`/`stop-color` attribute goes through
+ *  the strict `parseCssColor` gate, and every path `d` goes through
+ *  `validatePathData` — at EVERY render, because props are wire-
+ *  drivable live via LSDP deltas (`resolveProps`, tree.tsx).
  */
-export function Shape({ resolved, transitionFor, animateInitial }: PrimitiveProps) {
-  const kind = (resolved.kind as string | undefined) ?? "rect";
-  const legacyFill = (resolved.fill as string | undefined) ?? "transparent";
-  const legacyStroke = (resolved.stroke as string | undefined) ?? "transparent";
+export function Shape({ resolved, nodeId, transitionFor, animateInitial }: PrimitiveProps) {
+  // Canonical prop name is `geometry` (LSML §4.6 — what the compiler
+  // emits) ; `kind` is kept as a fallback for hand-rolled Solar-lineage
+  // RenderNodes that predate the compiler.
+  const kind =
+    (resolved.geometry as string | undefined) ?? (resolved.kind as string | undefined) ?? "rect";
+  const legacyFill = safeColor(resolved.fill, "shape.fill", nodeId) ?? "transparent";
+  const legacyStroke = safeColor(resolved.stroke, "shape.stroke", nodeId) ?? "transparent";
   const legacyStrokeWidth = numberOr(resolved.stroke_width, 0);
   const width = numberOr(resolved.width, 100);
   const height = numberOr(resolved.height, 100);
   const radius = numberOr(resolved.radius, 0);
   const opacity = numberOr(resolved.opacity, 1);
+  // LSML §4.6 `ariaLabel` was silently unrendered until issue #34's
+  // allowlist audit surfaced it — now forwarded as the SVG label.
+  const ariaLabel = typeof resolved.ariaLabel === "string" ? resolved.ariaLabel : undefined;
 
   const tx = resolveTransition(transitionFor, ["opacity"], animateInitial);
   const transition = toFramer(tx);
-  const play = mountPlay({ opacity }, animateInitial);
+  const play = mountPlay({ opacity }, animateInitial, nodeId);
 
   // LSML 1.1 §4.6 — `fills[]` is the preferred multi-fill form. Fall
-  // back to the singular `fill` for 1.0 bundles.
-  const fills = parseFills(resolved.fills);
+  // back to the singular `fill` for 1.0 bundles. Colours are strict-
+  // validated (a rejected colour drops its layer, with diagnostic).
+  const fills = sanitizeFills(
+    parseFills(resolved.fills, "shape.fills", nodeId),
+    "shape.fills",
+    nodeId,
+  );
   const strokes = parseStrokes(resolved.strokes);
 
+  // LSML 1.1 §4.6 — `geometry:"path"` : validated subpaths, one
+  // `<path>` element per entry (ADR 001 §3.2.3). Re-validated at every
+  // render — see module header of svg-path.ts (RC#10).
+  const subpaths = kind === "path" ? parseShapePaths(resolved, nodeId) : [];
+
   // Each fill compiles to a (defs, ref) pair. We render the shape
   // outline once per fill, layered top-to-bottom (first entry → on
   // top, per §4.12). The defs are aggregated for a single <defs>.
@@ -49,7 +74,10 @@ export function Shape({ resolved, transitionFor, animateInitial }: PrimitiveProp
   // as an additional pass over the same shape outline.
   const strokeLayers =
     strokes.length > 0
-      ? strokes.map((s) => ({ color: s.color ?? "transparent", width: s.width ?? 0 }))
+      ? strokes.map((s) => ({
+          color: safeColor(s.color, "shape.strokes.color", nodeId) ?? "transparent",
+          width: s.width ?? 0,
+        }))
       : [{ color: legacyStroke, width: legacyStrokeWidth }];
 
   // Stack order : fillRefs are emitted top-to-bottom per §4.12. SVG
@@ -57,12 +85,36 @@ export function Shape({ resolved, transitionFor, animateInitial }: PrimitiveProp
   // entry in fills[] ends up rendered last (visually on top).
   const stackedFills = [...fillRefs].reverse();
   const stackedStrokes = [...strokeLayers].reverse();
+  // For paths, a zero-width / transparent stroke pass would only emit
+  // invisible duplicate <path> elements — skip it.
+  const effectiveStrokes =
+    kind === "path"
+      ? stackedStrokes.filter((s) => s.width > 0 && s.color !== "transparent")
+      : stackedStrokes;
 
   const renderShape = (
     fill: string,
     stroke: { color: string; width: number },
     keyPrefix: string,
   ): ReactElement => {
+    if (kind === "path") {
+      // §4.6 — fills and strokes apply to the union of all subpaths ;
+      // each subpath keeps its own winding rule (fill-rule).
+      return (
+        <g key={keyPrefix}>
+          {subpaths.map((p: SubPath, i: number) => (
+            <path
+              key={i}
+              d={p.d}
+              fillRule={p.fillRule}
+              fill={fill}
+              stroke={stroke.color}
+              strokeWidth={stroke.width}
+            />
+          ))}
+        </g>
+      );
+    }
     if (kind === "circle") {
       return (
         <circle
@@ -111,6 +163,7 @@ export function Shape({ resolved, transitionFor, animateInitial }: PrimitiveProp
       width={width}
       height={height}
       viewBox={`0 0 ${width} ${height}`}
+      {...(ariaLabel !== undefined ? { "aria-label": ariaLabel, role: "img" } : {})}
       initial={play.initial}
       animate={play.animate}
       transition={transition}
@@ -120,11 +173,22 @@ export function Shape({ resolved, transitionFor, animateInitial }: PrimitiveProp
       {stackedFills.map((ref, i) =>
         renderShape(ref, { color: "transparent", width: 0 }, `fill-${i}`),
       )}
-      {stackedStrokes.map((s, i) => renderShape("none", s, `stroke-${i}`))}
+      {effectiveStrokes.map((s, i) => renderShape("none", s, `stroke-${i}`))}
     </motion.svg>
   );
 }
 
+/** Strict-validate a colour prop (RC#11 — SVG attributes are injection
+ * sites too once values are wire-drivable). Non-strings resolve to
+ * null silently (absent prop) ; a string that fails the strict grammar
+ * is rejected with a diagnostic (value withheld per R9). */
+function safeColor(value: unknown, field: string, nodeId?: string): string | null {
+  if (typeof value !== "string") return null;
+  const color = parseCssColor(value);
+  if (color === null) warnRejectedColor(field, nodeId);
+  return color;
+}
+
 function parseStrokes(value: unknown): StrokeSpec[] {
   if (!Array.isArray(value)) return [];
   return value.filter(

package/src/render/primitives/text.tsx

@@ -1,22 +1,105 @@
 import { motion } from "framer-motion";
 import type { PrimitiveProps } from "./index";
 import { toFramer, mountPlay, resolveTransition } from "../../animate/transitions";
+import { parseCssColor, warnRejectedColor } from "../css-color";
+import { emitDiagnostic } from "../diagnostics";
+
+// ── Typography grammars (LSML 1.1 TextStyle, schema.json) ───────────
+// Every typo prop is wire-drivable (static bundle prop OR live LSDP
+// delta via `resolveProps`, tree.tsx) and lands in inline CSS, so each
+// value is validated against the field's spec'd grammar before it may
+// reach the style object. Enum fields go through a closed allowlist
+// (the emitted string is always one of these constants — never the
+// input), numeric fields through finite-number checks. There is NO
+// string passthrough on any of these sites (ADR 001 RC#11 by
+// construction : no untrusted string ever reaches the style object).
+const TEXT_TRANSFORMS = new Set(["none", "uppercase", "lowercase", "capitalize"]);
+const TEXT_DECORATIONS = new Set(["none", "underline", "line-through"]);
+const FONT_STYLES = new Set(["normal", "italic", "oblique"]);
+
+// ── Defence-in-depth upper bounds (issue #34, Bastion follow-up on
+// PR #38) ─────────────────────────────────────────────────────────────
+// The numeric typo fields were type-validated but unbounded ; an absurd
+// value pushed by a hostile bundle or live delta could degrade layout /
+// rendering (e.g. a 10⁹-line clamp or a kilometric letter spacing).
+// Policy : a value beyond its cap is REJECTED (diagnostic + omit → CSS
+// initial), consistent with the existing typo grammar gates — NOT
+// clamped, unlike the R8 filter caps where the spec explicitly blesses
+// clamping. Rationale : there is no "nearest sensible rendering" for an
+// absurd typographic value, the author's intent is unknowable ; safe
+// default beats silently-altered output.
+/** Max `maxLines` accepted (Bastion suggested ≤ 1000 on PR #38). */
+export const MAX_MAX_LINES = 1000;
+/** Max unitless `lineHeight` multiplier (100× the font size is already
+ *  far beyond any broadcast layout). */
+export const MAX_LINE_HEIGHT = 100;
+/** Max |letterSpacing| in px, both directions (±1000 px covers any
+ *  legitimate broadcast typography). */
+export const MAX_LETTER_SPACING_PX = 1000;
+
+// ── fontFamily policy (issue #34, Bastion follow-up on PR #38) ───────
+// Decision : SHAPE validation, not a font allowlist. `fontFamily` is
+// assigned through the React style object (per-property assignment via
+// CSSStyleDeclaration), which cannot break out of the declaration — so
+// the residual risk is malformed CSS, not injection. A font allowlist
+// would couple the runtime to a host-specific font inventory (a spec /
+// RFC matter — flagged for Atlas in the PR), whereas shape validation
+// keeps any legitimate family name working. The grammar accepts
+// comma-separated family lists with optional quotes ; the injection
+// metacharacters (`;` `}` `{` `:` `\` `<` `>` `(` `)`) and `url(` are
+// rejected by construction (none of their characters are allowed).
+// Anchored, single character class with a bounded quantifier — linear
+// time (RC#12).
+const FONT_FAMILY_RE = /^[a-zA-Z0-9 ,.'"_-]{1,256}$/;
+
+/** Validate an untrusted `fontFamily` value. Returns the string or
+ *  `null` on rejection (handled as "omit → inherit", with diagnostic). */
+export function parseFontFamily(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  if (v.length === 0) return null;
+  return FONT_FAMILY_RE.test(v) ? v : null;
+}
 
 /** Text leaf. Value renders as the displayed string ; style props
- *  cover size / weight / colour / alignment. Opacity is animated when
- *  a transition is declared on `opacity` or `value`. An `animate.from`
- *  makes it mount-play (initial → target) on mount. */
-export function Text({ resolved, transitionFor, animateInitial }: PrimitiveProps) {
+ *  cover the full LSML TextStyle (size / font / weight / colour /
+ *  alignment / lineHeight / letterSpacing / textTransform /
+ *  textDecoration / fontStyle) plus `maxLines` (§4.4 ellipsis
+ *  truncation). Opacity is animated when a transition is declared on
+ *  `opacity` or `value`. An `animate.from` makes it mount-play
+ *  (initial → target) on mount. */
+export function Text({ resolved, nodeId, transitionFor, animateInitial }: PrimitiveProps) {
   const value = resolved.value === undefined ? "" : String(resolved.value);
   const size = (resolved.size as string | number | undefined) ?? "1rem";
-  const font = resolved.font as string | undefined;
   const weight = (resolved.weight as number | undefined) ?? 400;
-  const colour = (resolved.colour as string | undefined) ?? "currentColor";
+  // Issue #34 — `font` is untrusted and lands in inline CSS : shape-
+  // validate (see fontFamily policy above) ; rejected → inherit.
+  let font: string | undefined;
+  if (resolved.font !== undefined) {
+    const parsed = parseFontFamily(resolved.font);
+    if (parsed === null) {
+      emitDiagnostic(nodeId, "text.font", "rejected fontFamily : outside the family-list grammar");
+    } else {
+      font = parsed;
+    }
+  }
+  // RC#11 : `colour` is untrusted (static prop OR live LSDP delta) and
+  // lands in inline CSS — strict-parse ; rejected → safe default.
+  let colour = "currentColor";
+  if (resolved.colour !== undefined) {
+    const parsed = parseCssColor(resolved.colour);
+    if (parsed === null) {
+      warnRejectedColor("text.colour", nodeId);
+    } else {
+      colour = parsed;
+    }
+  }
   const align = (resolved.align as string | undefined) ?? "start";
   const opacity = numberOr(resolved.opacity, 1);
+  const typography = resolveTypography(resolved, nodeId);
 
   const tx = resolveTransition(transitionFor, ["opacity", "value"], animateInitial);
-  const play = mountPlay({ opacity }, animateInitial);
+  const play = mountPlay({ opacity }, animateInitial, nodeId);
 
   return (
     <motion.span
@@ -29,6 +112,7 @@ export function Text({ resolved, transitionFor, animateInitial }: PrimitiveProps
         fontWeight: weight,
         color: colour,
         textAlign: align as React.CSSProperties["textAlign"],
+        ...typography,
         willChange: "opacity, transform",
       }}
       initial={play.initial}
@@ -43,3 +127,136 @@ export function Text({ resolved, transitionFor, animateInitial }: PrimitiveProps
 function numberOr(v: unknown, fallback: number): number {
   return typeof v === "number" && Number.isFinite(v) ? v : fallback;
 }
+
+/**
+ * Resolve the LSML 1.1 TextStyle typography props (`lineHeight`,
+ * `letterSpacing`, `textTransform`, `textDecoration`, `fontStyle`) and
+ * `maxLines` (§4.4) into a validated React style fragment.
+ *
+ * Exported for boundary testing : happy-dom drops `-webkit-*`
+ * declarations from `CSSStyleDeclaration`, so the line-clamp pattern is
+ * asserted on the exact object handed to React's inline style (same
+ * approach as `backgroundsToCss` for `color-mix`).
+ *
+ * Defaults = omit the declaration (inherit / CSS initial). A
+ * non-conforming value → R9 diagnostic + omit ; the returned object
+ * only ever contains allowlisted constants or validated finite
+ * numbers — never the raw input. Numeric fields additionally enforce
+ * the defence-in-depth caps above (issue #34).
+ */
+export function resolveTypography(
+  resolved: Record<string, unknown>,
+  nodeId?: string,
+): React.CSSProperties {
+  // schema.json : lineHeight is a unitless multiplier ≥ 0 ;
+  // letterSpacing is a number (px) ; the three enums are closed sets.
+  const lineHeight = boundedNumber(
+    resolved.lineHeight,
+    0,
+    MAX_LINE_HEIGHT,
+    "text.lineHeight",
+    nodeId,
+  );
+  const letterSpacing = boundedNumber(
+    resolved.letterSpacing,
+    -MAX_LETTER_SPACING_PX,
+    MAX_LETTER_SPACING_PX,
+    "text.letterSpacing",
+    nodeId,
+  );
+  const textTransform = enumValue(
+    resolved.textTransform,
+    TEXT_TRANSFORMS,
+    "text.textTransform",
+    nodeId,
+  );
+  const textDecoration = enumValue(
+    resolved.textDecoration,
+    TEXT_DECORATIONS,
+    "text.textDecoration",
+    nodeId,
+  );
+  const fontStyle = enumValue(resolved.fontStyle, FONT_STYLES, "text.fontStyle", nodeId);
+  // §4.4 maxLines — truncation with ellipsis after N lines, via the
+  // standard line-clamp pattern (display:-webkit-box overrides the
+  // base inline-block ; this fragment is spread after it so it wins).
+  const maxLines = positiveInteger(resolved.maxLines, MAX_MAX_LINES, "text.maxLines", nodeId);
+
+  return {
+    ...(lineHeight !== undefined ? { lineHeight } : {}),
+    // Built from a validated finite number — no string passthrough.
+    ...(letterSpacing !== undefined ? { letterSpacing: `${letterSpacing}px` } : {}),
+    ...(textTransform !== undefined
+      ? { textTransform: textTransform as React.CSSProperties["textTransform"] }
+      : {}),
+    ...(textDecoration !== undefined ? { textDecoration } : {}),
+    ...(fontStyle !== undefined ? { fontStyle } : {}),
+    ...(maxLines !== undefined
+      ? {
+          display: "-webkit-box",
+          WebkitBoxOrient: "vertical" as const,
+          WebkitLineClamp: maxLines,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }
+      : {}),
+  };
+}
+
+/** Closed-allowlist enum gate. Returns the canonical constant from the
+ *  allowlist (NEVER the raw input) or `undefined` (field omitted →
+ *  CSS initial). Non-conforming value → R9 diagnostic, no passthrough. */
+function enumValue(
+  v: unknown,
+  allow: ReadonlySet<string>,
+  field: string,
+  nodeId?: string,
+): string | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v === "string" && allow.has(v)) return v;
+  warnRejectedTypo(field, nodeId);
+  return undefined;
+}
+
+/** Finite number within [min, max] or omit (R9 diagnostic on a
+ *  non-conforming or out-of-cap input — rejected, never clamped). */
+function boundedNumber(
+  v: unknown,
+  min: number,
+  max: number,
+  field: string,
+  nodeId?: string,
+): number | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v === "number" && Number.isFinite(v) && v >= min && v <= max) return v;
+  warnRejectedTypo(field, nodeId);
+  return undefined;
+}
+
+/** Integer in [1, max] or omit (schema : maxLines is a line count ;
+ *  capped per the issue #34 defence-in-depth bounds). */
+function positiveInteger(
+  v: unknown,
+  max: number,
+  field: string,
+  nodeId?: string,
+): number | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= max) return v;
+  warnRejectedTypo(field, nodeId);
+  return undefined;
+}
+
+/**
+ * Diagnostic for a typo value outside its spec'd grammar or caps.
+ * Bastion R9 (ADR 001 §5.1) : the rejected VALUE is never logged nor
+ * forwarded — only `node.id` (RC#7), the field name and a static
+ * reason. Routed through the structured diagnostics channel.
+ */
+function warnRejectedTypo(field: string, nodeId?: string): void {
+  emitDiagnostic(
+    nodeId,
+    field,
+    "rejected typography value : outside the field's spec'd grammar or caps",
+  );
+}

package/src/render/prop-allowlist.ts

@@ -0,0 +1,119 @@
+// Per-primitive prop allowlists (ADR 001 §3.4 D4, issue #34).
+//
+// Each primitive declares the exact set of resolved-prop keys it
+// consumes at render time. Any prop reaching the renderer outside the
+// allowlist — whether from a compiled bundle, a hand-rolled RenderNode
+// or a binding key — produces a structured diagnostic (never a silent
+// drop). Values are NEVER inspected nor reported (R9) : the check is
+// purely key-based.
+//
+// Key-based is sufficient for live deltas too : an LSDP delta can only
+// change the VALUE behind an already-declared binding key
+// (`resolveProps`, tree.tsx) — it can never introduce a new prop key.
+// The per-node key set is therefore static, and the check runs once per
+// RenderNode object (WeakSet dedup) instead of once per render.
+//
+// These sets mirror what each primitive's component ACTUALLY reads
+// today. Spec'd fields the renderer does not consume yet (e.g. `text`
+// `format`, `stack` `padding`) are deliberately NOT listed : per the
+// anti-silent-drop policy they must warn until they are implemented.
+
+import type { RenderKind, RenderNode } from "./bundle";
+import { emitDiagnostic } from "./diagnostics";
+
+/** Universal props consumed by the Tree renderer itself
+ *  (`UniversalWrapper`, LSML 1.1 §5.4) on every primitive. */
+const UNIVERSAL_PROPS = ["visible", "opacity", "universal_opacity", "rotation", "sizing"] as const;
+
+function allow(keys: readonly string[]): ReadonlySet<string> {
+  return new Set([...UNIVERSAL_PROPS, ...keys]);
+}
+
+/** Resolved-prop keys consumed per primitive (component + wrapper). */
+export const PRIMITIVE_PROP_ALLOWLIST: Readonly<Record<RenderKind, ReadonlySet<string>>> = {
+  stack: allow(["direction", "gap", "wrap", "crossGap", "align", "justify"]),
+  grid: allow(["cols", "rows", "gap"]),
+  frame: allow([
+    "x",
+    "y",
+    "width",
+    "height",
+    "scale",
+    "rotate",
+    "background",
+    "backgrounds",
+    "clipsContent",
+  ]),
+  text: allow([
+    "value",
+    "size",
+    "font",
+    "weight",
+    "colour",
+    "align",
+    "lineHeight",
+    "letterSpacing",
+    "textTransform",
+    "textDecoration",
+    "fontStyle",
+    "maxLines",
+  ]),
+  image: allow(["src", "alt", "fit", "position", "width", "height"]),
+  shape: allow([
+    "geometry",
+    "kind",
+    "width",
+    "height",
+    "radius",
+    "fill",
+    "fills",
+    "stroke",
+    "stroke_width",
+    "strokes",
+    "pathData",
+    "paths",
+    "ariaLabel",
+  ]),
+  media: allow(["src", "loop", "mute", "autoplay", "fit"]),
+  instance: allow(["scene_id", "scene_version", "size", "position"]),
+  // `repeat` is dispatched specially by the tree ; its only consumed
+  // binding is `items`.
+  repeat: new Set(["items"]),
+};
+
+function isAllowed(kind: RenderKind, key: string): boolean {
+  const allowed = PRIMITIVE_PROP_ALLOWLIST[kind];
+  if (allowed === undefined) return true; // unknown kind warns separately (tree.tsx)
+  if (allowed.has(key)) return true;
+  // `instance` exposes bound sub-scene parameters under `params.*`
+  // (LSML §4.9) — the whole namespace is part of its contract.
+  if (kind === "instance" && (key === "params" || key.startsWith("params."))) return true;
+  return false;
+}
+
+// One check per RenderNode object — bundles are immutable once fetched,
+// and a node's key set cannot change live (see module header).
+const checkedNodes = new WeakSet<RenderNode>();
+
+/**
+ * Audit a node's static props + binding keys against its primitive's
+ * allowlist. Every unknown key emits ONE structured diagnostic naming
+ * `node.id` + the prop (never the value, R9). Idempotent per node.
+ */
+export function checkNodeProps(node: RenderNode): void {
+  if (checkedNodes.has(node)) return;
+  checkedNodes.add(node);
+  const keys = new Set<string>([
+    ...Object.keys(node.props ?? {}),
+    ...Object.keys(node.bindings ?? {}),
+  ]);
+  for (const key of keys) {
+    if (!isAllowed(node.kind, key)) {
+      emitDiagnostic(
+        node.id,
+        `${node.kind}.${key}`,
+        "is not consumed by this primitive's renderer ; the prop is ignored (anti-silent-drop, ADR 001 §3.4)",
+      );
+    }
+  }
+}