@shortlink-org/portolan 0.1.0

package/src/chat/Composer.tsx

@@ -0,0 +1,99 @@
+// The question box.
+//
+// One line that grows to six, the send button inside the field where the
+// cursor already is, and stop in its place while an answer is coming. Enter
+// sends; a new line is shift-enter, said once under the field.
+
+import { useEffect, useRef, useState } from "react";
+import { ArrowUp, Square } from "lucide-react";
+
+const MAX_HEIGHT = 160;
+
+export function Composer({
+  busy,
+  onSend,
+  onStop,
+}: {
+  busy: boolean;
+  onSend: (question: string) => void;
+  onStop: () => void;
+}) {
+  const [draft, setDraft] = useState("");
+  const field = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    field.current?.focus();
+  }, []);
+
+  // Grow with the text, up to the limit; shrink back when it is deleted.
+  useEffect(() => {
+    const el = field.current;
+    if (!el) return;
+    el.style.height = "auto";
+    el.style.height = `${Math.min(el.scrollHeight, MAX_HEIGHT)}px`;
+  }, [draft]);
+
+  const send = () => {
+    const question = draft.trim();
+    if (!question || busy) return;
+    onSend(question);
+    setDraft("");
+  };
+
+  const BUTTON =
+    "absolute right-2 bottom-2 flex size-7 items-center justify-center rounded-control transition-colors";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        send();
+      }}
+      className="border-t border-line px-3 pt-3 pb-2"
+    >
+      <div className="relative">
+        <textarea
+          ref={field}
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && !event.shiftKey) {
+              event.preventDefault();
+              send();
+            }
+          }}
+          rows={1}
+          placeholder="ask about a service, a flow, a decision…"
+          aria-label="Your question"
+          className="block w-full resize-none rounded-card border border-line bg-canvas py-2.5 pr-11 pl-3 text-ink outline-none transition-colors focus:border-accent"
+          style={{ maxHeight: MAX_HEIGHT }}
+        />
+        {busy ? (
+          <button
+            type="button"
+            onClick={onStop}
+            aria-label="Stop the answer"
+            title="Stop"
+            className={`${BUTTON} border border-line text-ink hover:border-line-strong`}
+          >
+            <Square size={12} aria-hidden />
+          </button>
+        ) : (
+          <button
+            type="submit"
+            disabled={draft.trim() === ""}
+            aria-label="Ask"
+            title="Ask — ⏎"
+            className={`${BUTTON} bg-accent text-white hover:opacity-90 disabled:cursor-default disabled:opacity-30`}
+          >
+            <ArrowUp size={14} aria-hidden />
+          </button>
+        )}
+      </div>
+      <div className="mono mt-1.5 flex items-center gap-3 text-muted">
+        <span>⏎ send</span>
+        <span>⇧⏎ new line</span>
+      </div>
+    </form>
+  );
+}

package/src/chat/Conversation.tsx

