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

package/src/keyboard/slash-palette.ts

@@ -0,0 +1,129 @@
+/**
+ * The "/" quick-action palette behind a composer: the skill list a leading
+ * slash opens, its prefix > substring > subsequence filter, and the inline
+ * "/word" completion offered mid-sentence. Pure; the surfaces render it.
+ */
+
+import { quickActionBody, type QuickAction } from "../settings/config";
+
+export interface SlashItem {
+  name: string;
+  description: string;
+  body: string;
+}
+
+export function slashItemsFrom(quickActions: QuickAction[]): SlashItem[] {
+  return quickActions.map((action) => ({
+    name: action.prompt
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, ""),
+    description: action.metadata ?? action.prompt,
+    body: quickActionBody(action),
+  }));
+}
+
+const WORD_BOUNDARY = /[\s\-_./:]/;
+
+/** Order-preserving subsequence score, or null when a query character is missing; higher is better. */
+export function scoreMatch(name: string, query: string): number | null {
+  if (query.length === 0) return 0;
+  const lowerName = name.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+
+  if (lowerName === lowerQuery) return 1000;
+  if (lowerName.startsWith(lowerQuery)) return 500 - name.length;
+  let score = 0;
+  let cursor = 0;
+  let run = 0;
+
+  for (const character of lowerQuery) {
+    const found = lowerName.indexOf(character, cursor);
+
+    if (found === -1) return null;
+    run = found === cursor ? run + 1 : 0;
+    score += found === cursor ? 5 + run : 1;
+    if (found === 0 || WORD_BOUNDARY.test(lowerName[found - 1]!)) score += 10;
+    score -= found - cursor;
+    cursor = found + 1;
+  }
+
+  return score;
+}
+
+export function slashFilter(items: SlashItem[], query: string): SlashItem[] {
+  if (query.length === 0) return items;
+  const scored: Array<{ item: SlashItem; score: number }> = [];
+
+  for (const item of items) {
+    const score = scoreMatch(item.name, query);
+
+    if (score !== null) scored.push({ item, score });
+  }
+
+  return scored.toSorted((left, right) => right.score - left.score).map((entry) => entry.item);
+}
+
+// a skill or action name: the grammar loadSkills and slashItemsFrom can produce, so a "/name"
+// token closes only on whitespace or another slash, never inside a valid underscore-or-hyphen name
+const SLASH_TOKEN = /(?:^|\s)(\/[a-zA-Z0-9_-]*)$/;
+
+/**
+ * The "/word" token the caret is writing right now: the run from the last
+ * whitespace up to the caret, at the start of the draft or after it. Null once a
+ * space closes the token, so each new "/" reopens the palette and skills chain.
+ * Caret-aware, so editing an earlier "/name" targets it, not a trailing token.
+ */
+export function activeSlashToken(text: string, caret: number): string | null {
+  const head = text.slice(0, Math.max(0, Math.min(caret, text.length)));
+  const match = SLASH_TOKEN.exec(head);
+
+  return match ? match[1]! : null;
+}
+
+/** True while the whole draft is just a "/query" - the palette owns it, so a blur discards it. */
+export function isStandaloneSlashQuery(text: string): boolean {
+  return /^\/\S*$/.test(text.trim());
+}
+
+export function insertSlashItem(text: string, caret: number, itemName: string) {
+  const token = activeSlashToken(text, caret) ?? "";
+  const cut = caret - token.length;
+  const insertion = `/${itemName} `;
+
+  return {
+    text: text.slice(0, cut) + insertion + text.slice(caret),
+    caret: cut + insertion.length,
+  };
+}
+
+/**
+ * The character ranges of every completed "/name" in the draft that names a real
+ * action or skill, so a surface can paint the references. A half-typed "/na" is
+ * not a reference yet, so it stays unpainted until the palette completes it.
+ */
+export function skillReferenceRanges(
+  text: string,
+  names: ReadonlySet<string>,
+): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  const pattern = /(?:^|\s)(\/[a-zA-Z0-9_-]+)/g;
+
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const token = match[1]!;
+
+    if (!names.has(token.slice(1))) continue;
+    const start = match.index + match[0].length - token.length;
+
+    ranges.push({ start, end: start + token.length });
+  }
+
+  return ranges;
+}
+
+/** Quick actions and user skills in one palette; a quick action wins a name collision (it expands). */
+export function mergeSlashItems(actions: SlashItem[], skills: SlashItem[]): SlashItem[] {
+  const taken = new Set(actions.map((action) => action.name));
+
+  return [...actions, ...skills.filter((skill) => !taken.has(skill.name))];
+}

