@teaflask/assistant 0.0.0 → 0.3.0

package/src/persistence/stored-thread.ts

@@ -0,0 +1,85 @@
+// The browser's memory of its conversation: one localStorage entry per
+// publishable key (pk_test and pk_live on one origin stay apart; per-org
+// is impossible — the browser only knows the pk). `identified: false`
+// marks a thread still to be offered for adoption on the sign-in re-mint.
+
+export interface StoredThread {
+  threadId: string;
+  identified: boolean;
+}
+
+export function readStoredThread(publishableKey: string): StoredThread | null {
+  const raw = _storage()?.getItem(_storageKeyFor(publishableKey)) ?? null;
+  if (raw === null) {
+    return null;
+  }
+  return _decodeStoredThread(raw);
+}
+
+export function writeStoredThread(
+  publishableKey: string,
+  stored: StoredThread,
+): void {
+  try {
+    _storage()?.setItem(_storageKeyFor(publishableKey), JSON.stringify(stored));
+  } catch {
+    // Quota or privacy-mode failures cost persistence, never the widget.
+  }
+}
+
+export function clearStoredThread(publishableKey: string): void {
+  try {
+    _storage()?.removeItem(_storageKeyFor(publishableKey));
+  } catch {
+    // Same stance as writes: storage trouble never breaks the widget.
+  }
+}
+
+/**
+ * The host-logout contract: call this in the sign-out handler so the next
+ * visitor on this browser starts clean. Pure storage — it works on pages
+ * where the widget isn't mounted (the common case for logout flows).
+ */
+export function resetAssistant(options: { publishableKey: string }): void {
+  clearStoredThread(options.publishableKey);
+}
+
+function _storageKeyFor(publishableKey: string): string {
+  return `tf-assistant:${publishableKey}:thread`;
+}
+
+function _storage(): Storage | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    return window.localStorage;
+  } catch {
+    // Some embeds (sandboxed iframes, blocked third-party storage) throw
+    // on access; the widget then simply doesn't persist.
+    return null;
+  }
+}
+
+function _decodeStoredThread(raw: string): StoredThread | null {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (_isStoredThread(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // A corrupt entry reads as no entry.
+  }
+  return null;
+}
+
+function _isStoredThread(value: unknown): value is StoredThread {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "threadId" in value &&
+    typeof value.threadId === "string" &&
+    "identified" in value &&
+    typeof value.identified === "boolean"
+  );
+}

package/src/reader/accessible-name.ts

