@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/companion-drawer.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+import { lazy, useId, useRef, useState, type RefObject } from "react";
+
+import type { PanelDock } from "../persistence/panel-mode.js";
+import { useAssistantAppearance } from "./appearance-context.js";
+import {
+  CompanionHeaderTitle,
+  CompanionHistoryMenu,
+} from "./companion-history-menu.js";
+import {
+  CompanionModeMenu,
+  CompanionModeTrigger,
+} from "./companion-mode-menu.js";
+import { ComposeIcon, MinimizeIcon } from "./icons.js";
+import { LazyBody } from "./lazy-body.js";
+import { TfButton } from "./primitives/button.js";
+import { TfFloatingPanel } from "./primitives/floating-panel.js";
+import { useAssistantConversation } from "./use-assistant-conversation.js";
+
+// The companion's corner chat drawer: the non-modal TfFloatingPanel with
+// a real header — the visible grabber (swipe-to-dismiss starts only on
+// the handle, and an invisible handle is no touch affordance at all), a
+// title, and the controls. On the left the title IS the history
+// disclosure: the active conversation's name with a chevron, dropping
+// open the same list the page's rail shows — where you are and where
+// you've been are one affordance. On the right, compose starts a fresh
+// conversation, and the close control is a minimize dash, not an X:
+// dismissing the drawer collapses it back into the perch — the
+// conversation and the companion both survive — and an X would promise a
+// destruction that never happens. The title sits at the muted label step
+// so the empty state's centered question stays the surface's only
+// headline; the panel's aria-label carries the accessible name
+// regardless.
+//
+// The body is code-split behind the first expand. React.lazy's dynamic
+// import is the mechanism: the minimized companion ships without the
+// transcript (or the chat chassis under it), and the host's bundler
+// splits the chunk without configuration.
+const CompanionDrawerBody = lazy(() => import("./companion-drawer-body.js"));
+
+export function CompanionDrawer({
+  open,
+  exiting,
+  focusOnOpen,
+  onOpenChange,
+  corner,
+  dock,
+  onDockChange,
+}: {
+  open: boolean;
+  /** The open is the visitor's own gesture, so the caret may land in the
+   *  composer; false for an open written from outside (a tool
+   *  navigation), which must leave focus where it is. */
+  focusOnOpen: boolean;
+  /** The parent is holding the unmount so the close transition can
+   *  paint; the body stays for the ride so the card leaves whole, not
+   *  as a gutted header-only shell. */
+  exiting: boolean;
+  onOpenChange: (open: boolean) => void;
+  corner: "bottom-right" | "bottom-left";
+  /** The effective mode, already viewport-resolved by the parent — the
+   *  drawer never reads persistence or measures the window. */
+  dock: PanelDock;
+  /** Null hides the switcher: the viewport is below the sidebar's floor
+   *  and the parent already forced floating. */
+  onDockChange: ((dock: PanelDock) => void) | null;
+}) {
+  const { rootProps } = useAssistantAppearance();
+  const core = useAssistantConversation();
+  const menus = useDrawerMenus(onDockChange, onOpenChange);
+
+  return (
+    <TfFloatingPanel
+      open={open}
+      focusOnOpen={focusOnOpen}
+      onOpenChange={menus.changeOpenAndSettleMenu}
+      corner={corner}
+      dock={dock}
+      aria-label="Assistant"
+      {...rootProps}
+    >
+      {/* The hairline is the scroll boundary: a live transcript clips
+          its lines exactly at this row's bottom edge, and the palette —
+          the same header anatomy over the same conversation body —
+          already draws it. Same register, same line. */}
+      <div
+        data-tf-swipe-handle=""
+        className="tf:relative tf:flex tf:h-12 tf:shrink-0 tf:items-center tf:gap-1 tf:border-b tf:pr-2 tf:pl-4"
+      >
+        <span aria-hidden data-tf-companion-grabber="" />
+        <CompanionHeaderTitle
+          menuId={menus.historyMenuId}
+          open={menus.historyOpen}
+          onOpenChange={menus.discloseHistory}
+          triggerRef={menus.historyTriggerRef}
+        />
+        {/* Hidden only when the surface is broken — there is no session
+            for a fresh conversation to act on (palette parity). Anonymous
+            visitors keep it: they hold live conversations, just no
+            server-side history. */}
+        {core.setupError === null ? (
+          <NewConversationButton onStart={core.startNewConversation} />
+        ) : null}
+        {onDockChange !== null ? (
+          <CompanionModeTrigger
+            menuId={menus.modeMenuId}
+            open={menus.modeMenuOpen}
+            onOpenChange={menus.discloseModeMenu}
+            triggerRef={menus.modeTriggerRef}
+          />
+        ) : null}
+        <TfButton
+          variant="icon"
+          aria-label="Minimize assistant"
+          title="Minimize assistant"
+          onClick={menus.minimize}
+        >
+          <MinimizeIcon />
+        </TfButton>
+      </div>
+      {/* Mounted only while open or riding the exit hold, palette
+          parity: a closed drawer must not hold an invisible live stream
+          — a yield can last minutes while the palette holds the
+          transcript lease — and reopening replays the conversation
+          exactly. The exit hold is different in kind: a bounded
+          teardown grace, during which nothing else holds the lease and
+          the body's presence is what keeps the departing card whole. */}
+      {open || exiting ? (
+        <LazyBody>
+          <CompanionDrawerBody />
+        </LazyBody>
+      ) : null}
+      {/* A sibling of the handle row, not a child: a touch-drag over a
+          history row must never read as a grab of the drawer. Gated on
+          open too, so a yielded drawer holds the menu's flag without
+          holding its listeners. AFTER the body in the DOM: the package
+          ships no z-index, so among positioned boxes document order is
+          the paint order — earlier, the transcript's own positioned
+          bubbles drew over the dropped-open menu. */}
+      {open && menus.historyOpen ? (
+        <CompanionHistoryMenu
+          id={menus.historyMenuId}
+          onClose={menus.closeHistory}
+          triggerRef={menus.historyTriggerRef}
+        />
+      ) : null}
+      {open && menus.modeMenuOpen && onDockChange !== null ? (
+        <CompanionModeMenu
+          id={menus.modeMenuId}
+          dock={dock}
+          triggerRef={menus.modeTriggerRef}
+          onClose={menus.closeModeMenu}
+          onSelect={menus.selectDock}
+        />
+      ) : null}
+    </TfFloatingPanel>
+  );
+}
+
+interface DrawerMenus {
+  historyOpen: boolean;
+  historyMenuId: string;
+  historyTriggerRef: RefObject<HTMLButtonElement | null>;
+  modeMenuOpen: boolean;
+  modeMenuId: string;
+  modeTriggerRef: RefObject<HTMLButtonElement | null>;
+  discloseHistory: (next: boolean) => void;
+  discloseModeMenu: (next: boolean) => void;
+  closeHistory: () => void;
+  closeModeMenu: () => void;
+  selectDock: (next: PanelDock) => void;
+  changeOpenAndSettleMenu: (next: boolean) => void;
+  /** The dash: a deliberate dismissal, menus and all. */
+  minimize: () => void;
+}
+
+/** The header's two disclosures — history and dock mode — open one at a
+ *  time, and both taken down by any deliberate dismissal of the drawer. */
+function useDrawerMenus(
+  onDockChange: ((dock: PanelDock) => void) | null,
+  onOpenChange: (open: boolean) => void,
+): DrawerMenus {
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const historyMenuId = useId();
+  const historyTriggerRef = useRef<HTMLButtonElement | null>(null);
+  const [modeMenuOpen, setModeMenuOpen] = useState(false);
+  const modeMenuId = useId();
+  const modeTriggerRef = useRef<HTMLButtonElement | null>(null);
+
+  // The switcher leaving takes its menu down for good — without this, a
+  // menu open when the viewport drops below the sidebar floor would hold
+  // its flag through the unmount and pop back open, unprompted, when the
+  // viewport returns. Render-time adjustment (the sanctioned shape), not
+  // an effect: the flag must never survive into a paint that renders the
+  // trigger expanded.
+  if (onDockChange === null && modeMenuOpen) {
+    setModeMenuOpen(false);
+  }
+
+  // One disclosure at a time: two dropped-open menus would stack by
+  // paint order and race each other's light dismiss, so opening any
+  // takes the others down.
+  function discloseHistory(next: boolean) {
+    if (next) {
+      setModeMenuOpen(false);
+    }
+    setHistoryOpen(next);
+  }
+  function discloseModeMenu(next: boolean) {
+    if (next) {
+      setHistoryOpen(false);
+    }
+    setModeMenuOpen(next);
+  }
+  function closeHistory() {
+    setHistoryOpen(false);
+  }
+  function closeModeMenu() {
+    setModeMenuOpen(false);
+  }
+  function selectDock(next: PanelDock) {
+    setModeMenuOpen(false);
+    if (onDockChange !== null) {
+      onDockChange(next);
+    }
+    // The pick just re-geometried the whole panel under the
+    // keyboard user; the trigger is the one landmark that stayed
+    // put, so focus comes back to it rather than dying with the
+    // menu row.
+    modeTriggerRef.current?.focus();
+  }
+
+  // Every deliberate dismissal — the dash, Esc, a swipe, a forced park —
+  // arrives through this callback, and takes the menus down with the
+  // drawer. A yield to the palette deliberately does NOT: it flips the
+  // open prop without ringing here, and the drawer's contract for a
+  // yield is that everything comes back exactly as it was.
+  function changeOpenAndSettleMenu(next: boolean) {
+    if (!next) {
+      setHistoryOpen(false);
+      setModeMenuOpen(false);
+    }
+    onOpenChange(next);
+  }
+  function minimize() {
+    changeOpenAndSettleMenu(false);
+  }
+
+  return {
+    historyOpen,
+    historyMenuId,
+    historyTriggerRef,
+    modeMenuOpen,
+    modeMenuId,
+    modeTriggerRef,
+    discloseHistory,
+    discloseModeMenu,
+    closeHistory,
+    closeModeMenu,
+    selectDock,
+    changeOpenAndSettleMenu,
+    minimize,
+  };
+}
+
+/** Compose: a fresh conversation, with the caret handed to the composer. */
+function NewConversationButton({ onStart }: { onStart: () => void }) {
+  return (
+    <TfButton
+      variant="icon"
+      aria-label="New conversation"
+      title="New conversation"
+      onClick={(event) => {
+        onStart();
+        // The fresh conversation starts with the caret in the
+        // composer, not on this button (palette parity, retargeted:
+        // the drawer's root is the popover div, not a dialog).
+        const panel = event.currentTarget.closest("[data-tf-floating-panel]");
+        requestAnimationFrame(() => {
+          panel?.querySelector<HTMLElement>("[data-tf-autofocus]")?.focus();
+        });
+      }}
+    >
+      <ComposeIcon />
+    </TfButton>
+  );
+}