@@ -0,0 +1,281 @@
+// The conversation: the SDK's messages, arranged.
+//
+// What is added to useChat here is the catalog - ids in an answer become
+// links, and a show_* call becomes a card drawn from the data the app
+// already holds - and the shape of the wait, which on a free tier is long
+// enough to need a shape.
+
+import { useEffect, useMemo, useRef } from "react";
+import type { MouseEvent as ReactMouseEvent } from "react";
+import { 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 { paletteItems } from "../lib/palette";
+import { ToolCard, toolOutput } from "./Cards";
+import { Composer } from "./Composer";
+import { routeLabel } from "./flags";
+import type { ChatRoute } from "./flags";
+import { Header } from "./Header";
+import { linkify } from "./linkify";
+import { Message } from "./Message";
+import { TroubleNotice, classify } from "./Notice";
+import { DISPLAY_TOOLS } from "./prompt";
+import type { ToolName } from "./prompt";
+import { Starter } from "./Starter";
+import { ReadSteps } from "./Steps";
+import type { Read } from "./Steps";
+import { useChatUi } from "./store";
+import { transportFor } from "./transport";
+import { Sprite } from "./Waiting";
+
+export type Answering = Extract<ChatRoute, { kind: "proxy" | "own" }>;
+
+const base = import.meta.env.BASE_URL;
+
+/** Every id the catalog has a page for, and the page. */
+const LINKS: ReadonlyMap<string, string> = (() => {
+  const links = new Map<string, string>();
+  for (const item of paletteItems(catalog)) {
+    if (item.path && !links.has(item.id))
+      links.set(item.id, `${base}${item.path.replace(/^\//, "")}`);
+  }
+  return links;
+})();
+
+/**
+ * One conversation per answerer, kept for the tab's lifetime: the panel is a
+ * dialog and unmounts when it closes, and a reader who closes it to look at a
+ * page should find their question still there when they come back.
+ */
+const chats = new Map<string, Chat<UIMessage>>();
+function chatFor(route: Answering): Chat<UIMessage> {
+  const key = JSON.stringify(route);
+  let chat = chats.get(key);
+  if (!chat) {
+    chat = new Chat<UIMessage>({
+      transport: transportFor(route),
+      onFinish: ({ message }) => {
+        const ui = useChatUi.getState();
+        if (ui.askedAt !== null) {
+          ui.noteTook(message.id, Math.round((Date.now() - ui.askedAt) / 1000));
+          ui.setAskedAt(null);
+        }
+      },
+    });
+    chats.set(key, chat);
+  }
+  return chat;
+}
+
+function isDisplayTool(name: string): name is ToolName {
+  return (DISPLAY_TOOLS as readonly string[]).includes(name);
+}
+
+function pathOf(input: unknown): string | null {
+  const path = (input as { path?: unknown } | undefined)?.path;
+  return typeof path === "string" ? path : null;
+}
+
+/** The line beside the moving boat, or null when the answer itself is arriving. */
+function waitingLabel(
+  messages: UIMessage[],
+  status: ChatStatus,
+  phase: "index" | null,
+): string | null {
+  if (status !== "submitted" && status !== "streaming") return null;
+  if (phase === "index") return "reading the catalog…";
+  const last = messages[messages.length - 1];
+  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 (isToolUIPart(part) && getToolName(part) === "read_page") {
+    if (part.state === "input-streaming" || part.state === "input-available") {
+      return `reading ${pathOf(part.input) ?? "a page"}`;
+    }
+  }
+  return "thinking…";
+}
+
+function Answer({
+  message,
+  onNavigate,
+}: {
+  message: UIMessage;
+  onNavigate: () => void;
+}) {
+  // The pages read, gathered into one line where the first of them was.
+  const reads: Read[] = [];
+  for (const part of message.parts) {
+    if (
+      isToolUIPart(part) &&
+      getToolName(part) === "read_page" &&
+      (part.state === "output-available" || part.state === "output-error")
+    ) {
+      const path = pathOf(part.input);
+      if (path) reads.push({ path });
+    }
+  }
+  let readsShown = false;
+
+  return (
+    <>
+      {message.parts.map((part, index) => {
+        if (part.type === "text") {
+          return part.text ? (
+            <Markdown key={index}>{linkify(part.text, LINKS)}</Markdown>
+          ) : null;
+        }
+        if (!isToolUIPart(part)) return null;
+        const name = getToolName(part);
+        if (name === "read_page") {
+          if (readsShown) return null;
+          readsShown = true;
+          return <ReadSteps key={index} reads={reads} />;
+        }
+        if (isDisplayTool(name) && part.state !== "input-streaming") {
+          return (
+            <ToolCard key={index} name={name} input={part.input} onNavigate={onNavigate} />
+          );
+        }
+        return null;
+      })}
+    </>
+  );
+}
+
+export function Conversation({
+  route,
+  onOwnKey,
+  onSettings,
+  onClose,
+}: {
+  route: Answering;
+  onOwnKey: () => void;
+  onSettings: () => void;
+  onClose: () => void;
+}) {
+  const chat = useMemo(() => chatFor(route), [route]);
+  const {
+    messages,
+    sendMessage,
+    status,
+    stop,
+    error,
+    setMessages,
+    addToolOutput,
+    regenerate,
+    clearError,
+  } = useChat({ chat });
+  const phase = useChatUi((s) => s.phase);
+  const took = useChatUi((s) => s.took);
+  const navigate = useNavigate();
+  const list = useRef<HTMLDivElement>(null);
+  const busy = status === "submitted" || status === "streaming";
+  const waiting = waitingLabel(messages, status, phase);
+
+  // A show_* call ends the answer; its "output" is a note for the record,
+  // written once the stream is over and never sent on its own. It reaches
+  // the model only with the reader's next question.
+  useEffect(() => {
+    if (busy) return;
+    for (const message of messages) {
+      if (message.role !== "assistant") continue;
+      for (const part of message.parts) {
+        if (!isToolUIPart(part) || part.state !== "input-available") continue;
+        const name = getToolName(part);
+        if (!isDisplayTool(name)) continue;
+        void addToolOutput({
+          tool: name,
+          toolCallId: part.toolCallId,
+          output: toolOutput(name, part.input),
+        });
+      }
+    }
+  }, [messages, busy, addToolOutput]);
+
+  useEffect(() => {
+    const node = list.current;
+    if (node) node.scrollTop = node.scrollHeight;
+  }, [messages, waiting, error]);
+
+  const send = (question: string) => {
+    if (busy) return;
+    useChatUi.getState().setAskedAt(Date.now());
+    void sendMessage({ text: question });
+  };
+
+  // Links in an answer point into the app; follow them without a reload, and
+  // get out of the way of the page they open.
+  const onClick = (event: ReactMouseEvent<HTMLDivElement>) => {
+    const anchor = (event.target as HTMLElement).closest("a");
+    if (!anchor || anchor.target === "_blank") return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey) return;
+    const href = anchor.getAttribute("href") ?? "";
+    if (!href.startsWith(base) || /^[a-z]+:/i.test(href)) return;
+    event.preventDefault();
+    navigate(`/${href.slice(base.length)}`);
+    onClose();
+  };
+
+  return (
+    <>
+      <Header
+        route={route}
+        onSettings={onSettings}
+        onClose={onClose}
+        {...(messages.length > 0 && !busy ? { onClear: () => setMessages([]) } : {})}
+      />
+      <div
+        ref={list}
+        onClick={onClick}
+        role="log"
+        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}
+        {messages.map((message) =>
+          message.role === "user" ? (
+            <Message key={message.id} role="user">
+              {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` } : {})}
+            >
+              <Answer message={message} onNavigate={onClose} />
+            </Message>
+          ) : null,
+        )}
+        {waiting ? (
+          <Message role="assistant" glyph={<Sprite className="text-accent" />}>
+            <span role="status" className="mono text-muted">
+              {waiting}
+            </span>
+          </Message>
+        ) : null}
+        {error && !busy ? (
+          <div className="pl-10">
+            <TroubleNotice
+              trouble={classify(error)}
+              demo={route.kind === "proxy"}
+              where={routeLabel(route)}
+              onRetry={() => {
+                clearError();
+                useChatUi.getState().setAskedAt(Date.now());
+                void regenerate();
+              }}
+              onOwnKey={onOwnKey}
+            />
+          </div>
+        ) : null}
+      </div>
+      <Composer busy={busy} onSend={send} onStop={() => void stop()} />
+    </>
+  );
+}

package/src/chat/Header.tsx

@@ -0,0 +1,46 @@
+// The panel's top line: what this is, who answers, and three controls.
+
+import { Eraser, MessageSquare, Settings2, X } from "lucide-react";
+import { routeLabel } from "./flags";
+import type { ChatRoute } from "./flags";
+
+const ICON =
+  "flex size-8 items-center justify-center rounded-control text-muted t-micro transition-colors hover:bg-surface hover:text-ink";
+
+export function Header({
+  route,
+  onSettings,
+  onClear,
+  onClose,
+}: {
+  route: ChatRoute;
+  onSettings: () => void;
+  /** Present once there is a conversation to start over from. */
+  onClear?: () => void;
+  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>
+      </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}>
+            <Eraser size={15} aria-hidden />
+          </button>
+        ) : null}
+        <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>
+      </div>
+    </div>
+  );
+}

package/src/chat/Message.tsx

@@ -0,0 +1,49 @@
+// One turn of the conversation, on a grid.
+//
+// A gutter for who is speaking, a column for what was said. The reader's
+// turn sits on a raised block; the answer sits on the page itself, because
+// it is the page's own words arranged, and a block around every paragraph
+// and card would be a box in a box.
+
+import type { ReactNode } from "react";
+import { User } from "lucide-react";
+import { Boat } from "./Waiting";
+
+export function Message({
+  role,
+  glyph,
+  children,
+  foot,
+}: {
+  role: "user" | "assistant";
+  /** Replaces the role's own mark; the waiting row puts the moving boat here. */
+  glyph?: ReactNode;
+  children: ReactNode;
+  /** A last line under the turn: how long it took. */
+  foot?: ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-[28px_minmax(0,1fr)] gap-x-3">
+      <div className="flex h-7 items-center justify-center">
+        {glyph ??
+          (role === "user" ? (
+            <span className="flex size-6 items-center justify-center rounded-full bg-raised text-muted">
+              <User size={13} aria-hidden />
+            </span>
+          ) : (
+            <Boat size={24} className="text-accent" />
+          ))}
+      </div>
+      <div className="min-w-0 pt-0.5">
+        {role === "user" ? (
+          <div className="whitespace-pre-wrap rounded-card bg-surface px-3 py-2 text-ink">
+            {children}
+          </div>
+        ) : (
+          <div className="space-y-3">{children}</div>
+        )}
+        {foot ? <div className="mono mt-1.5 text-muted">{foot}</div> : null}
+      </div>
+    </div>
+  );
+}

package/src/chat/Notice.tsx

@@ -0,0 +1,195 @@
+// What the panel says when it cannot answer.
+//
+// One box for every such moment - a limit reached, a busy model, a failed
+// request, nothing configured - so they line up the same way and the reader
+// learns one shape. The two the free tier produces most are told apart: a
+// limit passes with a minute or a key of the reader's own; a busy model
+// passes with a retry.
+
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import {
+  CloudOff,
+  Hourglass,
+  Info,
+  KeyRound,
+  RotateCcw,
+  TriangleAlert,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+export type Tone = "limit" | "busy" | "error" | "info";
+
+const ICON: Record<Tone, LucideIcon> = {
+  limit: Hourglass,
+  busy: CloudOff,
+  error: TriangleAlert,
+  info: Info,
+};
+
+const TONE: Record<Tone, string> = {
+  limit: "text-declared",
+  busy: "text-declared",
+  error: "text-unresolved",
+  info: "text-accent",
+};
+
+export function Notice({
+  tone,
+  title,
+  children,
+  actions,
+}: {
+  tone: Tone;
+  title: string;
+  children?: ReactNode;
+  actions?: ReactNode;
+}) {
+  const Icon = ICON[tone];
+  return (
+    <div className="rounded-card border border-line bg-surface px-3 py-3">
+      <div className="grid grid-cols-[20px_minmax(0,1fr)] gap-x-2">
+        <Icon size={16} aria-hidden className={`mt-0.5 ${TONE[tone]}`} />
+        <div className="min-w-0">
+          <div className="font-semibold text-ink">{title}</div>
+          {children ? <div className="mt-1 text-muted">{children}</div> : null}
+          {actions ? <div className="mt-3 flex flex-wrap gap-2">{actions}</div> : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const ACTION =
+  "mono flex items-center gap-1.5 rounded-control border px-2.5 py-1 transition-colors disabled:cursor-default disabled:opacity-60";
+export const ACTION_PLAIN = `${ACTION} border-line text-ink hover:border-line-strong`;
+export const ACTION_ACCENT = `${ACTION} border-accent text-accent hover:bg-raised`;
+
+export type Trouble =
+  | { kind: "limit"; text: string }
+  | { kind: "busy"; text: string }
+  | { kind: "other"; text: string };
+
+/** The status, when the error carries one, and the text either way. */
+export function classify(error: unknown): Trouble {
+  const text =
+    error instanceof Error ? error.message : String(error ?? "unknown error");
+  const status =
+    error && typeof error === "object" && "statusCode" in error
+      ? Number((error as { statusCode?: unknown }).statusCode)
+      : NaN;
+  if (
+    status === 429 ||
+    /\b429\b|quota|rate.?limit|resource_exhausted|too many requests/i.test(text)
+  ) {
+    return { kind: "limit", text };
+  }
+  if (
+    status === 503 ||
+    /\b503\b|unavailable|high demand|overloaded/i.test(text)
+  ) {
+    return { kind: "busy", text };
+  }
+  return { kind: "other", text };
+}
+
+const RETRY_AFTER = 60;
+
+/** The SDK's word for a request that never got a response. */
+const GENERIC = /^an error occurred\.?$|failed to fetch|networkerror|load failed/i;
+
+export function TroubleNotice({
+  trouble,
+  demo,
+  where,
+  onRetry,
+  onOwnKey,
+}: {
+  trouble: Trouble;
+  /** Answering through the proxy: the limit is the demo's, and a key of the reader's own is a way round it. */
+  demo: boolean;
+  /** Who was asked, for the message that says nobody answered. */
+  where: string;
+  onRetry: () => void;
+  onOwnKey: () => void;
+}) {
+  const limit = trouble.kind === "limit";
+  const [left, setLeft] = useState(limit ? RETRY_AFTER : 0);
+
+  useEffect(() => {
+    if (!limit) return;
+    setLeft(RETRY_AFTER);
+    const timer = setInterval(() => setLeft((n) => (n > 0 ? n - 1 : 0)), 1000);
+    return () => clearInterval(timer);
+  }, [limit, trouble]);
+
+  const said = (
+    <details className="mono mt-2">
+      <summary className="cursor-pointer select-none">what it said</summary>
+      <div className="mt-1 break-words">{trouble.text}</div>
+    </details>
+  );
+
+  const retry = (
+    <button
+      type="button"
+      onClick={onRetry}
+      disabled={left > 0}
+      className={ACTION_PLAIN}
+    >
+      <RotateCcw size={13} aria-hidden />
+      {left > 0 ? `try again in ${left}s` : "try again"}
+    </button>
+  );
+
+  if (trouble.kind === "other") {
+    const unreachable = GENERIC.test(trouble.text.trim());
+    return (
+      <Notice
+        tone="error"
+        title={unreachable ? "nobody answered" : "the question did not go through"}
+        actions={retry}
+      >
+        {unreachable ? (
+          <>
+            Nothing came back from <span className="mono">{where}</span>. Check
+            the endpoint, or that the network lets the browser reach it.
+          </>
+        ) : (
+          <span className="mono break-words">{trouble.text}</span>
+        )}
+      </Notice>
+    );
+  }
+
+  if (trouble.kind === "busy") {
+    return (
+      <Notice tone="busy" title="the model is busy" actions={retry}>
+        Google reports high demand on the model. That usually passes in a moment.
+        {said}
+      </Notice>
+    );
+  }
+
+  return (
+    <Notice
+      tone="limit"
+      title="the free tier is out of breath"
+      actions={
+        <>
+          {retry}
+          {demo ? (
+            <button type="button" onClick={onOwnKey} className={ACTION_ACCENT}>
+              <KeyRound size={13} aria-hidden /> use your own key
+            </button>
+          ) : null}
+        </>
+      }
+    >
+      {demo
+        ? "The demo answers ten questions a minute per reader, and Google gives it a daily quota shared by everyone. Both come back on their own."
+        : "Your provider says the limit is reached. It comes back on its own."}
+      {said}
+    </Notice>
+  );
+}