package/src/keyboard/thread-chords.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { resolveNavKey } from "./thread-chords";
+
+const owner = { isOwner: true, resolved: false, treeActive: false };
+const readOnly = { type: "status" as const, message: "observer - read-only" };
+const submitted = { type: "status" as const, message: "review submitted - read-only" };
+
+describe("resolveNavKey", () => {
+  test("the session commands: submit, edit, share", () => {
+    expect(resolveNavKey({ name: "return" }, owner)).toEqual({ type: "openSubmit" });
+    expect(resolveNavKey({ name: "enter" }, owner)).toEqual({ type: "openSubmit" });
+    expect(resolveNavKey({ name: "e" }, owner)).toEqual({ type: "edit" });
+    expect(resolveNavKey({ name: "s" }, owner)).toEqual({ type: "share" });
+  });
+
+  test("a diff row's keys win over the shared letters, then fall through to curation", () => {
+    const diff = { ...owner, isDiff: true };
+
+    expect(resolveNavKey({ name: "x" }, diff)).toEqual({ type: "rejectChange" });
+    expect(resolveNavKey({ name: "c" }, diff)).toEqual({ type: "foldFile" });
+    expect(resolveNavKey({ name: "d" }, diff)).toEqual({ type: "toggleDiffView" });
+    expect(resolveNavKey({ name: "k" }, diff)).toEqual({ type: "walkStart" });
+    // a letter with no diff meaning still reaches the curation commands
+    expect(resolveNavKey({ name: "n" }, diff)).toEqual({ type: "nextAnnotation" });
+  });
+
+  test("the discussion and curation commands", () => {
+    expect(resolveNavKey({ name: "n" }, owner)).toEqual({ type: "nextAnnotation" });
+    expect(resolveNavKey({ name: "p" }, owner)).toEqual({ type: "prevAnnotation" });
+    expect(resolveNavKey({ name: "backspace" }, owner)).toEqual({ type: "removeAnnotation" });
+    expect(resolveNavKey({ name: "r" }, owner)).toEqual({ type: "openRename" });
+    expect(resolveNavKey({ name: "x" }, owner)).toEqual({ type: "cut" });
+    expect(resolveNavKey({ name: "u" }, owner)).toEqual({ type: "restoreCuration" });
+  });
+
+  test("the tree commands: move on the Tree tab, go, branch, label, fork, hand off", () => {
+    const onTree = { ...owner, treeActive: true };
+
+    expect(resolveNavKey({ name: "n" }, onTree)).toEqual({ type: "treeMove", direction: 1 });
+    expect(resolveNavKey({ name: "p" }, onTree)).toEqual({ type: "treeMove", direction: -1 });
+    expect(resolveNavKey({ name: "g" }, owner)).toEqual({ type: "treeGo" });
+    expect(resolveNavKey({ name: "b" }, owner)).toEqual({ type: "treeBranch" });
+    expect(resolveNavKey({ name: "l" }, owner)).toEqual({ type: "treeLabel" });
+    expect(resolveNavKey({ name: "f" }, owner)).toEqual({ type: "treeFork" });
+    expect(resolveNavKey({ name: "h" }, owner)).toEqual({ type: "treeForkShare" });
+  });
+
+  test("a shift letter resolves as its uppercase, which no command claims, so it returns to typing", () => {
+    expect(resolveNavKey({ name: "x", shift: true }, { ...owner, isDiff: true })).toBeNull();
+  });
+
+  test("a collaborator is refused the owner's commands; renaming stays open", () => {
+    const collaborator = { ...owner, isOwner: false };
+
+    expect(resolveNavKey({ name: "return" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "e" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "s" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "x" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "g" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "f" }, collaborator)).toEqual(readOnly);
+    expect(resolveNavKey({ name: "r" }, collaborator)).toEqual({ type: "openRename" });
+  });
+
+  test("a resolved review refuses every change and says so; a fork stays open", () => {
+    const resolved = { ...owner, resolved: true };
+
+    expect(resolveNavKey({ name: "return" }, resolved)).toBeNull();
+    expect(resolveNavKey({ name: "e" }, resolved)).toEqual(submitted);
+    expect(resolveNavKey({ name: "x" }, resolved)).toEqual(submitted);
+    expect(resolveNavKey({ name: "b" }, resolved)).toEqual(submitted);
+    expect(resolveNavKey({ name: "f" }, resolved)).toEqual({ type: "treeFork" });
+    expect(resolveNavKey({ name: "s" }, resolved)).toEqual({ type: "share" });
+  });
+
+  test("an unmapped key returns null, so the surface returns to typing", () => {
+    expect(resolveNavKey({ name: "z" }, owner)).toBeNull();
+    expect(resolveNavKey({ name: "j" }, owner)).toBeNull();
+  });
+});