@@ -0,0 +1,356 @@
+// Accessible-name computation, W3C-accname-shaped: the label a user
+// (or assistive tech) would know an element by. Precedence walks from
+// author overrides (aria-labelledby, aria-label) through native labeling
+// (label elements, alt, captions) down to content and tooltips. Results
+// are cached per snapshot pass — the walk asks for the same names many
+// times — and capped at 300 characters.
+
+import type { LayoutProbe } from "./layout-probe.js";
+import { roleOf } from "./roles.js";
+
+const MAX_NAME_DEPTH = 10;
+const MAX_NAME_LENGTH = 300;
+
+// Roles that take their name from their contents.
+const NAME_FROM_CONTENT_ROLES = new Set([
+  "button",
+  "link",
+  "heading",
+  "cell",
+  "columnheader",
+  "rowheader",
+  "tooltip",
+  "tab",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "treeitem",
+  "option",
+  "listitem",
+  "row",
+  "term",
+]);
+
+// Roles for which naming is prohibited outright — a bare div (generic)
+// has no accessible name, which is what lets the reader tell a labeled
+// control from an anonymous wrapper.
+const PROHIBITS_NAMING = new Set([
+  "caption",
+  "code",
+  "definition",
+  "deletion",
+  "emphasis",
+  "generic",
+  "insertion",
+  "mark",
+  "paragraph",
+  "presentation",
+  "strong",
+  "subscript",
+  "superscript",
+  "term",
+  "time",
+]);
+
+const NATIVELY_LABELABLE_TAGS = new Set([
+  "input",
+  "textarea",
+  "select",
+  "meter",
+  "progress",
+  "output",
+]);
+
+interface NameComputationState {
+  depth: number;
+  visited: Set<Element>;
+  inLabelledBy: boolean;
+  inLabel: boolean;
+  /** Inside a name-from-content descent, every child names from content. */
+  inContent: boolean;
+}
+
+export type AccessibleNameCache = Map<Element, string>;
+
+export function accessibleNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  cache: AccessibleNameCache,
+): string {
+  const cached = cache.get(element);
+  if (cached !== undefined) {
+    return cached;
+  }
+  let name = "";
+  if (!PROHIBITS_NAMING.has(roleOf(element))) {
+    name = _computedNameOf(element, probe, {
+      depth: 0,
+      visited: new Set(),
+      inLabelledBy: false,
+      inLabel: false,
+      inContent: false,
+    });
+  }
+  name = name.replace(/\s+/g, " ").trim().substring(0, MAX_NAME_LENGTH);
+  cache.set(element, name);
+  return name;
+}
+
+function _computedNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  state: NameComputationState,
+): string {
+  if (state.depth >= MAX_NAME_DEPTH || state.visited.has(element)) {
+    return "";
+  }
+  state.visited.add(element);
+
+  if (
+    !state.inLabelledBy &&
+    !state.inLabel &&
+    _isHiddenForNaming(element, probe)
+  ) {
+    return "";
+  }
+
+  if (!state.inLabelledBy) {
+    const labelledBy = _labelledByNameOf(element, probe, state);
+    if (labelledBy !== "") {
+      return labelledBy;
+    }
+  }
+
+  const ariaLabel = (element.getAttribute("aria-label") ?? "").trim();
+  if (ariaLabel !== "") {
+    return ariaLabel;
+  }
+
+  if (
+    NATIVELY_LABELABLE_TAGS.has(element.tagName.toLowerCase()) &&
+    !state.inLabel &&
+    !state.inLabelledBy
+  ) {
+    const fromLabels = _nativeLabelNameOf(element, probe, state);
+    if (fromLabels !== "") {
+      return fromLabels;
+    }
+  }
+
+  const alt = _altNameOf(element);
+  if (alt !== null) {
+    return alt;
+  }
+
+  const fromCaption = _captionNameOf(element, probe, state);
+  if (fromCaption !== "") {
+    return fromCaption;
+  }
+
+  if (element instanceof HTMLSelectElement && element.selectedIndex >= 0) {
+    const selected = element.options[element.selectedIndex] as
+      HTMLOptionElement | undefined;
+    const text = (selected?.textContent ?? "").trim();
+    if (text !== "") {
+      return text;
+    }
+  }
+
+  if (
+    NAME_FROM_CONTENT_ROLES.has(roleOf(element)) ||
+    state.inLabelledBy ||
+    state.inLabel ||
+    state.inContent
+  ) {
+    const fromContent = _contentNameOf(element, probe, state);
+    if (fromContent !== "") {
+      return fromContent;
+    }
+  }
+
+  if (
+    element instanceof HTMLInputElement &&
+    (element.type === "submit" || element.type === "button")
+  ) {
+    const value = element.value.trim();
+    if (value !== "") {
+      return value;
+    }
+  }
+
+  const placeholder = (element.getAttribute("placeholder") ?? "").trim();
+  if (placeholder !== "") {
+    return placeholder;
+  }
+
+  return (element.getAttribute("title") ?? "").trim();
+}
+
+function _labelledByNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  state: NameComputationState,
+): string {
+  const references = _idReferencesOf(
+    element,
+    element.getAttribute("aria-labelledby"),
+  );
+  const parts = references.map((reference) =>
+    _computedNameOf(reference, probe, {
+      depth: state.depth + 1,
+      visited: new Set(state.visited),
+      inLabelledBy: true,
+      inLabel: state.inLabel,
+      inContent: false,
+    }),
+  );
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+
+function _nativeLabelNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  state: NameComputationState,
+): string {
+  const parts = _labelsOf(element).map((label) =>
+    _computedNameOf(label, probe, {
+      depth: state.depth + 1,
+      visited: new Set(state.visited),
+      inLabelledBy: state.inLabelledBy,
+      inLabel: true,
+      inContent: false,
+    }),
+  );
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+
+function _altNameOf(element: Element): string | null {
+  const tag = element.tagName.toLowerCase();
+  const eligible =
+    tag === "area" ||
+    tag === "img" ||
+    (tag === "input" && element.getAttribute("type") === "image");
+  if (!eligible) {
+    return null;
+  }
+  const alt = element.getAttribute("alt");
+  // A present-but-empty alt is "purely decorative" and short-circuits.
+  return alt === null ? null : alt.trim();
+}
+
+function _captionNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  state: NameComputationState,
+): string {
+  const tag = element.tagName.toLowerCase();
+  const captionSelector =
+    tag === "fieldset"
+      ? ":scope > legend"
+      : tag === "figure"
+        ? ":scope > figcaption"
+        : tag === "table"
+          ? ":scope > caption"
+          : null;
+  if (captionSelector === null) {
+    return "";
+  }
+  const caption = element.querySelector(captionSelector);
+  if (caption === null) {
+    return "";
+  }
+  return _computedNameOf(caption, probe, {
+    depth: state.depth + 1,
+    visited: new Set(state.visited),
+    inLabelledBy: true,
+    inLabel: state.inLabel,
+    inContent: false,
+  });
+}
+
+function _contentNameOf(
+  element: Element,
+  probe: LayoutProbe,
+  state: NameComputationState,
+): string {
+  const parts: string[] = [probe.pseudoContentOf(element, "::before")];
+  for (const child of Array.from(element.childNodes)) {
+    if (child.nodeType === Node.TEXT_NODE) {
+      parts.push(child.textContent ?? "");
+    } else if (child.nodeType === Node.ELEMENT_NODE) {
+      parts.push(
+        _computedNameOf(child as Element, probe, {
+          depth: state.depth + 1,
+          visited: new Set(state.visited),
+          inLabelledBy: state.inLabelledBy,
+          inLabel: state.inLabel,
+          inContent: true,
+        }),
+      );
+    }
+  }
+  parts.push(probe.pseudoContentOf(element, "::after"));
+  // No separator: inline fragments carry their own whitespace, and a
+  // forced space would split words that wrap in nested spans.
+  return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+function _isHiddenForNaming(element: Element, probe: LayoutProbe): boolean {
+  if (element.getAttribute("aria-hidden") === "true") {
+    return true;
+  }
+  const style = probe.styleOf(element);
+  return style.display === "none" || style.visibility === "hidden";
+}
+
+function _idReferencesOf(
+  element: Element,
+  attributeValue: string | null,
+): Element[] {
+  if (attributeValue === null || attributeValue === "") {
+    return [];
+  }
+  const documentOf = element.ownerDocument;
+  return attributeValue
+    .split(/\s+/)
+    .filter((id) => id !== "")
+    .map((id) => documentOf.getElementById(id))
+    .filter((referenced): referenced is HTMLElement => referenced !== null);
+}
+
+function _labelsOf(element: Element): Element[] {
+  const labels: Element[] = [];
+  const id = element.getAttribute("id");
+  if (id !== null && id !== "") {
+    labels.push(..._labelsWiredTo(element.ownerDocument, id));
+  }
+  for (
+    let parent = element.parentElement;
+    parent !== null;
+    parent = parent.parentElement
+  ) {
+    if (parent.tagName.toLowerCase() === "label") {
+      // A label that both wraps its control and names it via for= is
+      // one label, not two — collecting it twice would double the name.
+      if (!labels.includes(parent)) {
+        labels.push(parent);
+      }
+      break;
+    }
+  }
+  return labels;
+}
+
+function _labelsWiredTo(documentOf: Document, id: string): Element[] {
+  // Inside a double-quoted CSS string only the quote and the backslash
+  // are meta — both must be escaped, or an id ending in a backslash eats
+  // the closing quote and the selector throws. The fence upholds the
+  // reader's invariant: an unselectable id costs one label, never the
+  // whole read.
+  const escaped = id.replace(/[\\"]/g, "\\$&");
+  try {
+    return Array.from(documentOf.querySelectorAll(`label[for="${escaped}"]`));
+  } catch {
+    return [];
+  }
+}

package/src/reader/interactivity.ts

@@ -0,0 +1,157 @@
+// Which elements the user can act on. Native interactive tags and
+// button/link roles are certain; onclick handlers, focusable tabindex,
+// contenteditable, and cursor:pointer are the heuristics that catch the
+// div-with-a-click-handler pattern. The cursor signal is suppressed when
+// the parent shares it and the element has no signal of its own —
+// otherwise every span inside a clickable card would read as
+// interactive.
+
+import type { LayoutProbe } from "./layout-probe.js";
+import { explicitRoleOf, isContentEditableElement } from "./roles.js";
+
+const INTERACTIVE_TAGS = new Set([
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "details",
+  "summary",
+]);
+
+// Roles that always earn a ref in the snapshot, interactive by nature.
+export const INTERACTIVE_REF_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "treeitem",
+]);
+
+// Content roles that earn a ref only when they carry an accessible name.
+export const CONTENT_REF_ROLES = new Set([
+  "cell",
+  "gridcell",
+  "columnheader",
+  "rowheader",
+  "listitem",
+  "article",
+  "region",
+  "main",
+  "navigation",
+]);
+
+const LANDMARK_TAGS = new Set([
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "nav",
+  "main",
+  "header",
+  "footer",
+  "section",
+  "article",
+  "aside",
+]);
+
+const SCROLLABLE_OVERFLOW_VALUES = new Set(["auto", "scroll", "overlay"]);
+
+export interface InteractivitySignals {
+  interactive: boolean;
+  isInteractiveTag: boolean;
+  /** The heuristic signals worth surfacing on non-native elements. */
+  hints: string[];
+}
+
+export function interactivitySignalsOf(
+  element: Element,
+  probe: LayoutProbe,
+): InteractivitySignals {
+  const tag = element.tagName.toLowerCase();
+  const role = explicitRoleOf(element);
+  const tabIndex = element.getAttribute("tabindex");
+  const hasTabIndex = tabIndex !== null && tabIndex !== "-1";
+  const hasOnClick = element.hasAttribute("onclick");
+  const hasCursorPointer = probe.styleOf(element).cursor === "pointer";
+  const isInteractiveTag = INTERACTIVE_TAGS.has(tag);
+  const isRoleInteractive = role === "button" || role === "link";
+  // The shared predicate, so the bare attribute and plaintext-only read
+  // as interactive exactly where roles.ts reads them as textboxes.
+  const isContentEditable = isContentEditableElement(element);
+
+  let hasPointerInteraction = hasCursorPointer;
+  if (hasCursorPointer && !hasOnClick && !hasTabIndex) {
+    const parent = element.parentElement;
+    if (parent !== null && probe.styleOf(parent).cursor === "pointer") {
+      hasPointerInteraction = false;
+    }
+  }
+
+  const hints: string[] = [];
+  if (hasPointerInteraction) {
+    hints.push("cursor:pointer");
+  }
+  if (hasOnClick) {
+    hints.push("onclick");
+  }
+  if (hasTabIndex) {
+    hints.push("tabindex");
+  }
+  return {
+    interactive:
+      isInteractiveTag ||
+      hasOnClick ||
+      hasTabIndex ||
+      isRoleInteractive ||
+      isContentEditable ||
+      hasPointerInteraction,
+    isInteractiveTag,
+    hints,
+  };
+}
+
+export function isScrollable(element: Element, probe: LayoutProbe): boolean {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "html" || tag === "body") {
+    return false; // page-level scroll is implicit
+  }
+  const style = probe.styleOf(element);
+  if (
+    !SCROLLABLE_OVERFLOW_VALUES.has(style.overflowX) &&
+    !SCROLLABLE_OVERFLOW_VALUES.has(style.overflowY)
+  ) {
+    return false;
+  }
+  return (
+    element.scrollHeight > element.clientHeight + 1 ||
+    element.scrollWidth > element.clientWidth + 1
+  );
+}
+
+export function isLandmark(element: Element): boolean {
+  const tag = element.tagName.toLowerCase();
+  if (LANDMARK_TAGS.has(tag)) {
+    return true;
+  }
+  const explicitRole = explicitRoleOf(element);
+  return (
+    explicitRole !== null &&
+    explicitRole !== "presentation" &&
+    explicitRole !== "none"
+  );
+}