@teaflask/assistant 0.3.0 → 0.6.0

package/dist/core/memory-provenance-anchors.d.ts

@@ -1,70 +1,19 @@
 import type { AgentSubscriber } from "@ag-ui/client";
 export interface MemoryUpdated {
     memoryId: string;
-    /** Open vocabulary: "org" | "user" today; render unknowns generically. */
     scope: string;
-    /** The canned human sentence — never the memory's content. */
     summary: string;
 }
 export declare const EMPTY_MEMORY_PROVENANCE_ANCHORS: ReadonlyMap<string, MemoryUpdated>;
-/**
- * Narrow a memory_updated marker's value. Null means ignore — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize": without its durable id the row has no reconcile key, and
- * without a sentence there is nothing safe to show.
- */
 export declare function memoryUpdatedAnchorOf(value: unknown): MemoryUpdated | null;
-/**
- * Reconcile-by-id, never append: the first anchor for a memory id wins,
- * so every replay re-delivery — and any delayed duplicate — is a no-op.
- * Insertion order is stream order, which is how consumers list the rows.
- */
 export declare function withMemoryUpdateAnchored(previous: ReadonlyMap<string, MemoryUpdated>, update: MemoryUpdated): ReadonlyMap<string, MemoryUpdated>;
-/**
- * A defensive copy for seeding from the resume store: entries that are
- * not a well-formed provenance record are dropped rather than rendered —
- * a dropped entry becomes a missing row until the next full replay,
- * never a crash.
- */
 export declare function wellFormedMemoryProvenanceAnchorsOf(stored: ReadonlyMap<string, MemoryUpdated>): ReadonlyMap<string, MemoryUpdated>;
 export declare const EMPTY_MEMORY_ATTRIBUTION_ANCHORS: ReadonlyMap<string, string>;
-/**
- * Reconcile-by-id, never move: the first message a memory id attributes
- * to wins, so a re-delivery flushing against a drifted message list is a
- * no-op — identical map identity, the anchor family's arbitration law.
- */
 export declare function withMemoryAttributed(previous: ReadonlyMap<string, string>, memoryId: string, messageId: string): ReadonlyMap<string, string>;
