@memberjunction/ng-conversations 6.1.0-edge.2 → 6.1.0-edge.3

package/dist/lib/services/conversation-detail-window.store.d.ts

@@ -0,0 +1,206 @@
+import type { UserInfo } from '@memberjunction/core';
+import type { MJConversationDetailEntity, LoadDetailWindowParams, DetailWindowLoadResult } from '@memberjunction/core-entities';
+import { ConversationDetailWindowCursor } from '../utils/conversation-detail-window';
+/**
+ * The engine surface this store needs. Declared structurally rather than importing
+ * ConversationEngine so tests can pass a plain `{ LoadDetailWindow: vi.fn() }` with no
+ * TestBed and no engine bootstrap.
+ */
+export interface DetailWindowLoader {
+    LoadDetailWindow(params: LoadDetailWindowParams, contextUser: UserInfo): Promise<DetailWindowLoadResult>;
+}
+/**
+ * Peripheral data for the loaded window, keyed the way the chat area already consumes it.
+ *
+ * Accumulates across pages: an older page brings its own artifacts and ratings, which merge
+ * into these maps rather than replacing them.
+ */
+export type ConversationDetailWindowPeripherals = Pick<DetailWindowLoadResult, 'AgentRunsByDetailId' | 'UserAvatars' | 'RatingsByDetailId' | 'ArtifactsByDetailId'>;
+/** What the chat area binds to after any store operation. */
+export interface ConversationDetailWindowSnapshot extends ConversationDetailWindowPeripherals {
+    ConversationID: string | null;
+    /** Loaded rows, chronological by Sequence. A NEW array each call, so ngOnChanges fires. */
+    Details: MJConversationDetailEntity[];
+    Cursor: ConversationDetailWindowCursor;
+    /** Pinned rows for the pins panel, INCLUDING pins older than the window. */
+    PinnedDetails: MJConversationDetailEntity[];
+    /**
+     * TRUE total pins in the conversation, which is NOT `PinnedDetails.length` until the
+     * panel has been opened — the open path reads only the count so the chip has a number
+     * without hydrating anything.
+     */
+    PinnedTotalCount: number;
+    IsLoadingLatest: boolean;
+    IsLoadingOlder: boolean;
+    /**
+     * True when the most recent load FAILED, as opposed to returning nothing.
+     *
+     * Exists so an empty transcript can be told apart from a broken one. Without it a failed
+     * first read renders as a conversation with no messages, which reads to the user as "my
+     * conversation is gone" — the one failure mode worse than an error message.
+     */
+    LoadFailed: boolean;
+}
+/**
+ * Holds ONE conversation's loaded transcript window and the cursors for paging further back.
+ *
+ * Owned per chat-area instance (not a singleton) so two hosts can never share window state.
+ *
+ * Contracts:
+ *  - {@link Reset} bumps a generation counter; every in-flight load checks it after each
+ *    await and discards its result if the conversation changed underneath.
+ *  - {@link LoadOlder} is a no-op while a load is in flight or when nothing is above.
+ *  - Merges dedupe by normalized ID and re-sort by `Sequence` — session expansion can
+ *    return rows an earlier page already had.
+ *  - {@link ApplyLocalDetail} never hits the network; it is the send/stream/edit path.
+ *  - Pins live in their own array. They are NOT unioned into the transcript, because a pin
+ *    below the window's oldest Sequence would break contiguity and the paging cursor.
+ */
+export declare class ConversationDetailWindowStore {
+    private loader;
+    private conversationId;
+    private loadedDetails;
+    private pinnedDetails;
+    private pinnedTotalCount;
+    private peripherals;
+    private cursor;
+    private generation;
+    private isLoadingLatest;
+    private isLoadingOlder;
+    private loadFailed;
+    constructor(loader: DetailWindowLoader);
+    /** Drops all state and invalidates in-flight loads. Call on every conversation switch. */
+    Reset(conversationId: string | null): void;
+    /**
+     * Fetches a page, WIDENING the raw over-read until it yields a full page of timeline
+     * items (or the conversation runs out).
+     *
+     * Raw rows are not display items: a realtime session folds many stamped rows into ONE
+     * timeline card, so the default `3 × pageSize` over-read can come back holding two or
+     * three items instead of ten. Taking that at face value gives the reader a stubby page
+     * and makes the sentinel fire again immediately — which is worse than one wider read.
+     *
+     * Bounded by {@link MAX_OVERREAD_ATTEMPTS}: a conversation that is almost entirely one
+     * long session would otherwise grow the read until it pulled the whole table.
+     */
+    private fetchPageFillingTimeline;
+    /**
+     * First paint: the newest page of a conversation.
+     *
+     * The loader is not expected to throw — `LoadDetailWindow` logs and returns an empty
+     * window on a failed read — but a transport-layer rejection would otherwise strand
+     * `isLoadingLatest` at true and wedge the store, so the flag is cleared in `finally`.
+     */
+    LoadLatest(conversationId: string, contextUser: UserInfo): Promise<void>;
+    /**
+     * Prepends the next older page. No-op when nothing is above or a load is running.
+     *
+     * `isLoadingOlder` is cleared in `finally` for the same reason as {@link LoadLatest} —
+     * and it matters more here, because a stuck flag makes {@link CanLoadOlder} false
+     * forever, which silently kills the transcript's "earlier messages" sentinel.
+     */
+    LoadOlder(contextUser: UserInfo): Promise<void>;
+    /**
+     * Re-fetches the tail and folds it into the existing window.
+     *
+     * The refresh-in-place counterpart to {@link LoadLatest}: used when something changed at
+     * the tail (an agent finished, artifacts were written) and the transcript needs to pick
+     * it up. Unlike `LoadLatest` it does NOT `Reset`, so a user who has paged up five times
+     * keeps those pages instead of being yanked back to a 10-row tail.
+     *
+     * Reads via {@link fetchRefreshedTail}, which keeps paging down until it reaches rows the
+     * window already holds — otherwise a conversation that grew by more than a page leaves a
+     * hole in the middle of the merged set that nothing in the UI can reveal.
+     */
+    RefreshLatest(contextUser: UserInfo): Promise<void>;
+    /**
+     * Reads the newest page, then keeps paging down until the read reaches back to
+     * `previousNewest` — the newest row the window already holds.
+     *
+     * One page is enough in the normal case: a refresh usually returns rows we already have
+     * plus the handful that arrived since. The loop is for the case that is not normal, where
+     * the tail has moved further than a page and a single read would land entirely above the
+     * loaded set.
+     *
+     * @returns Every page read, plus whether the reads joined up with the loaded window.
+     */
+    private fetchRefreshedTail;
+    /** True when this page reaches back into the loaded window, so nothing sits between them. */
+    private tailIsJoined;
+    /**
+     * Folds a refreshed tail into the window, choosing what to keep by whether the read
+     * joined up with the rows already loaded.
+     */
+    private applyRefreshedTail;
+    /** Merges the refreshed rows per the three refresh cases. @returns the new `HasMoreAbove`. */
+    private mergeRefreshedRows;
+    /**
+     * Cheap single-value reads for TEMPLATE binding.
+     *
+     * These exist because the chat area exposes `HasMoreAbove`, `IsLoadingOlder`,
+     * `PinnedTotalCount`, and `PinnedDetails` as getters bound in its template, so every
+     * change-detection cycle reads all four. Routing those through {@link GetSnapshot} copied
+     * the whole loaded window four times per cycle — during streaming, per token — on a
+     * component whose entire purpose is to stop doing work proportional to conversation length.
+     *
+     * {@link PinnedDetails} deliberately returns the internal array BY REFERENCE. Every mutator
+     * replaces that array rather than mutating it, so the reference is stable between real
+     * changes — which is precisely what keeps the pins panel's `ngOnChanges` from firing on
+     * every cycle. Callers must not mutate it.
+     */
+    get HasMoreAbove(): boolean;
+    get IsLoadingOlder(): boolean;
+    get IsLoadingLatest(): boolean;
+    get PinnedTotalCount(): number;
+    get PinnedDetails(): readonly MJConversationDetailEntity[];
+    /** True when the most recent load failed — an empty transcript vs. a broken one. */
+    get LoadFailed(): boolean;
+    /** True when a `LoadOlder` would actually do work. Drives the sentinel's observer. */
+    CanLoadOlder(): boolean;
+    /**
+     * Applies a locally-known row — sent, streamed, edited. Inserts or replaces by ID and
+     * re-sorts. Never queries; the caller already has the entity.
+     */
+    ApplyLocalDetail(detail: MJConversationDetailEntity): void;
+    /** Removes a row by ID — the delete path. */
+    RemoveDetail(detailId: string): void;
+    /**
+     * Records how many pins exist WITHOUT loading them.
+     *
+     * The conversation-open path calls only this: the chip needs a number, the panel needs
+     * nothing until it is opened, and hydrating every pin on open re-imports the cost this
+     * windowing work exists to remove.
+     */
+    SetPinnedCount(total: number): void;
+    /** Replaces the pins panel's contents. Pins outside the window are expected here. */
+    SetPinnedDetails(pins: MJConversationDetailEntity[]): void;
+    /**
+     * Reflects a pin/unpin the user just performed, without re-querying.
+     *
+     * Newly pinned rows go to the FRONT to match the panel's newest-pin-first order, which
+     * the initial `Sequence DESC` fetch also produces.
+     */
+    ApplyLocalPin(detail: MJConversationDetailEntity): void;
+    /**
+     * Everything the chat area needs to render, copied. Arrays are fresh so ngOnChanges fires.
+     *
+     * Call this from imperative paths (a load completing, a jump loop) — NOT from a template
+     * getter. It copies the loaded set on every call, so binding it into change detection
+     * pays that copy once per checked cycle for state that mostly has not moved. The cheap
+     * single-value accessors above exist for exactly that case.
+     */
+    GetSnapshot(): ConversationDetailWindowSnapshot;
+    /**
+     * Folds a newly-loaded page's peripherals into the accumulated maps.
+     *
+     * Later entries win on a key collision, which matters for a window refresh: a re-fetched
+     * newest page should replace a row's stale agent run rather than keep the old one.
+     */
+    private mergePeripherals;
+    /**
+     * Union-merges rows into the loaded set: replace-by-ID, then sort by `Sequence`.
+     * Dedupe is required because session expansion can re-return rows a prior page held.
+     */
+    private mergeDetails;
+}
+//# sourceMappingURL=conversation-detail-window.store.d.ts.map

package/dist/lib/services/conversation-detail-window.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-detail-window.store.d.ts","sourceRoot":"","sources":["../../../src/lib/services/conversation-detail-window.store.ts"],"names":[],"mappings":"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"}