@cueloop/client 0.1.0-alpha.8 → 0.1.0-alpha.81

package/src/markdown-grid.ts

@@ -0,0 +1,203 @@
+/**
+ * Grid layout for the two block kinds the read-only thread renders as tables:
+ * a GFM table (bold header over a rule, columns aligned per the delimiter row,
+ * no vertical borders) and leading YAML
+ * frontmatter (a full-bordered key/value grid, bold nowrap keys, wrapped
+ * values). Both are pure: they turn a block's source text and a width into
+ * positioned, styled segments the renderer prints verbatim, so a char-frame
+ * test can assert the exact grid.
+ */
+
+import { wrapLines } from "./mark-runs";
+
+/** One painted piece of a grid line: its text plus whether it reads bold or dim (a border). */
+export interface GridSegment {
+  text: string;
+  bold: boolean;
+  dim: boolean;
+}
+
+/** A grid line is left-to-right segments; concatenating their text gives the row. */
+export type GridLine = GridSegment[];
+
+export type ColumnAlign = "left" | "right" | "center";
+
+export interface MarkdownTable {
+  aligns: ColumnAlign[];
+  header: string[];
+  rows: string[][];
+}
+
+/**
+ * Split a table row into trimmed cells on unescaped pipes, unescaping `\|` into a
+ * literal pipe, and dropping the empty cells an optional leading or trailing
+ * border pipe produces (an intentional blank cell keeps its surrounding spaces).
+ */
+function splitTableRow(line: string): string[] {
+  const trimmed = line.trim();
+  const parts: string[] = [];
+  let cell = "";
+
+  for (let index = 0; index < trimmed.length; index++) {
+    const char = trimmed[index]!;
+
+    if (char === "\\" && trimmed[index + 1] === "|") {
+      cell += "|";
+      index++;
+    } else if (char === "|") {
+      parts.push(cell);
+      cell = "";
+    } else {
+      cell += char;
+    }
+  }
+  parts.push(cell);
+  if (parts.length > 1 && parts[0] === "") parts.shift();
+  if (parts.length > 1 && parts[parts.length - 1] === "") parts.pop();
+
+  return parts.map((part) => part.trim());
+}
+
+/** Parse a GFM table block's verbatim source into header cells, column alignments, and body rows. */
+export function parseMarkdownTable(text: string): MarkdownTable {
+  const lines = text.split("\n").filter((line) => line.trim() !== "");
+  const header = splitTableRow(lines[0] ?? "");
+  const aligns: ColumnAlign[] = splitTableRow(lines[1] ?? "").map((cell) => {
+    const left = cell.startsWith(":");
+    const right = cell.endsWith(":");
+
+    return left && right ? "center" : right ? "right" : "left";
+  });
+  const rows = lines.slice(2).map(splitTableRow);
+
+  return { aligns, header, rows };
+}
+
+/** Pad `text` to `width` cells under an alignment. */
+function pad(text: string, width: number, align: ColumnAlign): string {
+  const slack = Math.max(0, width - text.length);
+
+  if (align === "right") return " ".repeat(slack) + text;
+  if (align === "center") {
+    const left = Math.floor(slack / 2);
+
+    return " ".repeat(left) + text + " ".repeat(slack - left);
+  }
+
+  return text + " ".repeat(slack);
+}
+
+/** Two spaces separate table columns; the read-only render draws no vertical rule. */
+const COLUMN_GAP = "  ";
+
+/**
+ * Lay out a GFM table: a bold header row, a dim rule spanning the table width,
+ * then the body rows, every column padded to its widest cell under its alignment.
+ */
+export function layoutMarkdownTable(table: MarkdownTable): GridLine[] {
+  const columnCount = Math.max(table.header.length, ...table.rows.map((row) => row.length), 1);
+  const alignOf = (column: number): ColumnAlign => table.aligns[column] ?? "left";
+  const cellAt = (cells: string[], column: number): string => cells[column] ?? "";
+  const widths = Array.from({ length: columnCount }, (_unused, column) =>
+    Math.max(
+      cellAt(table.header, column).length,
+      ...table.rows.map((row) => cellAt(row, column).length),
+      1,
+    ),
+  );
+  const rowText = (cells: string[]): string =>
+    widths
+      .map((width, column) => pad(cellAt(cells, column), width, alignOf(column)))
+      .join(COLUMN_GAP);
+  const totalWidth =
+    widths.reduce((sum, width) => sum + width, 0) + COLUMN_GAP.length * (columnCount - 1);
+  const lines: GridLine[] = [
+    [{ text: rowText(table.header), bold: true, dim: false }],
+    [{ text: "─".repeat(totalWidth), bold: false, dim: true }],
+  ];
+
+  for (const row of table.rows) lines.push([{ text: rowText(row), bold: false, dim: false }]);
+
+  return lines;
+}
+
+export interface FrontmatterRow {
+  key: string;
+  value: string;
+}
+
+/** Parse frontmatter YAML into top-level key/value rows; indented lines fold into the row above. */
+export function parseFrontmatterRows(text: string): FrontmatterRow[] {
+  const rows: FrontmatterRow[] = [];
+
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    const match = /^([^:\s][^:]*):\s?(.*)$/.exec(line);
+
+    if (match) {
+      rows.push({ key: match[1]!.trim(), value: match[2]! });
+    } else if (rows.length > 0) {
+      const previous = rows[rows.length - 1]!;
+
+      previous.value = previous.value === "" ? line.trim() : `${previous.value}\n${line.trim()}`;
+    }
+  }
+
+  return rows;
+}
+
+/** The fixed cells a frontmatter grid row spends on borders and padding: `│ key │ value │`. */
+const FRONTMATTER_CHROME = 7;
+
+/** Wrap a cell value into lines no wider than `width`, honouring its own line breaks. */
+function wrapCell(value: string, width: number): string[] {
+  if (value === "") return [""];
+
+  return wrapLines(value, width).map((line) => value.slice(line.start, line.end));
+}
+
+/**
+ * Lay out leading frontmatter as a full-bordered key/value grid: bold nowrap
+ * keys on the left, values wrapped to the remaining width on the right, a rule
+ * between every row.
+ */
+export function layoutFrontmatterGrid(rows: FrontmatterRow[], maxWidth: number): GridLine[] {
+  if (rows.length === 0) return [];
+  const keyWidth = Math.max(3, ...rows.map((row) => row.key.length));
+  // size the value column to its content, capped at the width left after the key column and borders,
+  // so a short frontmatter table stays compact and a long value wraps instead of overflowing
+  const available = Math.max(3, maxWidth - keyWidth - FRONTMATTER_CHROME);
+  const naturalWidth = Math.max(
+    3,
+    ...rows.map((row) => Math.max(0, ...row.value.split("\n").map((line) => line.length))),
+  );
+  const valueWidth = Math.min(naturalWidth, available);
+  const rule = (left: string, mid: string, right: string): GridLine => [
+    {
+      text: left + "─".repeat(keyWidth + 2) + mid + "─".repeat(valueWidth + 2) + right,
+      bold: false,
+      dim: true,
+    },
+  ];
+  const lines: GridLine[] = [rule("┌", "┬", "┐")];
+
+  rows.forEach((row, rowIndex) => {
+    if (rowIndex > 0) lines.push(rule("├", "┼", "┤"));
+    const valueLines = wrapCell(row.value, valueWidth);
+
+    valueLines.forEach((valueLine, valueIndex) => {
+      const keyCell = valueIndex === 0 ? row.key.padEnd(keyWidth) : " ".repeat(keyWidth);
+
+      lines.push([
+        { text: "│ ", bold: false, dim: true },
+        { text: keyCell, bold: valueIndex === 0, dim: false },
+        { text: " │ ", bold: false, dim: true },
+        { text: valueLine.padEnd(valueWidth), bold: false, dim: false },
+        { text: " │", bold: false, dim: true },
+      ]);
+    });
+  });
+  lines.push(rule("└", "┴", "┘"));
+
+  return lines;
+}

