@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/chat-protocol/ip-normalize.ts

@@ -0,0 +1,146 @@
+/**
+ * `normalizeIpForBucketKey` — THE cross-repo normalizer for turning a raw
+ * client-IP candidate (`x-forwarded-for` hop, socket remote address, proxy
+ * header) into a stable rate-limit / dedup bucket key.
+ *
+ * WHY IT LIVES HERE: producer and consumer sit in DIFFERENT repos (the app
+ * emits the candidate, the hub buckets it) and each had grown its own
+ * normalizer. They disagreed — one unwrapped `::ffff:1.2.3.4` to the bare
+ * IPv4 and stripped `%zone`, the other kept the zone and only lower-cased the
+ * mapped form — so ONE visitor could land in TWO buckets depending on which
+ * side normalized. Both repos already depend on this package, and
+ * `./chat-protocol` is its server-safe subpath (no React, no browser APIs),
+ * so this is the one place both sides can share.
+ *
+ * Contract:
+ *   - input longer than `IP_BUCKET_KEY_MAX_LENGTH` → `null` (an unbounded
+ *     header must never become an unbounded map key);
+ *   - `[…]` brackets and a trailing `]:port` are stripped, as is a bare
+ *     `:port` on an IPv4 (`203.0.113.4:8080`) — an unbracketed IPv6 with a
+ *     bare port stays ambiguous and is not stripped;
+ *   - a `%zone` suffix is stripped (link-local scope is per-host, not part of
+ *     the peer's identity);
+ *   - IPv4-mapped IPv6 (`::ffff:203.0.113.4`) collapses to the bare IPv4, so
+ *     the same peer buckets identically over either stack;
+ *   - IPv6 is lower-cased;
+ *   - IPv4 octets are range-checked and REJECTED when zero-padded (`.04`
+ *     would otherwise bucket separately from `.4`), and IPv6 is
+ *     charset/shape-checked (one `::` at most, ≤8 groups, an embedded IPv4
+ *     only in the last group, no dangling separator); anything else returns
+ *     `null` rather than a junk bucket key.
+ *
+ * It does NOT canonicalize IPv6 zero-compression (`2001:db8::1` vs
+ * `2001:0db8:0:0:0:0:0:1`) — peers do not spell their own address two ways
+ * within one deployment, and a full expander is more surface than the bucket
+ * key warrants.
+ */
+
+/** Longest accepted candidate. A full IPv6 + zone fits well inside this. */
+export const IP_BUCKET_KEY_MAX_LENGTH = 64
+
+function isIpv4(value: string): boolean {
+  const parts = value.split('.')
+  if (parts.length !== 4) return false
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return false
+    // Leading zeros are a SECOND spelling of the same address (`203.0.113.04`),
+    // so accepting them verbatim splits one peer across two buckets. Reject
+    // rather than canonicalize: no legitimate emitter zero-pads, and some
+    // resolvers read a `0`-prefixed octet as octal, i.e. it is not even
+    // reliably the same address.
+    if (part.length > 1 && part.startsWith('0')) return false
+    if (Number(part) > 255) return false
+  }
+  return true
+}
+
+function isIpv6(value: string): boolean {
+  if (!value.includes(':')) return false
+  // Charset gate first: hex digits, separators, and the dots of a trailing
+  // embedded IPv4. Anything else (a hostname, a header injection) is out.
+  if (!/^[0-9a-f:.]+$/.test(value)) return false
+  if (value.includes(':::')) return false
+  // A dangling separator (`2001:db8::1:`) leaves an EMPTY trailing group that
+  // is not part of a `::` compression — malformed, not an address.
+  if (value.endsWith(':') && !value.endsWith('::')) return false
+  if (value.startsWith(':') && !value.startsWith('::')) return false
+  const compressions = value.split('::').length - 1
+  if (compressions > 1) return false
+  const groups = value.split(':')
+  if (groups.length > 8) return false
+  for (let i = 0; i < groups.length; i += 1) {
+    const group = groups[i]
+    if (group === '') continue
+    if (group.includes('.')) {
+      // An embedded IPv4 occupies the LAST two groups; anywhere else
+      // (`1.2.3.4::1`) it is malformed.
+      if (i !== groups.length - 1) return false
+      if (!isIpv4(group)) return false
+      continue
+    }
+    if (!/^[0-9a-f]{1,4}$/.test(group)) return false
+  }
+  // Uncompressed form must be exactly 8 groups (a trailing embedded IPv4
+  // occupies two, so 7 written groups is also complete).
+  if (compressions === 0) {
+    const embedsIpv4 = groups[groups.length - 1]?.includes('.') ?? false
+    if (groups.length !== (embedsIpv4 ? 7 : 8)) return false
+  }
+  return true
+}
+
+/**
+ * Normalize one IP candidate to its canonical bucket key, or `null` when the
+ * value is not a usable address.
+ */
+export function normalizeIpForBucketKey(value: string): string | null {
+  if (typeof value !== 'string') return null
+  let candidate = value.trim()
+  if (candidate === '' || candidate.length > IP_BUCKET_KEY_MAX_LENGTH) return null
+
+  // `[2001:db8::1]` / `[::1]:443` — the bracketed forms a proxy emits so the
+  // port is unambiguous.
+  if (candidate.startsWith('[')) {
+    const close = candidate.indexOf(']')
+    if (close === -1) return null
+    const trailer = candidate.slice(close + 1)
+    if (trailer !== '' && !/^:\d{1,5}$/.test(trailer)) return null
+    candidate = candidate.slice(1, close)
+  }
+
+  // `%eth0` / `%25eth0` scope id — host-local, never part of peer identity.
+  const zone = candidate.indexOf('%')
+  if (zone !== -1) candidate = candidate.slice(0, zone)
+  if (candidate === '') return null
+
+  // UNBRACKETED `203.0.113.4:8080` — Azure App Service / Front Door and several
+  // CDNs write the client hop that way. Rejecting it left the caller with NO
+  // candidate at all, collapsing every visitor into the single egress bucket:
+  // exactly the silent regression this module exists to prevent. Stripped ONLY
+  // when the remainder is a valid IPv4; an unbracketed IPv6 with a bare port
+  // (`::1:443`) is genuinely ambiguous — `:443` is equally a final group — so
+  // that shape is left to the IPv6 path.
+  const portSplit = candidate.lastIndexOf(':')
+  if (portSplit > 0 && /^\d{1,5}$/.test(candidate.slice(portSplit + 1))) {
+    const head = candidate.slice(0, portSplit)
+    if (isIpv4(head)) candidate = head
+  }
+
+  if (isIpv4(candidate)) return candidate
+
+  const lowered = candidate.toLowerCase()
+
+  // IPv4-mapped IPv6 → the bare IPv4 (same peer, one bucket). EVERY spelling
+  // is handled: the compressed `::ffff:1.2.3.4` that dual-stack listeners
+  // actually emit, the written-out `0:0:0:0:0:ffff:1.2.3.4` that a hop doing
+  // its own (non-compressing) formatting can produce, and the ZERO-PADDED
+  // `0000:0000:0000:0000:0000:ffff:1.2.3.4` that a fixed-width formatter
+  // produces — leading zeros in an IPv6 group are purely cosmetic, so all
+  // three name the same peer. Matching only some of them would split one peer
+  // across two buckets — the exact failure this module exists to prevent.
+  const mapped = /^(?:(?:0{1,4}:){5}|::)ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(lowered)
+  if (mapped) return isIpv4(mapped[1]) ? mapped[1] : null
+
+  if (isIpv6(lowered)) return lowered
+  return null
+}