package/src/keyboard/thread-chords.ts

@@ -0,0 +1,163 @@
+import type { Intent } from "./keymap";
+
+export interface NavKey {
+  name: string;
+  shift?: boolean;
+}
+
+export interface ThreadNavContext {
+  isOwner: boolean;
+  resolved: boolean;
+  treeActive: boolean;
+  isDiff?: boolean;
+}
+
+export interface ChordEntry {
+  keys: string;
+  label: string;
+}
+
+export function sessionCommandEntries(): ChordEntry[] {
+  return [
+    { keys: "⏎", label: "submit the review" },
+    { keys: "e", label: "edit in $EDITOR" },
+    { keys: "s", label: "share" },
+  ];
+}
+
+export function diffCommandEntries(): ChordEntry[] {
+  return [
+    { keys: "x", label: "reject the change under the caret" },
+    { keys: "u", label: "restore the last rejection" },
+    { keys: "c", label: "collapse the file to its band" },
+    { keys: "d", label: "split / stacked (when wide)" },
+    { keys: "k", label: "start the guided walk" },
+  ];
+}
+
+export function curationCommandEntries(): ChordEntry[] {
+  return [
+    { keys: "n / p", label: "next / previous card" },
+    { keys: "z", label: "fold / unfold the card" },
+    { keys: "⌫", label: "delete the card" },
+    { keys: "r", label: "rename the author" },
+    { keys: "x", label: "cut the block" },
+    { keys: "u", label: "restore the last cut" },
+  ];
+}
+
+export function treeCommandEntries(): ChordEntry[] {
+  return [
+    { keys: "g", label: "go to the entry" },
+    { keys: "b", label: "branch off the tip" },
+    { keys: "l", label: "label a checkpoint" },
+    { keys: "f", label: "fork the path" },
+    { keys: "h", label: "fork and hand off" },
+  ];
+}
+
+const READ_ONLY: Intent = { type: "status", message: "observer - read-only" };
+const RESOLVED: Intent = { type: "status", message: "review submitted - read-only" };
+
+function mutating(intent: Intent, context: ThreadNavContext): Intent {
+  if (!context.isOwner) return READ_ONLY;
+  if (context.resolved) return RESOLVED;
+
+  return intent;
+}
+
+function resolveDiffKey(name: string, context: ThreadNavContext): Intent | null {
+  switch (name) {
+    case "x":
+      return mutating({ type: "rejectChange" }, context);
+    case "c":
+      return { type: "foldFile" };
+    case "d":
+      return { type: "toggleDiffView" };
+    case "k":
+      return context.resolved ? RESOLVED : { type: "walkStart" };
+    default:
+      return null;
+  }
+}
+
+function resolveSessionKey(name: string, context: ThreadNavContext): Intent | null {
+  switch (name) {
+    case "e":
+      return mutating({ type: "edit" }, context);
+    case "s":
+      return context.isOwner ? { type: "share" } : READ_ONLY;
+    default:
+      return null;
+  }
+}
+
+function resolveCurationKey(name: string, context: ThreadNavContext): Intent | null {
+  switch (name) {
+    case "n":
+      return context.treeActive ? { type: "treeMove", direction: 1 } : { type: "nextAnnotation" };
+    case "p":
+      return context.treeActive ? { type: "treeMove", direction: -1 } : { type: "prevAnnotation" };
+    case "g":
+      return mutating({ type: "treeGo" }, context);
+    case "b":
+      return mutating({ type: "treeBranch" }, context);
+    case "l":
+      return mutating({ type: "treeLabel" }, context);
+    case "f":
+      return context.isOwner ? { type: "treeFork" } : READ_ONLY;
+    case "h":
+      return context.isOwner ? { type: "treeForkShare" } : READ_ONLY;
+    case "backspace":
+      return mutating({ type: "removeAnnotation" }, context);
+    case "r":
+      return { type: "openRename" };
+    case "x":
+      return mutating({ type: "cut" }, context);
+    case "u":
+      return mutating({ type: "restoreCuration" }, context);
+    default:
+      return null;
+  }
+}
+
+export interface SessionChordKey {
+  name: string;
+  ctrl?: boolean;
+  meta?: boolean;
+  super?: boolean;
+}
+
+export function resolveSessionChord(
+  key: SessionChordKey,
+  context: Pick<ThreadNavContext, "isOwner" | "resolved">,
+): Intent | null {
+  if (key.name === "return" || key.name === "enter") {
+    if (!(key.ctrl || key.meta || key.super)) return null;
+    if (!context.isOwner) return READ_ONLY;
+
+    return context.resolved ? null : { type: "openSubmit" };
+  }
+  if (!key.ctrl) return null;
+  if (key.name === "e")
+    return context.resolved ? RESOLVED : context.isOwner ? { type: "edit" } : READ_ONLY;
+  if (key.name === "s") return context.isOwner ? { type: "share" } : READ_ONLY;
+
+  return null;
+}
+
+export function resolveNavKey(key: NavKey, context: ThreadNavContext): Intent | null {
+  const name = key.shift ? key.name.toUpperCase() : key.name;
+
+  if (name === "return" || name === "enter") {
+    if (!context.isOwner) return READ_ONLY;
+
+    return context.resolved ? null : { type: "openSubmit" };
+  }
+
+  return (
+    (context.isDiff ? resolveDiffKey(name, context) : null) ??
+    resolveSessionKey(name, context) ??
+    resolveCurationKey(name, context)
+  );
+}