package/src/components/companion-header-disclosure.tsx

@@ -0,0 +1,200 @@
+"use client";
+
+import {
+  useEffect,
+  useRef,
+  type ComponentProps,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+import { TfButton } from "./primitives/button.js";
+import { cx } from "./primitives/cx.js";
+
+// The drawer header's disclosure mechanics: a trigger in the header row
+// that drops a small dialog open over the transcript. The history menu
+// wears this today; the mode switcher joins it from the same pair.
+//
+// Trigger and menu are two exports rather than one component because
+// they live on opposite sides of a boundary the DOM enforces: the
+// trigger sits inside the header row, which IS the swipe-dismiss handle
+// (`data-tf-swipe-handle` matches by closest()), and a menu nested in
+// that row would turn every touch-drag over a menu row into a drawer
+// dismissal. The parent owns the open flag and threads it through.
+//
+// The caller's side of the contract: render the menu as a DOM sibling
+// AFTER the panel body, not inside the header row. The package ships no
+// z-index, so among positioned boxes document order is the paint order —
+// a menu mounted before the body would lose to the transcript's own
+// positioned bubbles. This file can't enforce placement; the caller
+// carries the law.
+
+/** The header-row half: owns the disclosure aria wiring and the
+ *  Esc-closes-the-menu-not-the-drawer keydown. Everything else — variant,
+ *  className, children — passes through to TfButton. */
+export function HeaderDisclosureTrigger({
+  menuId,
+  open,
+  onOpenChange,
+  triggerRef,
+  children,
+  ...buttonProps
+}: {
+  menuId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  children: ReactNode;
+  // "ref" stripped alongside the handlers this component owns: TfButton is
+  // a forwardRef component, so its ComponentProps include a ref that would
+  // ride ...buttonProps and clobber triggerRef in the spread below under
+  // React 19 (and silently vanish under 18.3). triggerRef IS this
+  // component's ref channel.
+} & Omit<ComponentProps<typeof TfButton>, "onClick" | "onKeyDown" | "ref">) {
+  return (
+    <TfButton
+      ref={triggerRef}
+      aria-expanded={open}
+      aria-controls={menuId}
+      {...buttonProps}
+      onClick={() => {
+        onOpenChange(!open);
+      }}
+      onKeyDown={(event) => {
+        // Escape with focus on the trigger closes the menu, not the
+        // drawer — stopped so the panel's own Esc-to-close never sees it.
+        if (!open || event.key !== "Escape") {
+          return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        onOpenChange(false);
+      }}
+    >
+      {children}
+    </TfButton>
+  );
+}
+
+/** The dropped-open half. Mounted only while open — the parent gates the
+ *  render, so unmounting is the close and no state survives a minimize.
+ *  The caller's className carries the anchor side and measure (the
+ *  history menu hangs `left-2 w-72` under its title; a right-edge
+ *  disclosure would pass `right-2`). */
+export function HeaderDisclosureMenu({
+  id,
+  onClose,
+  triggerRef,
+  triggerId,
+  "aria-label": ariaLabel,
+  className,
+  insetFromSurfaceTop = false,
+  autoFocusFirstButton = true,
+  children,
+}: {
+  id: string;
+  onClose: () => void;
+  triggerRef?: RefObject<HTMLButtonElement | null>;
+  triggerId?: string;
+  "aria-label": string;
+  className?: string;
+  /** A host-rendered full-page trigger can live in the host header
+   *  immediately above the assistant. Its menu starts at the surface's
+   *  top inset instead of below the companion's own 56px header. */
+  insetFromSurfaceTop?: boolean;
+  /** Default true: the first button is the menu's primary command. A
+   *  tenant whose first button is NOT a safe primary (the connect
+   *  panel's resting state leads with the destructive disconnect, and a
+   *  held Enter on the trigger key-repeats onto whatever gets focus)
+   *  opts out — focus then rests on the trigger, the classic
+   *  disclosure convention, whose own Esc handling still closes. */
+  autoFocusFirstButton?: boolean;
+  children: ReactNode;
+}) {
+  const menuRef = useRef<HTMLDivElement | null>(null);
+
+  // Light dismissal: any pointer that goes down outside the menu closes
+  // it. Judged by composedPath(), not contains() — the script-tag
+  // distribution runs in an open shadow root, where document-level
+  // events retarget to the host element and contains() would call every
+  // in-shadow press an outside one. The trigger is excluded so its own
+  // press doesn't close-then-reopen through the click that follows.
+  useEffect(() => {
+    const menu = menuRef.current;
+    if (menu === null) {
+      return;
+    }
+    const closeUnlessInside = (event: Event) => {
+      const path = event.composedPath();
+      if (path.includes(menu)) {
+        return;
+      }
+      const trigger =
+        triggerRef?.current ??
+        (triggerId === undefined
+          ? null
+          : menu.ownerDocument.getElementById(triggerId));
+      if (trigger !== null && path.includes(trigger)) {
+        return;
+      }
+      onClose();
+    };
+    const doc = menu.ownerDocument;
+    doc.addEventListener("pointerdown", closeUnlessInside);
+    return () => {
+      doc.removeEventListener("pointerdown", closeUnlessInside);
+    };
+  }, [onClose, triggerId, triggerRef]);
+
+  // Opening moves focus into the panel — its first button is the menu's
+  // primary command (unless the tenant opted out above).
+  useEffect(() => {
+    if (autoFocusFirstButton) {
+      menuRef.current?.querySelector("button")?.focus();
+    }
+  }, [autoFocusFirstButton]);
+
+  return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the keydown is the menu's own Esc-to-close; every focusable inside is a real button.
+    <div
+      ref={menuRef}
+      id={id}
+      role="dialog"
+      aria-label={ariaLabel}
+      // Absolute against the assistant surface: the fixed companion or
+      // the relative full-page root. It is a sibling of the transcript,
+      // painted over it by document order alone — the package ships no
+      // z-index. Fill, blur, and shadow come from the sanctioned
+      // liquid-glass portal material.
+      data-tf-glass=""
+      // The flag the panel reads to throw its conversation out of focus
+      // while this menu is open (styles.css) — the menu's own glass
+      // tints the transcript's text but cannot soften it.
+      data-tf-disclosure=""
+      data-tf-surface-inset={insetFromSurfaceTop ? "" : undefined}
+      className={cx(
+        "tf:absolute tf:top-14 tf:flex tf:max-h-96 tf:flex-col tf:overflow-hidden tf:rounded-2xl tf:border",
+        className,
+      )}
+      onKeyDown={(event) => {
+        // Esc closes the menu and hands focus back to its trigger; the
+        // drawer survives — stopped before the panel's handler minimizes
+        // it too.
+        if (event.key !== "Escape") {
+          return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        onClose();
+        const trigger =
+          triggerRef?.current ??
+          (triggerId === undefined
+            ? null
+            : menuRef.current?.ownerDocument.getElementById(triggerId));
+        trigger?.focus();
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/components/companion-history-menu.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { type RefObject } from "react";
+
+import {
+  HeaderDisclosureMenu,
+  HeaderDisclosureTrigger,
+} from "./companion-header-disclosure.js";
+import { ChevronDownIcon } from "./icons.js";
+import { ThreadHistory } from "./thread-list.js";
+import { useAssistantConversation } from "./use-assistant-conversation.js";
+
+// The drawer header's title-as-disclosure (the Notion register): the
+// active conversation's title with a chevron, and pressing it drops open
+// a small popover of past conversations over the transcript — the same
+// ThreadHistory the page's rail and phone sheet render. One list, three
+// densities, never a fork.
+
+/** The title half of the header row. For anonymous visitors the server's
+ *  thread list is honestly empty, so there is no history to disclose —
+ *  the title stays a static heading with no chevron and no menu (the
+ *  page gates its rail the same way). */
+export function CompanionHeaderTitle({
+  menuId,
+  open,
+  onOpenChange,
+  triggerRef,
+  fallbackTitle = "Assistant",
+}: {
+  menuId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  fallbackTitle?: string;
+}) {
+  const core = useAssistantConversation();
+  // `||`, not `??`: a just-created thread can hold an empty title until
+  // the server names it, and while a thread is opening the title lags
+  // one beat behind — "Assistant" covers both gaps. The muted label step
+  // keeps the empty state's centered question the surface's only
+  // headline; weight stated explicitly because the package ships no
+  // preflight, so an unweighted h2 inherits the UA's bold in one host
+  // and the host's own reset in another.
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- the empty-string fallback is the point, per above.
+  const title = core.conversation?.thread.title || fallbackTitle;
+  if (!core.historyExpected) {
+    return (
+      <h2 className="tf:min-w-0 tf:flex-1 tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground">
+        {title}
+      </h2>
+    );
+  }
+  return (
+    <h2 className="tf:flex tf:min-w-0 tf:flex-1 tf:items-center tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground">
+      {/* A button inside the heading, not a heading inside a button: the
+          h2 keeps the document outline and its muted ink (`bare` is
+          text-inherit), and the button's accessible name is the visible
+          title itself — an aria-label like "Conversation history" would
+          hide the name on the screen from the name in the tree. The
+          disclosure semantics ride aria-expanded + aria-controls to a
+          dialog that carries the "Conversation history" label. The
+          negative margin gives the hover wash its own inset while the
+          title text holds the header's 16px line. */}
+      <HeaderDisclosureTrigger
+        menuId={menuId}
+        open={open}
+        onOpenChange={onOpenChange}
+        triggerRef={triggerRef}
+        variant="bare"
+        className="tf:-ml-1.5 tf:min-w-0 tf:px-1.5 tf:py-1 tf:hover:bg-tf-accent tf:hover:text-tf-foreground"
+      >
+        <span className="tf:min-w-0 tf:truncate">{title}</span>
+        <ChevronDownIcon />
+      </HeaderDisclosureTrigger>
+    </h2>
+  );
+}
+
+/** The dropped-open history panel: the shared disclosure menu hung
+ *  left-anchored under the title that discloses it, wrapping the shared
+ *  thread list. Its first row is "New conversation" — a deliberate twin
+ *  of the header's compose button, shared with the page rail and the
+ *  phone sheet. */
+export function CompanionHistoryMenu({
+  id,
+  onClose,
+  triggerRef,
+  triggerId,
+  insetFromSurfaceTop,
+}: {
+  id: string;
+  onClose: () => void;
+  triggerRef?: RefObject<HTMLButtonElement | null>;
+  triggerId?: string;
+  insetFromSurfaceTop?: boolean;
+}) {
+  const core = useAssistantConversation();
+  return (
+    <HeaderDisclosureMenu
+      id={id}
+      aria-label="Conversation history"
+      onClose={onClose}
+      triggerRef={triggerRef}
+      triggerId={triggerId}
+      insetFromSurfaceTop={insetFromSurfaceTop}
+      // left-2.5 + the panel hairline puts the menu's edge on the
+      // trigger pill's own left edge; w-80 keeps the menu at least as
+      // wide as the widest title the trigger can show, so a thread name
+      // legible in the header never truncates in the list beneath it
+      // (and still clears the 358px phone card with room to spare).
+      className="tf:left-2.5 tf:w-80 tf:max-w-[calc(100%-1.25rem)] tf:pt-2"
+    >
+      <ThreadHistory
+        threads={core.threads}
+        activeThreadId={core.conversation?.thread.id ?? null}
+        safeAreaBottom={false}
+        onSelectThread={(thread) => {
+          onClose();
+          core.openThread(thread);
+        }}
+        onNewConversation={() => {
+          onClose();
+          core.startNewConversation();
+        }}
+      />
+    </HeaderDisclosureMenu>
+  );
+}

package/src/components/companion-mark-image.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { useState } from "react";
+
+import { AgentIdentityMark } from "./agent-identity-mark.js";
+
+// The script-tag route's companion mark: `companion-mark-src` as a
+// decorative image, keeping the stance of the loader it replaced — a
+// broken mark costs the mark, never the page. A 404, a CSP or ad-block
+// refusal, or a URL that is not an image fires the img's error event:
+// one readable console warning per source, then the package flask in
+// its place. The flask is inline SVG and cannot fail to load, so there
+// is no third state. Rendered inside the host-view marker either way;
+// the flask carries no border or box metrics, so the reset it is exempt
+// from there never touches it.
+const warnedSources = new Set<string>();
+
+export function CompanionMarkImage({ src }: { src: string }) {
+  const [failed, setFailed] = useState(false);
+  if (failed) {
+    return <AgentIdentityMark register="primary" size="fill" />;
+  }
+  return (
+    <img
+      src={src}
+      alt=""
+      draggable={false}
+      onError={() => {
+        if (!warnedSources.has(src)) {
+          warnedSources.add(src);
+          console.warn(
+            `[teaflask-assistant] companion-mark-src "${src}" did not load; showing the TeaFlask flask instead.`,
+          );
+        }
+        setFailed(true);
+      }}
+    />
+  );
+}

package/src/components/companion-mark.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { AgentIdentityMark } from "./agent-identity-mark.js";
+import { useAssistantAppearance } from "./appearance-context.js";
+
+// The one mark every companion stage shows — the corner perch and the
+// drawer's welcome — at one size. Static: the stylesheet sizes the box
+// and sets the node inside to 100% of it (the fill is the package's
+// promise, not the host's). A host's node is host DOM and wears the
+// data-tf-host-view marker so the package reset leaves it alone; the
+// default flask stays package DOM under the reset, unmarked. The null
+// branch is exact on purpose: the provider has already folded the
+// declining values (undefined, null, either boolean) into null.
+export function CompanionMark() {
+  const { companionMark } = useAssistantAppearance();
+  return (
+    <span aria-hidden data-tf-companion-mark="">
+      {companionMark === null ? (
+        <AgentIdentityMark register="primary" size="fill" />
+      ) : (
+        <span data-tf-host-view="" className="tf:contents">
+          {companionMark}
+        </span>
+      )}
+    </span>
+  );
+}