@matterfact/embed 0.7.0 → 0.9.0

package/examples/embed-demo/src/mockXH.ts

@@ -0,0 +1,492 @@
+/**
+ * A self-contained, in-memory mock of the pieces of `window.XH` the embed SDK's Hoist
+ * adapter reads — see `@matterfact/embed`'s `src/adapters/hoist-runtime.ts` and
+ * `adapters/HOIST-CONTRACT.md` for the real, confirmed shapes this mirrors. Demo-only:
+ * nothing here is imported BY the SDK, and the SDK's adapter source is never imported
+ * HERE — this just populates `window.XH` with fake-but-shape-accurate data so the exact
+ * same automatic detection that would fire on a real XH Hoist app fires here too, with
+ * zero host integration code (see App.tsx / HoistDemo.tsx: nothing calls into the SDK's
+ * Hoist adapter directly — `<MatterfactAgent>` just finds `window.XH` on its own).
+ *
+ * Opt-in via `?hoist=1` (see `isHoistModeEnabled`) and installed once, eagerly, from
+ * main.tsx — BEFORE React renders anything. That ordering matters: `<MatterfactAgent>`'s
+ * mount effect reads `window.XH` synchronously (the SDK's `start()` calls
+ * `advertiseTools()` at the end of mount), so installing the mock any later — e.g. from
+ * inside a React effect — risks losing the very first tool advertisement to a race.
+ *
+ * The "app" this pretends to be is the SAME Meridian Capital growth-sleeve portfolio
+ * App.tsx hand-declares context for, just read out of fake `GridModel` / `ChartModel` /
+ * `TabContainerModel` instances instead of a `getPageContext` callback — so toggling
+ * `?hoist=1` is a true side-by-side comparison of the two context mechanisms, not two
+ * unrelated demos.
+ *
+ * Site map (two nav levels, like a real Hoist app):
+ *   Site               → Holdings, Research                   (top-level tabs)
+ *   Company · <TICKER> → Thesis, Financials, Ownership         (per-holding sub-views)
+ * Route names deliberately reuse the exact `default.company.ticker.*` shape
+ * HOIST-CONTRACT.md confirms against the real app — including the literal
+ * `.company.ticker.` substring `readSitemap` matches to group-label a nav level
+ * "Company · <TICKER>" instead of "Site".
+ */
+import { useSyncExternalStore } from 'react';
+
+declare global {
+  interface Window {
+    /** Set only when the mock is installed — see installMockXH(). */
+    XH?: unknown;
+  }
+}
+
+type Params = Record<string, string>;
+
+/* ─────────────────────────────── portfolio data ────────────────────────── */
+
+export interface Holding {
+  ticker: string;
+  weight: string;
+  day: string;
+  ytd: string;
+  dayNeg?: boolean;
+  ytdNeg?: boolean;
+  thesis: string;
+}
+
+const HOLDINGS: Holding[] = [
+  {
+    ticker: 'NVDA',
+    weight: '9.4%',
+    day: '+2.8%',
+    ytd: '+41%',
+    thesis:
+      'AI datacenter demand is still outrunning supply, and the next-gen accelerator pipeline looks deep.',
+  },
+  {
+    ticker: 'MSFT',
+    weight: '8.1%',
+    day: '+0.9%',
+    ytd: '+22%',
+    thesis:
+      'Copilot attach rate is quietly the bigger seat-expansion story, more than Azure growth alone.',
+  },
+  {
+    ticker: 'UNH',
+    weight: '6.7%',
+    day: '−1.2%',
+    ytd: '−8%',
+    dayNeg: true,
+    ytdNeg: true,
+    thesis:
+      'MLR pressure from utilization normalization — watching for a trough in the next two prints.',
+  },
+  {
+    ticker: 'V',
+    weight: '5.9%',
+    day: '+0.4%',
+    ytd: '+11%',
+    thesis:
+      'Cross-border volume recovery continues; take-rate mix is the swing factor to watch.',
+  },
+  {
+    ticker: 'LLY',
+    weight: '5.2%',
+    day: '+1.7%',
+    ytd: '+34%',
+    thesis:
+      'GLP-1 ramp remains supply constrained — capacity buildout is the real next-year catalyst.',
+  },
+];
+
+const OWNERSHIP: Record<
+  string,
+  { holder: string; shares: string; pct: string }[]
+> = {
+  NVDA: [
+    { holder: 'Vanguard Group', shares: '812.4M', pct: '8.3%' },
+    { holder: 'BlackRock', shares: '694.1M', pct: '7.1%' },
+    { holder: 'State Street', shares: '331.8M', pct: '3.4%' },
+  ],
+  MSFT: [
+    { holder: 'Vanguard Group', shares: '651.2M', pct: '8.7%' },
+    { holder: 'BlackRock', shares: '556.9M', pct: '7.5%' },
+    { holder: 'State Street', shares: '267.3M', pct: '3.6%' },
+  ],
+  UNH: [
+    { holder: 'Vanguard Group', shares: '68.9M', pct: '7.6%' },
+    { holder: 'BlackRock', shares: '58.2M', pct: '6.4%' },
+    { holder: 'Berkshire Hathaway', shares: '5.0M', pct: '0.6%' },
+  ],
+  V: [
+    { holder: 'Vanguard Group', shares: '134.7M', pct: '6.5%' },
+    { holder: 'BlackRock', shares: '114.2M', pct: '5.5%' },
+    { holder: 'State Street', shares: '58.9M', pct: '2.8%' },
+  ],
+  LLY: [
+    { holder: 'Vanguard Group', shares: '84.3M', pct: '9.0%' },
+    { holder: 'BlackRock', shares: '71.6M', pct: '7.6%' },
+    { holder: 'State Street', shares: '34.1M', pct: '3.6%' },
+  ],
+};
+
+// Indexed (base-100) series, not real prices — only min/max/last ever reach the
+// agent (see hoist.ts's seriesSummary), so the exact values just need to tell a
+// story consistent with each holding's day/ytd sign.
+const PRICE_SERIES: Record<string, number[]> = {
+  NVDA: [100, 104, 109, 107, 115, 122, 119, 128, 135, 141],
+  MSFT: [100, 101, 103, 106, 105, 109, 112, 115, 118, 122],
+  UNH: [100, 98, 95, 97, 93, 90, 92, 89, 91, 88],
+  V: [100, 100.5, 102, 101, 103, 104, 106, 105, 108, 111],
+  LLY: [100, 105, 103, 110, 116, 121, 118, 126, 130, 134],
+};
+
+export function getHoldings(): Holding[] {
+  return HOLDINGS;
+}
+export function getOwnershipRows(
+  ticker: string,
+): { holder: string; shares: string; pct: string }[] {
+  return OWNERSHIP[ticker] ?? OWNERSHIP.NVDA;
+}
+export function getPriceSeries(ticker: string): number[] {
+  return PRICE_SERIES[ticker] ?? PRICE_SERIES.NVDA;
+}
+
+/* ───────────────────────── GridModel / ChartModel shapes ───────────────── */
+// Mirrors the exact fields hoist-runtime.ts reads (readGrid/readColumns/readChart) —
+// see HOIST-CONTRACT.md. `record()` matches the `{get(field), data}` shape its
+// `readRow` expects.
+
+interface LeafColumn {
+  field: string;
+  colId: string;
+  headerName: string;
+}
+interface GroupColumn {
+  headerName: string;
+  children: LeafColumn[];
+}
+type Column = LeafColumn | GroupColumn;
+const isGroup = (c: Column): c is GroupColumn => 'children' in c;
+const leafColumns = (cols: Column[]): LeafColumn[] =>
+  cols.flatMap((c) => (isGroup(c) ? c.children : [c]));
+
+function record<T extends object>(
+  data: T,
+): { get: (f: string) => unknown; data: T } {
+  return { get: (f: string) => (data as Record<string, unknown>)[f], data };
+}
+
+// One ColumnGroup ("Performance") with two leaf children — exercises the
+// group-qualified header path (readColumns' collectHeaders), same as the real
+// app's "5Y" group in HOIST-CONTRACT.md.
+const HOLDINGS_COLUMNS: Column[] = [
+  { field: 'ticker', colId: 'ticker', headerName: 'Ticker' },
+  {
+    headerName: 'Performance',
+    children: [
+      { field: 'day', colId: 'day', headerName: 'Day' },
+      { field: 'ytd', colId: 'ytd', headerName: 'YTD' },
+    ],
+  },
+  { field: 'weight', colId: 'weight', headerName: 'Weight' },
+];
+
+function holdingsGrid(selection: string | null) {
+  const records = HOLDINGS.map((h) => record(h));
+  return {
+    constructor: { name: 'GridModel' },
+    xhId: 'holdingsGrid',
+    title: 'Holdings',
+    columns: HOLDINGS_COLUMNS,
+    getVisibleLeafColumns: () => leafColumns(HOLDINGS_COLUMNS),
+    selectedRecords: records.filter((r) => r.data.ticker === selection),
+    store: { records, allCount: records.length },
+  };
+}
+
+const OWNERSHIP_COLUMNS: Column[] = [
+  { field: 'holder', colId: 'holder', headerName: 'Holder' },
+  { field: 'shares', colId: 'shares', headerName: 'Shares' },
+  { field: 'pct', colId: 'pct', headerName: '% Owned' },
+];
+
+function ownershipGrid(ticker: string) {
+  const rows = getOwnershipRows(ticker);
+  const records = rows.map((r) => record(r));
+  return {
+    constructor: { name: 'GridModel' },
+    xhId: `ownershipGrid-${ticker}`,
+    title: `${ticker} — top holders`,
+    columns: OWNERSHIP_COLUMNS,
+    getVisibleLeafColumns: () => leafColumns(OWNERSHIP_COLUMNS),
+    selectedRecords: [],
+    store: { records, allCount: records.length },
+  };
+}
+
+const DAY_MS = 86_400_000;
+const SERIES_START = Date.UTC(2026, 0, 5);
+
+function financialsChart(ticker: string) {
+  const values = getPriceSeries(ticker);
+  return {
+    constructor: { name: 'ChartModel' },
+    xhId: `financialsChart-${ticker}`,
+    title: `${ticker} — indexed price`,
+    // Confirmed shape: [timestamp, value] tuples, not bare numbers (HOIST-CONTRACT.md).
+    series: [
+      {
+        name: ticker,
+        data: values.map((v, i) => [SERIES_START + i * DAY_MS, v]),
+      },
+    ],
+  };
+}
+
+/* ─────────────────────────────── route tree ─────────────────────────────── */
+// Walked by the adapter's routeIndex() exactly like a real router5 tree (see
+// hoist-runtime.ts / HOIST-CONTRACT.md's confirmed `XH.router.rootNode` shape).
+
+const ROUTE_TREE = {
+  children: [
+    {
+      name: 'default',
+      children: [
+        { name: 'holdings', children: [] },
+        { name: 'research', children: [] },
+        {
+          name: 'company',
+          children: [
+            {
+              name: 'ticker',
+              children: [
+                { name: 'thesis', children: [] },
+                { name: 'financials', children: [] },
+                { name: 'ownership', children: [] },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+function buildPath(name: string, params: Params): string {
+  const ticker = encodeURIComponent(params.ticker ?? '');
+  const table: Record<string, string> = {
+    default: '/',
+    'default.holdings': '/holdings',
+    'default.research': '/research',
+    'default.company': '/company',
+    'default.company.ticker': `/company/${ticker}`,
+    'default.company.ticker.thesis': `/company/${ticker}/thesis`,
+    'default.company.ticker.financials': `/company/${ticker}/financials`,
+    'default.company.ticker.ownership': `/company/${ticker}/ownership`,
+  };
+  return table[name] ?? '';
+}
+
+/** The inverse of buildPath, for landing on a deep link or a browser back/forward —
+ *  see the popstate listener in installMockXH(). */
+function routeFromPath(pathname: string): { name: string; params: Params } {
+  const segs = pathname.split('/').filter(Boolean);
+  if (segs[0] === 'research') return { name: 'default.research', params: {} };
+  if (segs[0] === 'company' && segs[1]) {
+    const ticker = decodeURIComponent(segs[1]);
+    const leaf = segs[2];
+    const name =
+      leaf === 'financials'
+        ? 'default.company.ticker.financials'
+        : leaf === 'ownership'
+          ? 'default.company.ticker.ownership'
+          : 'default.company.ticker.thesis';
+    return { name, params: { ticker } };
+  }
+  return { name: 'default.holdings', params: {} }; // '/', '/holdings', or unrecognized
+}
+
+/* ─────────────────────────────── nav (TabContainers) ────────────────────── */
+
+function topSegment(routeName: string): string {
+  return routeName.split('.')[1] ?? '';
+}
+function leafSegment(routeName: string): string {
+  const parts = routeName.split('.');
+  return parts[parts.length - 1];
+}
+
+function siteTabs(routeName: string) {
+  return {
+    constructor: { name: 'TabContainerModel' },
+    xhId: 'siteTabs',
+    activeTabId: topSegment(routeName),
+    tabs: [
+      { id: 'holdings', title: 'Holdings' },
+      { id: 'research', title: 'Research' },
+    ],
+  };
+}
+
+// Always mounted (not just while inside a company sub-route) — so the agent can
+// jump straight into the currently-focused company's Ownership/Financials/Thesis
+// from anywhere, the same way a persistent detail-panel TabContainer would in a
+// real Hoist app. `store.params.ticker` is the "currently focused company" and is
+// always set (defaults to the first holding).
+function companyTabs(routeName: string) {
+  return {
+    constructor: { name: 'TabContainerModel' },
+    xhId: 'companyTabs',
+    activeTabId: routeName.startsWith('default.company.ticker')
+      ? leafSegment(routeName)
+      : '',
+    tabs: [
+      { id: 'thesis', title: 'Thesis' },
+      { id: 'financials', title: 'Financials' },
+      { id: 'ownership', title: 'Ownership' },
+    ],
+  };
+}
+
+/* ─────────────────────────────── the store ───────────────────────────────
+ * useSyncExternalStore requires getSnapshot() to return a value that changes
+ * (by Object.is) exactly when the underlying data changes, and stays stable
+ * otherwise — so `state` is REPLACED wholesale on every change, never mutated
+ * in place. */
+
+interface StoreState {
+  name: string;
+  params: Params;
+  /** Holdings-grid row selection, by ticker — independent of `params.ticker`
+   *  (the focused company for the nav/drill-in), same as a real grid letting
+   *  you select a row without navigating away. */
+  selection: string | null;
+}
+
+let state: StoreState = {
+  name: 'default.holdings',
+  params: { ticker: HOLDINGS[0].ticker },
+  selection: null,
+};
+
+const listeners = new Set<() => void>();
+function setState(patch: Partial<StoreState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+function toTicker(v: unknown, fallback: string): string {
+  return typeof v === 'string' && v ? v : fallback;
+}
+
+/**
+ * Navigate the mock — the SAME function whether the call came from the agent's
+ * `hoist.navigate` tool (assigned as `XH.navigate` below) or a plain click in
+ * HoistDemo.tsx, so there is exactly one code path for "the page changed" and a
+ * human click is indistinguishable from an agent-driven one.
+ *
+ * Also updates the real URL via history.pushState — which, by the time any
+ * navigation can actually happen, has already been monkey-patched by the SDK's
+ * own context.ts (watchNavigation, installed when <MatterfactAgent> mounts) — so
+ * an agent-driven navigate here also republishes host.context/host.tools exactly
+ * like a real SPA route change, with no extra wiring on our part.
+ */
+export function mockNavigate(
+  name: string,
+  params: Record<string, unknown> = {},
+): void {
+  const ticker = toTicker(params.ticker, state.params.ticker);
+  setState({ name, params: { ticker } });
+  const path = buildPath(name, { ticker }) || '/';
+  if (path !== location.pathname) {
+    // Preserve ?hoist=1 (and anything else in the query string) across
+    // navigation — pushState only touches the path.
+    history.pushState(null, '', path + location.search);
+  }
+}
+
+export function selectHolding(ticker: string): void {
+  setState({ selection: state.selection === ticker ? null : ticker });
+}
+
+export function useMockXH(): StoreState {
+  return useSyncExternalStore(
+    (onChange) => {
+      listeners.add(onChange);
+      return () => listeners.delete(onChange);
+    },
+    () => state,
+  );
+}
+
+/* ─────────────────────────────── window.XH ───────────────────────────────── */
+
+function getModels(className: string): unknown[] {
+  switch (className) {
+    case 'TabContainerModel':
+      return [siteTabs(state.name), companyTabs(state.name)];
+    case 'GridModel':
+      if (state.name === 'default.holdings')
+        return [holdingsGrid(state.selection)];
+      if (state.name === 'default.company.ticker.ownership')
+        return [ownershipGrid(state.params.ticker)];
+      return [];
+    case 'ChartModel':
+      if (state.name === 'default.company.ticker.financials')
+        return [financialsChart(state.params.ticker)];
+      return [];
+    default:
+      return [];
+  }
+}
+
+const XH = {
+  // A getter, not a plain property: hoist-runtime.ts reads `XH.routerState`
+  // fresh on every call, so this just has to reflect the CURRENT `state` live.
+  get routerState() {
+    return {
+      name: state.name,
+      path: buildPath(state.name, state.params) || location.pathname,
+      params: state.params,
+    };
+  },
+  router: { buildPath, rootNode: ROUTE_TREE },
+  getModels,
+  navigate: mockNavigate,
+};
+
+export function isHoistModeEnabled(): boolean {
+  if (typeof window === 'undefined') return false;
+  return new URLSearchParams(location.search).get('hoist') === '1';
+}
+
+let installed = false;
+
+/** Install the mock onto `window.XH`. Idempotent; call once, eagerly, before
+ *  React renders (see main.tsx) — never from inside a component effect. */
+export function installMockXH(): void {
+  if (typeof window === 'undefined' || installed) return;
+  installed = true;
+  window.XH = XH;
+
+  // Land on whatever the URL already says (a deep link or a reload), not always
+  // the Holdings default.
+  if (location.pathname !== '/') {
+    const initial = routeFromPath(location.pathname);
+    state = {
+      ...state,
+      name: initial.name,
+      params: { ticker: initial.params.ticker ?? state.params.ticker },
+    };
+  }
+
+  // Keep XH.routerState in sync on browser back/forward. The FORWARD direction
+  // (mockNavigate) already calls history.pushState itself, above; this is the
+  // other half.
+  window.addEventListener('popstate', () => {
+    const r = routeFromPath(location.pathname);
+    setState({
+      name: r.name,
+      params: { ticker: r.params.ticker ?? state.params.ticker },
+    });
+  });
+}

package/examples/embed-demo/src/placement.tsx

@@ -0,0 +1,43 @@
+import { useState } from 'react';
+
+/**
+ * Which PLACEMENT a demo page embeds the agent with — the two patterns we ship:
+ *
+ *   'panel'  — `inline`: the host owns the box, the widget fills it and draws no
+ *              chrome of its own. What a product with its own side panel uses.
+ *   'corner' — the widget owns everything: an edge tab (or a floating circle),
+ *              opening into a side panel it positions and sizes itself.
+ *
+ * Shared rather than per-page on purpose. The switch first existed only in App.tsx,
+ * so when the Hoist demo arrived it hardcoded `inline` and the widget-owned placement
+ * was simply unreachable there — a demo that can only show one of the two things it
+ * exists to demonstrate. One hook and one control means the next page can't drift.
+ */
+export type Placement = 'panel' | 'corner';
+
+export function usePlacement(initial: Placement = 'corner') {
+  return useState<Placement>(initial);
+}
+
+export function PlacementSwitch({
+  placement,
+  onChange,
+}: {
+  placement: Placement;
+  onChange: (p: Placement) => void;
+}) {
+  return (
+    <div className="placement" role="group" aria-label="Agent placement">
+      {(['corner', 'panel'] as const).map((p) => (
+        <button
+          key={p}
+          className={placement === p ? 'seg on' : 'seg'}
+          aria-pressed={placement === p}
+          onClick={() => onChange(p)}
+        >
+          {p === 'corner' ? 'Corner' : 'Panel'}
+        </button>
+      ))}
+    </div>
+  );
+}