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

package/dist/utils/markdown-fences.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fenced-code tracker — THE definition of "am I inside a code fence".
+ * Server-safe: no React, no DOM.
+ *
+ * Lives in its own module because it is a GENERAL CommonMark fence machine
+ * with two unrelated consumers: the heading scanner
+ * (`utils/markdown-heading-id`) and the streaming block splitter
+ * (`components/ui/markdown/streaming`). It used to live inside
+ * `markdown-heading-id`, which meant a streaming renderer imported its fence
+ * state machine from a module named after heading slugs. `markdown-heading-id`
+ * re-exports these names so the public `utils` surface is unchanged.
+ */
+/** True when `line` is a CommonMark blank line (spaces/tabs only, `\r`-tolerant). */
+export declare function isBlankLine(line: string): boolean;
+/**
+ * What one source line is, relative to fenced code:
+ *  - `open`  — this line opened a fence
+ *  - `close` — this line closed the open fence
+ *  - `inside`— this line is fence content (including a would-be delimiter that
+ *              does NOT close the open fence: wrong marker char, too short, or
+ *              carrying an info string)
+ *  - `text`  — this line is ordinary markdown outside any fence
+ *
+ * NOTE: no consumer discriminates the three non-`text` roles today — both the
+ * heading scanner and the streaming splitter only test `!== 'text'`, and the
+ * closer-haystack mask below only tests `=== 'open'` / `=== 'close'`. The
+ * four-value union is kept because the state machine already computes the
+ * distinction for free and a future consumer (e.g. fence-aware syntax
+ * post-processing) would otherwise have to re-derive it.
+ */
+export type FenceLineRole = 'open' | 'close' | 'inside' | 'text';
+export interface FenceTracker {
+    /** Advance across one raw source line (mutates) and classify it. */
+    push(line: string): FenceLineRole;
+    /** Marker CHARACTER of the currently open fence (`` ` `` / `~`), or null. */
+    openChar(): string | null;
+    /** Run length of the currently open fence (a closer must be ≥ this). */
+    openLength(): number;
+}
+/** A fresh fenced-code state machine. Server-safe: no React, no DOM. */
+export declare function createFenceTracker(): FenceTracker;
+//# sourceMappingURL=markdown-fences.d.ts.map

package/dist/utils/markdown-fences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-fences.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-fences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoDH,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEhE,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IACjC,6EAA6E;IAC7E,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAA;IACzB,wEAAwE;IACxE,UAAU,IAAI,MAAM,CAAA;CACrB;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,IAAI,YAAY,CA8BjD"}