package/src/keyboard/use-shared-keyboard.ts

@@ -0,0 +1,55 @@
+/** One keypress subscription per renderer, even when several editor tiles are mounted. */
+
+import { useEffect, useEffectEvent } from "react";
+import { useRenderer } from "@opentui/react";
+import type { KeyEvent } from "@opentui/core";
+
+type KeyInput = NonNullable<ReturnType<typeof useRenderer>>["keyInput"];
+type KeyHandler = (key: KeyEvent) => void;
+
+interface KeySubscriptions {
+  handlers: Set<KeyHandler>;
+  notify: KeyHandler;
+}
+
+const subscribers = new WeakMap<KeyInput, KeySubscriptions>();
+
+function subscribeToKeypress(input: KeyInput, handler: KeyHandler): () => void {
+  let subscription = subscribers.get(input);
+
+  if (!subscription) {
+    const handlers = new Set<KeyHandler>();
+    const notify = (key: KeyEvent): void => {
+      for (const subscriber of handlers) subscriber(key);
+    };
+
+    subscription = { handlers, notify };
+    subscribers.set(input, subscription);
+    input.on("keypress", notify);
+  }
+
+  const { handlers, notify } = subscription;
+
+  handlers.add(handler);
+
+  return () => {
+    handlers.delete(handler);
+    if (handlers.size > 0) return;
+
+    input.off("keypress", notify);
+    subscribers.delete(input);
+  };
+}
+
+export function useSharedKeyboard(handler: KeyHandler): void {
+  const renderer = useRenderer();
+  const stableHandler = useEffectEvent(handler);
+
+  useEffect(() => {
+    const input = renderer?.keyInput;
+
+    if (!input) return;
+
+    return subscribeToKeypress(input, stableHandler);
+  }, [renderer]);
+}