package/src/markdown-highlight.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { markdownHighlightRanges, type MarkdownHighlightGroup } from "./markdown-highlight";
+
+/** The substring a range covers, paired with its group, for readable assertions. */
+function painted(source: string): Array<{ text: string; group: MarkdownHighlightGroup }> {
+  return markdownHighlightRanges(source).map((range) => ({
+    text: source.slice(range.start, range.end),
+    group: range.group,
+  }));
+}
+
+describe("markdownHighlightRanges", () => {
+  test("a heading dims its marker and bolds the text without coloring it", () => {
+    expect(painted("## Rollout Plan")).toEqual([
+      { text: "## ", group: "marker" },
+      { text: "Rollout Plan", group: "heading" },
+    ]);
+  });
+
+  test("a plain link colors its brackets and href but leaves the label plain", () => {
+    const runs = painted("see [docs](https://x.dev)");
+
+    expect(runs).toContainEqual({ text: "[", group: "link" });
+    expect(runs).toContainEqual({ text: "](https://x.dev)", group: "link" });
+    expect(runs.some((run) => run.text.includes("docs"))).toBe(false);
+  });
+
+  test("an @-scope link label colors along with the brackets and href", () => {
+    expect(painted("[@pierre/diffs](https://npm/@pierre/diffs)")).toEqual([
+      { text: "[@pierre/diffs](https://npm/@pierre/diffs)", group: "link" },
+    ]);
+  });
+
+  test("inline code grays the whole backtick span", () => {
+    expect(painted("call `run()` now")).toContainEqual({ text: "`run()`", group: "code" });
+  });
+
+  test("a fenced code block grays the whole block", () => {
+    const source = "```ts\nconst a = 1;\n```";
+
+    expect(painted(source)).toEqual([{ text: source, group: "code" }]);
+  });
+
+  test("inline code inside a list item resolves against the whole source offset", () => {
+    const source = "- run `cueloop dev`";
+    const code = markdownHighlightRanges(source).find((range) => range.group === "code");
+
+    expect(code && source.slice(code.start, code.end)).toBe("`cueloop dev`");
+  });
+
+  test("bold, emphasis, list markers, quotes, and rules stay plain", () => {
+    expect(markdownHighlightRanges("ship **now** or _later_")).toEqual([]);
+    expect(markdownHighlightRanges("- a task")).toEqual([]);
+    expect(markdownHighlightRanges("> quoted line")).toEqual([]);
+    expect(markdownHighlightRanges("---")).toEqual([]);
+  });
+
+  test("plain prose yields no ranges", () => {
+    expect(markdownHighlightRanges("just words here")).toEqual([]);
+  });
+});

