@kuralle-syrinx/core 2.1.0

package/src/voice-text.test.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { takeCompleteVoiceText, isCompleteVoiceText, appendVoiceText } from "./voice-text.js";
+
+describe("isCompleteVoiceText", () => {
+  it("treats terminal punctuation as complete", () => {
+    expect(isCompleteVoiceText("Hello there.")).toBe(true);
+    expect(isCompleteVoiceText("Really?!")).toBe(true);
+  });
+
+  it("treats an unterminated fragment as incomplete", () => {
+    expect(isCompleteVoiceText("Hello there")).toBe(false);
+    expect(isCompleteVoiceText("and then we")).toBe(false);
+  });
+
+  it("looks past trailing closing quotes/brackets to the terminator", () => {
+    expect(isCompleteVoiceText('She said "hi."')).toBe(true);
+    expect(isCompleteVoiceText("(a complete aside.)")).toBe(true);
+    expect(isCompleteVoiceText('an open quote "')).toBe(false);
+  });
+
+  it("recognizes non-English terminal punctuation", () => {
+    expect(isCompleteVoiceText("こんにちは。")).toBe(true); // Japanese full stop
+    expect(isCompleteVoiceText("مرحبا؟")).toBe(true); // Arabic question mark
+    expect(isCompleteVoiceText("नमस्ते।")).toBe(true); // Devanagari danda
+  });
+});
+
+describe("takeCompleteVoiceText", () => {
+  it("splits leading complete sentences from the incomplete remainder", () => {
+    const { text, remaining } = takeCompleteVoiceText("One. Two. Thre");
+    expect(text).toBe("One. Two.");
+    expect(remaining).toBe("Thre");
+  });
+
+  it("returns no text when nothing is complete yet", () => {
+    const { text, remaining } = takeCompleteVoiceText("still going");
+    expect(text).toBe("");
+    expect(remaining).toBe("still going");
+  });
+
+  it("emits multiple complete sentences and buffers only the trailing fragment", () => {
+    const { text, remaining } = takeCompleteVoiceText("Done. And more.");
+    expect(text).toBe("Done. And more.");
+    expect(remaining).toBe("");
+  });
+
+  it("buffers the trailing incomplete fragment after a complete sentence", () => {
+    // Capitalized continuation so the locale-aware segmenter treats it as a new
+    // (still-incomplete) sentence rather than one run-on.
+    const { text, remaining } = takeCompleteVoiceText("Done. And more");
+    expect(text).toBe("Done.");
+    expect(remaining).toBe("And more");
+  });
+});
+
+describe("appendVoiceText", () => {
+  it("seeds from empty and trims", () => {
+    expect(appendVoiceText("", "  hi  ")).toBe("hi");
+  });
+
+  it("joins with a single space when neither side has whitespace at the seam", () => {
+    expect(appendVoiceText("Hello", "there")).toBe("Hello there");
+  });
+
+  it("does not double-space when the existing side already ends in whitespace", () => {
+    expect(appendVoiceText("Hello ", "there")).toBe("Hello there");
+  });
+
+  it("trims a whitespace-led next fragment (the seam's space collapses)", () => {
+    // Current behavior: a leading-whitespace `next` is trimmed and concatenated
+    // directly. Reachable inputs (trimmed segment text) never hit this path; the
+    // test pins the documented behavior rather than the intuitive one.
+    expect(appendVoiceText("Hello", " there")).toBe("Hellothere");
+  });
+
+  it("returns the existing text unchanged when the next fragment is blank", () => {
+    expect(appendVoiceText("Hello", "   ")).toBe("Hello");
+  });
+});

package/src/voice-text.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Voice Text Segmentation
+//
+// Pure helpers for turning a streaming LLM token feed into complete, speakable
+// sentence segments. No bus, no state — extracted from VoiceAgentSession so the
+// orchestrator owns wiring, not text rules.
+
+interface SentenceSegment {
+  segment: string;
+}
+
+/**
+ * Split off the leading run of complete sentences from `text`, returning the
+ * speakable prefix and the still-incomplete remainder. A segment is "complete"
+ * when it ends in terminal punctuation (optionally followed by closing quotes).
+ */
+export function takeCompleteVoiceText(text: string): { text: string; remaining: string } {
+  const segments = segmentSentences(text);
+  let emitted = "";
+  let remaining = "";
+  for (const segment of segments) {
+    if (remaining) {
+      remaining += segment;
+      continue;
+    }
+    if (isCompleteVoiceText(segment)) {
+      emitted += segment;
+    } else {
+      remaining = segment;
+    }
+  }
+  return { text: emitted.trimEnd(), remaining };
+}
+
+export function isCompleteVoiceText(text: string): boolean {
+  const trimmed = text.trim();
+  for (let index = trimmed.length - 1; index >= 0; index -= 1) {
+    const char = trimmed[index]!;
+    if (isClosingPunctuation(char)) continue;
+    return isTerminalPunctuation(char);
+  }
+  return false;
+}
+
+/** Join two voice-text fragments, normalizing whitespace at the seam. */
+export function appendVoiceText(existing: string, next: string): string {
+  const normalizedNext = next.trim();
+  if (!existing) return normalizedNext;
+  if (!normalizedNext) return existing;
+  if (/\s$/.test(existing) || /^\s/.test(next)) return `${existing}${normalizedNext}`;
+  return `${existing} ${normalizedNext}`;
+}
+
+function isClosingPunctuation(char: string): boolean {
+  return char === ")" || char === "]" || char === "}" || char === "\"" || char === "'" || char === "”" || char === "’";
+}
+
+function isTerminalPunctuation(char: string): boolean {
+  return char === "." ||
+    char === "!" ||
+    char === "?" ||
+    char === "。" ||
+    char === "！" ||
+    char === "？" ||
+    char === "؟" ||
+    char === "।" ||
+    char === "॥";
+}
+
+function segmentSentences(text: string): string[] {
+  const segmenter = createSentenceSegmenter();
+  if (segmenter) {
+    return Array.from(segmenter.segment(text), (part) => part.segment);
+  }
+
+  const segments: string[] = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (!isTerminalPunctuation(text[index]!)) continue;
+    let end = index + 1;
+    while (end < text.length && isClosingPunctuation(text[end]!)) end += 1;
+    if (end < text.length && !/\s/.test(text[end]!)) continue;
+    segments.push(text.slice(start, end));
+    start = end;
+  }
+  if (start < text.length) segments.push(text.slice(start));
+  return segments;
+}
+
+function createSentenceSegmenter(): { segment(text: string): Iterable<SentenceSegment> } | null {
+  const Segmenter = (Intl as unknown as { Segmenter?: new (
+    locale?: string | string[],
+    options?: { granularity: "sentence" },
+  ) => { segment(text: string): Iterable<SentenceSegment> } }).Segmenter;
+  if (!Segmenter) return null;
+  try {
+    return new Segmenter(undefined, { granularity: "sentence" });
+  } catch {
+    return null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}