@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.100

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

@@ -0,0 +1,119 @@
+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");
+});

package/src/performance/otlp-trace.ts

@@ -0,0 +1,134 @@
+/**
+ * Ship perf spans to a local OTLP/HTTP trace viewer (kundi) so an interaction's phases read as a
+ * callstack. Every export is a no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set. Tracing never throws
+ * into the app: a failed POST is swallowed. Attributes are scalar-only, matching the viewer's decoder.
+ */
+
+import type { PhaseMark } from "./perf-timings";
+
+export type SpanAttributeValue =
+  | { stringValue: string }
+  | { doubleValue: number }
+  | { boolValue: boolean };
+
+export interface SpanAttribute {
+  key: string;
+  value: SpanAttributeValue;
+}
+
+export interface TraceSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  startTimeUnixNano: string;
+  endTimeUnixNano: string;
+  attributes?: readonly SpanAttribute[];
+}
+
+function randomHex(bytes: number): string {
+  const buffer = new Uint8Array(bytes);
+
+  crypto.getRandomValues(buffer);
+
+  return Array.from(buffer, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** A 16-byte trace id as 32 lowercase hex chars, per the OTLP wire format. */
+export function newTraceId(): string {
+  return randomHex(16);
+}
+
+/** An 8-byte span id as 16 lowercase hex chars, per the OTLP wire format. */
+export function newSpanId(): string {
+  return randomHex(8);
+}
+
+/** Build the OTLP/JSON `resourceSpans` body the trace viewer's `/v1/traces` decoder reads. */
+export function buildOtlpTracePayload(serviceName: string, spans: readonly TraceSpan[]) {
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+        },
+        scopeSpans: [
+          {
+            spans: spans.map((span) => ({
+              traceId: span.traceId,
+              spanId: span.spanId,
+              // the viewer reads a missing parent as root; an empty string is the same, without a conditional key
+              parentSpanId: span.parentSpanId ?? "",
+              name: span.name,
+              startTimeUnixNano: span.startTimeUnixNano,
+              endTimeUnixNano: span.endTimeUnixNano,
+              attributes: (span.attributes ?? []).map((attribute) => ({
+                key: attribute.key,
+                value: attribute.value,
+              })),
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function nanosFromPerfMs(milliseconds: number): string {
+  const originNs = BigInt(Math.round(performance.timeOrigin * 1e6));
+
+  return String(originNs + BigInt(Math.round(milliseconds * 1e6)));
+}
+
+/** Turn drained phase marks into a span tree: a `scope` root with one child span per phase, in order. */
+export function phaseMarksToSpans(scope: string, marks: readonly PhaseMark[]): TraceSpan[] {
+  const totalMs = marks.reduce((sum, mark) => sum + mark.elapsedMs, 0);
+  const endMs = performance.now();
+  const startMs = endMs - totalMs;
+  const traceId = newTraceId();
+  const rootSpanId = newSpanId();
+  const root: TraceSpan = {
+    traceId,
+    spanId: rootSpanId,
+    name: `cueloop.${scope}`,
+    startTimeUnixNano: nanosFromPerfMs(startMs),
+    endTimeUnixNano: nanosFromPerfMs(endMs),
+  };
+
+  let cursorMs = startMs;
+  const children = marks.map((mark) => {
+    const phaseStartMs = cursorMs;
+
+    cursorMs += mark.elapsedMs;
+
+    return {
+      traceId,
+      spanId: newSpanId(),
+      parentSpanId: rootSpanId,
+      name: `cueloop.${scope}.${mark.label}`,
+      startTimeUnixNano: nanosFromPerfMs(phaseStartMs),
+      endTimeUnixNano: nanosFromPerfMs(cursorMs),
+    };
+  });
+
+  return [root, ...children];
+}
+
+/** POST the spans to `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces` as OTLP/JSON; a no-op when the endpoint is unset. */
+export async function postOtlpTrace(
+  serviceName: string,
+  spans: readonly TraceSpan[],
+): Promise<void> {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+
+  if (endpoint === undefined || spans.length === 0) return;
+
+  // strip a trailing slash so an endpoint like "http://host:4318/" does not become "//v1/traces"
+  const base = endpoint.replace(/\/+$/, "");
+
+  await fetch(`${base}/v1/traces`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(buildOtlpTracePayload(serviceName, spans)),
+  }).catch(() => undefined);
+}

package/src/performance/perf-report.ts

@@ -0,0 +1,18 @@
+/**
+ * Report the drained perf marks for a scope two ways from one set of instrumentation: a phase block on
+ * stderr when CUELOOP_PERF=1, and a kundi span tree when the OTLP endpoint is set. No-op when neither is on.
+ */
+
+import { formatPerfBlock, takePerfMarks } from "./perf-timings";
+import { phaseMarksToSpans, postOtlpTrace } from "./otlp-trace";
+
+const PERF_SERVICE_NAME = "cueloop-client";
+
+export function reportPerfMarks(scope: string): void {
+  const marks = takePerfMarks();
+
+  if (marks.length === 0) return;
+
+  if (process.env.CUELOOP_PERF === "1") process.stderr.write(formatPerfBlock(scope, marks));
+  void postOtlpTrace(PERF_SERVICE_NAME, phaseMarksToSpans(scope, marks));
+}

package/src/performance/perf-timings.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import { formatPerfBlock } from "./perf-timings";
+
+test("formatPerfBlock renders labeled rows and a summed TOTAL", () => {
+  const block = formatPerfBlock("startup", [
+    { label: "connect", elapsedMs: 12.34 },
+    { label: "firstRender", elapsedMs: 7.66 },
+  ]);
+
+  expect(block).toContain("--- perf startup ---");
+  expect(block).toContain("connect  12.3ms");
+  expect(block).toContain("firstRender  7.7ms");
+  expect(block).toContain("TOTAL  20.0ms");
+});
+
+test("formatPerfBlock totals to zero for no marks", () => {
+  expect(formatPerfBlock("startup", [])).toContain("TOTAL  0.0ms");
+});

package/src/performance/perf-timings.ts

@@ -0,0 +1,39 @@
+/** Startup phase timing for the perf harness: records elapsed ms between marks and flushes a
+ * labeled block to stderr. Every entry point is a no-op unless the CUELOOP_PERF env var is "1". */
+
+export interface PhaseMark {
+  label: string;
+  elapsedMs: number;
+}
+
+const phaseMarks: PhaseMark[] = [];
+let lastMarkAt: number | null = null;
+
+/** Marks record when the stderr timer (CUELOOP_PERF=1) or the kundi exporter (OTEL endpoint) is on. */
+function perfInstrumentationEnabled(): boolean {
+  return process.env.CUELOOP_PERF === "1" || process.env.OTEL_EXPORTER_OTLP_ENDPOINT !== undefined;
+}
+
+/** Record the elapsed ms since the previous mark (or process start) under `label`. */
+export function perfMark(label: string): void {
+  if (!perfInstrumentationEnabled()) return;
+  const now = performance.now();
+
+  phaseMarks.push({ label, elapsedMs: now - (lastMarkAt ?? 0) });
+  lastMarkAt = now;
+}
+
+/** Drain the recorded marks for a reporter to format or export; empties the buffer for the next scope. */
+export function takePerfMarks(): PhaseMark[] {
+  lastMarkAt = null;
+
+  return phaseMarks.splice(0, phaseMarks.length);
+}
+
+/** Render phase deltas as the stderr block: a header, one indented row per mark, a summed TOTAL. */
+export function formatPerfBlock(scope: string, marks: readonly PhaseMark[]): string {
+  const totalMs = marks.reduce((sum, mark) => sum + mark.elapsedMs, 0);
+  const rows = marks.map((mark) => `  ${mark.label}  ${mark.elapsedMs.toFixed(1)}ms`);
+
+  return [`--- perf ${scope} ---`, ...rows, `  TOTAL  ${totalMs.toFixed(1)}ms`, ""].join("\n");
+}

package/src/prototype/components/PrototypeContentView.stories.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { PrototypeContentView } from "./PrototypeContentView";
+
+export const meta: StoryMeta = { title: "Surfaces/PrototypeContentView" };
+
+// The story renderer reports no kitty graphics, so the view shows its fallback.
+export const Unsupported: Story = {
+  render: () => (
+    <PrototypeContentView
+      prototypePath="/tmp/example.html"
+      canComment={true}
+      onCommentElement={() => {}}
+    />
+  ),
+  expectedColors: [DARK.textDim],
+  size: { width: 80, height: 24 },
+};