package/src/markdown-highlight.ts

@@ -0,0 +1,122 @@
+/**
+ * Scan raw markdown source into highlight ranges for the inline thread editor.
+ * The scheme is deliberately restrained, matching a plain markdown editor: a
+ * heading dims its `#` marker and bolds the title text (no color); links render
+ * in one link color; inline and fenced code gray out. Everything else - bold,
+ * emphasis, list and quote markers, rules - stays plain source. Block structure
+ * reuses the schema parser so a heading or code fence is defined in one place.
+ */
+
+import { parseBlocks, LEADING_BLOCK_MARKER, type Block } from "@cueloop/schema";
+
+/** Every markdown token class the editor paints; "marker" is the dimmed heading punctuation. */
+export const MARKDOWN_HIGHLIGHT_GROUPS = ["heading", "marker", "link", "code"] as const;
+
+/** A markdown token class the editor paints. */
+export type MarkdownHighlightGroup = (typeof MARKDOWN_HIGHLIGHT_GROUPS)[number];
+
+/** A char range in the raw markdown source to paint with one group's style; end is exclusive. */
+export interface MarkdownHighlightRange {
+  start: number;
+  end: number;
+  group: MarkdownHighlightGroup;
+}
+
+/** The absolute source offset where each 0-based line begins. */
+function lineStartOffsets(source: string): number[] {
+  const offsets = [0];
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "\n") offsets.push(index + 1);
+  }
+
+  return offsets;
+}
+
+// gray a balanced backtick run and color a [text](href) link; bold and emphasis stay plain source
+const INLINE_TOKEN = /(`+)(?:.+?)\1|\[[^\]]+\]\([^)]+\)/g;
+
+/** Gray inline code and color links found in one text span; other inline markup stays plain. */
+function scanInlineTokens(text: string, base: number, into: MarkdownHighlightRange[]): void {
+  INLINE_TOKEN.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = INLINE_TOKEN.exec(text)) !== null) {
+    const token = match[0];
+    const start = base + match.index;
+    const end = start + token.length;
+
+    if (token.startsWith("`")) {
+      into.push({ start, end, group: "code" });
+      continue;
+    }
+    // a link colors its brackets and href; the [] label stays plain unless it is an @-scope, matching how a
+    // markdown source view paints links
+    const closeBracket = token.indexOf("]");
+
+    if (token.slice(1, closeBracket).startsWith("@")) {
+      into.push({ start, end, group: "link" });
+    } else {
+      into.push({ start, end: start + 1, group: "link" });
+      into.push({ start: start + closeBracket, end, group: "link" });
+    }
+  }
+}
+
+function isHeadingKind(kind: Block["kind"]): boolean {
+  return kind === "h1" || kind === "h2" || kind === "h3";
+}
+
+/** Dim a heading's `#` marker and bold the rest of the line (no color). */
+function scanHeadingBlock(
+  firstLineStart: number,
+  source: string,
+  lineStarts: number[],
+  block: Block,
+  into: MarkdownHighlightRange[],
+): void {
+  const lineText = source.slice(firstLineStart, lineStarts[block.lineStart + 1] ?? source.length);
+  const marker = lineText.match(LEADING_BLOCK_MARKER)?.[0] ?? "";
+
+  into.push({ start: firstLineStart, end: firstLineStart + marker.length, group: "marker" });
+  into.push({
+    start: firstLineStart + marker.length,
+    end: firstLineStart + lineText.trimEnd().length,
+    group: "heading",
+  });
+}
+
+/** Paint one block: heading marker and title, grayed code block, or inline code and links in prose. */
+function scanBlock(
+  block: Block,
+  source: string,
+  lineStarts: number[],
+  into: MarkdownHighlightRange[],
+): void {
+  const firstLineStart = lineStarts[block.lineStart] ?? 0;
+
+  if (isHeadingKind(block.kind)) {
+    scanHeadingBlock(firstLineStart, source, lineStarts, block, into);
+  } else if (block.kind === "code") {
+    into.push({
+      start: firstLineStart,
+      end: lineStarts[block.lineEnd + 1] ?? source.length,
+      group: "code",
+    });
+  } else if (block.kind !== "hr") {
+    for (let line = block.lineStart; line <= block.lineEnd; line++) {
+      const lineStart = lineStarts[line] ?? source.length;
+      const lineText = source.slice(lineStart, lineStarts[line + 1] ?? source.length);
+
+      scanInlineTokens(lineText.replace(/\r?\n$/, ""), lineStart, into);
+    }
+  }
+}
+
+/** Scan raw markdown source into highlight ranges over the source (markers included), for the inline editor. */
+export function markdownHighlightRanges(source: string): MarkdownHighlightRange[] {
+  const lineStarts = lineStartOffsets(source);
+  const ranges: MarkdownHighlightRange[] = [];
+
+  for (const block of parseBlocks(source)) scanBlock(block, source, lineStarts, ranges);
+
+  return ranges;
+}

