@burdenoff/microfe-hookmovies 2026.1031.2 → 2026.1031.4

package/dist/hookmovies/components/RecommendationRail.d.ts

@@ -0,0 +1,23 @@
+import { FC, ReactNode } from 'react';
+import { HokRecommendation, HokRecommendationSurface, HokRecommendationVariant } from '../hooks/useHookMoviesApi';
+
+interface RecommendationRailProps {
+    heading: string;
+    icon: ReactNode;
+    items: HokRecommendation[];
+    variant: HokRecommendationVariant;
+    surface: HokRecommendationSurface;
+    /** Seed title for a "more like this" rail. */
+    seedTitleId?: string;
+    loading?: boolean;
+    /** Optional one-line context under the heading. */
+    subheading?: string;
+    onOpen: (titleId: string) => void;
+    /** Extra classes for the outer section (spacing differs per page). */
+    className?: string;
+    /** Horizontal padding classes, so the rail aligns with its page gutter. */
+    gutterClassName?: string;
+}
+export declare const RecommendationRail: FC<RecommendationRailProps>;
+export {};
+//# sourceMappingURL=RecommendationRail.d.ts.map

package/dist/hookmovies/components/RecommendationRail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecommendationRail.d.ts","sourceRoot":"","sources":["../../../src/hookmovies/components/RecommendationRail.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAC;AAItF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAE9B,MAAM,2BAA2B,CAAC;AAInC,UAAU,uBAAuB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,wBAAwB,CAAC;IAClC,OAAO,EAAE,wBAAwB,CAAC;IAClC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6FD,eAAO,MAAM,kBAAkB,EAAE,EAAE,CAAC,uBAAuB,CAgF1D,CAAC"}

package/dist/hookmovies/components/RecommendationRail.js