package/dist/utils/markdown-heading-id.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Markdown heading-id slug SSOT (server-safe: no React, no DOM).
+ *
+ * This algorithm previously existed in THREE byte-identical copies:
+ *   - `components/ui/simple-markdown-renderer.tsx` (generateHeadingId)
+ *   - `components/ui/rich-markdown-renderer.tsx` (generateHeadingId)
+ *   - `utils/markdown-section-extractor.ts` (extractSections)
+ *
+ * The extractor is the PRODUCER of `sectionIds` and the renderers are the
+ * CONSUMERS — if the two ever drift, deep-link anchors and scroll-spy
+ * targets silently diverge. All three now call these helpers; the parity
+ * test `components/ui/__tests__/markdown-parity.test.tsx` asserts
+ * extractor-vs-renderer ID agreement over the fixture corpus.
+ */
+/** Emoji ranges stripped from heading text before slugification. */
+export declare const HEADING_EMOJI_RE: RegExp;
+/** Remove emoji characters and trim. */
+export declare function stripHeadingEmojis(text: string): string;
+/**
+ * Core slug chain WITHOUT the emoji strip (the extractor exposes emoji
+ * stripping as an option, so the two steps are kept separable):
+ * lowercase → drop non-word/space/hyphen chars → spaces to hyphens →
+ * trim leading/trailing hyphens. May return `''` for symbol-only input —
+ * callers apply their own fallback (`section-N`).
+ */
+export declare function slugifyHeadingBase(text: string): string;
+/** The full default chain used by the renderers: emoji strip + slugify. */
+export declare function slugifyHeadingText(text: string): string;
+/**
+ * Sharing the slug chain alone was not enough. The PRODUCER
+ * (`utils/markdown-section-extractor`) and the CONSUMER
+ * (`components/ui/markdown/heading-ids`) each carried their own copy of
+ * "which lines are headings" and "how do duplicates get suffixed", and the
+ * copies drifted:
+ *   - the extractor toggled its code-block state on a bare
+ *     `line.startsWith('```')`, so a `~~~`-fenced (or wider-backtick, or
+ *     indented) block containing `## Setup` produced a SECTION from the
+ *     extractor and NO id from the renderer — `sectionIdMap` then missed
+ *     silently and the deep-link anchor pointed nowhere;
+ *   - the extractor anchored ATX at column 0 while the renderer allowed the
+ *     CommonMark 0..3-space indent;
+ *   - the dedupe counter was hand-copied in both files, each with a comment
+ *     saying "the two must agree".
+ * Both now call `scanHeadings` + `createHeadingIdDeduper`. Server-safe: no
+ * React, no DOM.
+ */
+export { createFenceTracker, isBlankLine, type FenceTracker, type FenceLineRole, } from './markdown-fences';
+/** A heading the renderer will emit, located in the source. */
+export interface ScannedHeading {
+    /** 1-based line of the heading's FIRST line (setext: the title line). */
+    line: number;
+    level: number;
+    /** Raw title text, before `stripInlineMarkdown` / slugification. */
+    text: string;
+}
+export interface ScanHeadingsOptions {
+    /**
+     * Skip a leading YAML frontmatter block (`---` on line 1 through the next
+     * `---`). Only a DOCUMENT-LEADING block counts: a bare `---` mid-document
+     * is a thematic break or a setext underline, and treating it as a
+     * frontmatter toggle (what the extractor used to do) silently swallowed
+     * every heading until the next one.
+     */
+    skipFrontmatter?: boolean;
+    /** Include raw-HTML headings (`<h2>Title</h2>`). Default true. */
+    includeRawHtml?: boolean;
+    /**
+     * Skip fenced-code blocks. Default true — a `##` inside a code fence is
+     * code, not a heading, and the renderer emits no id for it.
+     */
+    skipFences?: boolean;
+}
+/**
+ * Collect every heading the markdown renderer will emit, in document order.
+ * THE single definition of "which lines are headings" for both the extractor
+ * and the renderer's id map.
+ */
+export declare function scanHeadings(content: string, options?: ScanHeadingsOptions): ScannedHeading[];
+/**
+ * The duplicate-id suffix counter, as ONE closure both sides instantiate.
+ * First occurrence keeps the bare slug; the Nth gets `-N`. Extractor and
+ * renderer MUST use the same counter or `#anchor` deep links diverge.
+ */
+export declare function createHeadingIdDeduper(): (cleanId: string) => string;
+//# sourceMappingURL=markdown-heading-id.d.ts.map

package/dist/utils/markdown-heading-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-heading-id.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-heading-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QACsC,CAAA;AAEnE,wCAAwC;AACxC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAKD;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAA;AAG1B,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,kEAAkE;IAClE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAkHD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,cAAc,EAAE,CAwGlB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAUpE"}

package/dist/utils/markdown-section-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-section-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-section-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAUD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,eAAe,EAAE,CAoEnB"}
+{"version":3,"file":"markdown-section-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-section-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAUD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,eAAe,EAAE,CA+CnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.508",
+  "version": "0.0.509",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -120,6 +120,12 @@
       "require": "./dist/platform-domains.cjs",
       "default": "./dist/platform-domains.js"
     },
