@agent-native/core 0.69.0 → 0.70.0

package/corpus/core/src/client/analytics.ts

@@ -61,6 +61,44 @@ const LLM_CONNECTION_CACHE_TTL_MS = 5 * 60 * 1000;
 // session over multiple visits.
 const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
+// First-touch referral attribution (viral attribution). Captured once on the
+// visitor's first page load and persisted across the signup boundary so the
+// server-side `signup` event can record where the user came from. First-write
+// wins — an existing value is never overwritten.
+const FIRST_TOUCH_STORAGE_KEY = "an_attribution";
+const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+// 30 days, matching the session cookie lifetime — long enough to bridge a
+// "land today, sign up next week" path without retaining attribution forever.
+const FIRST_TOUCH_COOKIE_MAX_AGE_SECONDS = 2592000;
+const FIRST_TOUCH_MAX_FIELD_LENGTH = 120;
+// Keep the serialized cookie well under the ~4KB browser cap; we bail rather
+// than write a runaway cookie if some field combination blows past this.
+const FIRST_TOUCH_MAX_COOKIE_BYTES = 1500;
+const FIRST_TOUCH_QUERY_FIELDS = [
+  "ref",
+  "via",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+] as const;
+
+let _firstTouchCaptured = false;
+
+export interface FirstTouchAttribution {
+  ref?: string;
+  via?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  landing_path?: string;
+  landing_referrer?: string;
+  landed_at?: string;
+}
+
 function generateVisitorId(): string {
   try {
     if (
@@ -214,6 +252,148 @@ function getOrCreateSessionId(): string | undefined {
   return id;
 }
 
+function truncateFirstTouchField(value: string | null | undefined): string {
+  if (!value) return "";
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  return trimmed.slice(0, FIRST_TOUCH_MAX_FIELD_LENGTH);
+}
+
+/**
+ * Extract just the host of a referrer URL — never the full URL or query
+ * string (those can carry tokens). Returns "" when there's no usable host or
+ * the referrer is same-origin (a same-site navigation isn't a referral).
+ */
+function scrubReferrerHost(referrer: string | undefined): string {
+  if (!referrer) return "";
+  try {
+    const url = new URL(referrer);
+    const host = url.host;
+    if (!host) return "";
+    if (
+      typeof window !== "undefined" &&
+      host.toLowerCase() === window.location.host.toLowerCase()
+    ) {
+      return "";
+    }
+    return truncateFirstTouchField(host);
+  } catch {
+    return "";
+  }
+}
+
+function buildFirstTouchAttribution(): FirstTouchAttribution {
+  const attribution: FirstTouchAttribution = {};
+  let params: URLSearchParams | null = null;
+  try {
+    params = new URLSearchParams(window.location.search);
+  } catch {
+    params = null;
+  }
+  if (params) {
+    for (const field of FIRST_TOUCH_QUERY_FIELDS) {
+      const value = truncateFirstTouchField(params.get(field));
+      if (value) attribution[field] = value;
+    }
+  }
+  const landingPath = truncateFirstTouchField(window.location.pathname);
+  if (landingPath) attribution.landing_path = landingPath;
+  const landingReferrer =
+    typeof document !== "undefined" ? scrubReferrerHost(document.referrer) : "";
+  if (landingReferrer) attribution.landing_referrer = landingReferrer;
+  attribution.landed_at = new Date().toISOString();
+  return attribution;
+}
+
+function readFirstTouchCookie(): string | null {
+  if (typeof document === "undefined") return null;
+  try {
+    const cookies = document.cookie ? document.cookie.split(";") : [];
+    for (const part of cookies) {
+      const eq = part.indexOf("=");
+      if (eq === -1) continue;
+      const name = part.slice(0, eq).trim();
+      if (name === FIRST_TOUCH_COOKIE_NAME) {
+        return part.slice(eq + 1).trim();
+      }
+    }
+  } catch {
+    // document.cookie can throw in sandboxed iframes — best-effort.
+  }
+  return null;
+}
+
+function writeFirstTouchCookie(encodedValue: string): void {
+  if (typeof document === "undefined") return;
+  // Non-sensitive, written by client JS, so no HttpOnly. SameSite=Lax keeps it
+  // on top-level navigations (which is how share links arrive) without leaking
+  // it to cross-site subresource requests.
+  const cookie =
+    `${FIRST_TOUCH_COOKIE_NAME}=${encodedValue}; path=/; ` +
+    `max-age=${FIRST_TOUCH_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+  if (cookie.length > FIRST_TOUCH_MAX_COOKIE_BYTES) return;
+  try {
+    document.cookie = cookie;
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Capture the visitor's first-touch referral attribution exactly once. Reads
+ * the current URL query params + landing info and, IF no attribution is
+ * already stored (first-write-wins), persists it to both `localStorage`
+ * (`an_attribution`) and the first-party `an_ft` cookie. Fully defensive and
+ * SSR-safe — any failure is swallowed so it can never break app boot.
+ */
+function captureFirstTouchAttribution(): void {
+  if (_firstTouchCaptured) return;
+  _firstTouchCaptured = true;
+  if (typeof window === "undefined") return;
+  try {
+    const existing = safeStorageGet(FIRST_TOUCH_STORAGE_KEY);
+    if (existing) {
+      // Already captured in a prior visit. Backfill the cookie if it expired
+      // or was cleared so the signup boundary still sees first-touch data, but
+      // never overwrite the stored value itself (first-write-wins).
+      if (!readFirstTouchCookie()) {
+        try {
+          writeFirstTouchCookie(encodeURIComponent(existing));
+        } catch {
+          // ignore
+        }
+      }
+      return;
+    }
+    const attribution = buildFirstTouchAttribution();
+    const json = JSON.stringify(attribution);
+    safeStorageSet(FIRST_TOUCH_STORAGE_KEY, json);
+    writeFirstTouchCookie(encodeURIComponent(json));
+  } catch {
+    // Attribution is best-effort telemetry; never let it break boot.
+  }
+}
+
+/**
+ * Return the parsed first-touch referral attribution captured for this
+ * visitor, or `null` when none is stored. Reads from `localStorage`
+ * (`an_attribution`). SSR-safe and defensive.
+ */
+export function getFirstTouchAttribution(): FirstTouchAttribution | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = safeStorageGet(FIRST_TOUCH_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as FirstTouchAttribution;
+  } catch {
+    return null;
+  }
+}
+
 function isLocalAnalyticsHostname(hostname: string | undefined): boolean {
   const h = (hostname || "").toLowerCase();
   return (
@@ -531,6 +711,7 @@ export function configureTracking(options: {
   if (typeof window !== "undefined") {
     ensureSentry();
     ensureAmplitude();
+    captureFirstTouchAttribution();
     installLlmConnectionRefresh();
     installPageviewTracking();
   }

package/corpus/core/src/client/changelog/Changelog.tsx

@@ -0,0 +1,321 @@
+/**
+ * Changelog UI — renders an app's CHANGELOG.md as an in-app "What's new"
+ * surface. Core owns all of this; a template just passes its own
+ * `CHANGELOG.md?raw` content in (Vite inlines it at build time, so this works
+ * on every host with no runtime file access or server route).
+ *
+ * Surfaces:
+ *   - <ChangelogDialog>      a self-contained modal listing every release.
+ *   - <ChangelogSettingsCard> a settings-page card with the latest updates.
+ *   - useChangelogSeen()     tracks the last release a user has seen (so the
+ *                            command menu can show an "unseen" dot).
+ *
+ * The command menu's built-in `changelog` prop (see CommandMenu.tsx) wires the
+ * dialog automatically — most templates never touch these directly.
+ */
+
+import React, { useEffect, useMemo, useState } from "react";
+import { IconX, IconHistory } from "@tabler/icons-react";
+
+import { parseChangelog, type ChangelogEntry } from "../../changelog/parse.js";
+import {
+  markdownModule,
+  remarkGfmFn,
+  useMarkdownReady,
+  markdownUrlTransform,
+} from "../chat/markdown-renderer.js";
+import { cn } from "../utils.js";
+
+// ─── Date formatting ──────────────────────────────────────────────────────────
+
+function formatEntryHeading(entry: ChangelogEntry): string {
+  if (entry.date) {
+    // Parse as a plain calendar date (avoid TZ shifting YYYY-MM-DD back a day).
+    const [y, m, d] = entry.date.split("-").map(Number);
+    if (y && m && d) {
+      const formatted = new Date(y, m - 1, d).toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      });
+      return entry.version ? `${entry.version} · ${formatted}` : formatted;
+    }
+  }
+  return entry.title;
+}
+
+// ─── Markdown body ────────────────────────────────────────────────────────────
+// A small, self-contained renderer for a release body. Avoids depending on the
+// typography plugin (`prose`) being generated in the host template by applying
+// explicit utility classes that Tailwind scans from core's compiled output.
+
+const changelogMarkdownComponents = {
+  h3: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <h3
+      {...props}
+      className="mb-1.5 mt-3 text-xs font-semibold uppercase tracking-wide text-muted-foreground first:mt-0"
+    />
+  ),
+  ul: (props: React.HTMLAttributes<HTMLUListElement>) => (
+    <ul
+      {...props}
+      className="mb-2 ml-1 list-disc space-y-1 pl-4 text-sm text-foreground marker:text-muted-foreground"
+    />
+  ),
+  ol: (props: React.HTMLAttributes<HTMLOListElement>) => (
+    <ol
+      {...props}
+      className="mb-2 ml-1 list-decimal space-y-1 pl-4 text-sm text-foreground marker:text-muted-foreground"
+    />
+  ),
+  li: (props: React.HTMLAttributes<HTMLLIElement>) => (
+    <li {...props} className="leading-relaxed" />
+  ),
+  p: (props: React.HTMLAttributes<HTMLParagraphElement>) => (
+    <p {...props} className="mb-2 text-sm leading-relaxed text-foreground" />
+  ),
+  a: (props: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a
+      {...props}
+      target="_blank"
+      rel="noreferrer"
+      className="font-medium underline underline-offset-2"
+    />
+  ),
+  code: (props: React.HTMLAttributes<HTMLElement>) => (
+    <code
+      {...props}
+      className="rounded bg-muted px-1 py-0.5 font-mono text-[0.85em]"
+    />
+  ),
+};
+
+function ChangelogBody({ markdown }: { markdown: string }) {
+  const ready = useMarkdownReady();
+  const ReactMarkdown = markdownModule?.default;
+  const gfm = remarkGfmFn;
+
+  if (!ready || !ReactMarkdown || !gfm) {
+    // The react-markdown chunk loads on module eval; this is typically only one
+    // frame. Show readable plain text rather than nothing in the meantime.
+    return (
+      <div className="whitespace-pre-wrap text-sm text-foreground">
+        {markdown}
+      </div>
+    );
+  }
+  return (
+    <ReactMarkdown
+      remarkPlugins={[gfm]}
+      components={changelogMarkdownComponents}
+      urlTransform={markdownUrlTransform}
+    >
+      {markdown}
+    </ReactMarkdown>
+  );
+}
+
+// ─── Unseen tracking ──────────────────────────────────────────────────────────
+
+function seenStorageKey(appKey: string): string {
+  return `an:changelog-seen:${appKey}`;
+}
+
+/**
+ * Tracks the latest release a user has already seen (per browser, via
+ * localStorage). Returns whether there's an unseen release and a `markSeen`
+ * callback to clear the indicator once the changelog is opened.
+ */
+export function useChangelogSeen(
+  appKey: string,
+  latestId: string | undefined,
+): { unseen: boolean; markSeen: () => void } {
+  const [seenId, setSeenId] = useState<string | null>(null);
+  const [hydrated, setHydrated] = useState(false);
+
+  useEffect(() => {
+    try {
+      setSeenId(window.localStorage.getItem(seenStorageKey(appKey)));
+    } catch {
+      // Private mode / disabled storage — treat as "nothing seen yet".
+    }
+    setHydrated(true);
+  }, [appKey]);
+
+  const markSeen = React.useCallback(() => {
+    if (!latestId) return;
+    setSeenId(latestId);
+    try {
+      window.localStorage.setItem(seenStorageKey(appKey), latestId);
+    } catch {
+      // Ignore storage failures; the dot just won't persist.
+    }
+  }, [appKey, latestId]);
+
+  // Don't flag "unseen" until hydrated, and never on a first-ever visit (no
+  // stored value) — only once the user has seen *something* and a newer
+  // release appears. This avoids nagging brand-new users.
+  const unseen =
+    hydrated && !!latestId && seenId !== null && seenId !== latestId;
+
+  return { unseen, markSeen };
+}
+
+// ─── Shared markup ────────────────────────────────────────────────────────────
+
+function ChangelogEntries({
+  entries,
+  emptyText,
+}: {
+  entries: ChangelogEntry[];
+  emptyText: string;
+}) {
+  if (entries.length === 0) {
+    return <p className="text-sm text-muted-foreground">{emptyText}</p>;
+  }
+  return (
+    <div className="space-y-6">
+      {entries.map((entry) => (
+        <section key={entry.id}>
+          <h4 className="mb-2 text-sm font-semibold text-foreground">
+            {formatEntryHeading(entry)}
+          </h4>
+          <ChangelogBody markdown={entry.body} />
+        </section>
+      ))}
+    </div>
+  );
+}
+
+// ─── Dialog ───────────────────────────────────────────────────────────────────
+
+export interface ChangelogDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Raw CHANGELOG.md contents (e.g. `import md from "../CHANGELOG.md?raw"`). */
+  markdown: string;
+  /** Dialog heading. Default: "What's new". */
+  title?: string;
+}
+
+export function ChangelogDialog({
+  open,
+  onOpenChange,
+  markdown,
+  title = "What's new",
+}: ChangelogDialogProps) {
+  const entries = useMemo(() => parseChangelog(markdown), [markdown]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onOpenChange(false);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onOpenChange]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 p-4"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onOpenChange(false);
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        className="mt-[8vh] flex max-h-[80vh] w-full max-w-xl flex-col rounded-lg border border-border bg-popover text-popover-foreground shadow-lg"
+      >
+        <div className="flex items-center justify-between border-b border-border px-5 py-3.5">
+          <div className="flex items-center gap-2">
+            <IconHistory className="h-4 w-4 text-muted-foreground" />
+            <h3 className="text-sm font-semibold">{title}</h3>
+          </div>
+          <button
+            type="button"
+            onClick={() => onOpenChange(false)}
+            aria-label="Close"
+            className="rounded-sm p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          >
+            <IconX className="h-4 w-4" />
+          </button>
+        </div>
+        <div className="overflow-y-auto px-5 py-4">
+          <ChangelogEntries
+            entries={entries}
+            emptyText="No updates have been published yet."
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ─── Settings card ────────────────────────────────────────────────────────────
+
+export interface ChangelogSettingsCardProps {
+  /** Raw CHANGELOG.md contents (e.g. `import md from "../CHANGELOG.md?raw"`). */
+  markdown: string;
+  /** How many recent releases to show inline before "View all". Default: 2. */
+  limit?: number;
+  /** Card heading. Default: "What's new". */
+  title?: string;
+  className?: string;
+}
+
+export function ChangelogSettingsCard({
+  markdown,
+  limit = 2,
+  title = "What's new",
+  className,
+}: ChangelogSettingsCardProps) {
+  const entries = useMemo(() => parseChangelog(markdown), [markdown]);
+  const [dialogOpen, setDialogOpen] = useState(false);
+
+  if (entries.length === 0) return null;
+
+  const shown = entries.slice(0, limit);
+  const hasMore = entries.length > shown.length;
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border bg-card text-card-foreground",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 border-b border-border px-5 py-4">
+        <IconHistory className="h-4 w-4 text-muted-foreground" />
+        <h3 className="text-sm font-semibold">{title}</h3>
+      </div>
+      <div className="px-5 py-4">
+        <ChangelogEntries entries={shown} emptyText="No updates yet." />
+        {hasMore && (
+          <button
+            type="button"
+            onClick={() => setDialogOpen(true)}
+            className="mt-4 text-sm font-medium text-foreground underline underline-offset-2"
+          >
+            View all updates
+          </button>
+        )}
+      </div>
+      <ChangelogDialog
+        open={dialogOpen}
+        onOpenChange={setDialogOpen}
+        markdown={markdown}
+        title={title}
+      />
+    </div>
+  );
+}
+
+export { parseChangelog };
+export type { ChangelogEntry };

package/corpus/core/src/client/index.ts

@@ -643,10 +643,12 @@ export {
   trackEvent,
   trackSessionStatus,
   configureTracking,
+  getFirstTouchAttribution,
   setSentryUser,
   captureError,
   captureClientException,
   type ClientCaptureContext,
+  type FirstTouchAttribution,
 } from "./analytics.js";
 export { track } from "./track.js";
 export {
@@ -713,6 +715,15 @@ export {
   type CommandItemProps,
   type CommandShortcutProps,
 } from "./CommandMenu.js";
+export {
+  ChangelogDialog,
+  ChangelogSettingsCard,
+  useChangelogSeen,
+  parseChangelog,
+  type ChangelogDialogProps,
+  type ChangelogSettingsCardProps,
+  type ChangelogEntry,
+} from "./changelog/Changelog.js";
 export {
   DevOverlay,
   useDevOverlayShortcut,

package/corpus/core/src/client/mcp-apps/McpAppRenderer.tsx

@@ -13,6 +13,7 @@ import { agentNativePath } from "../api-path.js";
 import { cn } from "../utils.js";
 
 export const DEFAULT_MCP_APP_IFRAME_HEIGHT = 650;
+export const MCP_APP_INITIALIZE_TIMEOUT_MS = 8000;
 const MIN_IFRAME_HEIGHT = 220;
 const VIEWPORT_MARGIN = 16;
 const SANDBOX_FLAGS = "allow-scripts allow-forms allow-popups";
@@ -46,6 +47,7 @@ export function McpAppRenderer({ app, className }: McpAppRendererProps) {
     () => (resourceHtml ? injectCsp(resourceHtml, csp) : ""),
     [resourceHtml, csp],
   );
+  const externalOpenUrl = useMemo(() => openUrlFromMcpApp(app), [app]);
 
   useEffect(() => {
     desiredHeightRef.current = DEFAULT_MCP_APP_IFRAME_HEIGHT;
@@ -115,6 +117,11 @@ export function McpAppRenderer({ app, className }: McpAppRendererProps) {
     if (!iframe?.contentWindow || !srcDoc || loadedSrcDoc !== srcDoc) return;
 
     let closed = false;
+    const initializeTimer = window.setTimeout(() => {
+      if (closed) return;
+      setReady(false);
+      setError("MCP App did not finish initializing.");
+    }, MCP_APP_INITIALIZE_TIMEOUT_MS);
     const bridge = new AppBridge(
       null,
       { name: "Agent Native", version: "1.0.0" },
@@ -144,7 +151,11 @@ export function McpAppRenderer({ app, className }: McpAppRendererProps) {
     });
     bridge.addEventListener("initialized", () => {
       if (closed) return;
+      clearTimeout(initializeTimer);
       setReady(true);
+      // Clear any error the initialize timeout may have set before a slow app
+      // finished — otherwise the error overlay stays stuck over a working app.
+      setError(null);
       void bridge.sendToolInput({ arguments: app.toolInput });
       void bridge.sendToolResult(app.toolResult as CallToolResult);
     });
@@ -194,12 +205,14 @@ export function McpAppRenderer({ app, className }: McpAppRendererProps) {
     setError(null);
     bridge.connect(transport).catch((err: any) => {
       if (!closed) {
+        clearTimeout(initializeTimer);
         setError(err?.message ?? "Failed to initialize MCP App.");
       }
     });
 
     return () => {
       closed = true;
+      clearTimeout(initializeTimer);
       setReady(false);
       void bridge
         .teardownResource({}, { timeout: 500 })
@@ -244,6 +257,17 @@ export function McpAppRenderer({ app, className }: McpAppRendererProps) {
         <div className="agent-mcp-app__error">
           <IconAlertTriangle size={15} />
           <span>{error}</span>
+          {externalOpenUrl && (
+            <button
+              type="button"
+              className="agent-mcp-app__open"
+              onClick={() =>
+                window.open(externalOpenUrl, "_blank", "noopener,noreferrer")
+              }
+            >
+              Open in new tab
+            </button>
+          )}
         </div>
       )}
       <iframe
@@ -281,6 +305,36 @@ function htmlFromResource(
   }
 }
 
+function recordValue(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function openUrlRecordValue(value: unknown): string | null {
+  const record = recordValue(value);
+  const webUrl = record?.webUrl;
+  return typeof webUrl === "string" && isSafeExternalUrl(webUrl)
+    ? webUrl
+    : null;
+}
+
+function openUrlFromMcpApp(app: AgentMcpAppPayload): string | null {
+  const result = recordValue(app.toolResult);
+  const meta = recordValue(result?._meta);
+  const fromMeta = openUrlRecordValue(meta?.["agent-native/openLink"]);
+  if (fromMeta) return fromMeta;
+
+  const structuredContent = recordValue(result?.structuredContent);
+  const fromStructured = openUrlRecordValue(structuredContent?.openLink);
+  if (fromStructured) return fromStructured;
+
+  const directUrl = structuredContent?.url ?? result?.url;
+  return typeof directUrl === "string" && isSafeExternalUrl(directUrl)
+    ? directUrl
+    : null;
+}
+
 export function supportedMcpAppPermissions(
   permissions: McpUiResourcePermissions | undefined,
 ): McpUiResourcePermissions {