-/**
- * A defensive copy for seeding from the resume store: pairs that are not
- * two non-empty strings are dropped rather than rendered — a dropped
- * pair becomes a missing footer until the next full replay, never a
- * crash.
- */
 export declare function wellFormedMemoryAttributionAnchorsOf(stored: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
-/**
- * The footer projection: provenance records grouped under the message
- * each one attributed to, in stream order (the provenance map's
- * insertion order). A record without attribution is skipped — an old
- * history renders no footer rather than a synthesized one.
- */
 export declare function memoryFootersOf(provenance: ReadonlyMap<string, MemoryUpdated>, attribution: ReadonlyMap<string, string>): ReadonlyMap<string, MemoryUpdated[]>;
-/** The recorder's two write channels: the provenance record itself, and
- *  the message id its footer renders under. */
 export interface MemoryUpdatedRecorderSink {
     onMemoryAnchored: (update: MemoryUpdated) => void;
     onMemoryAttributed: (memoryId: string, messageId: string) => void;
 }
-/**
- * Records each memory_updated marker's memory id → narrowed payload, and
- * attributes each write to the assistant prose message whose run caused
- * it. Attribution follows the receipt-family stream-position idiom
- * (core/receipt-anchors.ts): writes observed while the run is live
- * buffer and flush at the terminal against the run's own newest prose;
- * a run that authored no prose drops its buffer honestly (the annotated
- * tool row still tells the story, and an earlier turn's prose must never
- * adopt this turn's write). A marker arriving AFTER the terminal — the
- * settled-then-provenance arrival a reconnect tail produces — attributes
- * immediately, so the footer engages without waiting for another event.
- */
 export declare function memoryUpdatedRecorder(sink: MemoryUpdatedRecorderSink): AgentSubscriber;
-//# sourceMappingURL=memory-provenance-anchors.d.ts.map

package/dist/core/memory-provenance-anchors.js

@@ -1,41 +1,8 @@
-// The memory-provenance anchor model, pure of React: the recorder maps
-// each memory_updated CUSTOM marker to its durable memory id, consumers
-// read the map to show quiet "saved a memory" provenance rows, and the
-// resume store holds the map across remounts (the marker never becomes a
-// message, and a snapshot-seeded reconnect replays only past the
-// cursor). The memory id is the reconcile key — a replayed or delayed
-// re-delivery updates nothing and appends nothing, so one write is ever
-// one row. The payload is end-user safe by wire contract (a canned
-// sentence, a scope token, an id — never the memory's content), and the
-// narrower distrusts it anyway.
-//
-// ATTRIBUTION rides beside the provenance records: which
-// assistant prose message each write's footer renders under. The marker
-// deliberately carries no tool_call_id or message id (the store seam
-// sits below the tool layer), so the recorder anchors by stream
-// position — the receipt-family idiom: writes buffered during a run
-// flush to that run's newest assistant prose at the terminal, and a
-// marker arriving after the terminal attributes immediately. First
-// attribution wins, keyed by the durable memory id, so re-deliveries
-// against a drifted message list reconcile instead of moving the footer
-// (the anchor family's drifted-message arbitration law). A history whose markers were
-// recorded without attribution simply renders no footer — attribution
-// is evidence, never synthesized.
 import { MEMORY_UPDATED_EVENT_NAME } from "../contract/events.js";
 import { newestAssistantProseIdOf } from "./assistant-prose.js";
-// The summary is a backend-authored canned sentence; a runaway one is
-// retained capped, never unbounded (the display-text posture).
 const SUMMARY_MAX_CHARS = 500;
-// Scope is an open single-word vocabulary ("org", "user"); unknown
-// tokens survive verbatim capped — the renderer owns the fallback.
 const TOKEN_MAX_CHARS = 64;
 export const EMPTY_MEMORY_PROVENANCE_ANCHORS = new Map();
-/**
- * Narrow a memory_updated marker's value. Null means ignore — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize": without its durable id the row has no reconcile key, and
- * without a sentence there is nothing safe to show.
- */
 export function memoryUpdatedAnchorOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -56,11 +23,6 @@ export function memoryUpdatedAnchorOf(value) {
         summary: summary.slice(0, SUMMARY_MAX_CHARS),
     };
 }
