@teaflask/assistant 0.3.0 → 0.7.0

package/src/persistence/stored-thread.ts

@@ -1,85 +0,0 @@
-// 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

@@ -1,356 +0,0 @@
-// 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

@@ -1,157 +0,0 @@
-// 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"
-  );
-}