package/src/chat-protocol/nats-decoder.ts

@@ -0,0 +1,264 @@
+/**
+ * NATS chunk → normalized `ChatStreamEvent` decoder.
+ *
+ * THE live NATS reading path — the ONLY chunk parser in the codebase. Every
+ * consumer (this lib's `useNatsChatAdapter`, the hub, the product app) feeds
+ * raw chunks through `decodeNatsChunk` into `createChatStreamReducer`. The
+ * legacy `components/chat/utils/chunk-parser.ts` (`parseChunkToAction`) that
+ * this module superseded was DELETED — do not reintroduce a second decoder.
+ *
+ * Chunks map onto the transport-agnostic event union, with the JetStream
+ * `streamSeq` lifted into the `seq` envelope (the reducer's idempotency gate
+ * keys off it).
+ *
+ * Behavior is pinned by `__tests__/nats-decoder-golden.test.ts`.
+ *
+ * Server-safe: no React, no browser APIs.
+ */
+
+import { MESSAGE_TYPE } from '../components/chat/types/message.types'
+import type { ApprovalToolCall, ChatStreamEvent } from './events'
+
+/** Minimal structural view of a NATS chunk (see `ChunkData` in
+ *  `src/components/chat/types/network.types.ts`). */
+type NatsChunk = Record<string, any>
+
+/** Coerce the wire's `toolCalls[]` into the batch-approval shape, dropping
+ *  non-object entries and defaulting every field. */
+function normalizeToolCalls(raw: unknown): ApprovalToolCall[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((item): item is Record<string, any> => !!item && typeof item === 'object')
+    .map((item) => ({
+      toolExecutionRequestId: String(item.toolExecutionRequestId ?? ''),
+      toolName: String(item.toolName ?? ''),
+      toolTitle: typeof item.toolTitle === 'string' ? item.toolTitle : undefined,
+      toolExplanation:
+        typeof item.toolExplanation === 'string' ? item.toolExplanation : undefined,
+      toolType: typeof item.toolType === 'string' ? item.toolType : undefined,
+      requiresApproval: item.requiresApproval === true,
+      approvalType: typeof item.approvalType === 'string' ? item.approvalType : null,
+      toolCallArguments:
+        item.toolCallArguments && typeof item.toolCallArguments === 'object'
+          ? (item.toolCallArguments as Record<string, any>)
+          : null,
+    }))
+}
+
+/**
+ * Parse one raw NATS chunk into a normalized event. Returns `null` for
+ * unknown/malformed chunks — an unrecognized `type`, a missing required
+ * field, or a non-object payload are all tolerated as no-ops rather than
+ * throwing, so a backend that adds a chunk type can't break the stream.
+ */
+export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
+  if (!chunk || typeof chunk !== 'object') return null
+
+  const data = chunk as NatsChunk
+  const type = String(data.type || '')
+  // JetStream stream sequence → the generic `seq` envelope.
+  const seq: { seq?: number } =
+    typeof data.streamSeq === 'number' ? { seq: data.streamSeq } : {}
+
+  switch (type) {
+    case MESSAGE_TYPE.MESSAGE_START:
+      return { type: 'turn-start', ...seq }
+
+    case MESSAGE_TYPE.MESSAGE_END:
+      return { type: 'turn-end', ...seq }
+
+    case MESSAGE_TYPE.AI_METADATA: {
+      const providerName = data.providerName || data.provider
+      if (typeof data.modelName === 'string' && typeof providerName === 'string') {
+        return {
+          type: 'metadata',
+          modelLabel: data.modelDisplayName,
+          modelName: data.modelName,
+          provider: providerName,
+          contextWindowMaxTokens:
+            typeof data.contextWindow === 'number' ? data.contextWindow : 0,
+          ...seq,
+        }
+      }
+      return null
+    }
+
+    case MESSAGE_TYPE.TEXT:
+      if (typeof data.text === 'string') {
+        return { type: 'text-delta', text: data.text, ...seq }
+      }
+      return null
+
+    case MESSAGE_TYPE.THINKING:
+      if (typeof data.text === 'string') {
+        return { type: 'thinking-delta', text: data.text, ...seq }
+      }
+      return null
+
+    case MESSAGE_TYPE.GUIDE:
+      if (typeof data.text === 'string') {
+        return { type: 'guide-delta', text: data.text, ...seq }
+      }
+      return null
+
+    case MESSAGE_TYPE.EXECUTING_TOOL:
+      return {
+        type: 'tool-execution',
+        data: {
+          type: 'EXECUTING_TOOL',
+          integratedToolType: data.integratedToolType || '',
+          toolFunction: data.toolFunction || '',
+          toolTitle: typeof data.title === 'string' ? data.title : undefined,
+          // The human-readable "why this tool is running" line rendered inside
+          // the tool card. It rides ONLY the EXECUTING chunk — the EXECUTED one
+          // never carries it, and the accumulator's merge preserves whatever
+          // the EXECUTING segment held. Dropping it here therefore blanks the
+          // card for the whole lifetime of the run.
+          toolExplanation: typeof data.toolExplanation === 'string' ? data.toolExplanation : undefined,
+          parameters: data.parameters,
+          toolExecutionRequestId:
+            typeof data.toolExecutionRequestId === 'string'
+              ? data.toolExecutionRequestId
+              : undefined,
+        },
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.EXECUTED_TOOL:
+      return {
+        type: 'tool-execution',
+        data: {
+          type: 'EXECUTED_TOOL',
+          integratedToolType: data.integratedToolType || '',
+          toolFunction: data.toolFunction || '',
+          toolTitle: typeof data.title === 'string' ? data.title : undefined,
+          parameters: data.parameters,
+          result: data.result,
+          success: data.success,
+          toolExecutionRequestId:
+            typeof data.toolExecutionRequestId === 'string'
+              ? data.toolExecutionRequestId
+              : undefined,
+        },
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.APPROVAL_REQUEST: {
+      const requestId = data.approvalRequestId || data.approval_request_id || ''
+      const approvalType = data.approvalType || 'USER'
+      const toolCalls = normalizeToolCalls(data.toolCalls)
+
+      if (toolCalls.length > 0) {
+        return { type: 'approval-request', requestId, approvalType, toolCalls, ...seq }
+      }
+
+      return {
+        type: 'approval-request',
+        requestId,
+        approvalType,
+        command: data.command || '',
+        explanation: data.explanation,
+        ...seq,
+      }
+    }
+
+    case MESSAGE_TYPE.APPROVAL_RESULT: {
+      // Realtime chunks carry the resolver's name as `displayName`; the
+      // persisted GraphQL message exposes the same value as
+      // `resolvedByName`. Accept either so realtime and history-replay
+      // render "by {name}" identically.
+      const resolvedByName =
+        typeof data.resolvedByName === 'string'
+          ? data.resolvedByName
+          : typeof data.displayName === 'string'
+            ? data.displayName
+            : undefined
+      return {
+        type: 'approval-resolved',
+        requestId: data.approvalRequestId || data.approval_request_id || '',
+        status: data.approved === true ? 'approved' : 'rejected',
+        approvalType: data.approvalType || 'CLIENT',
+        resolvedByName,
+        ...seq,
+      }
+    }
+
+    case MESSAGE_TYPE.ERROR:
+      return {
+        type: 'error',
+        title: data.error || 'An error occurred',
+        details: data.details,
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.MESSAGE_REQUEST:
+      return {
+        type: 'participant',
+        kind: 'message-request',
+        text: String(data.text || ''),
+        ownerType: typeof data.ownerType === 'string' ? data.ownerType : undefined,
+        displayName: typeof data.displayName === 'string' ? data.displayName : undefined,
+        userId: typeof data.userId === 'string' ? data.userId : undefined,
+        // Wire shape carries no label; fall back to the id (parity with
+        // the history path in `process-historical-messages.ts`).
+        contextItems: Array.isArray(data.contextItems)
+          ? (data.contextItems as Array<{ type?: unknown; id?: unknown }>)
+              .filter((it) => typeof it?.type === 'string' && typeof it?.id === 'string')
+              .map((it) => ({
+                type: it.type as string,
+                id: it.id as string,
+                label: it.id as string,
+              }))
+          : undefined,
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.TOKEN_USAGE:
+      return {
+        type: 'token-usage',
+        inputTokensSize: data.inputTokensSize ?? 0,
+        outputTokensSize: data.outputTokensSize ?? 0,
+        totalTokensSize: data.totalTokensSize ?? 0,
+        contextSize: data.contextSize ?? 0,
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.CONTEXT_COMPACTION_START:
+      return { type: 'compaction', phase: 'start', ...seq }
+
+    case MESSAGE_TYPE.CONTEXT_COMPACTION_END:
+      return {
+        type: 'compaction',
+        phase: 'end',
+        summary: typeof data.text === 'string' ? data.text : undefined,
+        ...seq,
+      }
+
+    case MESSAGE_TYPE.SYSTEM:
+      if (typeof data.text === 'string') {
+        return { type: 'participant', kind: 'system', text: data.text, ...seq }
+      }
+      return null
+
+    case MESSAGE_TYPE.DIRECT_MESSAGE:
+      if (typeof data.text === 'string') {
+        return {
+          type: 'participant',
+          kind: 'direct-message',
+          text: data.text,
+          ownerType: typeof data.ownerType === 'string' ? data.ownerType : undefined,
+          displayName:
+            typeof data.displayName === 'string' ? data.displayName : undefined,
+          userId: typeof data.userId === 'string' ? data.userId : undefined,
+          ...seq,
+        }
+      }
+      return null
+
+    case MESSAGE_TYPE.DIALOG_CLOSED:
+      return { type: 'dialog-closed', ...seq }
+
+    default:
+      return null
+  }
+}

package/src/components/chat/.chat-message-list.md

@@ -1,25 +1,27 @@
-<!-- source-hash: bcd59a730239fa164668aa97e210c356 -->
+<!-- source-hash: d9436810c5dd4b6f6250d2c8f91f5212 -->
 Renders a scrollable, auto-anchoring chat message list with streaming indicators, infinite scroll upward pagination, and stick-to-bottom physics for AI chat interfaces.
 
 ## Key Components
 
 - **`ChatMessageList`** — Primary `forwardRef` component wrapping `useStickToBottom` for spring-physics scroll anchoring during token streaming
 - **`STREAMING_WORDS`** — Flamingo-themed cycling phrases displayed alongside the typing/streaming indicator
+- **`BOTTOM_THRESHOLD_PX`** / **`FOLLOW_RETAIN_MS`** — The at-bottom band (mirrors the library's `STICK_TO_BOTTOM_OFFSET_PX`) and the chase window each follow re-assert opens (mirrors its `RETAIN_ANIMATION_DURATION_MS`)
 - **`hasNonEmptyContent`** — Utility predicate that checks whether a `MessageContent` value (string or `MessageSegment[]`) contains visible text
-- **`AnchorWatcher`** / **`disposeAnchorWatcher`** — Interface and idempotent teardown helper for the prepend-anchor `ResizeObserver` settle window
+- **`AnchorWatcher`** / **`disposeAnchorWatcher`** — Interface and idempotent teardown helper for the top-anchor `ResizeObserver` settle window
 - **`ChatMessageEnhanced`** — Per-message renderer (avatars, approval variants, entity cards, context icons, mentions)
 - **`ChatMessageListSkeleton`** — Placeholder skeleton shown during initial load
-- **`CyclingPhrase`** — Animated word-cycling component used inside the streaming indicator
-- **`DotsLoaderIcon`** — Animated dots icon displayed while `isTyping` is active
+- **`CyclingPhrase`** / **`DotsLoaderIcon`** — The footer-pinned streaming indicator, rendered OUTSIDE the scroller so it can't jitter the thread
 
 ## Scroll Architecture
 
 | Concern | Owner |
 |---|---|
 | Streaming follow (spring) | `useStickToBottom` |
+| Follow INTENT (arm / disarm / re-assert) | `followBottomRef` + growth watch |
 | Dialog change / first load / new user message | Force-scroll `useEffect` |
 | Load-older prepend anchoring | `loadOlderAnchorRef` + geometry delta |
 | Top-sentinel infinite scroll | `sentinelRef` + `IntersectionObserver` |
+| Jump-to-bottom affordance | `atBottom` (measured geometry, NOT the library flag) |
 | Passive demo hard-pin | `pinBottom` prop path |
 
 ## Usage Example
@@ -53,5 +55,7 @@ export function MyChatView() {
 
 - Requires `use-stick-to-bottom` (StackBlitz Labs) — the same library used by Vercel AI SDK's `<Conversation>` and bolt.new
 - `initial: false` disables mount-time auto-scroll; the dialog-change `useEffect` owns first-paint positioning
-- Image attachments trigger a `requestAnimationFrame` follow-up scroll to handle Next.js `<Image>` progressive dimensioning
-- `pinBottom` bypasses smart-follow for scripted demos (Fae/Mingo) where no human controls scroll
+- The follow lock exists because this list's layout silently loses the library's own `isAtBottom` (siblings below the scroller change its box; a card settling out of its skeleton produces a resize-driven scroll the library reads as a gesture). Re-asserts pass `ignoreEscapes` and the library's COALESCING options (`wait: true` + `duration`) so per-frame growth folds into ONE spring instead of spawning competing chains
+- Growth is detected by an rAF poll on the scroller's `scrollHeight`, not only by `ResizeObserver`: the observed content node is a snapshot that React can swap out, after which the observer watches a detached element and streamed tokens grow the thread silently
+- `isLoading` is in the deps of every effect that touches the scroller (follow, load-more sentinel, imperative handle): the loading branch returns the skeleton, so those effects bail on null refs and would otherwise never re-run for hosts whose `isLoading` outlives `hasNextPage` turning true
+- `pinBottom` bypasses smart-follow for scripted demos (Fae/Mingo) where no human controls scroll