@teaflask/assistant 0.3.0 → 0.7.0

package/dist/components/use-assistant-conversation.d.ts

@@ -1,32 +1,120 @@
 import type { ServingAssistantThread } from "../contract/threads.js";
-import type { ActiveConversation, ComposerContract } from "../core/conversation-store.js";
+import type { ComposerContract } from "../core/conversation-store.js";
 import type { PendingDecisionGap } from "../core/pending-decision-gap.js";
 import type { ServingApiError } from "../transport/serving-error.js";
-/** The surface-facing view of the shared conversation core — exactly what
- *  the chromes render, nothing the store keeps to itself. */
+/** The conversation on screen. */
+export interface OpenConversation {
+    /**
+     * The conversation's server record, including its id, title, whether a
+     * reply is running, timestamps and saved model choice.
+     */
+    thread: ServingAssistantThread;
+}
+/**
+ * The open conversation, the visitor's history, the notices worth showing, and
+ * the actions that move between conversations, as returned by
+ * useAssistantConversation().
+ */
 export interface AssistantConversation {
+    /**
+     * Set when the assistant cannot start because of a configuration problem
+     * (code PUBLISHABLE_KEY_INVALID, ORIGIN_NOT_ALLOWED, END_USER_TOKEN_INVALID
+     * or END_USER_ID_MISMATCH); show it instead of the conversation. Null
+     * otherwise, and cleared once a session starts successfully.
+     */
     setupError: ServingApiError | null;
-    conversation: ActiveConversation | null;
+    /**
+     * The conversation on screen, or null when none is open (a fresh
+     * conversation has no record until its first message is sent).
+     */
+    conversation: OpenConversation | null;
+    /**
+     * The visitor's past conversations (up to 200), for a history list. Only
+     * loaded for an identified visitor; empty for anonymous visitors.
+     */
     threads: ServingAssistantThread[];
+    /**
+     * True when the visitor is identified (you passed a userId, or their
+     * session is signed in), so a history list makes sense; false for an
+     * anonymous visitor.
+     */
     historyExpected: boolean;
+    /**
+     * True while a conversation is loading (a stored conversation at startup,
+     * or one picked with openThread); show a loading state rather than the
+     * empty state.
+     */
     threadOpening: boolean;
+    /**
+     * Increases each time the live connection restarts (after each send, a
+     * retry, or an automatic reconnect). Use it with the conversation id as a
+     * React key if you want your transcript subtree to remount on reconnect.
+     */
     reconnectNonce: number;
+    /**
+     * The composer's state and controls for this conversation, the same value
+     * useConversation() returns.
+     */
     composerContract: ComposerContract;
+    /**
+     * A sentence to show the visitor when sending a message, opening a
+     * conversation or stopping a reply failed. Null otherwise; cleared by the
+     * next send, open or new conversation.
+     */
     sendError: string | null;
+    /**
+     * A sentence to show when the newest reply failed. Null when it didn't, and
+     * also once the transcript itself shows that failure as a receipt row, so
+     * you never show it twice.
+     */
     turnFailure: string | null;
+    /**
+     * True when the connection dropped while a reply was in progress; show a
+     * notice with a Retry button that calls retryStream. Never true while the
+     * visitor is stopping a reply.
+     */
     showInterruptionBanner: boolean;
+    /**
+     * Set when the agent is waiting on an approval or question that this page
+     * could not display (after a short grace period). Show a notice with a
+     * Retry button that calls refreshConversation; null otherwise.
+     */
     pendingDecisionGap: PendingDecisionGap | null;
+    /**
+     * Reconnects to the conversation and replays it from the start, clearing
+     * the interruption notice. Use it as the interruption notice's Retry.
+     */
     retryStream: () => void;
+    /**
+     * Re-reads the open conversation from the server and applies what it finds.
+     * Does nothing when no conversation is open; network failures are ignored.
+     */
     refreshConversation: () => Promise<void>;
+    /**
+     * Opens one of the visitor's past conversations (from threads) and makes it
+     * the one resumed next time. While it loads, threadOpening is true; if it
+     * can't be opened, sendError is set, and a conversation that no longer
+     * exists is removed from threads.
+     */
     openThread: (thread: ServingAssistantThread) => void;
+    /**
+     * Leaves the current conversation and shows an empty one. Clears the unsent
+     * draft, staged attachments, unsent question answers and model choice; the
+     * new conversation is created when the first message is sent.
+     */
     startNewConversation: () => void;
+    /**
+     * Re-opens the conversation this browser last used, as saved for this
+     * publishable key; if none is saved, an open conversation is closed. The
+     * provider calls it once at startup; call it again when your UI reopens if
+     * another surface may have switched conversations meanwhile.
+     */
     resumeStoredThread: () => void;
 }
 /**
- * The React binding of the shared conversation store: every mounted
- * surface subscribing here reads the SAME store — one thread, one resume
- * state, one send path — so surfaces are pure chrome over one live
- * conversation. The engine itself lives in core/conversation-store.
+ * Returns the live state and controls of the assistant conversation, for
+ * building your own UI. Must be called inside <TeaflaskAssistantProvider> (it
+ * throws otherwise); every component that calls it reads the same conversation
+ * as the widget, drawer, palette and full-page assistant.
  */
 export declare function useAssistantConversation(): AssistantConversation;