package/src/pasted-image.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { imagePlaceholder, looksLikeBinaryPaste } from "./pasted-image";
+
+function bytesOf(...values: number[]): Uint8Array {
+  return Uint8Array.from(values);
+}
+
+describe("looksLikeBinaryPaste", () => {
+  test("plain text pastes stay text", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("just a normal comment"))).toBe(false);
+  });
+
+  test("multi-line text with tabs and newlines stays text", () => {
+    expect(
+      looksLikeBinaryPaste(new TextEncoder().encode("line one\n\tline two\r\nline three")),
+    ).toBe(false);
+  });
+
+  test("unicode text stays text", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("café — naïve — 日本語 — 🎉"))).toBe(
+      false,
+    );
+  });
+
+  test("a PNG signature is binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a))).toBe(
+      true,
+    );
+  });
+
+  test("a JPEG signature is binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10))).toBe(true);
+  });
+
+  test("a GIF signature is binary", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("GIF89a\x01\x02"))).toBe(true);
+  });
+
+  test("a WEBP signature is binary", () => {
+    expect(
+      looksLikeBinaryPaste(bytesOf(0x52, 0x49, 0x46, 0x46, 1, 2, 3, 4, 0x57, 0x45, 0x42, 0x50)),
+    ).toBe(true);
+  });
+
+  test("a NUL byte marks binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x68, 0x69, 0x00, 0x74, 0x68, 0x65, 0x72, 0x65))).toBe(
+      true,
+    );
+  });
+
+  test("a burst of control bytes marks binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08))).toBe(
+      true,
+    );
+  });
+
+  test("an empty paste is not binary", () => {
+    expect(looksLikeBinaryPaste(new Uint8Array())).toBe(false);
+  });
+});
+
+describe("imagePlaceholder", () => {
+  test("numbers each pasted image", () => {
+    expect(imagePlaceholder(1)).toBe("[Image #1]");
+    expect(imagePlaceholder(2)).toBe("[Image #2]");
+  });
+});