@@ -0,0 +1,141 @@
+import { useRecordRecommendationEvents as e } from "../hooks/useHookMoviesApi.js";
+import { cn as t } from "../utils/cn.js";
+import { useFileUrl as n } from "../hooks/useFiles.js";
+import { formatEnumLabel as r } from "../utils/formatters.js";
+import { useEffect as i, useMemo as a, useRef as o, useState as s } from "react";
+import { Film as c, Info as l } from "lucide-react";
+import { jsx as u, jsxs as d } from "react/jsx-runtime";
+//#region src/hookmovies/components/RecommendationRail.tsx
+var f = ({ fileId: e, alt: t }) => {
+	let { data: r } = n(e), [i, a] = s(!1);
+	return e && r && !i ? /* @__PURE__ */ u("img", {
+		src: r,
+		alt: t,
+		loading: "lazy",
+		onError: () => a(!0),
+		className: "h-full w-full object-cover"
+	}) : /* @__PURE__ */ u("div", {
+		className: "flex h-full w-full items-center justify-center text-text-muted",
+		"aria-hidden": "true",
+		children: /* @__PURE__ */ u(c, { className: "h-8 w-8" })
+	});
+}, p = ({ item: e, onOpen: n }) => {
+	let [i, a] = s(!1), o = e.title;
+	if (!o) return null;
+	let c = e.reasons[0]?.label ?? null, p = [r(o.type), o.releaseYear ? String(o.releaseYear) : null].filter(Boolean).join(" · ");
+	return /* @__PURE__ */ d("div", {
+		className: "w-36 shrink-0 snap-start sm:w-44",
+		"data-testid": "recommendation-card",
+		children: [
+			/* @__PURE__ */ d("button", {
+				type: "button",
+				onClick: n,
+				"aria-label": `Open ${o.title}`,
+				className: "group block w-full text-left focus:outline-none",
+				children: [
+					/* @__PURE__ */ u("div", {
+						className: t("relative aspect-[2/3] overflow-hidden rounded-xl border border-border-seam bg-bg-sunken", "shadow-elevation-1 transition-[border-color,box-shadow] duration-200", "group-hover:border-border-strong group-hover:shadow-elevation-2", "group-focus-visible:ring-2 group-focus-visible:ring-[var(--color-focus-ring)]"),
+						children: /* @__PURE__ */ u("div", {
+							className: "absolute inset-0 motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-105",
+							children: /* @__PURE__ */ u(f, {
+								fileId: o.posterFileId,
+								alt: `${o.title} poster`
+							})
+						})
+					}),
+					/* @__PURE__ */ u("p", {
+						className: "mt-2 line-clamp-1 text-sm font-medium text-text-primary",
+						children: o.title
+					}),
+					p && /* @__PURE__ */ u("p", {
+						className: "mt-0.5 line-clamp-1 text-xs text-text-secondary",
+						children: p
+					})
+				]
+			}),
+			c && /* @__PURE__ */ d("div", {
+				className: "mt-1 flex items-start gap-1",
+				children: [/* @__PURE__ */ u("p", {
+					className: "line-clamp-2 flex-1 text-xs text-action-primary-bg",
+					"data-testid": "recommendation-reason",
+					children: c
+				}), e.reasons.length > 1 && /* @__PURE__ */ u("button", {
+					type: "button",
+					onClick: () => a((e) => !e),
+					"aria-expanded": i,
+					"aria-label": `Why ${o.title} is recommended`,
+					className: "rounded text-text-muted transition-colors hover:text-text-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)]",
+					children: /* @__PURE__ */ u(l, { className: "h-3.5 w-3.5" })
+				})]
+			}),
+			i && /* @__PURE__ */ u("ul", {
+				className: "mt-1 space-y-0.5 rounded-lg border border-border-seam bg-bg-surface p-2 text-[11px] text-text-secondary",
+				children: e.reasons.map((e) => /* @__PURE__ */ u("li", { children: e.label }, `${e.kind}-${e.relatedTitleId ?? ""}`))
+			})
+		]
+	});
+}, m = ({ heading: n, icon: r, items: s, variant: c, surface: l, seedTitleId: f, loading: m = !1, subheading: h, onOpen: g, className: _, gutterClassName: v = "px-4 sm:px-6" }) => {
+	let { mutate: y } = e(), b = o(null), x = a(() => s.filter((e) => e.title), [s]);
+	if (i(() => {
+		if (x.length === 0) return;
+		let e = `${c}:${l}:${f ?? ""}:${x.map((e) => e.titleId).join(",")}`;
+		b.current !== e && (b.current = e, y(x.slice(0, 50).map((e, t) => ({
+			titleId: e.titleId,
+			variant: c,
+			surface: l,
+			action: "IMPRESSION",
+			seedTitleId: f,
+			position: t
+		}))));
+	}, [
+		x,
+		c,
+		l,
+		f,
+		y
+	]), !m && x.length === 0) return null;
+	let S = (e, t) => {
+		y([{
+			titleId: e,
+			variant: c,
+			surface: l,
+			action: "CLICK",
+			seedTitleId: f,
+			position: t
+		}]), g(e);
+	};
+	return /* @__PURE__ */ d("section", {
+		className: _,
+		"aria-label": n,
+		"data-testid": `recommendation-rail-${l.toLowerCase()}`,
+		children: [/* @__PURE__ */ d("div", {
+			className: t("mb-3", v),
+			children: [/* @__PURE__ */ d("div", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ u("span", {
+					className: "text-action-primary-bg",
+					children: r
+				}), /* @__PURE__ */ u("h2", {
+					className: "text-base font-semibold text-text-primary sm:text-lg",
+					children: n
+				})]
+			}), h && /* @__PURE__ */ u("p", {
+				className: "mt-0.5 text-xs text-text-secondary",
+				children: h
+			})]
+		}), /* @__PURE__ */ u("div", {
+			className: t("flex gap-3 overflow-x-auto pb-3 snap-x [scrollbar-width:thin]", v),
+			children: m ? Array.from({ length: 6 }).map((e, t) => /* @__PURE__ */ u("div", {
+				className: "aspect-[2/3] w-36 shrink-0 rounded-xl border border-border-seam bg-bg-sunken motion-safe:animate-pulse sm:w-44",
+				"aria-hidden": "true"
+			}, t)) : x.map((e, t) => /* @__PURE__ */ u(p, {
+				item: e,
+				onOpen: () => S(e.titleId, t)
+			}, e.titleId))
+		})]
+	});
+};
+//#endregion
+export { m as RecommendationRail };
+
+//# sourceMappingURL=RecommendationRail.js.map