-//# sourceMappingURL=use-assistant-conversation.d.ts.map

package/dist/components/use-assistant-conversation.js

@@ -1,12 +1,6 @@
 "use client";
 import { useAssistantSession } from "./teaflask-assistant-provider.js";
 import { useCell } from "./use-store-cell.js";
-/**
- * The React binding of the shared conversation store: every mounted
- * surface subscribing here reads the SAME store — one thread, one resume
- * state, one send path — so surfaces are pure chrome over one live
- * conversation. The engine itself lives in core/conversation-store.
- */
 export function useAssistantConversation() {
     const { setupError, store } = useAssistantSession();
     const conversation = useCell(store.conversation);
@@ -30,4 +24,3 @@ export function useAssistantConversation() {
         resumeStoredThread: store.resumeStoredThread,
     };
 }
-//# sourceMappingURL=use-assistant-conversation.js.map

package/dist/components/use-assistant-surface-presence.js

@@ -1,11 +1,6 @@
 "use client";
 import { useSyncExternalStore } from "react";
 import { assistantSurfaceRegistry, } from "../core/surface-registry.js";
-// Arrow wrappers on purpose: the registry's methods are instance
-// methods, and useSyncExternalStore calls what it's given unbound. The
-// registry never registers on the server, so the live getter doubles as
-// the server snapshot (the frozen all-false presence).
 export function useAssistantSurfacePresence() {
     return useSyncExternalStore((listener) => assistantSurfaceRegistry.subscribe(listener), () => assistantSurfaceRegistry.getSnapshot(), () => assistantSurfaceRegistry.getSnapshot());
 }
-//# sourceMappingURL=use-assistant-surface-presence.js.map

package/dist/components/use-child-replay-stream.js

@@ -9,79 +9,21 @@ import { toolErrorRecorder, withToolErrorAnchored, } from "../core/tool-error-an
 import { ServingReplayStreamAgent } from "../transport/replay-stream-agent.js";
 import { streamUrlForChild } from "../transport/serving-api.js";
 import { resumeMarkerRecorder } from "../transport/stream-resume.js";