package/src/markdown/__snapshots__/view-plan.regression.test.ts.snap

@@ -0,0 +1,100 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`view-plan regression harness (M0) blockRuns output is stable across the representative blocks 1`] = `
+[
+  {
+    "runs": [
+      {
+        "role": "plain",
+        "start": 0,
+        "text": "Heading with ",
+      },
+      {
+        "role": "strong",
+        "start": 15,
+        "text": "bold",
+      },
+    ],
+    "text": "Heading with **bold**",
+    "type": "same",
+  },
+  {
+    "runs": [
+      {
+        "role": "plain",
+        "start": 0,
+        "text": "A paragraph with ",
+      },
+      {
+        "role": "strong",
+        "start": 19,
+        "text": "strong",
+      },
+      {
+        "role": "plain",
+        "start": 27,
+        "text": ", ",
+      },
+      {
+        "role": "em",
+        "start": 30,
+        "text": "em",
+      },
+      {
+        "role": "plain",
+        "start": 33,
+        "text": ", ",
+      },
+      {
+        "role": "code",
+        "start": 36,
+        "text": "code",
+      },
+      {
+        "role": "plain",
+        "start": 41,
+        "text": ", ",
+      },
+      {
+        "role": "strike",
+        "start": 45,
+        "text": "strike",
+      },
+      {
+        "role": "plain",
+        "start": 53,
+        "text": " and a ",
+      },
+      {
+        "href": "https://example.com",
+        "role": "link",
+        "start": 61,
+        "text": "label",
+      },
+      {
+        "role": "plain",
+        "start": 88,
+        "text": ".",
+      },
+    ],
+    "text": "A paragraph with **strong**, *em*, \`code\`, ~~strike~~ and a [label](https://example.com).",
+    "type": "same",
+  },
+  {
+    "runs": [
+      {
+        "role": "plain",
+        "start": 0,
+        "text": "a list item with ",
+      },
+      {
+        "role": "em",
+        "start": 18,
+        "text": "emphasis",
+      },
+    ],
+    "text": "a list item with *emphasis*",
+    "type": "same",
+  },
+]
+`;

package/src/markdown/components/MarkdownGridBlock.stories.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import { buildDisplay, type DisplayBlock } from "../view-plan";
+import type { Story, StoryMeta } from "../../stories/story";
+import { MarkdownGridBlock } from "./MarkdownGridBlock";
+
+export const meta: StoryMeta = { title: "Surfaces/MarkdownGridBlock" };
+
+/** The first display block of a kind, for a story that renders one grid in isolation. */
+function firstBlock(markdown: string, kind: DisplayBlock["kind"]): DisplayBlock {
+  return buildDisplay(markdown).find((block) => block.kind === kind)!;
+}
+
+const TABLE = firstBlock(
+  "| Name | Size |\n| :--- | ---: |\n| daemon | 12 |\n| client | 7 |",
+  "table",
+);
+const FRONTMATTER = firstBlock(
+  "---\ntitle: Migration Plan\nowner: platform team\nstatus: in review\n---\n\n# Plan\n",
+  "frontmatter",
+);
+
+export const Table: Story = {
+  render: () => <MarkdownGridBlock block={TABLE} theme={DARK} contentWidth={60} />,
+  expectedColors: [DARK.text, DARK.textDim],
+  size: { width: 62, height: 6 },
+};
+
+export const Frontmatter: Story = {
+  render: () => <MarkdownGridBlock block={FRONTMATTER} theme={DARK} contentWidth={60} />,
+  expectedColors: [DARK.text, DARK.textDim],
+  size: { width: 62, height: 9 },
+};