package/src/pasted-image.ts

@@ -0,0 +1,60 @@
+/** Detects an image or other binary paste so a composer shows an [Image #n] placeholder instead of dumping raw bytes into the draft. */
+
+const IMAGE_MAGIC_SIGNATURES: number[][] = [
+  [0x89, 0x50, 0x4e, 0x47], // PNG
+  [0xff, 0xd8, 0xff], // JPEG
+  [0x47, 0x49, 0x46, 0x38], // GIF87a / GIF89a
+];
+
+const CONTROL_RATIO_THRESHOLD = 0.15;
+const PASTE_DECODER = new TextDecoder("utf-8", { fatal: false });
+
+function hasImageMagic(bytes: Uint8Array): boolean {
+  for (const signature of IMAGE_MAGIC_SIGNATURES) {
+    if (signature.every((byte, index) => bytes[index] === byte)) return true;
+  }
+
+  const isRiffWebp =
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 && // R
+    bytes[1] === 0x49 && // I
+    bytes[2] === 0x46 && // F
+    bytes[3] === 0x46 && // F
+    bytes[8] === 0x57 && // W
+    bytes[9] === 0x45 && // E
+    bytes[10] === 0x42 && // B
+    bytes[11] === 0x50; // P
+
+  return isRiffWebp;
+}
+
+function isControlCodePoint(codePoint: number): boolean {
+  if (codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d) return false;
+
+  return codePoint < 0x20 || codePoint === 0x7f;
+}
+
+/** True when a paste is an image or other non-text binary payload and should collapse to a placeholder. */
+export function looksLikeBinaryPaste(bytes: Uint8Array): boolean {
+  if (bytes.length === 0) return false;
+  if (hasImageMagic(bytes)) return true;
+
+  const decoded = PASTE_DECODER.decode(bytes);
+  let controlCount = 0;
+  let total = 0;
+
+  for (const character of decoded) {
+    total += 1;
+    const codePoint = character.codePointAt(0) ?? 0;
+
+    if (codePoint === 0 || codePoint === 0xfffd) return true;
+    if (isControlCodePoint(codePoint)) controlCount += 1;
+  }
+
+  return total > 0 && controlCount / total > CONTROL_RATIO_THRESHOLD;
+}
+
+/** The draft placeholder for the nth image pasted into a composer: [Image #1], [Image #2], … */
+export function imagePlaceholder(index: number): string {
+  return `[Image #${index}]`;
+}