-/**
- * Reconcile-by-id, never append: the first anchor for a memory id wins,
- * so every replay re-delivery — and any delayed duplicate — is a no-op.
- * Insertion order is stream order, which is how consumers list the rows.
- */
 export function withMemoryUpdateAnchored(previous, update) {
     if (previous.has(update.memoryId)) {
         return previous;
@@ -69,12 +31,6 @@ export function withMemoryUpdateAnchored(previous, update) {
     next.set(update.memoryId, update);
     return next;
 }
-/**
- * A defensive copy for seeding from the resume store: entries that are
- * not a well-formed provenance record are dropped rather than rendered —
- * a dropped entry becomes a missing row until the next full replay,
- * never a crash.
- */
 export function wellFormedMemoryProvenanceAnchorsOf(stored) {
     const seeded = new Map();
     const entries = stored;
@@ -87,11 +43,6 @@ export function wellFormedMemoryProvenanceAnchorsOf(stored) {
     return seeded;
 }
 export const EMPTY_MEMORY_ATTRIBUTION_ANCHORS = new Map();
-/**
- * Reconcile-by-id, never move: the first message a memory id attributes
- * to wins, so a re-delivery flushing against a drifted message list is a
- * no-op — identical map identity, the anchor family's arbitration law.
- */
 export function withMemoryAttributed(previous, memoryId, messageId) {
     if (previous.has(memoryId)) {
         return previous;
@@ -100,12 +51,6 @@ export function withMemoryAttributed(previous, memoryId, messageId) {
     next.set(memoryId, messageId);
     return next;
 }
-/**
- * A defensive copy for seeding from the resume store: pairs that are not
- * two non-empty strings are dropped rather than rendered — a dropped
- * pair becomes a missing footer until the next full replay, never a
- * crash.
- */
 export function wellFormedMemoryAttributionAnchorsOf(stored) {
     const seeded = new Map();
     const entries = stored;
@@ -120,12 +65,6 @@ export function wellFormedMemoryAttributionAnchorsOf(stored) {
     }
     return seeded;
 }
-/**
- * The footer projection: provenance records grouped under the message
- * each one attributed to, in stream order (the provenance map's
- * insertion order). A record without attribution is skipped — an old
- * history renders no footer rather than a synthesized one.
- */
 export function memoryFootersOf(provenance, attribution) {
     const footers = new Map();
     for (const [memoryId, update] of provenance) {
@@ -143,34 +82,8 @@ export function memoryFootersOf(provenance, attribution) {
     }
     return footers;
 }
-/**
- * Records each memory_updated marker's memory id → narrowed payload, and
- * attributes each write to the assistant prose message whose run caused
- * it. Attribution follows the receipt-family stream-position idiom
- * (core/receipt-anchors.ts): writes observed while the run is live
- * buffer and flush at the terminal against the run's own newest prose;
- * a run that authored no prose drops its buffer honestly (the annotated
- * tool row still tells the story, and an earlier turn's prose must never
- * adopt this turn's write). A marker arriving AFTER the terminal — the
- * settled-then-provenance arrival a reconnect tail produces — attributes
- * immediately, so the footer engages without waiting for another event.
- */
 export function memoryUpdatedRecorder(sink) {
     let runLive = false;
-    // The newest assistant prose id, and whether it changed since the
-    // current run started — the "this run authored prose" evidence the
-    // flush needs. The BASELINE is taken at RUN_STARTED from the params'
-    // own message list (AgentSubscriberParams.messages — the pre-run
-    // list; the pipeline appends nothing before that callback and its
-    // verifier requires RUN_STARTED to be a run's first event), because a
-    // fresh epoch's agent is SEEDED with history rather than replaying
-    // it: no onMessagesChanged fires between onRunInitialized and
-    // RUN_STARTED, so a null baseline would make the run's first message
-    // change read the seeded history's old prose as "authored this run"
-    // and hand the previous turn's message this run's writes — sticky
-    // across replays, since attribution is first-wins. Deliberately NOT
-    // reset at the terminal: the post-settle arrival arm still needs to
-    // know the settled run's prose was fresh.
     let newestProseId = null;
     let proseThisRun = false;
     let pending = [];
@@ -183,10 +96,6 @@ export function memoryUpdatedRecorder(sink) {
         pending = [];
     };
     return {
-        // One agent can be connected more than once (StrictMode detaches the
-        // first run terminal-free and starts over): writes a dead connection
-        // buffered but never flushed must not ride into the replacement's
-        // flush — the receipt recorders' same guard.
         onRunInitialized() {
             runLive = false;
             newestProseId = null;
@@ -218,7 +127,6 @@ export function memoryUpdatedRecorder(sink) {
                 pending.push(update.memoryId);
             }
             else if (newestProseId !== null && proseThisRun) {
-                // Post-settle arrival: no further event will flush for us.
                 sink.onMemoryAttributed(update.memoryId, newestProseId);
             }
         },
@@ -244,4 +152,3 @@ function _isWellFormedUpdate(update) {
         typeof summary === "string" &&
         summary !== "");
 }
-//# sourceMappingURL=memory-provenance-anchors.js.map

package/dist/core/messages-cell.d.ts

@@ -2,16 +2,10 @@ import type { AgentSubscriber } from "@ag-ui/client";
 import type { Message } from "@ag-ui/core";
 export declare function messagesRecorder(publish: (messages: readonly Message[]) => void): AgentSubscriber;
 export declare function streamErrorRecorder(onStreamError: (error: Error) => void): AgentSubscriber;
-/** Whether an error is our own abort wearing one of the runtime's spellings
- *  — the DOMException name, or a message saying so. Matches the message on
- *  purpose: the chassis rejects with plain Errors carrying those sentences. */
 export declare function isAbortShaped(error: Error): boolean;
 export interface MessagesSnapshot {
     messages: readonly Message[];
-    /** True while a run streams — drives the streaming-markdown repair and
-     *  the still-pending tool read. */
     running: boolean;
 }
 export declare function messagesSnapshotRecorder(publish: (snapshot: MessagesSnapshot) => void): AgentSubscriber;
 export declare function connectionErrorRecorder(onStreamError: (error: Error) => void): AgentSubscriber;
-//# sourceMappingURL=messages-cell.d.ts.map

package/dist/core/messages-cell.js

@@ -1,8 +1,3 @@
-// The owned message list's wire tap: the AbstractAgent maintains
-// `agent.messages` itself; this recorder mirrors every change into the cell.
-// onMessagesChanged fires per APPLIED event (deltas included) plus
-// initialize/finalize/error and setMessages. The pipeline REUSES its array
-// and mutates in place: publish shallow copies; never memo on message identity.
 export function messagesRecorder(publish) {
     return {
         onMessagesChanged({ messages }) {
@@ -10,10 +5,6 @@ export function messagesRecorder(publish) {
         },
     };
 }
-// The connection's error tap: only a transport death reaches onRunFailed (a
-// dead fetch, a non-2xx, a protocol refusal, a body that errored mid-read);
-// a served RUN_ERROR surfaces as onRunErrorEvent, which the surfaces
-// subscribe themselves. Aborts are OUR OWN doing and never paint the banner.
 export function streamErrorRecorder(onStreamError) {
     return {
         onRunFailed({ error }) {
@@ -24,16 +15,9 @@ export function streamErrorRecorder(onStreamError) {
         },
     };
 }
-/** Whether an error is our own abort wearing one of the runtime's spellings
- *  — the DOMException name, or a message saying so. Matches the message on
- *  purpose: the chassis rejects with plain Errors carrying those sentences. */
 export function isAbortShaped(error) {
     return error.name === "AbortError" || /\baborted?\b/i.test(error.message);
 }
-// messagesRecorder's wire tap plus the run bit. isRunning flips outside
-// message changes too (a run can start or settle without a delta), so the
-// three run-edge hooks mirror those edges and the pending read and repair
-// windows track the run, not the last delta.
 export function messagesSnapshotRecorder(publish) {
     return {
         onMessagesChanged({ agent, messages }) {
@@ -50,11 +34,6 @@ export function messagesSnapshotRecorder(publish) {
         },
     };
 }
-// The connection-owning surface's error tap: a pre-stream failure or an
-// event-verify error arrives as onRunFailed; a mid-stream transport death is
-// SYNTHESIZED by @ag-ui/client into a RUN_ERROR event (onRunFailed never
-// fires for it), so onRunErrorEvent carries it, along with genuine and
-// replayed failed-run terminals, which the hosts absorb. Aborts paint no banner.
 export function connectionErrorRecorder(onStreamError) {
     return {
         onRunFailed({ error }) {
@@ -68,4 +47,3 @@ export function connectionErrorRecorder(onStreamError) {
         },
     };
 }
-//# sourceMappingURL=messages-cell.js.map

package/dist/core/observable-cell.d.ts

@@ -10,4 +10,3 @@ export declare class ObservableCell<T> implements ReadonlyCell<T> {
     set(next: T): void;
     subscribe: (listener: () => void) => (() => void);
 }
-//# sourceMappingURL=observable-cell.d.ts.map

package/dist/core/observable-cell.js

@@ -1,17 +1,9 @@
-// The store's observation primitive: a cached snapshot plus change
-// notification, the exact contract `useSyncExternalStore` binds to. The
-// snapshot's identity changes only when a new value is set, so React (or
-// any other subscriber) can compare by reference; publishers must set a
-// cell only when state actually changed — the inbox classes' did-change
-// booleans are what gate those writes.
 export class ObservableCell {
     value;
     listeners = new Set();
     constructor(initial) {
         this.value = initial;
     }
-    // Arrow fields on purpose: get/subscribe travel unbound into
-    // useSyncExternalStore and any other subscriber wiring.
     get = () => {
         return this.value;
     };
@@ -31,4 +23,3 @@ export class ObservableCell {
         };
     };
 }
-//# sourceMappingURL=observable-cell.js.map

package/dist/core/pending-decision-gap.d.ts

@@ -1,16 +1,4 @@
 import type { AssistantTurnStatus } from "../generated/models/assistantTurnStatus.js";
-/** The five turn fields the derivation reads — structural on purpose,
- *  so both callers assign with zero casts: the widget store
- *  passes the widget's generated ServingAssistantTurn (pause fields
- *  required), the dashboard playground its own generated
- *  AssistantTurnResponse (pause fields generated optional, though the
- *  server always supplies them). The optional array makes the type tell
- *  the truth the runtime tolerance below already pins. `status` keeps
- *  the generated union, not string: the two literal
- *  comparisons below stay compile-checked, both generated status types
- *  are the identical union so assignability costs nothing, and the day
- *  the dashboard's union drifts from this one the playground call site
- *  fails to compile — the loud drift signal, not a silent never-fires. */
 export interface GapJudgeableTurn {
     id: string;
     status: AssistantTurnStatus;
@@ -18,48 +6,25 @@ export interface GapJudgeableTurn {
     pending_interrupt_ids?: readonly string[];
     unservable_interrupt_ids?: readonly string[];
 }
-/** Representation is by interruptId, any holder — structural so the
- *  playground's refusal entries (not the widget's ExecutionEntryModel)
- *  count as holders without a cast that would break silently the day
- *  the derivation read a second field. */
 interface InterruptHolder {
     interruptId: string;
 }
 export interface PendingDecisionGap {
     turnId: string;
-    /** The pending interrupt ids nothing on this client answers for. */
     missingInterruptIds: readonly string[];
 }
 export declare function pendingDecisionGapOf(turn: GapJudgeableTurn | null, approvalCards: readonly InterruptHolder[], elicitationCards: readonly InterruptHolder[], executionEntries: readonly InterruptHolder[], consumedInterruptIds?: ReadonlySet<string>): PendingDecisionGap | null;
-/** Content identity for publish dedupe and the grace probe's scope: one
- *  gap per (turn, missing set), order-insensitive. */
 export declare function gapSignatureOf(gap: PendingDecisionGap): string;
 export declare const GAP_PROBE_SETTLE_MS = 2000;
 export interface PendingDecisionGapGateDeps {
-    /** Receives the loud gap, or null when the gap clears. */
     publish: (gap: PendingDecisionGap | null) => void;
-    /** One best-effort re-read per signature — never a gate on the timer,
-     *  which is the alert's only liveness driver. */
     probe: () => void;
-    /** Whether the evidence channel has had its chance — read at elapse,
-     *  never latched here, because the two owners' evidence differs in
-     *  shape: the widget store's epoch-connected-once record resets per
-     *  connection epoch, while the playground transcript's replay-finalized
-     *  latch is monotonic for the mount. Until it answers true, an elapsed
-     *  window re-arms as a quiet heartbeat instead of alarming. */
     evidenceSettled: () => boolean;
 }
-/**
- * The per-signature grace window over the evidence predicate. States:
- * quiet | armed(sig) | loud(sig), crossed with `evidenceSettled` read at
- * elapse; every transition is enumerated in docs/decision-anchors.md.
- */
 export declare class PendingDecisionGapGate {
     private readonly deps;
     private timer;
-    /** The signature the armed window judges, or null when quiet. */
     private armedSignature;
-    /** The last judged gap — what the window publishes if it elapses. */
     private judged;
     private loudSignature;
     constructor(deps: PendingDecisionGapGateDeps);
@@ -69,4 +34,3 @@ export declare class PendingDecisionGapGate {
     private _disarm;
 }
 export {};
-//# sourceMappingURL=pending-decision-gap.d.ts.map

package/dist/core/pending-decision-gap.js

@@ -1,7 +1,3 @@
-// The pending-decision gap: the server says the turn waits on
-// named interrupts and this client holds NOTHING that answers for one —
-// no card, no execution-inbox entry — so the gap must be loud. The premise
-// and the two server-asserted non-gap subsets: docs/decision-anchors.md.
 const EMPTY_CONSUMED_IDS = new Set();
 export function pendingDecisionGapOf(turn, approvalCards, elicitationCards, executionEntries, consumedInterruptIds = EMPTY_CONSUMED_IDS) {
     if (turn === null) {
@@ -13,9 +9,6 @@ export function pendingDecisionGapOf(turn, approvalCards, elicitationCards, exec
     if (turn.run_id === null || !Array.isArray(turn.pending_interrupt_ids)) {
         return null;
     }
-    // Representation by id, whatever the holder's status: a held card —
-    // even answered or stale — renders its own truthful state, and a
-    // claimed execution entry is the driver's to answer.
     const represented = new Set();
     for (const card of approvalCards) {
         represented.add(card.interruptId);
@@ -26,15 +19,9 @@ export function pendingDecisionGapOf(turn, approvalCards, elicitationCards, exec
     for (const entry of executionEntries) {
         represented.add(entry.interruptId);
     }
-    // The server's own non-gap assertion: no card can ever be served for
-    // these ids, so a wait must not be presented. Tolerates any non-array
-    // shape (an older server omits the field) — never a false subtraction.
     const unservable = new Set(Array.isArray(turn.unservable_interrupt_ids)
         ? turn.unservable_interrupt_ids.filter((id) => typeof id === "string")
         : []);
-    // The per-element string guard mirrors the unservable filter's (and
-    // regains the narrowing Array.isArray cannot give a readonly array):
-    // a non-string element is wire garbage, never a missing id.
     const missing = turn.pending_interrupt_ids.filter((id) => typeof id === "string" &&
         !represented.has(id) &&
         !consumedInterruptIds.has(id) &&
@@ -44,29 +31,14 @@ export function pendingDecisionGapOf(turn, approvalCards, elicitationCards, exec
     }
     return { turnId: turn.id, missingInterruptIds: missing };
 }
-/** Content identity for publish dedupe and the grace probe's scope: one
- *  gap per (turn, missing set), order-insensitive. */
 export function gapSignatureOf(gap) {
     return `${gap.turnId}:${[...gap.missingInterruptIds].sort().join(",")}`;
 }
-// The gap's settle window: how long the evidence channel gets to
-// land its recorded interrupts (execution entries, elicitations) before a
-// gap the best-effort re-read could not close goes loud. A hard timer,
-// deliberately not a wait on any stream OR network event — boundedness is
-// the alert's liveness guarantee, and neither door's transport aborts a
-// stalled request.
 export const GAP_PROBE_SETTLE_MS = 2_000;
-/**
- * The per-signature grace window over the evidence predicate. States:
- * quiet | armed(sig) | loud(sig), crossed with `evidenceSettled` read at
- * elapse; every transition is enumerated in docs/decision-anchors.md.
- */
 export class PendingDecisionGapGate {
     deps;
     timer = null;
-    /** The signature the armed window judges, or null when quiet. */
     armedSignature = null;
-    /** The last judged gap — what the window publishes if it elapses. */
     judged = null;
     loudSignature = null;
     constructor(deps) {
@@ -127,4 +99,3 @@ export class PendingDecisionGapGate {
         this.armedSignature = null;
     }
 }
-//# sourceMappingURL=pending-decision-gap.js.map

package/dist/core/perch-clearance.d.ts

@@ -8,31 +8,12 @@ export interface ClearanceRect {
     width: number;
     height: number;
 }
-/** The lifts tried, in order — 0 first, so an unobstructed corner never
- *  moves. Steps of roughly a control's height; capped so a page that is
- *  interactive everywhere gets the corner back instead of a perch chasing
- *  clearance up the viewport. */
 export declare const PERCH_LIFT_STEPS_PX: readonly number[];
-/** The corners and center of a rect — five probes decide a rect. */
 export declare function probePointsOf(rect: ClearanceRect): ClearancePoint[];
 export declare function liftedBy(rect: ClearanceRect, liftPx: number): ClearanceRect;
-/**
- * The verdict: the smallest lift step at which no probe point over the
- * perch's hit box hits an obstruction. Falls back to 0 — never a partial
- * lift — when every step is obstructed or a step would push the box off
- * the top of the viewport: on a page that gives the corner no clearance
- * anywhere, a perch parked where the user expects it beats one that
- * wandered.
- */
 export declare function firstClearLiftFor(options: {
-    /** The perch's hit box at lift 0 (its natural position). */
     rect: ClearanceRect;
-    /** Whether the page stacks an interactive obstruction at a viewport
-     *  point, with the dock's own elements already excluded by the caller. */
     probe: (point: ClearancePoint) => boolean;
     liftSteps?: readonly number[];
 }): number;
-/** What counts as the host's interactive surface under a probe point.
- *  Anything a click would activate; label pulls in its control. */
 export declare const INTERACTIVE_OBSTRUCTION_SELECTOR: string;
-//# sourceMappingURL=perch-clearance.d.ts.map

package/dist/core/perch-clearance.js

@@ -1,21 +1,5 @@
-// The dock's collision awareness: a
-// fixed corner perch dropped onto a page that already owns that corner —
-// a composer's send button, a copy control — steals the host's clicks.
-// The cure is a lift: the widget probes what the page stacks under the
-// perch's hit box and raises the dock in fixed steps until nothing
-// interactive sits beneath. This module is the pure half — the
-// geometry and the verdict — so the decision is exhaustively testable;
-// the widget owns the DOM probing (document.elementsFromPoint) and the
-// re-measure clocks (resize, scroll, mutations).
-/** The lifts tried, in order — 0 first, so an unobstructed corner never
- *  moves. Steps of roughly a control's height; capped so a page that is
- *  interactive everywhere gets the corner back instead of a perch chasing
- *  clearance up the viewport. */
 export const PERCH_LIFT_STEPS_PX = [0, 56, 112, 168];
-/** How far probe points pull in from a rect's edges, so a rounded corner
- *  or a hairline neighbour never reads as an obstruction. */
 const PROBE_EDGE_INSET_PX = 3;
-/** The corners and center of a rect — five probes decide a rect. */
 export function probePointsOf(rect) {
     const left = rect.left + PROBE_EDGE_INSET_PX;
     const right = rect.left + rect.width - PROBE_EDGE_INSET_PX;
@@ -34,14 +18,6 @@ export function probePointsOf(rect) {
 export function liftedBy(rect, liftPx) {
     return { ...rect, top: rect.top - liftPx };
 }
-/**
- * The verdict: the smallest lift step at which no probe point over the
- * perch's hit box hits an obstruction. Falls back to 0 — never a partial
- * lift — when every step is obstructed or a step would push the box off
- * the top of the viewport: on a page that gives the corner no clearance
- * anywhere, a perch parked where the user expects it beats one that
- * wandered.
- */
 export function firstClearLiftFor(options) {
     const { rect, probe } = options;
     const liftSteps = options.liftSteps ?? PERCH_LIFT_STEPS_PX;
@@ -56,8 +32,6 @@ export function firstClearLiftFor(options) {
     }
     return 0;
 }
-/** What counts as the host's interactive surface under a probe point.
- *  Anything a click would activate; label pulls in its control. */
 export const INTERACTIVE_OBSTRUCTION_SELECTOR = [
     "a[href]",
     "button",
@@ -77,4 +51,3 @@ export const INTERACTIVE_OBSTRUCTION_SELECTOR = [
     '[role="tab"]',
     '[role="textbox"]',
 ].join(", ");
-//# sourceMappingURL=perch-clearance.js.map

package/dist/core/question-drafts.d.ts

@@ -9,38 +9,21 @@ export interface QuestionAnswerDraft {
     customText: string;
 }
 export interface QuestionSetDraft {
-    /** Which question the panel shows — kept here so paging, remounts and
-     *  reconnects all return the member to where they were. */
     cursor: number;
     answers: ReadonlyMap<string, QuestionAnswerDraft>;
 }
 export interface QuestionLike {
     id: string;
 }
-/** The per-answer transport bound the server enforces (QuestionAnswer.text
- *  maxLength on the serving contract — pinned equal by the monorepo's
- *  contract-parity test). The panel says so beside the row instead of
- *  clipping: no silent truncation. Measured here in UTF-16 units
- *  (String.length) while the server counts code points — an astral
- *  character costs two here and one there, so this side is the stricter
- *  or equal one and a text that passes the panel never fails the door. */
 export declare const MAX_ANSWER_TEXT_CHARS = 1900;
 export declare class QuestionDraftStore {
     private readonly drafts;
     private readonly listeners;
     get: (interruptId: string) => QuestionSetDraft;
     subscribe: (listener: () => void) => (() => void);
-    /** True when the member has entered anything for this set — what the
-     *  panel's Cancel consults before asking "Discard answers?". */
     hasContent(interruptId: string): boolean;
     selectOption(interruptId: string, questionId: string, text: string): void;
     selectCustom(interruptId: string, questionId: string): void;
-    /** Typing makes the custom row the active choice — the one implicit
-     *  switch, and it is the member's own keystroke. The text is written
-     *  as the door will accept it: pasted control characters are
-     *  normalized here (see normalizeCustomText), so the panel's posture —
-     *  every per-answer rule the door enforces is kept in view before the
-     *  POST — holds for the control rule as it does for the length bound. */
     setCustomText(interruptId: string, questionId: string, text: string): void;
     setCursor(interruptId: string, cursor: number): void;
     clear(interruptId: string): void;
@@ -48,18 +31,10 @@ export declare class QuestionDraftStore {
     private updateAnswer;
     private notify;
 }
-/** The complete answer set in question order, or null while any
- *  question is unanswered — the panel's Submit gate and its POST body. */
 export declare function answersOf(questions: readonly QuestionLike[], draft: QuestionSetDraft): {
     id: string;
     text: string;
 }[] | null;
-/** The index of the first question still without a usable answer, or -1
- *  when the set is complete — what the footer names when Submit is gated,
- *  and where a continue from the last question jumps to. */
 export declare function firstUnansweredIndexOf(questions: readonly QuestionLike[], draft: QuestionSetDraft): number;
-/** The ids whose custom text exceeds the transport bound — the panel
- *  says so beside the row instead of clipping (no silent truncation). */
 export declare function overLimitOf(questions: readonly QuestionLike[], draft: QuestionSetDraft, maxChars: number): string[];
 export {};
-//# sourceMappingURL=question-drafts.d.ts.map