@shortlink-org/portolan 0.1.0 → 0.2.0

package/src/chat/Conversation.tsx

@@ -7,12 +7,12 @@
 
 import { useEffect, useMemo, useRef } from "react";
 import type { MouseEvent as ReactMouseEvent } from "react";
-import { useNavigate } from "react-router";
+import { useLocation, useNavigate } from "react-router";
 import { Chat, useChat } from "@ai-sdk/react";
 import { getToolName, isToolUIPart } from "ai";
 import type { ChatStatus, UIMessage } from "ai";
 import { Markdown } from "../components/Markdown";
-import { catalog } from "../data";
+import { activeCatalogProfile, catalog } from "../data";
 import { paletteItems } from "../lib/palette";
 import { ToolCard, toolOutput } from "./Cards";
 import { Composer } from "./Composer";
@@ -30,10 +30,12 @@ import type { Read } from "./Steps";
 import { useChatUi } from "./store";
 import { transportFor } from "./transport";
 import { Sprite } from "./Waiting";
+import { pageContext } from "./page-context";
 
 export type Answering = Extract<ChatRoute, { kind: "proxy" | "own" }>;
 
 const base = import.meta.env.BASE_URL;
+const stayHere = () => {};
 
 /** Every id the catalog has a page for, and the page. */
 const LINKS: ReadonlyMap<string, string> = (() => {
@@ -91,7 +93,8 @@ function waitingLabel(
   if (!last || last.role !== "assistant") return "thinking…";
   const part = last.parts[last.parts.length - 1];
   if (!part) return "thinking…";
-  if (part.type === "text") return part.state === "streaming" ? null : "thinking…";
+  if (part.type === "text")
+    return part.state === "streaming" ? null : "thinking…";
   if (isToolUIPart(part) && getToolName(part) === "read_page") {
     if (part.state === "input-streaming" || part.state === "input-available") {
       return `reading ${pathOf(part.input) ?? "a page"}`;
@@ -138,7 +141,12 @@ function Answer({
         }
         if (isDisplayTool(name) && part.state !== "input-streaming") {
           return (
-            <ToolCard key={index} name={name} input={part.input} onNavigate={onNavigate} />
+            <ToolCard
+              key={index}
+              name={name}
+              input={part.input}
+              onNavigate={onNavigate}
+            />
           );
         }
         return null;
@@ -147,16 +155,41 @@ function Answer({
   );
 }
 
+function SeededExchange({ onNavigate }: { onNavigate: () => void }) {
+  return (
+    <>
+      <Message role="user">Show the “Checkout” flow.</Message>
+      <Message role="assistant" foot="grounded in flows/cart-checkout.md">
+        <ReadSteps reads={[{ path: "flows/cart-checkout.md" }]} />
+        <p className="leading-6 text-muted">
+          <span className="font-medium text-ink">shop.cart</span> validates the
+          session with auth.auth, loads the basket, requests its total from
+          shop.pricing, saves it, then publishes BasketCheckedOut.
+        </p>
+        <ToolCard
+          name="show_flow"
+          input={{ id: "flow.cart-checkout" }}
+          onNavigate={onNavigate}
+        />
+      </Message>
+    </>
+  );
+}
+
 export function Conversation({
   route,
   onOwnKey,
   onSettings,
   onClose,
+  seeded = false,
 }: {
   route: Answering;
   onOwnKey: () => void;
   onSettings: () => void;
-  onClose: () => void;
+  /** Omitted when the conversation is embedded in a page. */
+  onClose?: () => void;
+  /** Show one useful, catalog-grounded exchange before the reader asks. */
+  seeded?: boolean;
 }) {
   const chat = useMemo(() => chatFor(route), [route]);
   const {
@@ -173,6 +206,8 @@ export function Conversation({
   const phase = useChatUi((s) => s.phase);
   const took = useChatUi((s) => s.took);
   const navigate = useNavigate();
+  const location = useLocation();
+  const page = useMemo(() => pageContext(location.pathname), [location.pathname]);
   const list = useRef<HTMLDivElement>(null);
   const busy = status === "submitted" || status === "streaming";
   const waiting = waitingLabel(messages, status, phase);
@@ -205,7 +240,15 @@ export function Conversation({
   const send = (question: string) => {
     if (busy) return;
     useChatUi.getState().setAskedAt(Date.now());
-    void sendMessage({ text: question });
+    void sendMessage(
+      { text: question },
+      {
+        body: {
+          catalogId: activeCatalogProfile.id,
+          ...(page ? { pageContext: page } : {}),
+        },
+      },
+    );
   };
 
   // Links in an answer point into the app; follow them without a reload, and
@@ -218,16 +261,19 @@ export function Conversation({
     if (!href.startsWith(base) || /^[a-z]+:/i.test(href)) return;
     event.preventDefault();
     navigate(`/${href.slice(base.length)}`);
-    onClose();
+    onClose?.();
   };
 
   return (
     <>
       <Header
         route={route}
+        page={page}
         onSettings={onSettings}
-        onClose={onClose}
-        {...(messages.length > 0 && !busy ? { onClear: () => setMessages([]) } : {})}
+        {...(onClose ? { onClose } : {})}
+        {...(messages.length > 0 && !busy
+          ? { onClear: () => setMessages([]) }
+          : {})}
       />
       <div
         ref={list}
@@ -236,19 +282,27 @@ export function Conversation({
         aria-live="polite"
         className="min-h-0 flex-1 space-y-5 overflow-y-auto px-4 py-4"
       >
-        {messages.length === 0 ? <Starter onAsk={send} /> : null}
+        {seeded ? (
+          <SeededExchange onNavigate={onClose ?? stayHere} />
+        ) : messages.length === 0 ? (
+          <Starter onAsk={send} page={page} />
+        ) : null}
         {messages.map((message) =>
           message.role === "user" ? (
             <Message key={message.id} role="user">
-              {message.parts.map((part) => (part.type === "text" ? part.text : "")).join("")}
+              {message.parts
+                .map((part) => (part.type === "text" ? part.text : ""))
+                .join("")}
             </Message>
           ) : message.role === "assistant" ? (
             <Message
               key={message.id}
               role="assistant"
-              {...(took[message.id] !== undefined ? { foot: `took ${took[message.id]}s` } : {})}
+              {...(took[message.id] !== undefined
+                ? { foot: `took ${took[message.id]}s` }
+                : {})}
             >
-              <Answer message={message} onNavigate={onClose} />
+              <Answer message={message} onNavigate={onClose ?? stayHere} />
             </Message>
           ) : null,
         )}
@@ -268,14 +322,24 @@ export function Conversation({
               onRetry={() => {
                 clearError();
                 useChatUi.getState().setAskedAt(Date.now());
-                void regenerate();
+                void regenerate({
+                  body: {
+                    catalogId: activeCatalogProfile.id,
+                    ...(page ? { pageContext: page } : {}),
+                  },
+                });
               }}
               onOwnKey={onOwnKey}
             />
           </div>
         ) : null}
       </div>
-      <Composer busy={busy} onSend={send} onStop={() => void stop()} />
+      <Composer
+        busy={busy}
+        onSend={send}
+        onStop={() => void stop()}
+        focusOnMount={!seeded}
+      />
     </>
   );
 }

package/src/chat/Header.tsx

@@ -3,6 +3,7 @@
 import { Eraser, MessageSquare, Settings2, X } from "lucide-react";
 import { routeLabel } from "./flags";
 import type { ChatRoute } from "./flags";
+import type { ChatPageContext } from "./page-context";
 
 const ICON =
   "flex size-8 items-center justify-center rounded-control text-muted t-micro transition-colors hover:bg-surface hover:text-ink";
@@ -12,34 +13,67 @@ export function Header({
   onSettings,
   onClear,
   onClose,
+  page,
 }: {
   route: ChatRoute;
+  page?: ChatPageContext | null;
   onSettings: () => void;
   /** Present once there is a conversation to start over from. */
   onClear?: () => void;
-  onClose: () => void;
+  /** Omitted when the conversation is embedded in a page. */
+  onClose?: () => void;
 }) {
   return (
     <div className="flex items-center gap-2.5 border-b border-line px-4 py-2.5">
       <MessageSquare size={16} aria-hidden className="shrink-0 text-accent" />
       <div className="min-w-0">
-        <div className="font-semibold leading-tight text-ink">ask the catalog</div>
-        <div className="mono truncate text-muted">
-          {routeLabel(route) || "nothing set to answer"}
+        <div className="font-semibold leading-tight text-ink">
+          ask the catalog
+        </div>
+        <div className="mono flex min-w-0 items-center gap-1.5 truncate text-muted">
+          <span className="truncate">{routeLabel(route) || "nothing set to answer"}</span>
+          {page ? (
+            <>
+              <span aria-hidden className="text-faint">·</span>
+              <span className="truncate text-ink" title={`${page.kind} ${page.id}`}>
+                {page.kind} · {page.title}
+              </span>
+            </>
+          ) : null}
         </div>
       </div>
       <div className="ml-auto flex shrink-0 items-center">
         {onClear ? (
-          <button type="button" onClick={onClear} aria-label="New conversation" title="New conversation" className={ICON}>
+          <button
+            type="button"
+            onClick={onClear}
+            aria-label="New conversation"
+            title="New conversation"
+            className={ICON}
+          >
             <Eraser size={15} aria-hidden />
           </button>
         ) : null}
-        <button type="button" onClick={onSettings} aria-label="Model settings" title="Model settings" className={ICON}>
+        <button
+          type="button"
+          onClick={onSettings}
+          aria-label="Model settings"
+          title="Model settings"
+          className={ICON}
+        >
           <Settings2 size={15} aria-hidden />
         </button>
-        <button type="button" onClick={onClose} aria-label="Close" title="Close — Esc" className={ICON}>
-          <X size={15} aria-hidden />
-        </button>
+        {onClose ? (
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            title="Close — Esc"
+            className={ICON}
+          >
+            <X size={15} aria-hidden />
+          </button>
+        ) : null}
       </div>
     </div>
   );

package/src/chat/Starter.tsx

@@ -6,7 +6,9 @@
 
 import { KindIcon } from "../components/kind";
 import type { Kind } from "../lib/kinds";
-import { catalog } from "../data";
+import { activeCatalogProfile, catalog } from "../data";
+import type { ChatPageContext } from "./page-context";
+import { contextQuestions } from "./page-context";
 
 interface Example {
   kind: Kind;
@@ -34,7 +36,26 @@ function examples(): Example[] {
   return out;
 }
 
-export function Starter({ onAsk }: { onAsk: (question: string) => void }) {
+const base = import.meta.env.BASE_URL;
+
+export function Starter({
+  onAsk,
+  page,
+}: {
+  onAsk: (question: string) => void;
+  page?: ChatPageContext | null;
+}) {
+  const choices: Example[] = page
+    ? contextQuestions(page).map((question) => ({
+        kind: page.kind,
+        question,
+      }))
+    : examples();
+  const profileSuffix =
+    activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
+  const docsRoot = `${base}docs/${profileSuffix}`;
+  const indexHref = profileSuffix ? `${docsRoot}llms.txt` : `${base}llms.txt`;
+
   return (
     <div className="pt-1">
       <p className="text-muted">
@@ -42,9 +63,49 @@ export function Starter({ onAsk }: { onAsk: (question: string) => void }) {
         link. Ask about a service, a flow, a decision, or what stands between two
         contexts.
       </p>
+      {page ? (
+        <div className="mt-4 rounded-card border border-line bg-surface px-3 py-2.5 shadow-xs">
+          <div className="flex min-w-0 items-start gap-2.5">
+            <KindIcon
+              kind={page.kind}
+              size={16}
+              className="mt-0.5 shrink-0"
+            />
+            <div className="min-w-0 flex-1">
+              <div className="label">current page</div>
+              <div className="mt-0.5 truncate font-medium text-ink" title={page.title}>
+                {page.title}
+              </div>
+              <div className="mono truncate text-muted" title={page.id}>{page.id}</div>
+            </div>
+          </div>
+          <div className="mono mt-2.5 flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-line pt-2 text-muted">
+            <span className="text-faint">model context</span>
+            <a
+              href={indexHref}
+              target="_blank"
+              rel="noreferrer"
+              className="rounded-control text-accent hover:underline"
+            >
+              llms.txt
+            </a>
+            {page.docPath ? (
+              <a
+                href={`${docsRoot}${page.docPath}`}
+                target="_blank"
+                rel="noreferrer"
+                className="max-w-full truncate rounded-control text-accent hover:underline"
+                title={page.docPath}
+              >
+                current catalog page
+              </a>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
       <div className="label mt-5 mb-1">try one</div>
       <ul className="-mx-1">
-        {examples().map((example) => (
+        {choices.map((example) => (
           <li key={example.question}>
             <button
               type="button"

package/src/chat/Steps.tsx

@@ -24,7 +24,7 @@ export function ReadSteps({ reads }: { reads: Read[] }) {
           className="transition-transform group-open:rotate-90"
         />
         <FileText size={13} aria-hidden />
-        read {reads.length} {reads.length === 1 ? "page" : "pages"}
+        sources · {reads.length} {reads.length === 1 ? "page" : "pages"}
       </summary>
       <ul className="mono mt-1 space-y-0.5 pl-6">
         {reads.map((read, index) => (

package/src/chat/flags.test.ts

@@ -2,18 +2,32 @@ import { describe, expect, it } from "vitest";
 import { chatRoute, ownReady, parsePrefs, routeLabel } from "./flags";
 import type { ChatBuild, OwnModel } from "./flags";
 
-const withProxy: ChatBuild = { built: true, proxyUrl: "https://x.workers.dev/chat" };
+const withProxy: ChatBuild = {
+  built: true,
+  proxyUrl: "https://x.workers.dev/chat",
+};
 const noProxy: ChatBuild = { built: true, proxyUrl: "" };
-const notBuilt: ChatBuild = { built: false, proxyUrl: "https://x.workers.dev/chat" };
-const own: OwnModel = { baseUrl: "https://api.groq.com/openai/v1", apiKey: "k", model: "llama" };
+const notBuilt: ChatBuild = {
+  built: false,
+  proxyUrl: "https://x.workers.dev/chat",
+};
+const own: OwnModel = {
+  baseUrl: "https://api.groq.com/openai/v1",
+  apiKey: "k",
+  model: "llama",
+};
 
 describe("chatRoute", () => {
   it("is off when the build has no chat, whatever the reader set", () => {
-    expect(chatRoute(notBuilt, { enabled: true, own })).toEqual({ kind: "off" });
+    expect(chatRoute(notBuilt, { enabled: true, own })).toEqual({
+      kind: "off",
+    });
   });
 
   it("is off when the reader switched it off, even with a proxy and a key", () => {
-    expect(chatRoute(withProxy, { enabled: false, own })).toEqual({ kind: "off" });
+    expect(chatRoute(withProxy, { enabled: false, own })).toEqual({
+      kind: "off",
+    });
   });
 
   it("uses the proxy by default when the build has one", () => {
@@ -24,25 +38,43 @@ describe("chatRoute", () => {
   });
 
   it("prefers the reader's own model over the proxy", () => {
-    expect(chatRoute(withProxy, { enabled: null, own })).toEqual({ kind: "own", model: own });
+    expect(chatRoute(withProxy, { enabled: null, own })).toEqual({
+      kind: "own",
+      model: own,
+    });
   });
 
   it("stays off without a proxy until switched on, then asks to be configured", () => {
-    expect(chatRoute(noProxy, { enabled: null, own: null })).toEqual({ kind: "off" });
-    expect(chatRoute(noProxy, { enabled: true, own: null })).toEqual({ kind: "unconfigured" });
+    expect(chatRoute(noProxy, { enabled: null, own: null })).toEqual({
+      kind: "off",
+    });
+    expect(chatRoute(noProxy, { enabled: true, own: null })).toEqual({
+      kind: "unconfigured",
+    });
   });
 
   it("does not count a half-filled model as one", () => {
     expect(ownReady({ baseUrl: "", apiKey: "k", model: "m" })).toBe(false);
-    expect(ownReady({ baseUrl: "https://a", apiKey: "", model: "m" })).toBe(true);
-    expect(chatRoute(noProxy, { enabled: true, own: { baseUrl: "https://a", apiKey: "", model: " " } })).toEqual({ kind: "unconfigured" });
+    expect(ownReady({ baseUrl: "https://a", apiKey: "", model: "m" })).toBe(
+      true,
+    );
+    expect(
+      chatRoute(noProxy, {
+        enabled: true,
+        own: { baseUrl: "https://a", apiKey: "", model: " " },
+      }),
+    ).toEqual({ kind: "unconfigured" });
   });
 });
 
 describe("routeLabel", () => {
   it("names the model and the host, or the proxy", () => {
-    expect(routeLabel({ kind: "own", model: own })).toBe("llama · api.groq.com");
-    expect(routeLabel({ kind: "proxy", url: "u" })).toBe("demo proxy");
+    expect(routeLabel({ kind: "own", model: own })).toBe(
+      "llama · api.groq.com",
+    );
+    expect(routeLabel({ kind: "proxy", url: "u" })).toBe(
+      "default model · demo proxy",
+    );
     expect(routeLabel({ kind: "off" })).toBe("");
   });
 });
@@ -50,8 +82,13 @@ describe("routeLabel", () => {
 describe("parsePrefs", () => {
   it("reads the switch and the model, and shrugs at junk", () => {
     expect(parsePrefs("on", null)).toEqual({ enabled: true, own: null });
-    expect(parsePrefs("off", "{bad json")).toEqual({ enabled: false, own: null });
-    expect(parsePrefs(null, JSON.stringify({ baseUrl: "https://a", model: "m" }))).toEqual({
+    expect(parsePrefs("off", "{bad json")).toEqual({
+      enabled: false,
+      own: null,
+    });
+    expect(
+      parsePrefs(null, JSON.stringify({ baseUrl: "https://a", model: "m" })),
+    ).toEqual({
       enabled: null,
       own: { baseUrl: "https://a", apiKey: "", model: "m" },
     });

package/src/chat/flags.ts

@@ -39,7 +39,13 @@ export type ChatRoute =
 
 export const BUILD: ChatBuild = {
   built: import.meta.env.VITE_CHAT !== "off",
-  proxyUrl: (import.meta.env.VITE_CHAT_PROXY_URL ?? "").trim(),
+  // The public build receives the worker URL from CI. In development Vite
+  // exposes the same worker through a same-origin proxy, so the real demo chat
+  // works on any local port without weakening the worker's CORS allowlist.
+  proxyUrl: (
+    import.meta.env.VITE_CHAT_PROXY_URL ??
+    (import.meta.env.DEV ? "/api/portolan-chat" : "")
+  ).trim(),
 };
 
 const OFF: ChatRoute = { kind: "off" };
@@ -66,7 +72,7 @@ export function chatRoute(build: ChatBuild, prefs: ChatPrefs): ChatRoute {
 export function routeLabel(route: ChatRoute): string {
   switch (route.kind) {
     case "proxy":
-      return "demo proxy";
+      return "default model · demo proxy";
     case "own": {
       let host = route.model.baseUrl;
       try {

package/src/chat/page-context.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import type { PaletteItem } from "../lib/palette";
+import { contextQuestions, pageContextFrom } from "./page-context";
+
+const flow: PaletteItem = {
+  kind: "flow",
+  id: "flow.cart-checkout",
+  name: "cart-checkout",
+  detail: "Checkout",
+  path: "/flows/cart-checkout",
+  context: null,
+};
+
+const service: PaletteItem = {
+  kind: "service",
+  id: "shop.cart",
+  name: "cart",
+  detail: "shop.cart",
+  path: "/c/shop/cart",
+  context: "shop",
+};
+
+describe("pageContextFrom", () => {
+  it("turns the exact entity route into model context", () => {
+    expect(pageContextFrom([flow], "/flows/cart-checkout")).toEqual({
+      kind: "flow",
+      id: "flow.cart-checkout",
+      title: "Checkout",
+      docPath: "flows/cart-checkout.md",
+    });
+  });
+
+  it("does not mistake an index or nested route for the entity", () => {
+    expect(pageContextFrom([flow], "/flows")).toBeNull();
+    expect(pageContextFrom([flow], "/flows/cart-checkout/extra")).toBeNull();
+  });
+
+  it("points a service at the markdown path from llms.txt", () => {
+    expect(pageContextFrom([service], "/c/shop/cart")?.docPath).toBe(
+      "shop/cart/README.md",
+    );
+  });
+});
+
+describe("contextQuestions", () => {
+  it("keeps every flow starter anchored to the catalog id", () => {
+    const page = pageContextFrom([flow], "/flows/cart-checkout");
+    expect(page).not.toBeNull();
+    expect(contextQuestions(page!).every((question) => question.includes(flow.id))).toBe(true);
+  });
+});