package/src/perf/otlp-trace.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  buildOtlpTracePayload,
+  phaseMarksToSpans,
+  postOtlpTrace,
+  type TraceSpan,
+} from "./otlp-trace";
+
+afterEach(() => {
+  delete process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+});
+
+const span: TraceSpan = {
+  traceId: "0123456789abcdef0123456789abcdef",
+  spanId: "0123456789abcdef",
+  name: "cueloop.interaction",
+  startTimeUnixNano: "1000",
+  endTimeUnixNano: "2000",
+  attributes: [
+    { key: "terminal.trigger", value: { stringValue: "key:j" } },
+    { key: "terminal.frame.budget_ms", value: { doubleValue: 16.7 } },
+    { key: "terminal.backpressure", value: { boolValue: true } },
+  ],
+};
+
+test("buildOtlpTracePayload carries service.name and maps scalar attributes to OTLP values", () => {
+  const payload = buildOtlpTracePayload("cueloop-client", [span]);
+
+  expect(payload).toEqual({
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [{ key: "service.name", value: { stringValue: "cueloop-client" } }],
+        },
+        scopeSpans: [
+          {
+            spans: [
+              {
+                traceId: "0123456789abcdef0123456789abcdef",
+                spanId: "0123456789abcdef",
+                parentSpanId: "",
+                name: "cueloop.interaction",
+                startTimeUnixNano: "1000",
+                endTimeUnixNano: "2000",
+                attributes: [
+                  { key: "terminal.trigger", value: { stringValue: "key:j" } },
+                  { key: "terminal.frame.budget_ms", value: { doubleValue: 16.7 } },
+                  { key: "terminal.backpressure", value: { boolValue: true } },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+});
+
+test("phaseMarksToSpans builds a scope root with one child span per phase under one trace", () => {
+  const spans = phaseMarksToSpans("startup", [
+    { label: "renderer", elapsedMs: 10 },
+    { label: "firstFrame", elapsedMs: 20 },
+  ]);
+
+  expect(spans).toHaveLength(3);
+  const [root, first, second] = spans;
+  expect(root!.name).toBe("cueloop.startup");
+  expect(root!.parentSpanId).toBeUndefined();
+  expect(first!.name).toBe("cueloop.startup.renderer");
+  expect(first!.parentSpanId).toBe(root!.spanId);
+  expect(second!.parentSpanId).toBe(root!.spanId);
+  expect(new Set(spans.map((each) => each.traceId)).size).toBe(1);
+});
+
+test("postOtlpTrace sends no request when the endpoint is unset", async () => {
+  const requests: string[] = [];
+  const server = Bun.serve({
+    port: 0,
+    fetch(request) {
+      requests.push(request.url);
+
+      return new Response("{}");
+    },
+  });
+  try {
+    await postOtlpTrace("cueloop-client", [span]);
+  } finally {
+    await server.stop(true);
+  }
+
+  expect(requests).toHaveLength(0);
+});
+
+test("postOtlpTrace POSTs OTLP JSON to /v1/traces when the endpoint is set", async () => {
+  const requests: string[] = [];
+  const server = Bun.serve({
+    port: 0,
+    async fetch(request) {
+      requests.push(`${request.method} ${new URL(request.url).pathname}\n${await request.text()}`);
+
+      return new Response("{}");
+    },
+  });
+  // a trailing slash must not double up into "//v1/traces"
+  process.env.OTEL_EXPORTER_OTLP_ENDPOINT = `http://127.0.0.1:${server.port}/`;
+  try {
+    await postOtlpTrace("cueloop-client", [span]);
+  } finally {
+    await server.stop(true);
+  }
+
+  expect(requests).toHaveLength(1);
+  expect(requests[0]).toContain("POST /v1/traces");
+  expect(requests[0]).toContain('"service.name"');
+  expect(requests[0]).toContain("cueloop.interaction");
+});