package/src/markdown/components/MarkdownGridBlock.tsx

@@ -0,0 +1,72 @@
+/**
+ * Render a table or frontmatter display block as its grid: a GFM table (bold
+ * header over a rule, aligned columns) or a leading-frontmatter key/value box.
+ * Layout is computed in markdown-grid; this only paints the positioned segments,
+ * dim for borders and bold for the header or key column. The grid annotates as
+ * one unit: every row registers the same block span for hit-testing, so a click
+ * or drag anchors a comment on it and a mark tints the whole grid.
+ */
+
+import React from "react";
+import type { MouseEvent as TerminalMouseEvent, TextRenderable } from "@opentui/core";
+import { displayText, type DisplayBlock } from "../view-plan";
+import type { Theme } from "../../appearance/theme";
+import { BOLD } from "../../annotations/annotation-palette";
+import {
+  layoutFrontmatterGrid,
+  layoutMarkdownTable,
+  parseFrontmatterRows,
+  parseMarkdownTable,
+  type GridLine,
+} from "../markdown-grid";
+
+function gridLines(block: DisplayBlock, contentWidth: number): GridLine[] {
+  if (block.kind === "table") return layoutMarkdownTable(parseMarkdownTable(displayText(block)));
+
+  return layoutFrontmatterGrid(parseFrontmatterRows(displayText(block)), contentWidth);
+}
+
+export function MarkdownGridBlock({
+  block,
+  theme,
+  contentWidth,
+  marked = false,
+  markBackdrop,
+  registerRow,
+  onRowMouseDown,
+}: {
+  block: DisplayBlock;
+  theme: Theme;
+  contentWidth: number;
+  /** True while a discussion or held selection marks this grid; tints it so the annotation reads. */
+  marked?: boolean;
+  markBackdrop?: string;
+  /** Registers a grid row's renderable with the annotation surface, all mapping to the one block span. */
+  registerRow?: (rowIndex: number) => (renderable: TextRenderable | null) => void;
+  onRowMouseDown?: (event: TerminalMouseEvent) => void;
+}): React.ReactNode {
+  const lines = gridLines(block, Math.max(12, contentWidth));
+
+  return (
+    <box style={{ flexDirection: "column", backgroundColor: marked ? markBackdrop : undefined }}>
+      {lines.map((line, lineIndex) => (
+        <box key={`grid-${lineIndex}`} style={{ flexDirection: "row" }}>
+          <text selectable={false}>
+            <span fg={theme.textDim}>{"  "}</span>
+          </text>
+          <text selectable={false} ref={registerRow?.(lineIndex)} onMouseDown={onRowMouseDown}>
+            {line.map((segment, segmentIndex) => (
+              <span
+                key={segmentIndex}
+                fg={segment.dim ? theme.textDim : theme.text}
+                attributes={segment.bold ? BOLD : 0}
+              >
+                {segment.text}
+              </span>
+            ))}
+          </text>
+        </box>
+      ))}
+    </box>
+  );
+}

package/src/markdown/components/MarkdownThreadEditor.stories.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { MarkdownThreadEditor } from "./MarkdownThreadEditor";
+
+export const meta: StoryMeta = { title: "Surfaces/MarkdownThreadEditor" };
+
+const SAMPLE =
+  "# Rollout Plan\n\nShip the store move behind a `flag`. See [docs](https://x.dev).\n\n- first step\n- second step\n";
+
+export const Editing: Story = {
+  render: () => <MarkdownThreadEditor initialText={SAMPLE} theme={DARK} onExitEditor={() => {}} />,
+  expectedColors: [DARK.blue, DARK.textMuted, DARK.textDim],
+  size: { width: 62, height: 14 },
+};