package/dist/hookmovies/components/RecommendationRail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecommendationRail.js","names":[],"sources":["../../../src/hookmovies/components/RecommendationRail.tsx"],"sourcesContent":["/**\n * RecommendationRail\n * @module hookmovies/components\n *\n * A horizontally-scrolling shelf of recommended titles (BOFF-4181). Every card\n * shows the strongest reason it was recommended (\"Because you watched X\",\n * \"Fans of Y also liked this\", shared cast …) straight from the ranker's\n * explanation, and an info toggle lists all contributing reasons.\n *\n * The rail also feeds the ranking A/B experiment: it logs one IMPRESSION per\n * rendered item (once per mounted list) and a CLICK when a card is opened,\n * tagged with the experiment arm the server chose. Logging is fire-and-forget\n * and never blocks navigation.\n *\n * Tokenized colors only; motion is `motion-safe:`; the rail scrolls inside its\n * own container so the page never overflows horizontally.\n */\n\nimport { type FC, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';\nimport { Film, Info } from 'lucide-react';\n\nimport { useFileUrl } from '../hooks/useFiles';\nimport {\n  type HokRecommendation,\n  type HokRecommendationSurface,\n  type HokRecommendationVariant,\n  useRecordRecommendationEvents,\n} from '../hooks/useHookMoviesApi';\nimport { cn } from '../utils/cn';\nimport { formatEnumLabel } from '../utils/formatters';\n\ninterface RecommendationRailProps {\n  heading: string;\n  icon: ReactNode;\n  items: HokRecommendation[];\n  variant: HokRecommendationVariant;\n  surface: HokRecommendationSurface;\n  /** Seed title for a \"more like this\" rail. */\n  seedTitleId?: string;\n  loading?: boolean;\n  /** Optional one-line context under the heading. */\n  subheading?: string;\n  onOpen: (titleId: string) => void;\n  /** Extra classes for the outer section (spacing differs per page). */\n  className?: string;\n  /** Horizontal padding classes, so the rail aligns with its page gutter. */\n  gutterClassName?: string;\n}\n\nconst Poster: FC<{ fileId: string | null; alt: string }> = ({ fileId, alt }) => {\n  const { data: url } = useFileUrl(fileId);\n  const [errored, setErrored] = useState(false);\n  if (fileId && url && !errored) {\n    return (\n      <img\n        src={url}\n        alt={alt}\n        loading=\"lazy\"\n        onError={() => setErrored(true)}\n        className=\"h-full w-full object-cover\"\n      />\n    );\n  }\n  return (\n    <div\n      className=\"flex h-full w-full items-center justify-center text-text-muted\"\n      aria-hidden=\"true\"\n    >\n      <Film className=\"h-8 w-8\" />\n    </div>\n  );\n};\n\nconst RecommendationCard: FC<{\n  item: HokRecommendation;\n  onOpen: () => void;\n}> = ({ item, onOpen }) => {\n  const [showWhy, setShowWhy] = useState(false);\n  const title = item.title;\n  if (!title) return null;\n  const topReason = item.reasons[0]?.label ?? null;\n  const meta = [formatEnumLabel(title.type), title.releaseYear ? String(title.releaseYear) : null]\n    .filter(Boolean)\n    .join(' · ');\n\n  return (\n    <div className=\"w-36 shrink-0 snap-start sm:w-44\" data-testid=\"recommendation-card\">\n      <button\n        type=\"button\"\n        onClick={onOpen}\n        aria-label={`Open ${title.title}`}\n        className=\"group block w-full text-left focus:outline-none\"\n      >\n        <div\n          className={cn(\n            'relative aspect-[2/3] overflow-hidden rounded-xl border border-border-seam bg-bg-sunken',\n            'shadow-elevation-1 transition-[border-color,box-shadow] duration-200',\n            'group-hover:border-border-strong group-hover:shadow-elevation-2',\n            'group-focus-visible:ring-2 group-focus-visible:ring-[var(--color-focus-ring)]'\n          )}\n        >\n          <div className=\"absolute inset-0 motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-105\">\n            <Poster fileId={title.posterFileId} alt={`${title.title} poster`} />\n          </div>\n        </div>\n        <p className=\"mt-2 line-clamp-1 text-sm font-medium text-text-primary\">{title.title}</p>\n        {meta && <p className=\"mt-0.5 line-clamp-1 text-xs text-text-secondary\">{meta}</p>}\n      </button>\n      {topReason && (\n        <div className=\"mt-1 flex items-start gap-1\">\n          <p\n            className=\"line-clamp-2 flex-1 text-xs text-action-primary-bg\"\n            data-testid=\"recommendation-reason\"\n          >\n            {topReason}\n          </p>\n          {item.reasons.length > 1 && (\n            <button\n              type=\"button\"\n              onClick={() => setShowWhy((v) => !v)}\n              aria-expanded={showWhy}\n              aria-label={`Why ${title.title} is recommended`}\n              className=\"rounded text-text-muted transition-colors hover:text-text-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)]\"\n            >\n              <Info className=\"h-3.5 w-3.5\" />\n            </button>\n          )}\n        </div>\n      )}\n      {showWhy && (\n        <ul className=\"mt-1 space-y-0.5 rounded-lg border border-border-seam bg-bg-surface p-2 text-[11px] text-text-secondary\">\n          {item.reasons.map((reason) => (\n            <li key={`${reason.kind}-${reason.relatedTitleId ?? ''}`}>{reason.label}</li>\n          ))}\n        </ul>\n      )}\n    </div>\n  );\n};\n\nexport const RecommendationRail: FC<RecommendationRailProps> = ({\n  heading,\n  icon,\n  items,\n  variant,\n  surface,\n  seedTitleId,\n  loading = false,\n  subheading,\n  onOpen,\n  className,\n  gutterClassName = 'px-4 sm:px-6',\n}) => {\n  const recordEvents = useRecordRecommendationEvents();\n  const { mutate } = recordEvents;\n  const loggedKey = useRef<string | null>(null);\n  const visible = useMemo(() => items.filter((item) => item.title), [items]);\n\n  // One IMPRESSION batch per distinct rendered list.\n  useEffect(() => {\n    if (visible.length === 0) return;\n    const key = `${variant}:${surface}:${seedTitleId ?? ''}:${visible.map((i) => i.titleId).join(',')}`;\n    if (loggedKey.current === key) return;\n    loggedKey.current = key;\n    mutate(\n      visible.slice(0, 50).map((item, position) => ({\n        titleId: item.titleId,\n        variant,\n        surface,\n        action: 'IMPRESSION' as const,\n        seedTitleId,\n        position,\n      }))\n    );\n  }, [visible, variant, surface, seedTitleId, mutate]);\n\n  if (!loading && visible.length === 0) return null;\n\n  const open = (titleId: string, position: number) => {\n    mutate([{ titleId, variant, surface, action: 'CLICK', seedTitleId, position }]);\n    onOpen(titleId);\n  };\n\n  return (\n    <section\n      className={className}\n      aria-label={heading}\n      data-testid={`recommendation-rail-${surface.toLowerCase()}`}\n    >\n      <div className={cn('mb-3', gutterClassName)}>\n        <div className=\"flex items-center gap-2\">\n          <span className=\"text-action-primary-bg\">{icon}</span>\n          <h2 className=\"text-base font-semibold text-text-primary sm:text-lg\">{heading}</h2>\n        </div>\n        {subheading && <p className=\"mt-0.5 text-xs text-text-secondary\">{subheading}</p>}\n      </div>\n      <div\n        className={cn(\n          'flex gap-3 overflow-x-auto pb-3 snap-x [scrollbar-width:thin]',\n          gutterClassName\n        )}\n      >\n        {loading\n          ? Array.from({ length: 6 }).map((_, i) => (\n              <div\n                key={i}\n                className=\"aspect-[2/3] w-36 shrink-0 rounded-xl border border-border-seam bg-bg-sunken motion-safe:animate-pulse sm:w-44\"\n                aria-hidden=\"true\"\n              />\n            ))\n          : visible.map((item, position) => (\n              <RecommendationCard\n                key={item.titleId}\n                item={item}\n                onOpen={() => open(item.titleId, position)}\n              />\n            ))}\n      </div>\n    </section>\n  );\n};\n"],"mappings":"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"}

package/dist/hookmovies/components/SearchInterpretation.d.ts

@@ -0,0 +1,26 @@
+import { FC } from 'react';
+import { HokSearchInterpretation } from '../hooks/useHookMoviesApi';
+
+/** Display name for an ISO 639-1 code ("ta" → "Tamil"); falls back to the code. */
+export declare function languageName(code: string): string;
+/** Human label for a runtime range in minutes. */
+export declare function runtimeLabel(min: number | null, max: number | null): string | null;
+/** Human label for a release-year range. */
+export declare function eraLabel(from: number | null, to: number | null): string | null;
+interface Chip {
+    key: string;
+    label: string;
+    icon: FC<{
+        className?: string;
+    }>;
+    tone: 'constraint' | 'concept' | 'exclude';
+}
+/** Flatten an interpretation into the chips shown to the viewer. */
+export declare function interpretationChips(interpretation: HokSearchInterpretation): Chip[];
+interface SearchInterpretationProps {
+    interpretation: HokSearchInterpretation;
+    className?: string;
+}
+export declare const SearchInterpretation: FC<SearchInterpretationProps>;
+export {};
+//# sourceMappingURL=SearchInterpretation.d.ts.map

package/dist/hookmovies/components/SearchInterpretation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchInterpretation.d.ts","sourceRoot":"","sources":["../../../src/hookmovies/components/SearchInterpretation.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAYhC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAIzE,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAKlF;AAED,4CAA4C;AAC5C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED,UAAU,IAAI;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,EAAE,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;CAC5C;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,uBAAuB,GAAG,IAAI,EAAE,CAqDnF;AAQD,UAAU,yBAAyB;IACjC,cAAc,EAAE,uBAAuB,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,oBAAoB,EAAE,EAAE,CAAC,yBAAyB,CAgC9D,CAAC"}

package/dist/hookmovies/components/SearchInterpretation.js

@@ -0,0 +1,111 @@
+import { cn as e } from "../utils/cn.js";
+import { formatEnumLabel as t } from "../utils/formatters.js";
+import { Ban as n, CalendarRange as r, Clock as i, Film as a, Languages as o, ShieldCheck as s, Sparkles as c, User as l } from "lucide-react";
+import { jsx as u, jsxs as d } from "react/jsx-runtime";
+//#region src/hookmovies/components/SearchInterpretation.tsx
+function f(e) {
+	try {
+		return new Intl.DisplayNames(["en"], { type: "language" }).of(e) ?? e;
+	} catch {
+		return e;
+	}
+}
+function p(e, t) {
+	return e !== null && t !== null ? `${e}–${t} min` : t === null ? e === null ? null : `Over ${e} min` : `Under ${t} min`;
+}
+function m(e, t) {
+	return e !== null && t !== null ? e === t ? String(e) : `${e}–${t}` : e === null ? t === null ? null : `${t} or earlier` : `${e} or later`;
+}
+function h(e) {
+	let u = [];
+	for (let t of e.languages) u.push({
+		key: `lang-${t}`,
+		label: f(t),
+		icon: o,
+		tone: "constraint"
+	});
+	for (let t of e.excludeLanguages) u.push({
+		key: `xlang-${t}`,
+		label: `Not ${f(t)}`,
+		icon: n,
+		tone: "exclude"
+	});
+	for (let t of e.subtitleLanguages) u.push({
+		key: `sub-${t}`,
+		label: `${f(t)} subtitles`,
+		icon: o,
+		tone: "constraint"
+	});
+	for (let n of e.types) u.push({
+		key: `type-${n}`,
+		label: t(n),
+		icon: a,
+		tone: "constraint"
+	});
+	let d = p(e.minRuntimeMinutes, e.maxRuntimeMinutes);
+	d && u.push({
+		key: "runtime",
+		label: d,
+		icon: i,
+		tone: "constraint"
+	});
+	let h = m(e.releaseYearFrom, e.releaseYearTo);
+	h && u.push({
+		key: "era",
+		label: h,
+		icon: r,
+		tone: "constraint"
+	}), e.familyFriendly && u.push({
+		key: "family",
+		label: "Family friendly",
+		icon: s,
+		tone: "constraint"
+	});
+	for (let n of e.concepts) u.push({
+		key: `concept-${n}`,
+		label: t(n.replace(/-/g, "_")),
+		icon: c,
+		tone: "concept"
+	});
+	for (let t of e.matchedPeople) u.push({
+		key: `person-${t.id}`,
+		label: t.name,
+		icon: l,
+		tone: "concept"
+	});
+	return u;
+}
+var g = {
+	constraint: "border-border-subtle bg-bg-surface text-text-primary",
+	concept: "border-border-subtle bg-bg-sunken text-text-secondary",
+	exclude: "border-status-warning-border bg-status-warning-bg-subtle text-status-warning-text"
+}, _ = ({ interpretation: t, className: n }) => {
+	let r = h(t);
+	return r.length === 0 && !t.transliteratedQuery ? null : /* @__PURE__ */ d("div", {
+		className: e("flex flex-wrap items-center gap-1.5", n),
+		"aria-label": "How your search was understood",
+		"data-testid": "search-interpretation",
+		children: [
+			/* @__PURE__ */ u("span", {
+				className: "text-xs text-text-muted",
+				children: "Understood as"
+			}),
+			t.transliteratedQuery && /* @__PURE__ */ d("span", {
+				className: "inline-flex items-center gap-1 rounded-full border border-border-subtle bg-bg-sunken px-2 py-0.5 text-xs italic text-text-secondary",
+				children: [
+					"“",
+					t.transliteratedQuery,
+					"”"
+				]
+			}),
+			r.map(({ key: t, label: n, icon: r, tone: i }) => /* @__PURE__ */ d("span", {
+				className: e("inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium", g[i]),
+				children: [/* @__PURE__ */ u(r, { className: "h-3 w-3" }), n]
+			}, t))
+		]
+	});
+};
+//#endregion
+export { _ as SearchInterpretation };
+
+//# sourceMappingURL=SearchInterpretation.js.map

package/dist/hookmovies/components/SearchInterpretation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchInterpretation.js","names":[],"sources":["../../../src/hookmovies/components/SearchInterpretation.tsx"],"sourcesContent":["/**\n * Search interpretation chips (BOFF-4187)\n * @module hookmovies/components\n *\n * Shows how `hokSemanticSearch` read a natural-language query — languages,\n * excluded languages, runtime, era, type, family-safety, recognised moods and\n * genres, and the people it resolved — so a viewer can see (and rephrase) the\n * interpretation instead of guessing why a title matched.\n *\n * Fully tokenized (fe-libs semantic tokens only), wraps on narrow screens.\n */\n\nimport type { FC } from 'react';\nimport {\n  Languages,\n  Clock,\n  CalendarRange,\n  Sparkles,\n  User,\n  Ban,\n  ShieldCheck,\n  Film,\n} from 'lucide-react';\n\nimport type { HokSearchInterpretation } from '../hooks/useHookMoviesApi';\nimport { cn } from '../utils/cn';\nimport { formatEnumLabel } from '../utils/formatters';\n\n/** Display name for an ISO 639-1 code (\"ta\" → \"Tamil\"); falls back to the code. */\nexport function languageName(code: string): string {\n  try {\n    const names = new Intl.DisplayNames(['en'], { type: 'language' });\n    return names.of(code) ?? code;\n  } catch {\n    return code;\n  }\n}\n\n/** Human label for a runtime range in minutes. */\nexport function runtimeLabel(min: number | null, max: number | null): string | null {\n  if (min !== null && max !== null) return `${min}–${max} min`;\n  if (max !== null) return `Under ${max} min`;\n  if (min !== null) return `Over ${min} min`;\n  return null;\n}\n\n/** Human label for a release-year range. */\nexport function eraLabel(from: number | null, to: number | null): string | null {\n  if (from !== null && to !== null) return from === to ? String(from) : `${from}–${to}`;\n  if (from !== null) return `${from} or later`;\n  if (to !== null) return `${to} or earlier`;\n  return null;\n}\n\ninterface Chip {\n  key: string;\n  label: string;\n  icon: FC<{ className?: string }>;\n  tone: 'constraint' | 'concept' | 'exclude';\n}\n\n/** Flatten an interpretation into the chips shown to the viewer. */\nexport function interpretationChips(interpretation: HokSearchInterpretation): Chip[] {\n  const chips: Chip[] = [];\n  for (const code of interpretation.languages) {\n    chips.push({\n      key: `lang-${code}`,\n      label: languageName(code),\n      icon: Languages,\n      tone: 'constraint',\n    });\n  }\n  for (const code of interpretation.excludeLanguages) {\n    chips.push({\n      key: `xlang-${code}`,\n      label: `Not ${languageName(code)}`,\n      icon: Ban,\n      tone: 'exclude',\n    });\n  }\n  for (const code of interpretation.subtitleLanguages) {\n    chips.push({\n      key: `sub-${code}`,\n      label: `${languageName(code)} subtitles`,\n      icon: Languages,\n      tone: 'constraint',\n    });\n  }\n  for (const type of interpretation.types) {\n    chips.push({\n      key: `type-${type}`,\n      label: formatEnumLabel(type),\n      icon: Film,\n      tone: 'constraint',\n    });\n  }\n  const runtime = runtimeLabel(interpretation.minRuntimeMinutes, interpretation.maxRuntimeMinutes);\n  if (runtime) chips.push({ key: 'runtime', label: runtime, icon: Clock, tone: 'constraint' });\n  const era = eraLabel(interpretation.releaseYearFrom, interpretation.releaseYearTo);\n  if (era) chips.push({ key: 'era', label: era, icon: CalendarRange, tone: 'constraint' });\n  if (interpretation.familyFriendly) {\n    chips.push({ key: 'family', label: 'Family friendly', icon: ShieldCheck, tone: 'constraint' });\n  }\n  for (const concept of interpretation.concepts) {\n    chips.push({\n      key: `concept-${concept}`,\n      label: formatEnumLabel(concept.replace(/-/g, '_')),\n      icon: Sparkles,\n      tone: 'concept',\n    });\n  }\n  for (const person of interpretation.matchedPeople) {\n    chips.push({ key: `person-${person.id}`, label: person.name, icon: User, tone: 'concept' });\n  }\n  return chips;\n}\n\nconst toneStyles: Record<Chip['tone'], string> = {\n  constraint: 'border-border-subtle bg-bg-surface text-text-primary',\n  concept: 'border-border-subtle bg-bg-sunken text-text-secondary',\n  exclude: 'border-status-warning-border bg-status-warning-bg-subtle text-status-warning-text',\n};\n\ninterface SearchInterpretationProps {\n  interpretation: HokSearchInterpretation;\n  className?: string;\n}\n\nexport const SearchInterpretation: FC<SearchInterpretationProps> = ({\n  interpretation,\n  className,\n}) => {\n  const chips = interpretationChips(interpretation);\n  if (chips.length === 0 && !interpretation.transliteratedQuery) return null;\n  return (\n    <div\n      className={cn('flex flex-wrap items-center gap-1.5', className)}\n      aria-label=\"How your search was understood\"\n      data-testid=\"search-interpretation\"\n    >\n      <span className=\"text-xs text-text-muted\">Understood as</span>\n      {interpretation.transliteratedQuery && (\n        <span className=\"inline-flex items-center gap-1 rounded-full border border-border-subtle bg-bg-sunken px-2 py-0.5 text-xs italic text-text-secondary\">\n          “{interpretation.transliteratedQuery}”\n        </span>\n      )}\n      {chips.map(({ key, label, icon: Icon, tone }) => (\n        <span\n          key={key}\n          className={cn(\n            'inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium',\n            toneStyles[tone]\n          )}\n        >\n          <Icon className=\"h-3 w-3\" />\n          {label}\n        </span>\n      ))}\n    </div>\n  );\n};\n"],"mappings":";;;;;AA6BA,SAAgB,EAAa,GAAsB;AACjD,KAAI;AAEF,SADc,IAAI,KAAK,aAAa,CAAC,KAAK,EAAE,EAAE,MAAM,YAAY,CAAC,CACpD,GAAG,EAAK,IAAI;SACnB;AACN,SAAO;;;AAKX,SAAgB,EAAa,GAAoB,GAAmC;AAIlF,QAHI,MAAQ,QAAQ,MAAQ,OAAa,GAAG,EAAI,GAAG,EAAI,QACnD,MAAQ,OACR,MAAQ,OACL,OADkB,QAAQ,EAAI,QADZ,SAAS,EAAI;;AAMxC,SAAgB,EAAS,GAAqB,GAAkC;AAI9E,QAHI,MAAS,QAAQ,MAAO,OAAa,MAAS,IAAK,OAAO,EAAK,GAAG,GAAG,EAAK,GAAG,MAC7E,MAAS,OACT,MAAO,OACJ,OADiB,GAAG,EAAG,eADJ,GAAG,EAAK;;AAapC,SAAgB,EAAoB,GAAiD;CACnF,IAAM,IAAgB,EAAE;AACxB,MAAK,IAAM,KAAQ,EAAe,UAChC,GAAM,KAAK;EACT,KAAK,QAAQ;EACb,OAAO,EAAa,EAAK;EACzB,MAAM;EACN,MAAM;EACP,CAAC;AAEJ,MAAK,IAAM,KAAQ,EAAe,iBAChC,GAAM,KAAK;EACT,KAAK,SAAS;EACd,OAAO,OAAO,EAAa,EAAK;EAChC,MAAM;EACN,MAAM;EACP,CAAC;AAEJ,MAAK,IAAM,KAAQ,EAAe,kBAChC,GAAM,KAAK;EACT,KAAK,OAAO;EACZ,OAAO,GAAG,EAAa,EAAK,CAAC;EAC7B,MAAM;EACN,MAAM;EACP,CAAC;AAEJ,MAAK,IAAM,KAAQ,EAAe,MAChC,GAAM,KAAK;EACT,KAAK,QAAQ;EACb,OAAO,EAAgB,EAAK;EAC5B,MAAM;EACN,MAAM;EACP,CAAC;CAEJ,IAAM,IAAU,EAAa,EAAe,mBAAmB,EAAe,kBAAkB;AAChG,CAAI,KAAS,EAAM,KAAK;EAAE,KAAK;EAAW,OAAO;EAAS,MAAM;EAAO,MAAM;EAAc,CAAC;CAC5F,IAAM,IAAM,EAAS,EAAe,iBAAiB,EAAe,cAAc;AAElF,CADI,KAAK,EAAM,KAAK;EAAE,KAAK;EAAO,OAAO;EAAK,MAAM;EAAe,MAAM;EAAc,CAAC,EACpF,EAAe,kBACjB,EAAM,KAAK;EAAE,KAAK;EAAU,OAAO;EAAmB,MAAM;EAAa,MAAM;EAAc,CAAC;AAEhG,MAAK,IAAM,KAAW,EAAe,SACnC,GAAM,KAAK;EACT,KAAK,WAAW;EAChB,OAAO,EAAgB,EAAQ,QAAQ,MAAM,IAAI,CAAC;EAClD,MAAM;EACN,MAAM;EACP,CAAC;AAEJ,MAAK,IAAM,KAAU,EAAe,cAClC,GAAM,KAAK;EAAE,KAAK,UAAU,EAAO;EAAM,OAAO,EAAO;EAAM,MAAM;EAAM,MAAM;EAAW,CAAC;AAE7F,QAAO;;AAGT,IAAM,IAA2C;CAC/C,YAAY;CACZ,SAAS;CACT,SAAS;CACV,EAOY,KAAuD,EAClE,mBACA,mBACI;CACJ,IAAM,IAAQ,EAAoB,EAAe;AAEjD,QADI,EAAM,WAAW,KAAK,CAAC,EAAe,sBAA4B,OAEpE,kBAAC,OAAD;EACE,WAAW,EAAG,uCAAuC,EAAU;EAC/D,cAAW;EACX,eAAY;YAHd;GAKE,kBAAC,QAAD;IAAM,WAAU;cAA0B;IAAoB,CAAA;GAC7D,EAAe,uBACd,kBAAC,QAAD;IAAM,WAAU;cAAhB;KAAsJ;KAClJ,EAAe;KAAoB;KAChC;;GAER,EAAM,KAAK,EAAE,QAAK,UAAO,MAAM,GAAM,cACpC,kBAAC,QAAD;IAEE,WAAW,EACT,sFACA,EAAW,GACZ;cALH,CAOE,kBAAC,GAAD,EAAM,WAAU,WAAY,CAAA,EAC3B,EACI;MARA,EAQA,CACP;GACE"}

package/dist/hookmovies/components/index.d.ts

@@ -10,4 +10,5 @@ export { EmptyState } from './EmptyState';
 export { LoadingState, ErrorState } from './StateViews';
 export { Pagination } from './Pagination';
 export { AddToListButton } from './AddToListButton';
+export { RecommendationRail } from './RecommendationRail';
 //# sourceMappingURL=index.d.ts.map

package/dist/hookmovies/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hookmovies/components/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hookmovies/components/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/hookmovies/components/index.js

@@ -6,3 +6,4 @@ import "./EmptyState.js";
 import "./Pagination.js";
 import "./RatingDisplay.js";
 import "./AddToListButton.js";
+import "./RecommendationRail.js";

package/dist/hookmovies/hooks/useHookMoviesApi.d.ts

@@ -276,6 +276,63 @@ export interface HokTitleFilters {
     studioId?: string;
 }
 export declare const useTitles: (filters?: HokTitleFilters, pagination?: HokPaginationInput, search?: string) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokConnection<HokTitle>>, Error>;
+/** Explicit constraints merged with whatever the query text implies. */
+export interface HokSemanticSearchFilters {
+    types?: HokTitleType[];
+    statuses?: HokTitleStatus[];
+    languages?: string[];
+    excludeLanguages?: string[];
+    genres?: string[];
+    minRuntimeMinutes?: number;
+    maxRuntimeMinutes?: number;
+    releaseYearFrom?: number;
+    releaseYearTo?: number;
+    studioId?: string;
+    personId?: string;
+}
+/** How the search read the query — every constraint and concept it applied. */
+export interface HokSearchInterpretation {
+    query: string;
+    transliteratedQuery: string | null;
+    keywords: string[];
+    concepts: string[];
+    languages: string[];
+    excludeLanguages: string[];
+    subtitleLanguages: string[];
+    originCountries: string[];
+    types: HokTitleType[];
+    minRuntimeMinutes: number | null;
+    maxRuntimeMinutes: number | null;
+    releaseYearFrom: number | null;
+    releaseYearTo: number | null;
+    familyFriendly: boolean;
+    matchedPeople: Array<Pick<HokPerson, 'id' | 'name'>>;
+}
+export interface HokSemanticSearchHit {
+    title: HokTitle;
+    score: number;
+    matchedConcepts: string[];
+    matchedKeywords: string[];
+    matchedLanguage: string | null;
+    matchedPeople: Array<Pick<HokPerson, 'id' | 'name'>>;
+}
+export interface HokSemanticSearchResult {
+    hits: HokSemanticSearchHit[];
+    interpretation: HokSearchInterpretation;
+    candidateCount: number;
+    totalMatches: number;
+    truncated: boolean;
+}
+/**
+ * Natural-language, cross-script catalog search (`hokSemanticSearch`).
+ *
+ * Understands moods/genres, languages ("Tamil", "not in English"), runtime
+ * ("under 2 hours"), era and family-safety, matches titles across scripts and
+ * localisations, and boosts titles crediting people the query names. Disabled
+ * while `query` is blank. Callers fall back to keyword `useTitles` search when
+ * this errors (for example when the `hookmovies.semantic_search` flag is off).
+ */
+export declare const useSemanticSearch: (query: string | undefined, filters?: HokSemanticSearchFilters, limit?: number) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokSemanticSearchResult>, Error>;
 export declare const useTitle: (id: string | undefined) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokTitleDetail | null>, Error>;
 /**
  * Resolve an arbitrary set of title ids in ONE round trip.
@@ -1187,5 +1244,60 @@ export interface SetRoyaltyRevenuePoolInput {
 export declare const useSetRoyaltyRevenuePool: () => import('@tanstack/react-query').UseMutationResult<{
     id: string;
 }, Error, SetRoyaltyRevenuePoolInput, unknown>;
+export type HokRecommendationVariant = 'PERSONALIZED' | 'BASELINE';
+export type HokRecommendationSurface = 'HOME' | 'TITLE';
+export type HokRecommendationAction = 'IMPRESSION' | 'CLICK';
+export type HokRecommendationReasonKind = 'SHARED_CAST' | 'SHARED_CREW' | 'SAME_STUDIO' | 'SHARED_GENRE' | 'SHARED_TAG' | 'SAME_LANGUAGE' | 'SAME_TYPE' | 'SIMILAR_ERA' | 'BECAUSE_YOU_WATCHED' | 'FANS_ALSO_LIKED' | 'PREFERRED_LANGUAGE' | 'PREFERRED_TYPE' | 'POPULAR' | 'NEW_RELEASE';
+export interface HokRecommendationReason {
+    kind: HokRecommendationReasonKind;
+    label: string;
+    weight: number;
+    relatedTitleId: string | null;
+    relatedTitleName: string | null;
+}
+export interface HokRecommendation {
+    titleId: string;
+    score: number;
+    reasons: HokRecommendationReason[];
+    title: HokTitle | null;
+}
+export interface HokRecommendationFeed {
+    variant: HokRecommendationVariant;
+    coldStart: boolean;
+    seedCount: number;
+    generatedAt: string;
+    items: HokRecommendation[];
+}
+export interface HokRecommendationEventInput {
+    titleId: string;
+    variant: HokRecommendationVariant;
+    surface: HokRecommendationSurface;
+    action: HokRecommendationAction;
+    seedTitleId?: string;
+    position?: number;
+}
+export interface HokRecommendationArmStats {
+    variant: HokRecommendationVariant;
+    impressions: number;
+    clicks: number;
+    clickThroughRate: number;
+    viewers: number;
+}
+export interface HokRecommendationExperimentSummary {
+    sinceDays: number;
+    baselinePercent: number;
+    arms: HokRecommendationArmStats[];
+}
+/** Personalised "for you" list for the signed-in viewer (self-scoped). */
+export declare const useRecommendForViewer: (limit?: number) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokRecommendationFeed>, Error>;
+/** "More like this" for a title. */
+export declare const useSimilarTitles: (titleId: string | undefined, limit?: number) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokRecommendation[]>, Error>;
+/**
+ * Record recommendation impressions / clicks for the ranking A/B experiment.
+ * Fire-and-forget: a failed log never affects browsing.
+ */
+export declare const useRecordRecommendationEvents: () => import('@tanstack/react-query').UseMutationResult<number, Error, HokRecommendationEventInput[], unknown>;
+/** Click-through per experiment arm (studio analytics). */
+export declare const useRecommendationExperimentSummary: (sinceDays?: number) => import('@tanstack/react-query').UseQueryResult<NoInfer<HokRecommendationExperimentSummary>, Error>;
 export {};
 //# sourceMappingURL=useHookMoviesApi.d.ts.map