+    "./chat-protocol": {
+      "types": "./dist/chat-protocol/index.d.ts",
+      "import": "./dist/chat-protocol/index.js",
+      "require": "./dist/chat-protocol/index.cjs",
+      "default": "./dist/chat-protocol/index.js"
+    },
     "./components/ui/file-manager": {
       "types": "./dist/components/ui/file-manager/index.d.ts",
       "import": "./dist/components/ui/file-manager/index.js",

package/src/chat-protocol/__tests__/__snapshots__/nats-decoder-golden.test.ts.snap

@@ -0,0 +1,319 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to normalized events (snapshot) 1`] = `
+{
+  "ai_metadata_full": {
+    "contextWindowMaxTokens": 200000,
+    "modelLabel": "Claude Sonnet",
+    "modelName": "claude-sonnet-x",
+    "provider": "anthropic",
+    "type": "metadata",
+  },
+  "ai_metadata_legacy_provider_field": {
+    "contextWindowMaxTokens": 0,
+    "modelLabel": undefined,
+    "modelName": "gpt-x",
+    "provider": "openai",
+    "type": "metadata",
+  },
+  "ai_metadata_missing_model": null,
+  "ai_metadata_non_numeric_context_window": {
+    "contextWindowMaxTokens": 0,
+    "modelLabel": undefined,
+    "modelName": "claude-sonnet-x",
+    "provider": "anthropic",
+    "type": "metadata",
+  },
+  "approval_request_batch": {
+    "approvalType": "ADMIN",
+    "requestId": "batch-1",
+    "toolCalls": [
+      {
+        "approvalType": "ADMIN",
+        "requiresApproval": true,
+        "toolCallArguments": {
+          "subject": "Printer down",
+        },
+        "toolExecutionRequestId": "exec-a",
+        "toolExplanation": "Opens a new support ticket",
+        "toolName": "create_ticket",
+        "toolTitle": "Create ticket",
+        "toolType": "WRITE",
+      },
+      {
+        "approvalType": null,
+        "requiresApproval": false,
+        "toolCallArguments": null,
+        "toolExecutionRequestId": "exec-b",
+        "toolExplanation": undefined,
+        "toolName": "read_kb",
+        "toolTitle": undefined,
+        "toolType": undefined,
+      },
+    ],
+    "type": "approval-request",
+  },
+  "approval_request_batch_malformed_entries": {
+    "approvalType": "USER",
+    "requestId": "batch-2",
+    "toolCalls": [
+      {
+        "approvalType": null,
+        "requiresApproval": false,
+        "toolCallArguments": null,
+        "toolExecutionRequestId": "",
+        "toolExplanation": undefined,
+        "toolName": "42",
+        "toolTitle": undefined,
+        "toolType": undefined,
+      },
+    ],
+    "type": "approval-request",
+  },
+  "approval_request_empty_tool_calls": {
+    "approvalType": "USER",
+    "command": "echo hi",
+    "explanation": undefined,
+    "requestId": "req-3",
+    "type": "approval-request",
+  },
+  "approval_request_single": {
+    "approvalType": "CLIENT",
+    "command": "systemctl restart nats",
+    "explanation": "Restart the message broker",
+    "requestId": "req-1",
+    "type": "approval-request",
+  },
+  "approval_request_snake_case_id": {
+    "approvalType": "USER",
+    "command": "rm -rf /tmp/cache",
+    "explanation": undefined,
+    "requestId": "req-2",
+    "type": "approval-request",
+  },
+  "approval_result_approved": {
+    "approvalType": "CLIENT",
+    "requestId": "req-1",
+    "resolvedByName": "Jane Admin",
+    "status": "approved",
+    "type": "approval-resolved",
+  },
+  "approval_result_rejected_resolved_by_name": {
+    "approvalType": "CLIENT",
+    "requestId": "req-1",
+    "resolvedByName": "Bob Tech",
+    "status": "rejected",
+    "type": "approval-resolved",
+  },
+  "approval_result_truthy_string_approved": {
+    "approvalType": "CLIENT",
+    "requestId": "req-9",
+    "resolvedByName": undefined,
+    "status": "rejected",
+    "type": "approval-resolved",
+  },
+  "context_compaction_end": {
+    "phase": "end",
+    "summary": "Compacted 34 messages",
+    "type": "compaction",
+  },
+  "context_compaction_end_no_summary": {
+    "phase": "end",
+    "summary": undefined,
+    "type": "compaction",
+  },
+  "context_compaction_start": {
+    "phase": "start",
+    "type": "compaction",
+  },
+  "dialog_closed": {
+    "type": "dialog-closed",
+  },
+  "direct_message": {
+    "displayName": "Jane Admin",
+    "kind": "direct-message",
+    "ownerType": "ADMIN",
+    "text": "Hi, human here taking over",
+    "type": "participant",
+    "userId": "admin-7",
+  },
+  "direct_message_no_text": null,
+  "empty_object": null,
+  "error_bare": {
+    "details": undefined,
+    "title": "An error occurred",
+    "type": "error",
+  },
+  "error_full": {
+    "details": "{"error":{"message":"boom"}}",
+    "title": "Agent crashed",
+    "type": "error",
+  },
+  "executed_tool": {
+    "data": {
+      "integratedToolType": "TACTICAL_RMM",
+      "parameters": {
+        "script": "cleanup.sh",
+      },
+      "result": "Freed 2.3 GB",
+      "success": true,
+      "toolExecutionRequestId": "exec-1",
+      "toolFunction": "run_script",
+      "toolTitle": undefined,
+      "type": "EXECUTED_TOOL",
+    },
+    "type": "tool-execution",
+  },
+  "executed_tool_failure_no_exec_id": {
+    "data": {
+      "integratedToolType": "FLEET_MDM",
+      "parameters": undefined,
+      "result": "Device unreachable",
+      "success": false,
+      "toolExecutionRequestId": undefined,
+      "toolFunction": "lock_device",
+      "toolTitle": undefined,
+      "type": "EXECUTED_TOOL",
+    },
+    "type": "tool-execution",
+  },
+  "executing_tool": {
+    "data": {
+      "integratedToolType": "TACTICAL_RMM",
+      "parameters": {
+        "script": "cleanup.sh",
+        "timeout": 30,
+      },
+      "toolExecutionRequestId": "exec-1",
+      "toolExplanation": "Discovering columns available in the system_info table for accurate querying.",
+      "toolFunction": "run_script",
+      "toolTitle": "Run cleanup script",
+      "type": "EXECUTING_TOOL",
+    },
+    "type": "tool-execution",
+  },
+  "executing_tool_minimal": {
+    "data": {
+      "integratedToolType": "",
+      "parameters": undefined,
+      "toolExecutionRequestId": undefined,
+      "toolExplanation": undefined,
+      "toolFunction": "",
+      "toolTitle": undefined,
+      "type": "EXECUTING_TOOL",
+    },
+    "type": "tool-execution",
+  },
+  "guide": {
+    "text": "## Enroll a device
+1. Open Settings",
+    "type": "guide-delta",
+  },
+  "guide_empty_string": {
+    "text": "",
+    "type": "guide-delta",
+  },
+  "guide_missing_text": null,
+  "message_end": {
+    "type": "turn-end",
+  },
+  "message_request": {
+    "contextItems": undefined,
+    "displayName": "Alice",
+    "kind": "message-request",
+    "ownerType": "CLIENT",
+    "text": "open a ticket",
+    "type": "participant",
+    "userId": "user-42",
+  },
+  "message_request_no_text": {
+    "contextItems": undefined,
+    "displayName": undefined,
+    "kind": "message-request",
+    "ownerType": undefined,
+    "text": "",
+    "type": "participant",
+    "userId": undefined,
+  },
+  "message_request_with_context_items": {
+    "contextItems": [
+      {
+        "id": "dev-1",
+        "label": "dev-1",
+        "type": "device",
+      },
+    ],
+    "displayName": undefined,
+    "kind": "message-request",
+    "ownerType": undefined,
+    "text": "diagnose this device",
+    "type": "participant",
+    "userId": undefined,
+  },
+  "message_start": {
+    "type": "turn-start",
+  },
+  "missing_type": null,
+  "null_chunk": null,
+  "number_chunk": null,
+  "string_chunk": null,
+  "system": {
+    "kind": "system",
+    "text": "Technician joined the chat",
+    "type": "participant",
+  },
+  "system_no_text": null,
+  "text": {
+    "text": "Hello, ",
+    "type": "text-delta",
+  },
+  "text_empty_string": {
+    "text": "",
+    "type": "text-delta",
+  },
+  "text_missing_text_field": null,
+  "thinking": {
+    "text": "Considering options…",
+    "type": "thinking-delta",
+  },
+  "thinking_missing_text": null,
+  "token_usage": {
+    "contextSize": 180000,
+    "inputTokensSize": 1200,
+    "outputTokensSize": 340,
+    "totalTokensSize": 1540,
+    "type": "token-usage",
+  },
+  "token_usage_empty_defaults": {
+    "contextSize": 0,
+    "inputTokensSize": 0,
+    "outputTokensSize": 0,
+    "totalTokensSize": 0,
+    "type": "token-usage",
+  },
+  "undefined_chunk": null,
+  "unknown_type": null,
+}
+`;
+
+exports[`decodeNatsChunk — seq envelope > lifts a numeric JetStream \`streamSeq\` into \`seq\`, and omits it otherwise (snapshot) 1`] = `
+{
+  "absent": {
+    "text": "hi",
+    "type": "text-delta",
+  },
+  "non_numeric": {
+    "text": "hi",
+    "type": "text-delta",
+  },
+  "numeric": {
+    "seq": 42,
+    "text": "hi",
+    "type": "text-delta",
+  },
+  "zero": {
+    "seq": 0,
+    "type": "turn-start",
+  },
+}
+`;