-// A child's log carries no THREAD markers — turn-level receipts are the
-// parent conversation's story. Tool errors and cancellations are
-// different: per-tool-call wire facts any run emits, recorded live below
-// so an errored search reads output-error, never a clean result. Resume
-// markers are the child's own too: a retried run activity writes
-// run_resumed under the CHILD's session id, and without the anchor the
-// severed attempt's open calls would read as running forever. Display
-// annotations stay empty deliberately: children run the worker's
-// toolbelt, not the client's annotated tools.
 const THREADLESS_ANCHORS = {
     turnFailedAnchors: new Map(),
     subagentDeliveryAnchors: new Map(),
     toolCallDisplayAnchors: new Map(),
-    // Schema anchors stay empty deliberately, the same law as the
-    // display annotations above: children run the worker's toolbelt (no
-    // display hook, so no tool_call_annotated markers) and render no
-    // approval cards, so a live recorder here would be dead code.
     toolSchemaAnchors: new Map(),
-    // Offload anchors stay empty deliberately, like display annotations:
-    // children run bespoke subagent harnesses that never mount the context
-    // offloader (only the agent/v1 compiler produces context "auto"), so a
-    // live recorder here would be dead code.
     toolOffloadAnchors: new Set(),
-    // Refusal anchors stay empty deliberately: the doors that refuse (the
-    // subagent family) never extend a child's belt — a child never
-    // dispatches, parks, or queries — so a live recorder here would be
-    // dead code, like the offload tap above.
     toolRefusalAnchors: new Map(),
-    // Decision anchors stay empty deliberately: a coworker's thread
-    // carries no member decisions — approvals and asks pause the PARENT
-    // turn, and their cards anchor to the parent's calls — so no decision
-    // marker can name a child call and no hold can go unheld here. Stated
-    // explicitly even though the snapshot field is optional (optional for
-    // the ./transcript composition surface's additivity): this ledger
-    // records a decision per family, and an omission reads as an
-    // oversight where an empty value reads as a ruling.
     toolDecisionAnchors: new Set(),
-    // Denial anchors stay empty for the same reason: with no approval
-    // ever anchored to a child call, no member can decline one — the same
-    // ruling as the decision line above, recorded rather than omitted.
     toolDenialAnchors: new Set(),
-    // Usage and provenance anchors stay empty: the drill-in panel renders
-    // no usage or provenance rows of its own — the parent transcript owns
-    // those reads. Block timing is different: the panel's run folds render
-    // "Worked for …" from it, so a live recorder folds it below beside the
-    // error/cancel taps.
     turnUsageAnchors: new Map(),
     memoryProvenanceAnchors: new Map(),
     memoryAttributionAnchors: new Map(),
 };
-// The page-wide child-stream budget: ONE live child tail beside the parent
-// stream and the 10s dispatches poll — under the browser's six-per-origin
-// cap. Module-scoped: the budget is the origin's. The pool QUEUES, it never
-// evicts: hosts mount ONE preview at a time, so switching cards UNMOUNTS the
-// previous preview — its cleanup unsubscribes every tap BEFORE abortRun(),
-// so a handoff never reaches the error funnel — and an overlapping second
-// host waits its turn. Capacity 1 stands: cards are ROWS fed by the one open
-// stream, not streams.
 const CHILD_TAIL_SLOTS = new TailSlotPool(1);
 export function useChildReplayStream({ session, threadId, childSessionId, refreshLedger, }) {
-    // ONE fact drives every flag below: how this panel's stream ended. The
-    // end-state table, the QUIET-ending rule (a body closing with no
-    // terminal is a dropped connection; REST is the authority, judged ONCE
-    // and LATCHED) and the UNREAD row (only an affirmative
-    // dispatchHasSettled reads clean) are in docs/transcript-surfaces.md,
-    // "The child panel's end-state table". The judge orders itself: on an
-    // error the ledger is caught up FIRST (the settle tap), then streamEnd
-    // lands "error", so an honest RUN_ERROR already reads failed when the
-    // banner question is asked. Any non-"open" end returns the tail slot;
-    // Retry re-opens. Deferred setters guard on the PANEL's lifetime
-    // (disposedRef), never the stream effect's own teardown — the ending
-    // trips that teardown itself, so an effect-scoped flag would drop the
-    // very verdict being delivered.
     const [messages, setMessages] = useState([]);
     const [streamEnd, setStreamEnd] = useState("open");
     const [attempt, setAttempt] = useState(0);
@@ -94,21 +36,7 @@ export function useChildReplayStream({ session, threadId, childSessionId, refres
     }, []);
     const [toolErrors, setToolErrors] = useState(() => new Map());
     const [toolCancels, setToolCancels] = useState(() => new Set());
-    // Resume anchors: the run_resumed marker a retried run activity
-    // writes under the child's own session id, anchored to the retry's
-    // first message. Copy-on-write like its siblings; never reset across
-    // Retry — re-anchoring the same message id is an idempotent re-set.
     const [resumeAnchors, setResumeAnchors] = useState(() => new Map());
-    // Block timing: the child's stored events carry the same emit-side
-    // server timestamps as the parent's, so its folds render a real
-    // "Worked for …" — never the unknown register on a surface that simply
-    // forgot to record. Copy-on-write like the error/cancel anchors above,
-    // deliberately NOT the parent store's mutate-in-place map: that idiom
-    // exists because a parent history is unbounded, while this panel
-    // replays one dispatch's bounded run — identity stays the change
-    // signal and no revision counter is needed. Never reset across Retry:
-    // the fold reduction is min/max idempotent, so a re-replayed sequence
-    // changes nothing.
     const [blockTimings, setBlockTimings] = useState(() => new Map());
     const { tailed, slotDenied } = useChildTailLease(streamEnd);
     useEffect(() => {
@@ -150,17 +78,6 @@ export function useChildReplayStream({ session, threadId, childSessionId, refres
         },
     };
 }
-// The lease lives exactly as long as the connection could (the
-// stop-wanting posture): acquired at mount — a settled
-// child's REPLAY still dials the stream door, so even it owes the
-// budget while its connection is in flight (the recorded adjudication)
-// — and released the moment the stream ENDS, not when the panel
-// closes, so a finished replay frees the capacity-1 slot in moments
-// instead of parking it for the length of the visit. Keyed by the
-// PANEL, never the child (the rows' own-toolCallId posture) — two
-// surfaces drilled into the SAME child are two streams, and a shared
-// id would collapse them into one holder whose first release kills the
-// survivor's tail with no waiter to promote.
 function useChildTailLease(streamEnd) {
     const leaseId = useId();
     useEffect(() => {
@@ -173,16 +90,9 @@ function useChildTailLease(streamEnd) {
         };
     }, [leaseId, streamEnd]);
     const tailed = useSyncExternalStore(CHILD_TAIL_SLOTS.subscribe, () => CHILD_TAIL_SLOTS.holds(leaseId), () => false);
-    // Asked and DENIED — queued behind a full pool. False both before the
-    // lease effect asks and after a promotion, so the waiting copy can
-    // never flash on an uncontended open (the acquire announces its own
-    // enqueue).
     const slotDenied = useSyncExternalStore(CHILD_TAIL_SLOTS.subscribe, () => CHILD_TAIL_SLOTS.waiting(leaseId), () => false);
     return { tailed, slotDenied };
 }
-// One attempt at the child stream: the agent, its taps, and the ending
-// judge. Returns the teardown — every tap unsubscribed BEFORE the abort,
-// so a handoff never reaches the error funnel.
 function openChildReplayStream({ session, threadId, childSessionId, refreshLedger, disposedRef, setStreamEnd, record, }) {
     const agent = new ServingReplayStreamAgent({
         streamUrl: streamUrlForChild(session, threadId, childSessionId),
@@ -190,27 +100,12 @@ function openChildReplayStream({ session, threadId, childSessionId, refreshLedge
         authorizedFetch: session.authorizedFetch,
     });
     const unsubscribeAnchorTaps = subscribeAnchorTaps(agent, record);
-    // The chassis splits this stream's two error shapes: a served
-    // RUN_ERROR (the child's honest terminal, verbatim or synthesized by
-    // the door) arrives as onRunErrorEvent WITH the connect promise
-    // still resolving, while only a transport death reaches onRunFailed
-    // (streamErrorRecorder; our own aborts are filtered there). Both are
-    // this stream's error ending, funneled once — and they OWN it: the
-    // settle handler may claim "clean" only when no error was seen, or
-    // it would overwrite the verdict a moment after it landed.
     let sawError = false;
     const endWithError = () => {
         if (sawError) {
             return;
         }
         sawError = true;
-        // A RUN_ERROR mid-watch is usually the child's HONEST terminal,
-        // not a dropped connection — but the ledger only learns on its
-        // 10s tick. Catch it up first, and only then land the error end
-        // (the table's judge order). Guarded on the PANEL's disposal:
-        // this very ending tears the stream effect down (end → lease
-        // released → tailed false), so an effect-scoped flag would drop
-        // the verdict — the unreachable-banner regression.
         void refreshLedger().finally(() => {
             if (!disposedRef.current) {
                 setStreamEnd("error");
@@ -218,13 +113,6 @@ function openChildReplayStream({ session, threadId, childSessionId, refreshLedge
         });
     };
     const errorTap = agent.subscribe(streamErrorRecorder(endWithError));
-    // The two facts the ending judge reads: whether THIS wire carried a
-    // terminal, and whether this effect run has already been torn down.
-    // `torn` guards ONLY the then-handler: an effect re-run's (or
-    // StrictMode's) aborted predecessor resolves through the client's
-    // swallowed-abort path and must not judge the successor's stream —
-    // while the error funnel above keeps its PANEL-lifetime guard, per
-    // the table's judge order (the unreachable-banner regression).
     let sawTerminal = false;
     let torn = false;
     const terminalTap = agent.subscribe({
@@ -232,11 +120,6 @@ function openChildReplayStream({ session, threadId, childSessionId, refreshLedge
             sawTerminal = true;
         },
         onRunErrorEvent({ event }) {
-            // The chassis synthesizes a RUN_ERROR coded "abort" when the body
-            // read is aborted — ours or the browser's. Never a served terminal
-            // (the door sets no code), so it is not this stream's verdict: the
-            // quiet-ending judge below reads the ledger instead. Matched on
-            // the code only — a child's honest sentence may say "aborted".
             if (event.code === "abort") {
                 return;
             }
@@ -251,25 +134,10 @@ function openChildReplayStream({ session, threadId, childSessionId, refreshLedge
             return;
         }
         if (sawTerminal) {
-            // A clean ending is the settle signal: the ledger catches up
-            // now, not at the next tick, and the ended stream returns its
-            // tail slot (a waiting sibling panel is promoted) — the error
-            // path does the same through the funnel above, after its
-            // catch-up.
             void refreshLedger();
             setStreamEnd("clean");
             return;
         }
-        // The QUIET ending (the table's quiet rows): the body closed with
-        // no terminal at all. Ledger first — the tap resolves with the row
-        // it landed — then the verdict is judged ONCE against that row
-        // and LATCHED as an ordinary ending. The question is AFFIRMATIVE
-        // (the table's UNREAD row): only a ledger that says settled reads
-        // clean; a still-dispatched row and no row at all both read as
-        // the error ending, banner and Retry. Never left to a live
-        // render-time read of the row, which un-painted the banner on the
-        // next ledger tick over a replay truncated at the drop;
-        // the error ending has always latched this way.
         void refreshLedger().then((row) => {
             if (disposedRef.current || torn) {
                 return;
@@ -287,9 +155,6 @@ function openChildReplayStream({ session, threadId, childSessionId, refreshLedge
         void agent.detachActiveRun().catch(() => undefined);
     };
 }
-// The recorders that turn the child's wire into anchored state: messages,
-// tool errors, tool cancellations, resume markers, block timing. Returns
-// the one unsubscribe for all five taps.
 function subscribeAnchorTaps(agent, record) {
     const messagesTap = agent.subscribe(messagesRecorder(record.setMessages));
     const errorAnchorTap = agent.subscribe(toolErrorRecorder((toolCallId, errorText) => {
@@ -298,16 +163,7 @@ function subscribeAnchorTaps(agent, record) {
     const cancelAnchorTap = agent.subscribe(toolCancelRecorder((toolCallId) => {
         record.setToolCancels((previous) => withToolCancelAnchored(previous, toolCallId));
     }));
-    const resumeAnchorTap = agent.subscribe(
-    // The run id (the STORE-side arbitration key's first component)
-    // is unused here on purpose: this preview's agent is never
-    // snapshot-seeded — every open is a full replay into fresh
-    // component state — so the seeded-replay re-delivery window does
-    // not exist and the message-id gate below stays sufficient.
-    resumeMarkerRecorder((_runId, messageId, markerValue) => {
-        // Identity is the publish gate, like the sibling anchor taps: a
-        // replayed re-anchor of the same message id (StrictMode's double
-        // mount, Retry) must not re-derive the whole row projection.
+    const resumeAnchorTap = agent.subscribe(resumeMarkerRecorder((_runId, messageId, markerValue) => {
         record.setResumeAnchors((previous) => previous.has(messageId)
             ? previous
             : new Map(previous).set(messageId, markerValue));
@@ -328,4 +184,3 @@ function subscribeAnchorTaps(agent, record) {
         timingAnchorTap.unsubscribe();
     };
 }
-//# sourceMappingURL=use-child-replay-stream.js.map

package/dist/components/use-latest-ref.js

@@ -1,8 +1,5 @@
 "use client";
 import { useEffect, useRef } from "react";
-/** A ref that holds the latest committed value: written at commit time
- *  (every commit, never during render), so an effect that must reach the
- *  newest callback or label without re-running reads it from here. */
 export function useLatestRef(value) {
     const ref = useRef(value);
     useEffect(() => {
@@ -10,4 +7,3 @@ export function useLatestRef(value) {
     });
     return ref;
 }
-//# sourceMappingURL=use-latest-ref.js.map

package/dist/components/use-member-toggle-outrank.js

@@ -1,44 +1,5 @@
 "use client";
 import { useEffect, useRef, useState, } from "react";
-/**
- * The member's outrank, permanent for the fold: one explicit toggle of
- * the fold's OWN summary pins the disclosure to native <details> for the
- * component's lifetime — a later view-bearing call, a fresh decision, a
- * first failure, and the decay release all stop writing the open
- * attribute. The pin is session state, not derived state: it records the
- * member's gesture, which no replay re-derives (Law 9 governs the DEFAULT
- * state).
- *
- * The gesture is recognized in TWO stages: the capture click on the
- * group wrapper writes a REF only — keyboard activation dispatches the
- * same click, and only the fold's own summary matches (a member row's
- * summary has its own parent <details>) — and the state flips from the
- * fold <details>' own toggle event. Committing state in the capture
- * handler races the summary's activation behaviour: React 19 flushes a
- * discrete update at the microtask checkpoint the browser reaches DURING
- * propagation, so on a held-open fold the commit would remove the open
- * attribute before the activation behaviour ran — which then toggles the
- * now-absent attribute back ON, swallowing the member's collapse.
- *
- * The premise this ordering rests on: the DOM queues the toggle event
- * AFTER the activation behaviour has applied the attribute change
- * (HTML's details toggle steps), so by the time the pin commits, the
- * <details> already holds the member's chosen state — and the pin's own
- * re-render releases the prop to undefined, whose only DOM effect is
- * removing an attribute the collapse case has already removed (a no-op
- * writes no mutation and queues no second toggle). In the window between
- * the activation and the toggle task, an unrelated re-render still holds
- * the prop's OLD value — and React re-writes the open attribute only on
- * a prop VALUE change (see primitives/disclosure.tsx), so it cannot fight
- * the member there either. preventDefault is no fix: it would keep a
- * held fold collapsible and make a decayed fold un-expandable.
- *
- * The census of every activation handler in the class this guards is
- * the activation-commit class census record.
- *
- * `groupRef` goes on the group wrapper, `onGroupActivation` on its
- * capture click; the fold's <details> must be the wrapper's direct child.
- */
 export function useMemberToggleOutrank() {
     const groupRef = useRef(null);
     const [memberToggled, setMemberToggled] = useState(false);
@@ -56,11 +17,6 @@ export function useMemberToggleOutrank() {
         if (details === null || details === undefined) {
             return;
         }
-        // toggle does not bubble, so the listener rides the <details>
-        // itself (the element is stable for this component's lifetime).
-        // Programmatic toggles — decay's release, an arrival's re-open —
-        // find the ref unarmed and commit nothing; the member's activation
-        // is the only path that arms it, and its own toggle consumes it.
         const commitMemberToggle = () => {
             if (memberToggleIntentRef.current) {
                 memberToggleIntentRef.current = false;
@@ -74,4 +30,3 @@ export function useMemberToggleOutrank() {
     }, []);
     return { groupRef, memberToggled, onGroupActivation };
 }
-//# sourceMappingURL=use-member-toggle-outrank.js.map

package/dist/components/use-perch-clearance.js

@@ -1,26 +1,7 @@
 "use client";
 import { useEffect } from "react";
 import { firstClearLiftFor, INTERACTIVE_OBSTRUCTION_SELECTOR, } from "../core/perch-clearance.js";
-/**
- * Collision awareness for the fixed corner perch: a page that already
- * owns the corner — a composer's send button, a copy control — must keep
- * its clicks. The hook probes what the page stacks beneath the perch's
- * hit box (document.elementsFromPoint sees through the top layer) and
- * lifts the dock by the smallest clear step (core/perch-clearance owns
- * the verdict). Re-measured on resize, any scroll, and DOM mutations —
- * route swaps included — all coalesced to one measurement per frame.
- * Browsers without elementsFromPoint keep the unlifted corner; the
- * transparent dock itself never obstructs anything (pointer-events:
- * none).
- */
-// How long the settle fallback waits out the dock's 180ms bottom glide
-// when transitionend cannot fire, with room for a busy frame.
 const LIFT_SETTLE_FALLBACK_MS = 400;
-// When the dock lives inside a shadow root (the script-tag custom
-// element), document.elementsFromPoint retargets in-shadow hits to the
-// shadow host — an element the dock neither contains nor shares a tree
-// with, so the self-exclusion checks below can't recognize it and the
-// dock would read itself as an obstruction.
 function _shadowHostChainOf(node) {
     const hosts = [];
     let root = node.getRootNode();
@@ -39,9 +20,6 @@ export function usePerchClearance(dockRef, active) {
         return _watchPerchClearance(dock);
     }, [dockRef, active]);
 }
-/** Whether the PAGE stacks an interactive control under a point: the
- *  dock's own elements, its shadow hosts and every other assistant
- *  surface are never obstructions. */
 function _hostObstructionProbeFor(dock) {
     const doc = dock.ownerDocument;
     const shadowHostsOfDock = _shadowHostChainOf(dock);
@@ -52,11 +30,6 @@ function _hostObstructionProbeFor(dock) {
         element.closest("[data-tf-assistant]") === null &&
         element.closest(INTERACTIVE_OBSTRUCTION_SELECTOR) !== null);
 }
-// The dock's one click target: the mark's hit box.
-// The rect is re-based to lift 0 (the natural corner) so the verdict is
-// absolute, not relative to wherever the dock sits right now — valid
-// because a settled dock sits exactly at appliedLift. Null while the
-// box has no size (unmounted, or a dock the browser never showed).
 function _hitBoxRectOf(dock, appliedLift) {
     const body = dock.querySelector("[data-tf-companion-body]");
     if (body === null) {
@@ -73,8 +46,6 @@ function _hitBoxRectOf(dock, appliedLift) {
         height: rect.height,
     };
 }
-/** Measures, lifts and re-measures the dock for as long as it is shown;
- *  returns the teardown. */
 function _watchPerchClearance(dock) {
     const doc = dock.ownerDocument;
     if (typeof doc.elementsFromPoint !== "function") {
@@ -83,10 +54,6 @@ function _watchPerchClearance(dock) {
     const view = doc.defaultView ?? window;
     let frame = null;
     let appliedLift = 0;
-    // A lift change glides there over the dock's bottom transition, and
-    // getBoundingClientRect reads the in-flight position — re-basing with
-    // appliedLift is only exact once the glide lands. While settling,
-    // every trigger defers to the single post-settle measure.
     let settling = false;
     let settleTimer = null;
     const hostObstructionAt = _hostObstructionProbeFor(dock);
@@ -104,10 +71,6 @@ function _watchPerchClearance(dock) {
             appliedLift = lift;
             settling = true;
             dock.style.setProperty("--_tf-companion-lift", `${String(lift)}px`);
-            // Belt-and-braces settle: transitionend is the precise clock, but
-            // it never fires when the transition doesn't run (a hidden dock,
-            // a browser without the property) — the timer outlasts the 180ms
-            // glide either way.
             settleTimer = view.setTimeout(settle, LIFT_SETTLE_FALLBACK_MS);
         }
     };
@@ -117,8 +80,6 @@ function _watchPerchClearance(dock) {
         }
         frame ??= view.requestAnimationFrame(measure);
     };
-    // Landing re-measures once: anything the page did mid-glide was
-    // deferred, and the verdict must be re-checked from exact geometry.
     const settle = () => {
         if (!settling) {
             return;
@@ -160,4 +121,3 @@ function _watchPerchClearance(dock) {
         dock.style.removeProperty("--_tf-companion-lift");
     };
 }
-//# sourceMappingURL=use-perch-clearance.js.map